@fuzdev/fuz_app 0.53.0 → 0.55.0

package/dist/auth/CLAUDE.md

@@ -84,8 +84,10 @@ Design notes:
 ### Identity entities (`account_schema.ts`)
 
 - `Account` (primary identity, holds `password_hash`), `Actor` (the entity
-  that acts — owns cells, holds permits, appears in audit trails; 1:1 with
-  account in v1), `Permit` (time-bounded, revocable grant of a role to an
+  that acts — owns cells, holds permits, appears in audit trails; an account
+  may host one or more actors, with the dispatcher's authorization phase
+  resolving the acting actor per-request via `acting?: ActingActor` on
+  inputs), `Permit` (time-bounded, revocable grant of a role to an
   actor — carries `scope_id`, `source_offer_id`, `revoked_reason`),
   `AuthSession` (server-side, keyed by blake3), `ApiToken`.
 - Every `id` / `*_id` field on entity interfaces, `*Json` schemas, and
@@ -209,6 +211,50 @@ Zod enum; `AuditOutcome` is `'success' | 'failure'`.
   `AuditLogListOptions` (supports `since_seq` for SSE reconnection gap fill);
   `AUDIT_LOG_DEFAULT_LIMIT = 50` (default page size, lives on the schema
   side so client codegen can import it without dragging in the query layer).
+  `target_actor_id` lives parallel to `target_account_id` on both row
+  and input. **Rule** — `target_actor_id` is populated when the event
+  subject is bound to a specific actor. Concretely: `permit_revoke`
+  and `permit_grant` (admin direct-grant, self-service toggle, and
+  in-tx accept all populate both target columns — the grantee is the
+  subject regardless of initiator), in-tx `permit_offer_accept` on
+  accept, and `permit_offer_decline` always populate both target
+  columns (decline joins `from_account_id` into the RETURNING so the
+  "both populated → same account" invariant holds uniformly).
+  Offer-shape events (`permit_offer_create`, `_expire`, `_retract`,
+  `_supersede`) populate `target_actor_id` when the offer was
+  actor-targeted at create time (`permit_offer.to_actor_id` set),
+  null when the offer was account-grain (any actor on
+  `to_account_id` may accept). Account-shape events (login, logout,
+  signup, bootstrap, password change, session/token revoke,
+  app_settings update, invite events) stay account-grain on both
+  `target_actor_id` **and** `actor_id` — the operation is performed
+  by the account, and a multi-actor user must be able to log out
+  (or change password, or revoke sessions) without first picking an
+  acting actor. Permit/admin/offer events keep recording the
+  initiator's actor in `actor_id`.
+  SSE/WS socket-close keys on `target_account_id ?? account_id`
+  (sessions stay account-grain at the routing layer even though
+  they bind to a specific actor at request-context resolution time —
+  see request_context.ts).
+- **Actor-targetable offers** — `permit_offer.to_actor_id` is the
+  optional column that flips an offer from account-grain (null,
+  default) to actor-grain (non-null). `query_permit_offer_create`
+  validates the actor↔account binding in one SELECT and rejects with
+  `PermitOfferActorAccountMismatchError` when the supplied actor isn't
+  on `to_account_id`. `query_accept_offer` rejects wrong-actor accepts
+  on actor-targeted offers with `PermitOfferActorMismatchError` —
+  surfaced to RPC callers as `permit_offer_actor_mismatch`. Closes the
+  audit hole where offer-shape events left `target_actor_id` null even
+  when the recipient binding was known at offer time.
+- **`emit_permit_target_event` helper** — the canonical entry point
+  for permit-shape audit emissions. Takes `(ctx, auth, deps, {event_type,
+target_account_id, target_actor_id, metadata, outcome?})` and lifts
+  the `actor_id` / `account_id` / `ip` boilerplate that every
+  `permit_*` audit emit site repeats. Use this instead of
+  `audit_log_fire_and_forget` for any event populating one of the
+  `target_*_id` columns; reach for the lower-level helper only when
+  the event is non-permit-shape (e.g., `app_settings_update`,
+  bootstrap, signup).
 - Client-safe: `AuditLogEventJson`, `AuditLogEventWithUsernamesJson`,
   `PermitHistoryEventJson`, `AdminSessionJson`.
 - `get_audit_metadata(event)` type-narrows after checking `event_type`.
@@ -334,7 +380,12 @@ CRUD + listing:
 - `query_update_account_password`, `query_delete_account` (cascades to
   actors, permits, sessions, tokens).
 - `query_account_has_any` — used by bootstrap for belt-and-suspenders check.
-- `query_actor_by_account`, `query_actor_by_id`.
+- `query_actors_by_account` — list every actor on an account, ordered
+  by `created_at`. Used by `resolve_acting_actor` to pick the unique
+  actor on single-actor accounts or surface `actor_required` when the
+  account has multiple actors.
+- `query_actor_by_id` — direct lookup by id; preferred when the caller
+  already has an actor id in scope.
 - `query_admin_account_list` — composes accounts + actors + active permits +
   pending inbound offers with **four flat queries** instead of N+1. Pending
   offers exclude `message` on purpose (cross-admin visibility). Returns
