feat(account): read-only mode for abuse-paused accounts

[jiashuoz]

An account whose sending is paused with pause_class = 'abuse' (columns from migration 122) is now read-only on every customer surface: no write of any kind succeeds. Pauses with the other classes (operator, billing, system) keep today's behaviour (sending refused, everything else works), because those are the automated detector's lever and may hit legitimate customers.

Motivation. The 2026-09 phishing operator, while paused, could still create brand-named agents, rename them, delete messages and register domains; only sending and permanent deletion were blocked.

Rule. State is exactly state='paused' AND pause_class='abuse' (identity.Store.AccountReadOnly); a resume lifts it immediately. Enforced at one guard per surface: internal/httpapi/read_only.go (/v1), internal/agent/read_only.go (legacy dashboard mux), mcp/src/tools/mutating.ts (per-tool flag), WebSocket by message type; agent access tokens and delegated tokens are refused for writes like any other credential. Fails closed on DB errors (503, no write).

Refused (403 account_read_only): agent create/update/rename/restore/trash; message send/reply/forward/schedule; review approve/reject; message delete/restore/label edits; domain register/verify/delete; API key create/delete; webhook create/update/delete/rotate/test; event redelivery; contacts + imports; templates; outreach upserts/deletes; protection settings; suppression create/delete; sending-access request; legacy dashboard writes; OAuth consent allow (mints a grant; checked in the handler after consent's own provider/authorize/session handling); HITL magic-link approve/reject; attaching a NEW external principal (403 account_read_only from POST /api/internal/users/external-principals/attach — TC side: a reconciler replay of an already-attached (issuer, subject) → user triple still returns 200; only a new principal for a paused account gets the new 403). The legacy account-write routes authenticate the session cookie only, and the guard resolves the caller the same way: an Authorization header on one of them is 400 ambiguous_credentials for everyone, and no valid session is 401 from the guard. A legacy write route missing from the classification table defaults to refuse. The HITL expiry sweep leaves a read-only account's approve-on-expiry holds pending_review (nothing released into the inbox/webhooks, nothing sent); reject-on-expiry holds still resolve.

Allowed: every read (incl. exports, metrics, events, attachment downloads, WS live-tail); POST /v1/templates/validate; sign-in/out, OAuth token exchange/revocation, /agent/identity; OAuth consent deny (fosite's access_denied redirect still reaches the client); account trash (DELETE /v1/account without permanent → mode: "trash"); the restore/erase interstitial (erase stays 409 erase_held). Operator local commands unaffected.

Decision: SES sender identities survive the trash of a read-only account. Trashing an account normally enqueues the SES sender-identity teardown for each owned domain. While the account is read-only (abuse pause) the trash skips that teardown: the provider-side identities are evidence for the abuse review, and deleting them at trash time would destroy it. The domains are still unverified, so nothing is sent from them. The purge at the end of the trash window is not held by a pause and still tears the identities down, so nothing is kept forever. Other pause classes and unpaused accounts are unchanged.

MCP: every tool advertises _meta["e2a/mutating"]; the classification is pinned to the HTTP methods of the /v1 operations each tool calls (walked against api/openapi.yaml) and every destructiveHint tool must be mutating. Raw (non-Huma) routes on the /v1 chi root are walked too: each non-GET one is a Huma operation or on an explicit exemption list.

Rate limiting: /v1 rate limiting runs before the read-only guard, so a refused write still counts against the request budget. Kept deliberately — running the guard's DB lookup first would let an over-the-limit caller drive unlimited lookups.

Clients: new vocabulary code account_read_only in openapi, both generated SDK models, TS/Python error mapping, CLI guidance (distinct exit code), MCP tool error text, web copy; a persistent dashboard banner plus disabled write controls (web/src/app/components/ReadOnlyBanner.tsx). Contract server seeds an abuse-paused account; conformance scenario: one representative write per resource family → 403, reads → 200, trash delete → 200.

Tests: spec-walk test classifies every openapi operation as read or write explicitly — an unclassified route fails the build; store/guard tests with real Postgres; -race on touched packages. Docs: docs/design/account-read-only.md, docs/api.md, docs/data-handling.md, docs/deployment.md.

Accepted window: the guards read the control row outside the handler transaction, so a write whose check passed milliseconds before a pause commits can complete; sending is re-checked at the sending gate. Documented in the design doc's Freshness section.

Operator note: -pause-account-sending -pause-class abuse now also freezes writes; -resume-account-sending lifts it.

Implementation by a Claude Code subagent; the final push and this PR were made by the main session after the subagent's connection dropped twice post-implementation. Review rounds to follow before merge.

🤖 Generated with Claude Code

https://claude.ai/code/session_018tVLxUHk3fqQuq8C3wqyHW