Harden inbound policy gate

[raysvitla]

Depends on #3.

Turns the policy-runner skeleton into a hardened single chokepoint between authenticated network reception and any agent-runtime side effect. Every event reaching Agent.inboundQueue or firing inbound:message on the Agent has now passed PolicyGate.evaluate(). Fail-closed paths produce no side effect.

No tool execution. No plaintext logging. Fails closed.

Architecture

GroupManager.handleGroupMessage   (auth + decrypt + persist; unchanged)
        │ emit('inbound:message', ev)
        ▼
PolicyGate.evaluate(ev)
  1. validateInboundEvent       → fail-closed: malformed-event / unknown-event-kind
  2. dedup check                → fail-closed: duplicate-event
  3. isMember recheck (group)   → fail-closed: not-a-member  (defence-in-depth)
  4. AgentPolicy.decide         → pure: act | ask | ignore
  5. PolicyAuditLog.record      → metadata-only PolicyAuditEntry
  6. mark messageId in dedup    ← only here, post-audit
  7. emit('decision', ...)
        │
   allowed ┴ denied → no queue, no emit
        ▼
inboundQueue.push + Agent.emit('inbound:message')

The gate is the only writer of Agent.inboundQueue and the only emitter of Agent-level inbound:message. 'group:message' (legacy) is preserved unchanged.

Files changed

New source (8 files):

• packages/core/src/policy/audit.ts — PolicyAuditEntry (metadata-only) + redactPlaintext helper.
• packages/node/src/policy/validate.ts — strict validateInboundEvent(unknown) returning a typed result.
• packages/node/src/policy/audit-log.ts — bounded in-memory ring buffer.
• packages/node/src/policy/policy-gate.ts — the gate itself.
• packages/mcp/src/tools/policy.ts — get_policy_audit_recent MCP tool + toPolicyAuditDTO.
• 4 new test files (see below).

Modified (5 files):

• packages/core/src/policy/types.ts — extends PolicyReason with the 4 fail-closed tokens; exports stable POLICY_REASONS vocabulary.
• packages/node/src/policy/agent-policy.ts — adds setConfig (decisions remain pure).
• packages/node/src/agent.ts — constructs PolicyAuditLog / AgentPolicy / PolicyGate in start(); routes groupManager.on('inbound:message') through the gate; adds setPolicyConfig, 'policy:decision', 'policy:audit'.
• packages/node/src/index.ts and packages/mcp/src/server.ts — register the new exports/tool.
• docs/ARCHITECTURE.md — adds policy-gate subsection cross-linking POLICY.md.

New docs:

• docs/POLICY.md — full lifecycle, decision table, reason codes, privacy invariant, dedup retry-poison invariant, future tool-execution extension point (explicitly NOT implemented).

Diffstat: 18 files, 1871 insertions, 3 deletions.

Tests added (42 new; total 186; previous 144 unchanged)

File	Tests	Coverage
policy-validate.test.ts	13	structural validation + locked POLICY_REASONS vocabulary
policy-gate-unit.test.ts	10	gate happy path, four fail-closed branches, dedup ordering, FIFO eviction, retry-poison invariant (validation/membership/audit-throw)
policy-gate-adversarial.test.ts	10	the 9 mission scenarios driven through a real Agent (with mocked hyperswarm/hyperdht): allowed-member, denied-non-member, unknown-kind, malformed (5 mutations), duplicate-no-double-effect, retry-after-transient-fail, plaintext-canary, locked POLICY_REASONS, ordering-audit-before-queue, queue-is-post-gate
policy-gate-fuzz.test.ts	3	500×{never-throw, never-allowed-by-default, content-never-leaks}, with intercepted console + stdout + stderr; locked PolicyAuditEntry key set
policy-audit-dto.test.ts	6	DTO is explicit projection: pollution canaries (plaintext, decryptedBody, toolArgs) stripped; locked DTO key set; matchedInterests is sliced (caller cannot mutate audit log)

Invariants protected

1. Privacy: no plaintext, ciphertext, decrypted body, tool args, raw event payload, or private key material in policy decisions, audit entries, audit log, MCP tool output, or any console / stdout / stderr write from the policy code path. Three independent test layers (adversarial canary, fuzz with intercepted IO, MCP DTO pollution test) enforce this.
2. Fail-closed: malformed structure, unknown kind, duplicate messageId, and non-member sender all bypass AgentPolicy.decide entirely and produce no side effect (no queue push, no public re-emit).
3. Dedup retry-safety: a messageId enters the dedup set ONLY after validation, membership recheck, the decision, and the audit write all succeed. Validation/membership failure or audit.record throw does NOT poison the dedup set; legitimate retries with the same messageId are re-evaluated.
4. Decision purity: AgentPolicy.decide is unchanged in signature and remains pure; validation/dedup/audit/membership all live outside it.
5. Audit shape lock: an explicit-key test on PolicyAuditEntry and a separate explicit-key test on PolicyAuditDTO fail the moment any new (potentially content-bearing) field is added without deliberate review.
6. Stable reason vocabulary: POLICY_REASONS is exhaustively listed and asserted in tests; renaming or adding a token is a deliberate diff.
7. Defence-in-depth membership: the gate independently rechecks membership for group events. Even direct in-process injection (test bypass, future transports) cannot route a non-member event into the queue.
8. Legacy compatibility: 'group:message' event payload is unchanged; existing 144 tests pass without modification.
9. Owner-private message store untouched: the existing messages.content TEXT column (plaintext at rest, owner-only) is intentionally outside the privacy invariant. No schema/storage changes in this PR.

Known limitations

• In-memory audit only. No SQLite persistence in this PR; the audit log is lost on process restart. Durability is a deliberate follow-up.
• DM events not gated yet. Agent.handleDirectMessage is still fail-closed per fix: harden group protocol and key storage #1. The gate accepts kind: 'dm' for forward compatibility, but no DM emitter exists. Wires when DM signing / Double Ratchet lands.
• Default config is restrictive ({}). Without a configured mention/trust/interest list, decide returns ignore / not-addressed for everything; the queue stays empty. Production deployments configure via AgentOptions.policyConfig or agent.setPolicyConfig(...).
• No tool / handler execution. The PR delivers decisions only. Consumers wire agent.on('policy:decision', ...) for action; act actions are NOT auto-invoked.
• Replay protection at the protocol layer is unchanged. Gate-level dedup catches double-dispatch within a process; protocol-level replay (chain-key monotonicity in SenderKeys) is the network layer's responsibility.

Hard constraints honored

• ❌ No tool execution.
• ❌ No payments / token economics.
• ❌ No server-trust assumptions.
• ❌ No weakened encryption / privacy claims.
• ❌ No plaintext logging.
• ✅ Public API extension is deliberate: new Agent.policy / policyGate / policyAudit surfaces, two new 'policy:decision' / 'policy:audit' events, setPolicyConfig. All documented in POLICY.md and exercised by tests.

Exact commands run

pnpm install                # already up to date
pnpm build                  # 5 packages green
pnpm test                   # 186 tests passing (was 144); 0 failed
pnpm lint                   # no-op (no per-package lint script defined)
git diff --check HEAD~7..HEAD   # clean
git diff HEAD~7..HEAD | grep "^+" | grep -iE "(api_key|secret|password|token|private_key)"
                            # only test/doc canary phrasing — no real secrets

🤖 Generated with Claude Code