@@ -347,8 +398,14 @@ CRUD + listing:
   uses `IS NOT DISTINCT FROM` (plain `=` would miss the NULL-scope conflict
   case).
 - `query_permit_find_active_role_for_actor(deps, permit_id, actor_id)` —
-  actor-scoped read, so IDOR protection is consistent with revoke. Returns
-  `{role}` or `null`.
+  actor-scoped read, so IDOR protection is consistent with revoke.
+  Returns `{role, account_id}` (the actor's `account_id` joined in) or
+  `null`. The `account_id` flows into the audit envelope's
+  `target_account_id` and the SSE/WS socket-close fan-out target —
+  collapsing what used to be a second `query_actor_by_id` round-trip in
+  the revoke handler into one read closes the small TOCTOU window
+  where the actor row could be deleted between the IDOR check and the
+  actor lookup.
 - **`query_revoke_permit(deps, permit_id, actor_id, revoked_by, reason?)`** —
   actor-scoped IDOR guard (returns `null` if the permit belongs to a
   different actor). Supersedes pending offers for the revoked permit's
@@ -360,7 +417,10 @@ CRUD + listing:
 - `query_permit_find_active_for_actor`, `query_permit_list_for_actor`.
 - `query_permit_has_role(deps, actor_id, role, scope_id?)` — `IS NOT DISTINCT FROM`
   handles the NULL case. Omitted scope matches `scope_id IS NULL` (pre-scope
-  callers keep semantics).
+  callers keep semantics). Use only when checking an arbitrary `actor_id`
+  that isn't the request actor (e.g., post-mutation verification, scripts,
+  audit-time checks). For the request actor, prefer `has_scoped_role` /
+  `has_any_scoped_role` on the in-memory `auth.permits` snapshot.
 - `query_permit_find_account_id_for_role(deps, role)` — joins
   permit → actor → account, returns first match. Used by daemon token
   middleware to resolve the keeper account.
@@ -372,8 +432,9 @@ CRUD + listing:
   active permit at `scope_id` (role-agnostic) and supersedes every pending
   offer at `scope_id` (tuple-matched and orphan, undifferentiated) in the
   caller's transaction. Returns `RevokeForScopeResult = {revoked, superseded_offers}`
-  — `revoked` carries `account_id` for `permit_revoke` fan-out;
-  `superseded_offers` carries `from_account_id`. Caller emits
+  — `revoked` carries both `actor_id` (drives `target_actor_id` audit
+  envelopes) and `account_id` (drives `target_account_id` for socket-close
+  fan-out); `superseded_offers` carries `from_account_id`. Caller emits
   `permit_offer_supersede` audits with `reason: 'scope_destroyed'` and
   `cause_id: <destroyed scope row id>` per superseded offer (the cause is
   the scope deletion, not any individual permit revoke). Use from a
@@ -386,9 +447,12 @@ CRUD + listing:
 Error classes (all extend `Error` with stable `.name` — never use
 `instanceof` against plain messages):
 
