# Board API Key Audit Boundary

Board API key allow decisions authorize a request only when the matching
security disposition is durable. PostgreSQL mutations and non-database effects
have different atomicity constraints, so this document states the boundary
explicitly.

## PostgreSQL guarantee

`server/src/security/board-key-audit-coupling.ts` stages an allow disposition in
the request context.

- A mutation inside `db.transaction` writes the allow disposition on that
  transaction before the first domain mutation. Both commit or both roll back.
- Direct `db.insert`, `db.update`, `db.delete`, and mutating `db.execute` calls
  are replayed lazily inside a transaction with the staged disposition. An
  audit insert failure therefore rolls back the direct domain mutation.
- Direct mutation-builder operations that cannot be replayed safely fail before
  issuing SQL and must be moved into an explicit `db.transaction`.
- There is no successful untransacted fallback. Response settlement persists
  only successful no-mutation dispositions; it cannot convert an uncoupled
  mutation into success.

This boundary deliberately classifies unknown raw SQL as mutating. Read-only
raw SQL is limited to statements beginning with `SELECT`, `SHOW`, `EXPLAIN`,
`TABLE`, or `VALUES`.

## Non-database side-effect review

The runtime route inventory denies undeclared board-key routes. Explicit denials
also cover the MCP surface, tool calls and sessions, plugin action/bridge/data
and webhook surfaces, skill-test execution, agent instruction-file mutation,
and auth/claim/invite surfaces. Board keys can still reach authorized management
routes whose handlers may combine PostgreSQL state with effects that PostgreSQL
cannot roll back.

| Reachable route family | Effect outside PostgreSQL | Residual failure mode |
| --- | --- | --- |
| Artifacts, attachments, company import/export, skills | Object storage or local filesystem writes/removals | An audit or domain rollback can leave an orphaned object/materialized tree; compensation can also fail. |
| Agents, heartbeat/runtime, workspaces, environments | Process start/cancel, git/worktree changes, or provider calls | A crash can occur between durable intent and execution/acknowledgement, causing a missed action or a retry. |
| Plugin and tool management | Plugin lifecycle, OAuth/provider, or network activity | Remote state cannot join the database transaction and may be applied despite a later local failure. |
| Activity publication, plugin events, assignee wakeups | In-process publication or adapter dispatch | A post-commit crash can miss delivery; retry after an ambiguous acknowledgement can duplicate delivery. |

The database audit coupling does not claim atomic rollback for these effects.
Side-effecting handlers must use the following pattern when the effect matters
to correctness or security:

1. Persist the domain change, board-key allow disposition, and an intent/outbox
   row in one transaction.
2. Execute the external effect only from the committed intent.
3. Give the effect a stable idempotency key derived from the intent, not from a
   delivery attempt.
4. Persist completion or failure so a worker can retry ambiguous outcomes.
5. Use compensating cleanup for object/file/provider state and treat cleanup as
   retryable, not guaranteed rollback.

Existing durable wake requests and idempotency keys reduce duplicate/lost-work
risk where they are used. Live UI/plugin publications remain best effort. A
successful no-mutation request is audited during response settlement; if that
audit write fails there is no PostgreSQL domain commit to roll back. A handler
that performs only an external effect must therefore not rely on no-mutation
settlement: it needs a durable intent/outbox boundary before the effect.

When a route becomes board-key reachable, security review must identify every
filesystem, object-store, process, adapter, plugin, and outbound-network effect
and either prove an existing outbox/idempotency boundary or record the residual
risk and remediation owner.