-- `PermitOfferSelfTargetError` — grantor offered themselves. Enforced via
-  cross-row JOIN in `query_permit_offer_create` (rather than CHECK) to avoid
-  denormalized columns.
+- `PermitOfferSelfTargetError` — grantor offered themselves. Enforced
+  via a single SELECT on the grantor's `actor.account_id` in
+  `query_permit_offer_create` (resolving from the grantor side keeps
+  the check multi-actor-correct — the grantor → account binding stays
+  1:1 by definition of `actor`, while the recipient account may host
+  many actors under multi-actor).
 - `PermitOfferAlreadyTerminalError` — offer exists for the caller but is
   accepted / declined / retracted / superseded.
 - `PermitOfferExpiredError` — pending but past `expires_at` (distinct from
@@ -512,19 +576,24 @@ run'` if the seed somehow missed (defensive — migrations always seed).
 - `query_audit_log_list(deps, options?)` — supports `event_type`,
   `event_type_in`, `account_id` (matches `account_id` OR
   `target_account_id`), `outcome`, `since_seq`, `limit`, `offset`.
-- `query_audit_log_list_with_usernames` — joins twice to `account`.
+  `target_actor_id` filtering is not yet exposed; will land alongside
+  the admin-viewer's actor-grain forensics pass.
+- `query_audit_log_list_with_usernames` — joins twice to `account`
+  (chains `target_account_id` for the `target_username` field).
+  `target_actor_id` is on the row but not currently joined to actor
+  for a name; the admin viewer will resolve via `actor_lookup` /
+  `actor.name` when the actor-grain forensics pass lands.
 - `query_audit_log_list_for_account`, `query_audit_log_list_permit_history`
   (filters to `permit_grant` / `permit_revoke`).
 - `query_audit_log_cleanup_before`.
 - **`audit_log_fire_and_forget(route, input, deps)`** —
   writes to `route.background_db` (pool-level), so audit entries persist
-  even when the request transaction rolls back. `deps` is an
-  `AuditLogFireAndForgetDeps` bundle (`{log, on_audit_event, audit_log_config?}`)
-  — structurally compatible with `Pick<AppDeps, 'log' | 'on_audit_event' | 'audit_log_config'>`,
-  so call sites pass the surrounding deps object directly. Bundling
-  replaces the prior 5-arg positional signature; consumers that forgot
-  the trailing `config` would silently fall back to
-  `BUILTIN_AUDIT_LOG_CONFIG`. Write and `on_audit_event` callback
+  even when the request transaction rolls back. `deps` is the shared
+  `AuditEmitDeps` bundle (`{log, on_audit_event, audit_log_config?}`)
+  from `auth/deps.ts`, so call sites pass the surrounding deps object
+  directly. Bundling replaces the prior 5-arg positional signature;
+  consumers that forgot the trailing `config` would silently fall back
+  to `BUILTIN_AUDIT_LOG_CONFIG`. Write and `on_audit_event` callback
   failures are logged separately. Pushes onto `route.pending_effects`
   for test flushing.
 
@@ -563,11 +632,14 @@ by `sequence`, then enforces:
 3. **Run the pending tail** (`code[applied.length..]`) inside a single
    chain transaction; each `INSERT` uses `sequence = max(sequence) + 1`.
 
-**Append-only after first publish.** Once a fuz_app version containing a
-migration is published, the migration's name and position are frozen.
-Pre-publish, anything goes; the cliff is the publish event. Body edits to
-a published migration slip past the runner (no content hashing) — schema-
-snapshot tests in consumers catch these.
+**Schema is not stabilized yet — append-only is NOT the rule today.**
+While fuz_app is pre-stable, migration bodies, names, and positions can
+change freely between versions and consumers upgrading across a schema
+change are expected to drop and re-bootstrap their dev/test databases.
+Once the schema is declared stable, a hard append-only-after-publish rule
+will apply (with the cliff called out in that release's notes). Until
+then bias toward editing the existing migration entries rather than
+appending patch migrations.
 
 `MigrationError` is the only error class thrown from `run_migrations` /
 `baseline`; branch on `.kind` (never on message text). Kinds:
@@ -634,37 +706,109 @@ consciously violate the contract.
 
 ## Middleware
 
-Side of the chain ordering (concept-level — see the root `../../../CLAUDE.md`
-§Middleware Ordering for the canonical assembly order):
-
-**Session parsing is separate from auth enforcement.** The session /
-request-context middleware populates `{account, actor, permits}` from a
-cookie but does not 401; `require_auth` / `require_role` / `require_keeper`
-enforce. This lets `/login` and `/bootstrap` participate in cookie refresh
-without being blocked.
+See the root `../../../CLAUDE.md` §Middleware Ordering for the canonical
+assembly order. Two-phase identity:
+
+- **Authentication** runs in middleware (session / bearer / daemon
+  token). Sets `c.var.account_id` + `CREDENTIAL_TYPE_KEY` on a valid
+  credential. Account-only — never loads actor or permits, never
+  populates `REQUEST_CONTEXT_KEY`. **Production-middleware invariant**:
+  no production middleware on the auth path (session / bearer / daemon
+  token) populates `REQUEST_CONTEXT_KEY`; identity-related context vars
+  it does set are `ACCOUNT_ID_KEY`, `CREDENTIAL_TYPE_KEY`, and (for
+  sessions / bearer) `AUTH_SESSION_TOKEN_HASH_KEY` /
+  `AUTH_API_TOKEN_ID_KEY`. Other middleware (proxy, app server,
+  session-cookie parser) sets unrelated vars like `client_ip`,
+  `pending_effects`, and the session-token slot keyed by
+  `session_options.context_key` (default `auth_session_id`) — those
+  are out of scope for this invariant. Test harnesses pre-populate
+  `REQUEST_CONTEXT_KEY` + `TEST_CONTEXT_PRESET_KEY` to bypass DB-backed
+  actor resolution; production code that consults
+  `REQUEST_CONTEXT_KEY` is reading test escape-hatch state, never live
+  middleware output.
+- **Authorization** runs in the route-spec wrapper / RPC dispatcher
+  before input validation (matches the RPC dispatcher's order so 401 /
+  403 surface ahead of `invalid_params`). When the route's input
+  declares `acting?: ActingActor` or its auth requires permits
+  (`role` / `keeper`), the authorization phase calls
+  `resolve_acting_actor` over the raw `acting` value extracted from
+  query (GET) or pre-parsed body (mutating methods), builds the
+  actor-bound `RequestContext`, and sets `REQUEST_CONTEXT_KEY` before
+  the role / keeper guards fire. Account-grain routes skip resolution
+  and run with `RequestContext.actor: null`. Resolution failures come
+  back as `AuthorizationFailure` (`{status, body}`) — the auth domain
+  stops short of constructing a `Response` so each transport binds the
+  same failure to its wire shape: REST emits `c.json(body, status)`;
+  the WS upgrade does the same; the RPC dispatcher folds it into a
+  JSON-RPC envelope (`{jsonrpc, id, error: {code, message, data}}`)
+  with `error.message` carrying the reason string and
+  `error.data: {reason, ...rest}` flattening any diagnostic fields
+  (e.g. `available[]` for `actor_required`). The two 500 reasons the
+  phase emits are kept distinct: `no_actors_on_account` names a signup
+  invariant violation (`resolve_acting_actor` enumerated zero actors);
+  `account_vanished` names a torn-read race (`build_request_context` /
+  `build_account_context` returned null after a successful resolve —
+  the account or actor row was deleted between credential validation
+  and the dispatcher's follow-up read). See the root
+  `../../../CLAUDE.md` § Cleanest architecture takes priority for the
+  rationale.
+
+Session parsing is separate from auth enforcement — login / bootstrap
+participate in cookie refresh without being blocked. `require_auth` /
+`require_role` / `require_keeper` are the gates.
 
 ### `request_context.ts`
 
-- `RequestContext = {account, actor, permits}`.
+- `RequestContext = {account, actor: Actor | null, permits}`. `actor`
+  is null on account-grain routes (no `acting`, no permit-requiring
+  auth); `permits` is empty in that case.
 - `REQUEST_CONTEXT_KEY` — Hono context variable name.
 - **`AUTH_SESSION_TOKEN_HASH_KEY`** — holds the blake3 session hash. Set on
   successful session lookup; `null` for unauthenticated or non-session
   credentials. Exposed so SSE endpoints can scope per-session resource
   identity (the audit-log SSE uses this to close only the revoked session's
   stream on `session_revoke`).
-- `get_request_context(c)`, `require_request_context(c)` (throws on misuse
-  — misconfigured middleware surfaces immediately), `has_role(ctx, role, now?)`.
-- `build_request_context(deps, account_id)` — shared helper used by
-  session, bearer, and daemon token middleware; does
-  `account → actor → permits` and returns `null` if either lookup misses.
+- `get_request_context(c)`, `require_request_context(c)` (throws on
+  misuse — handler ran without authorization phase wiring).
+- **In-memory permit predicates** — `has_role(ctx, role, now?)`,
+  `has_scoped_role(ctx, role, scope_id, now?)`,
+  `has_any_scoped_role(ctx, roles, scope_id, now?)`. All three take
+  `RequestContext | null` and return `false` for null ctx and for
+  account-grain ctx (`actor: null`, empty `permits`); they drop into
+  `auth: 'public'` and account-grain handlers without a manual narrow.
+  `scope_id === null` matches global permits only; UUID matches that
+  exact scope. Empty `roles` short-circuits `has_any_scoped_role` to
+  `false`. Decide-time predicates only — the predicate / mutation
+  race window is the same as the SQL `query_permit_has_role` style and
+  only a transactional re-check inside the UPDATE/INSERT closes it.
+- `build_request_context(deps, account_id, actor_id)` — loads
+  `account` + the named `actor` + active permits. Verifies
+  `actor.account_id === account.id`; returns `null` when the account
+  or actor is missing, or when they don't bind to each other. Called
+  by the authorization phase after `resolve_acting_actor` succeeds —
+  a null return there is a torn read (account/actor deleted mid-request)
+  rather than the missing-actor invariant `resolve_acting_actor` would
+  have caught upstream, so the phase surfaces `ERROR_ACCOUNT_VANISHED`
+  on null. Not called from middleware.
+- `resolve_acting_actor(deps, account_id, acting_actor_id)` — uniform
+  resolver. Resolves to `{ok: true, actor_id}` for 1 actor (any
+  `acting`) or matching supplied id; `actor_required` with the
+  available list when multi-actor and `acting` is missing;
+  `actor_not_on_account` when supplied id doesn't belong; `no_actors`
+  defensively.
 - `refresh_permits(ctx, deps)` — reloads permits without mutating the
-  original (concurrent-safe). Useful for long-lived WebSocket connections.
+  original (concurrent-safe). Useful for long-lived WebSocket
+  connections that have an acting actor.
 - `create_request_context_middleware(deps, log, session_context_key?)` —
-  reads session token from context, hashes, validates, loads context, sets
-  `CREDENTIAL_TYPE_KEY = 'session'`, fires `session_touch_fire_and_forget`.
-- `require_auth` — 401 (`ERROR_AUTHENTICATION_REQUIRED`) on no context.
-- `require_role(role)` — 401 on no context, 403 (`ERROR_INSUFFICIENT_PERMISSIONS`
-  - `required_role`) on missing role.
+  validates the session and sets `c.var.account_id` +
+  `CREDENTIAL_TYPE_KEY = 'session'` + `AUTH_SESSION_TOKEN_HASH_KEY`.
+  Touches the session fire-and-forget. Does not load actor / permits.
+- `require_auth` — 401 (`ERROR_AUTHENTICATION_REQUIRED`) when
+  `account_id` is null. Does not require an acting actor.
+- `require_role(role)` — 401 on no auth, 403
+  (`ERROR_INSUFFICIENT_PERMISSIONS` + `required_role`) when permits
+  don't carry the role. Implies the authorization phase ran (a
+  role-gated route always resolves an actor).
 
 ### `bearer_auth.ts`
 
@@ -938,7 +1082,7 @@ Closure state:
 `all_admin_action_specs: Array<RequestResponseActionSpec>` — codegen-ready
 registry of all eleven specs (always includes the two app-settings specs).
 
-Deps: `AdminActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'>`. The `audit_log_config` slot flows through to `audit_log_fire_and_forget` so consumer-extended event-type metadata gets validated.
+Deps: `AdminActionDeps = AuditEmitDeps` — the shared `Pick<AppDeps, 'log' | 'on_audit_event' | 'audit_log_config'>` slice every audit-emitting site picks (defined in `auth/deps.ts`). The `audit_log_config` slot flows through to `audit_log_fire_and_forget` so consumer-extended event-type metadata gets validated.
 
 ### `permit_offer_action_specs.ts` + `permit_offer_actions.ts` — seven RPC actions
 
@@ -973,15 +1117,19 @@ Six offer-lifecycle methods plus `permit_revoke`. Authorization is a mix:
   **`actor_id`, not `account_id`** — permits are actor-scoped and deriving
   actor from account collapses under multi-actor accounts.
 
-| Spec                               | Input                                        | Output                                     |
-| ---------------------------------- | -------------------------------------------- | ------------------------------------------ |
-| `permit_offer_create_action_spec`  | `{to_account_id, role, scope_id?, message?}` | `{offer}`                                  |
-| `permit_offer_accept_action_spec`  | `{offer_id}`                                 | `{permit_id, offer, superseded_offer_ids}` |
-| `permit_offer_decline_action_spec` | `{offer_id, reason?}`                        | `{ok}`                                     |
-| `permit_offer_retract_action_spec` | `{offer_id}`                                 | `{ok}`                                     |
-| `permit_offer_list_action_spec`    | `{account_id?}`                              | `{offers}`                                 |
-| `permit_offer_history_action_spec` | `{account_id?, limit?, offset?}`             | `{offers}`                                 |
-| `permit_revoke_action_spec`        | `{actor_id, permit_id, reason?}`             | `{ok, revoked}`                            |
+Every input row below also carries the shared `acting?: ActingActor`
+field that the dispatcher's authorization phase reads off the raw
+params (omitted from the table for brevity).
+
+| Spec                               | Input                                                      | Output                                     |
+| ---------------------------------- | ---------------------------------------------------------- | ------------------------------------------ |
+| `permit_offer_create_action_spec`  | `{to_account_id, to_actor_id?, role, scope_id?, message?}` | `{offer}`                                  |
+| `permit_offer_accept_action_spec`  | `{offer_id}`                                               | `{permit_id, offer, superseded_offer_ids}` |
+| `permit_offer_decline_action_spec` | `{offer_id, reason?}`                                      | `{ok}`                                     |
+| `permit_offer_retract_action_spec` | `{offer_id}`                                               | `{ok}`                                     |
+| `permit_offer_list_action_spec`    | `{account_id?}`                                            | `{offers}`                                 |
+| `permit_offer_history_action_spec` | `{account_id?, limit?, offset?}`                           | `{offers}`                                 |
+| `permit_revoke_action_spec`        | `{actor_id, permit_id, reason?}`                           | `{ok, revoked}`                            |
 
 Error reason constants (exported as `as const` literals):
 
@@ -991,6 +1139,11 @@ Error reason constants (exported as `as const` literals):
 - `ERROR_OFFER_NOT_FOUND` (`'offer_not_found'` — 404-over-403 IDOR mask)
 - `ERROR_OFFER_ROLE_NOT_GRANTABLE` (`'offer_role_not_grantable'`)
 - `ERROR_OFFER_NOT_AUTHORIZED` (`'offer_not_authorized'`)
+- `ERROR_OFFER_ACTOR_ACCOUNT_MISMATCH` (`'offer_actor_account_mismatch'` —
+  `permit_offer_create` was called with a `to_actor_id` that does not
+  belong to `to_account_id`)
+- `ERROR_OFFER_ACTOR_MISMATCH` (`'offer_actor_mismatch'` —
+  actor-targeted offer was accepted by an actor other than `to_actor_id`)
 
 Plus re-uses from `../http/error_schemas.ts`: `ERROR_PERMIT_NOT_FOUND`,
 `ERROR_ROLE_NOT_WEB_GRANTABLE`, `ERROR_INSUFFICIENT_PERMISSIONS`,
@@ -1007,11 +1160,18 @@ Failure-outcome audit events emitted (success and failure rows both carry
 `ip: ctx.client_ip` — uniform with the admin and self-service surfaces):
 
 - `permit_offer_create` failure — `web_grantable` denial, `authorize`
-  denial, self-target rejection (all three denial paths emit the same
-  audit row with `target_account_id`).
+  denial, self-target rejection, and actor-account mismatch all emit
+  the same audit row via `emit_create_failure_audit`. `target_account_id`
+  carries `input.to_account_id`; `target_actor_id` echoes
+  `input.to_actor_id` when supplied so failure rows match the
+  success-shape envelope of actor-targeted offers (null on
+  account-grain offers — see audit_log_schema rule).
 - `permit_revoke` failure — `web_grantable` denial after IDOR / role
   lookup succeeded. The admin-role-denied path (pre-IDOR) emits no audit,
-  matching the middleware auth-guard precedent.
+  matching the middleware auth-guard precedent. `target_account_id` +
+  `target_actor_id` both populated (the IDOR-passing branch resolves
+  the target actor before the gate; the subject is an actor-bound
+  permit).
 
 WS notifications (post-commit via `emit_after_commit` from
 `../http/pending_effects.js` — swallows exceptions so one failed send
@@ -1025,7 +1185,7 @@ can't starve others; see `../http/CLAUDE.md` §Pending Effects):
 - Revoke → `permit_revoke` to revokee + one `permit_offer_supersede` per
   superseded sibling.
 
-Deps: `PermitOfferActionDeps extends Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'> & {notification_sender?: NotificationSender | null}`.
+Deps: `PermitOfferActionDeps extends AuditEmitDeps & {notification_sender?: NotificationSender | null}`.
 Notification sender is optional — when absent, WS fan-out is silently
 skipped (DB-only side effects still happen).
 
@@ -1128,7 +1288,7 @@ Audit events emitted (via `audit_log_fire_and_forget` with `ip: ctx.client_ip`):
 IP is the resolved trusted-proxy value from `ActionContext.client_ip`,
 matching the REST handler convention.
 
-Deps: `AccountActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'>`.
+Deps: `AccountActionDeps = AuditEmitDeps`.
 Options: `{max_tokens?: number | null}` — defaults to `DEFAULT_MAX_TOKENS`
 from `account_routes.ts`; `null` disables the cap.
 
@@ -1172,16 +1332,17 @@ codegen invariant and grow the surface linearly per role.
   `eligible_roles` is checked against `roles.role_options` at factory
   time so typos throw at startup instead of at first call.
 
-Grant branch uses `query_permit_has_role` for a benign-TOCTOU pre-check
-(distinguishes new grant from idempotent re-grant), then
-`query_grant_permit` for the actual insert. Revoke branch filters
+Grant branch uses `has_scoped_role(auth, role, null)` for a
+benign-TOCTOU pre-check (distinguishes new grant from idempotent
+re-grant) — reads from the in-memory `auth.permits` snapshot, no DB
+roundtrip — then `query_grant_permit` for the actual insert. Revoke branch filters
 `query_permit_find_active_for_actor` in JS for the matching
 `(actor, role, scope_id IS NULL)` row before calling
 `query_revoke_permit`. Bundle is **not** included in
 `create_standard_rpc_actions` — `eligible_roles` is app-specific, opt-in,
 spread alongside the standard bundle when needed.
 
-Deps: `SelfServiceRoleActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'>`.
+Deps: `SelfServiceRoleActionDeps = AuditEmitDeps`.
 
 `all_self_service_role_action_specs: ReadonlyArray<RequestResponseActionSpec>` —
 codegen-ready registry of the single unified spec.
@@ -1231,6 +1392,12 @@ resulting permit.
 - **`RouteFactoryDeps = Omit<AppDeps, 'db'>`** — for route factories. Route
   handlers receive DB access via `RouteContext`, so factories don't capture
   a pool-level `Db`.
+- **`AuditEmitDeps = Pick<AppDeps, 'log' | 'on_audit_event' | 'audit_log_config'>`**
+  — the slice every audit-emitting site needs. Used by `audit_log_fire_and_forget`
+  / `emit_permit_target_event` (the primitives) and aliased by every
+  action-factory deps type (`AdminActionDeps`, `AccountActionDeps`,
+  `PermitOfferActionDeps`, `SelfServiceRoleActionDeps`) so the five
+  factories stop spelling the same `Pick` independently.
 
 See root `../../../CLAUDE.md` §AppDeps Vocabulary for the
 capability / options / runtime-state split across the whole project.

package/dist/auth/account_actions.d.ts

@@ -22,7 +22,7 @@
  * @module
  */
 import { type RpcAction } from '../actions/action_rpc.js';
-import type { RouteFactoryDeps } from './deps.js';
+import type { AuditEmitDeps } from './deps.js';
 /** Options for `create_account_actions`. */
 export interface AccountActionOptions {
     /**
@@ -36,12 +36,12 @@ export interface AccountActionOptions {
 /**
  * Dependencies for `create_account_actions`.
  *
- * Shares shape with `AdminActionDeps` / `PermitOfferActionDeps` so consumers
- * can pass the same deps to every action factory. `audit_log_config` is
- * carried through `AppDeps` and consumed by `audit_log_fire_and_forget`;
- * absent → defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
+ * Aliases the shared `AuditEmitDeps` (the `log` / `on_audit_event` /
+ * optional `audit_log_config` slice every audit-emitting site picks).
+ * `audit_log_config` is consumed by `audit_log_fire_and_forget`; absent →
+ * defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
  */
-export type AccountActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'>;
+export type AccountActionDeps = AuditEmitDeps;
 /**
  * Create the self-service account RPC actions.
  *

package/dist/auth/account_actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAgBxF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAwBhD,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CACnC,gBAAgB,EAChB,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,iBAAiB,EACvB,UAAS,oBAAyB,KAChC,KAAK,CAAC,SAAS,CAyHjB,CAAC"}
+{"version":3,"file":"account_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAgBxF,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,WAAW,CAAC;AAyB7C,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,iBAAiB,EACvB,UAAS,oBAAyB,KAChC,KAAK,CAAC,SAAS,CAqHjB,CAAC"}

package/dist/auth/account_actions.js

@@ -28,6 +28,7 @@ import { query_api_token_enforce_limit, query_api_token_list_for_account, query_
 import { generate_api_token } from './api_token.js';
 import { audit_log_fire_and_forget } from './audit_log_queries.js';
 import { DEFAULT_MAX_TOKENS } from './account_routes.js';
+import { require_request_auth } from './request_context.js';
 import { account_verify_action_spec, account_session_list_action_spec, account_session_revoke_action_spec, account_session_revoke_all_action_spec, account_token_create_action_spec, account_token_list_action_spec, account_token_revoke_action_spec, } from './account_action_specs.js';
 /**
  * Create the self-service account RPC actions.
@@ -39,21 +40,20 @@ import { account_verify_action_spec, account_session_list_action_spec, account_s
 export const create_account_actions = (deps, options = {}) => {
     const { max_tokens = DEFAULT_MAX_TOKENS } = options;
     const verify_handler = (_input, ctx) => {
-        const auth = ctx.auth;
+        const auth = require_request_auth(ctx.auth);
         return to_session_account(auth.account);
     };
     const session_list_handler = async (_input, ctx) => {
-        const auth = ctx.auth;
+        const auth = require_request_auth(ctx.auth);
         const sessions = await query_session_list_for_account(ctx, auth.account.id);
         return { sessions };
     };
     const session_revoke_handler = async (input, ctx) => {
-        const auth = ctx.auth;
+        const auth = require_request_auth(ctx.auth);
         const revoked = await query_session_revoke_for_account(ctx, input.session_id, auth.account.id);
         void audit_log_fire_and_forget(ctx, {
             event_type: 'session_revoke',
             outcome: revoked ? 'success' : 'failure',
-            actor_id: auth.actor.id,
             account_id: auth.account.id,
             ip: ctx.client_ip,
             metadata: { session_id: input.session_id },
@@ -61,11 +61,10 @@ export const create_account_actions = (deps, options = {}) => {
         return { ok: true, revoked };
     };
     const session_revoke_all_handler = async (_input, ctx) => {
-        const auth = ctx.auth;
+        const auth = require_request_auth(ctx.auth);
         const count = await query_session_revoke_all_for_account(ctx, auth.account.id);
         void audit_log_fire_and_forget(ctx, {
             event_type: 'session_revoke_all',
-            actor_id: auth.actor.id,
             account_id: auth.account.id,
             ip: ctx.client_ip,
             metadata: { count },
@@ -73,7 +72,7 @@ export const create_account_actions = (deps, options = {}) => {
         return { ok: true, count };
     };
     const token_create_handler = async (input, ctx) => {
-        const auth = ctx.auth;
+        const auth = require_request_auth(ctx.auth);
         const { token, id, token_hash } = generate_api_token();
         await query_create_api_token(ctx, id, auth.account.id, input.name, token_hash);
         if (max_tokens != null) {
@@ -81,7 +80,6 @@ export const create_account_actions = (deps, options = {}) => {
         }
         void audit_log_fire_and_forget(ctx, {
             event_type: 'token_create',
-            actor_id: auth.actor.id,
             account_id: auth.account.id,
             ip: ctx.client_ip,
             metadata: { token_id: id, name: input.name },
@@ -89,17 +87,16 @@ export const create_account_actions = (deps, options = {}) => {
         return { ok: true, token, id, name: input.name };
     };
     const token_list_handler = async (_input, ctx) => {
-        const auth = ctx.auth;
+        const auth = require_request_auth(ctx.auth);
         const tokens = await query_api_token_list_for_account(ctx, auth.account.id);
         return { tokens };
     };
     const token_revoke_handler = async (input, ctx) => {
-        const auth = ctx.auth;
+        const auth = require_request_auth(ctx.auth);
         const revoked = await query_revoke_api_token_for_account(ctx, input.token_id, auth.account.id);
         void audit_log_fire_and_forget(ctx, {
             event_type: 'token_revoke',
             outcome: revoked ? 'success' : 'failure',
-            actor_id: auth.actor.id,
             account_id: auth.account.id,
             ip: ctx.client_ip,
             metadata: { token_id: input.token_id },

package/dist/auth/account_queries.d.ts

@@ -68,11 +68,14 @@ export declare const query_account_has_any: (deps: QueryDeps) => Promise<boolean
  */
 export declare const query_create_actor: (deps: QueryDeps, account_id: string, name: string) => Promise<Actor>;
 /**
- * Find the actor for an account.
+ * List every actor on an account, ordered by `created_at`.
  *
- * For v1, each account has exactly one actor.
+ * Used by `resolve_acting_actor` to resolve the acting actor for a
+ * request: 1 actor picks transparently, multiple require an explicit
+ * `acting` field on the request payload. For lookups by id, use
+ * `query_actor_by_id` instead.
  */
-export declare const query_actor_by_account: (deps: QueryDeps, account_id: string) => Promise<Actor | undefined>;
+export declare const query_actors_by_account: (deps: QueryDeps, account_id: string) => Promise<Array<Actor>>;
 /**
  * Find an actor by id.
  */

package/dist/auth/account_queries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAEN,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,GAAG,SAAS,CAE7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAS7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,eAAe,MAAM,EACrB,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC,IAAI,CAKd,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,OAAO,CAAC,OAAO,CAKvF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,OAAO,CAK5E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,MAAM,MAAM,KACV,OAAO,CAAC,KAAK,CAMf,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,GAAG,SAAS,CAE3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,KAAK,GAAG,SAAS,CAE3B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAC,CAI1C,CAAC;AAyBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CA+EtC,CAAC"}
+{"version":3,"file":"account_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAEN,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,GAAG,SAAS,CAE7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAS7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,eAAe,MAAM,EACrB,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC,IAAI,CAKd,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,OAAO,CAAC,OAAO,CAKvF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,OAAO,CAK5E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,MAAM,MAAM,KACV,OAAO,CAAC,KAAK,CAMf,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAKtB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,KAAK,GAAG,SAAS,CAE3B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAC,CAI1C,CAAC;AAyBF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAqFtC,CAAC"}

package/dist/auth/account_queries.js

@@ -101,12 +101,15 @@ export const query_create_actor = async (deps, account_id, name) => {
     return assert_row(row, 'INSERT INTO actor');
 };
 /**
- * Find the actor for an account.
+ * List every actor on an account, ordered by `created_at`.
  *
- * For v1, each account has exactly one actor.
+ * Used by `resolve_acting_actor` to resolve the acting actor for a
+ * request: 1 actor picks transparently, multiple require an explicit
+ * `acting` field on the request payload. For lookups by id, use
+ * `query_actor_by_id` instead.
  */
-export const query_actor_by_account = async (deps, account_id) => {
-    return deps.db.query_one(`SELECT * FROM actor WHERE account_id = $1`, [account_id]);
+export const query_actors_by_account = async (deps, account_id) => {
+    return deps.db.query(`SELECT * FROM actor WHERE account_id = $1 ORDER BY created_at ASC, id ASC`, [account_id]);
 };
 /**
  * Find an actor by id.
@@ -161,7 +164,13 @@ export const query_admin_account_list = async (deps) => {
 			   AND po.expires_at > NOW()
 			 ORDER BY po.expires_at ASC`),
     ]);
-    // Index actors by account_id (1:1 in v1)
+    // Index actors by account_id. Multi-actor TODO: this Map keyed by
+    // account_id silently overwrites earlier actors when an account
+    // hosts more than one — when multi-actor lands, the admin row shape
+    // must change from "account → one actor" to "account → Array<Actor>"
+    // (or split into a separate per-actor row). The JSON shape change
+    // will ripple into the admin UI; bundle that with the multi-actor
+    // session-actor-selector work.
     const actor_by_account = new Map();
     for (const actor of actors) {
         actor_by_account.set(actor.account_id, actor);