@fuzdev/fuz_app 0.117.1 → 0.119.0

package/dist/auth/CLAUDE.md

@@ -16,9 +16,9 @@ documents the cross-cutting invariants that don't fit on any single symbol.
 
 ## AppDeps split
 
-- **Capabilities** — `AppDeps` — stateless, injectable per env: `read_secure_file` (hardened bootstrap-token read), `delete_file`, `keyring`, `password`, `db`, `log`, `audit`.
+- **Capabilities** — `AppDeps` — stateless, injectable per env: `read_secure_file` (hardened bootstrap-token read), `delete_file`, `keyring`, `password`, `db`, `log`, `audit`, `connection_closer` (the `RealtimeCloser` every revocation handler closes live connections through — `actions/CLAUDE.md` §Connection closer).
 - **Route caps** — `RouteFactoryDeps` — `Omit<AppDeps, 'db'>`; handlers get `db` via `RouteContext`.
-- **Action caps** — `ActionFactoryDeps` (`auth/deps.ts`) — the `{log, audit}` shape action factories take; `RouteFactoryDeps`/`AppDeps` satisfy it structurally (role-grant-offer adds `notification_sender?`). The two pure-read actor factories (`actor_lookup`/`actor_search`) take only `{log: Logger}`.
+- **Action caps** — `ActionFactoryDeps` (`auth/deps.ts`) — the `{log, audit}` shape action factories take; `RouteFactoryDeps`/`AppDeps` satisfy it structurally (role-grant-offer adds `notification_sender?`). The factories whose handlers end credentials (`create_account_actions`, `create_admin_actions`, and the standard bundle) take `RevokingActionFactoryDeps` — `ActionFactoryDeps` plus a required `connection_closer`. The two pure-read actor factories (`actor_lookup`/`actor_search`) take only `{log: Logger}`.
 - **Parameters** — `*Options` — static startup values, per-factory.
 - **Runtime state** — inline ref — mutable values: `bootstrap_status`, `DaemonTokenState`. NOT in deps or options.
 
@@ -56,7 +56,7 @@ Cross-cutting notes that don't live on any single symbol:
 
 Convention — `*_schema.ts` is Zod-only; `*_ddl.ts` holds DDL strings.
 
-- `auth/account_schema.ts` — `Account`, `Actor`, `RoleGrant`, `AuthSession`, `ApiToken` + client-safe JSON shapes.
+- `auth/account_schema.ts` — `Account`, `Actor`, `RoleGrant`, `AuthSession`, `ApiToken` + client-safe JSON shapes. Grant predicates over wire fields: `is_role_grant_active` (not revoked, not expired) and `has_global_role(role_grants, role, now?)` (an active grant of the role with `scope_id === null` — the bare-list form of `has_scoped_role(ctx, role, null)`, used client-side by `AuthState`).
 - `auth/role_schema.ts` — `RoleName`, `RoleSpec`, `ROLE_KEEPER`, `ROLE_ADMIN`, `is_builtin_role`, `create_role_schema`, `builtin_role_specs_by_name`, `role_has_grant_path`, `list_roles_with_grant_path`.
 - `auth/scope_kind_schema.ts` — `ScopeKindName`, `create_scope_kind_schema` (open registry, no builtins).
 - `auth/credential_type_schema.ts` — `CredentialTypeName`, `CREDENTIAL_TYPE_SESSION` / `_API_TOKEN` / `_DAEMON_TOKEN`, `create_credential_type_schema`.
@@ -81,8 +81,8 @@ All take `deps: QueryDeps = {db}` first; `query_validate_api_token` adds `log`.
 - `auth/actor_search_queries.ts` — case-insensitive prefix search on `actor.name`, scope-filtered when not admin.
 - `auth/role_grant_queries.ts` — idempotent create, IDOR-guarded revoke (with in-tx supersede), scope-aware lookup, role/account predicates, `query_role_grant_revoke_for_scope` parent-scope cascade.
 - `auth/role_grant_offer_queries.ts` — offer create/decline/retract/list/history/sweep, atomic `query_accept_offer` with sibling supersede; error classes `RoleGrantOfferSelfTargetError` / `_AlreadyTerminalError` / `_ExpiredError` / `_NotFoundError` / `_ActorAccountMismatchError` / `_ActorMismatchError`.
-- `auth/session_queries.ts` — server-side sessions (blake3-hashed), `query_session_revoke_by_hash_unscoped` (logout only), `query_session_enforce_limit` (transaction-required). No touch/renewal query — `expires_at` is an absolute cap set at mint (`AUTH_SESSION_LIFETIME_MS`).
-- `auth/api_token_queries.ts` — token validation with fire-and-forget usage tracking, IDOR-guarded revoke, `query_api_token_enforce_limit` (transaction-required).
+- `auth/session_queries.ts` — server-side sessions (blake3-hashed), `query_session_revoke_by_hash_unscoped` (logout only), `query_session_enforce_limit` (transaction-required; returns the evicted sessions' ids — their token hashes — so the caller closes their connections after the commit), `query_session_cleanup_expired` (returns the swept sessions' ids for the same close — `cleanup_expired_sessions` is its caller). No touch/renewal query — `expires_at` is an absolute cap set at mint (`AUTH_SESSION_LIFETIME_MS`).
+- `auth/api_token_queries.ts` — token validation with fire-and-forget usage tracking, `query_api_token_live_account` (the by-id, no-touch re-check read; shares the `API_TOKEN_IS_LIVE` predicate with the validate query so the two can't drift), IDOR-guarded revoke, `query_api_token_enforce_limit` (transaction-required; returns the evicted tokens' ids for the same post-commit close).
 - `auth/invite_queries.ts` — invite create/find/claim/list/delete; `query_invite_claim_unscoped` (scoping enforced upstream by `_find_unclaimed_match_for_update`, which runs inside the signup tx with `FOR UPDATE` so find + claim are atomic).
 - `auth/app_settings_queries.ts` — load/update for the single-row settings table.
 - `auth/audit_log_queries.ts` — `query_audit_log` (in-tx insert), `_list` / `_list_with_usernames` / `_list_role_grant_history` / `_cleanup_before`, drift counters (`get_audit_metadata_validation_failures` / `get_audit_unknown_event_type_failures`).
@@ -123,20 +123,43 @@ upstream in `auth/signup_routes.ts` via `query_invite_find_unclaimed_match_for_u
 `audit_factory` callback over `create_audit_emitter`; closes over the pool +
 its registered listeners + optional `AuditLogConfig`. Six methods:
 
-- `emit(ctx, input)` — fire-and-forget pool write, pushes to `ctx.pending_effects`
+- `emit(ctx, input)` — fire-and-forget pool write, pushes to `ctx.pending_effects`; a success row's listener fan-out goes on `ctx.post_commit_effects`
 - `emit_role_grant_target(ctx, auth, input)` — lifts `actor_id` / `account_id` / `ip` boilerplate for role-grant-shape events
-- `emit_pool(input)` — awaitable pool write for code paths without `pending_effects` (cleanup sweeps)
+- `emit_pool(input)` — awaitable pool write for code paths without a request context (ad-hoc maintenance scripts; not for success audits paired with a mutation — those write in-tx and `notify` post-commit). Writes, then notifies, whatever the outcome
 - `notify(event)` — fan out an already-written row to listeners (used by in-tx audit batches like `query_accept_offer.audit_events`)
 - `add_listener(listener)` — append-only listener registration (twin of Rust `fuz_auth` `AuditEmitter::add_listener`)
 - `listener_count()` — registered-listener count, for tests / diagnostics
 
 Listeners are closure-private and append-only. `create_app_server` registers
-the audit-log SSE listener and per-endpoint WS auth guards / logout closers via
+the audit-log SSE listener and per-endpoint WS auth guards via
 `add_listener` so SSE + WS fan-out compose on top of the consumer's
 `on_audit_event` callback without shallow-copying `AppDeps`. `notify` iterates a
 snapshot so a listener registered mid-fan-out fires only on the next event
 (converges with the Rust twin's cloned vec).
 
+**When listeners hear about a row.** `emit` always writes at once, on the pool
+(the row survives a rollback). The fan-out depends on the outcome: a
+**failure** row is announced as soon as it is written — the attempt happened
+whatever the transaction does; a **success** row is announced only after the
+request's transaction commits (a thunk on `ctx.post_commit_effects` that awaits
+the write) and never when the handler throws. The listeners act on a success
+row — the revocation guards close connections, the audit stream broadcasts it
+— so announcing one before its commit would close while the revoked credential
+still reads as valid, and a rolled-back revocation would close anyway. The
+Rust spine gets the same order by writing a success row in the transaction and
+queueing its fan-out behind the commit. `AuditEmitterContext` is therefore
+`{pending_effects, post_commit_effects}` — `RouteContext` and `ActionContext`
+both satisfy it.
+
+**Revocation scopes** (`auth/audit_log_schema.ts`) —
+`audit_event_revocation_scopes` declares, per builtin event type, what a
+successful row invalidates (`RevocationScope`: `none` / `session` / `token` /
+`account` / `role`), and `to_revocation_scope(event_type)` reads it (an unknown
+event type is `none`). Typed over `AuditEventType`, so a new event type does not
+compile until it declares its scope. Both revocation listeners
+(`create_ws_auth_guard`, `create_sse_auth_guard`) dispatch on it. Twin of the
+`revocation_scope` column on the Rust `AUDIT_EVENT_SPECS`.
+
 **Drift counters** (`auth/audit_log_queries.ts`) — `audit_metadata_validation_failures`
 and `audit_unknown_event_type_failures` are process-wide, fail-open
 (write the row anyway). Independent in implementation; under the factory
@@ -147,7 +170,7 @@ they track the same config. Sample via `get_*`; `reset_*` are test-only.
 - `auth/account_routes.ts` — `POST /login` / `/logout` / `/password`, `GET /verify` (nginx `auth_request` shim), `GET /api/account/status`. Constants: `DEFAULT_MAX_SESSIONS = 5`, `DEFAULT_MAX_TOKENS = 10`, `DEFAULT_LOGIN_FAIL_FLOOR_MS = 250`, `DEFAULT_LOGIN_FAIL_JITTER_MS = 25`.
 - `auth/bootstrap_routes.ts` — `POST /bootstrap` + `check_bootstrap_status`; `BootstrapStatus` runtime ref.
 - `auth/signup_routes.ts` — `POST /signup` (open or invite-gated).
-- `auth/audit_log_routes.ts` — optional `GET /audit/stream` (SSE); list/history are on the RPC surface.
+- `auth/audit_log_routes.ts` — optional `GET /audit/stream` (SSE); list/history are on the RPC surface. Takes `stream: {registry, log}` (an `AuditLogSse` satisfies it). The handler admits the stream in two phases — register pending on the `SubscriberRegistry`, re-read the credential (`revalidate_resolved_auth`) and the acting actor's role grants, admit — so a revocation racing the request opens no stream: 401 / 403 from the re-reads, or a 200 whose body is the connect comment alone when the pending registration was closed.
 - `auth/auth_guard_resolver.ts` — `fuz_auth_guard_resolver` injected into `apply_route_specs` so the framework stays auth-agnostic. Maps each `RouteAuth` axis to a guard and is the single site every route spec traverses, so it also carries the two invariants the schema can't (a `required_scope` that isn't a well-formed capability, and one on an unrestricted route).
 
 **Hono-free route shapes.** Each cookie/SSE-coupled route module has a sibling
@@ -176,6 +199,12 @@ tokens (force re-auth everywhere), then clears the session cookie. Declares
 `credential_types: ['session']` (see ../../../docs/security.md
 §Credential-channel gating).
 
+**The routes close what they revoke, after the commit.** `/logout` and
+`/password` queue an account-wide close, and `/login` queues a session close
+for each session its cap evicted (`queue_connection_close` on
+`deps.connection_closer`). The queue runs once the route's transaction has
+committed and is dropped if the handler throws.
+
 REST-only post RPC migration: `/login`, `/logout`, `/password`, `/signup`,
 `/bootstrap`, `/verify` (empty-body shim), optional `/audit/stream`.
 Everything else listed under §RPC action surfaces.
@@ -184,7 +213,8 @@ Everything else listed under §RPC action surfaces.
 
 - `auth/middleware.ts` — `create_auth_middleware_specs(deps, options)` assembles `[origin, session, request_context, bearer_auth]` + optional `daemon_token`.
 - `auth/request_context.ts` — `RequestContext`, `resolve_acting_actor`, `build_request_context`, predicates (`has_role`, `has_scoped_role`, `has_any_scoped_role` — the dispatcher's role gate and every builtin-role check read the **global** grant via `has_scoped_role(_, role, null)` / `has_any_scoped_role(_, roles, null)`; scope-blind `has_role` is never the gate for a builtin role), guards (`require_auth`, `require_role`, `require_credential_types`, `require_token_scope`), `token_scope_surface_denial` (the direct-call form, for surfaces that aren't route specs), `refresh_role_grants`.
-- `auth/session_middleware.ts` — `process_session_cookie` integration, `create_session_and_set_cookie` (shared by login / signup / bootstrap).
+- `auth/session_middleware.ts` — `process_session_cookie` integration, `create_session_and_set_cookie` (shared by login / signup / bootstrap; returns the token hashes of the sessions the cap evicted, which the caller closes after its commit — only login passes a cap).
+- `auth/resolved_auth.ts` — `ResolvedAuth` (the resolved credential as one value: `account_id`, `credential_type`, `token_hash`, `api_token_id`), `get_resolved_auth(c)` (gathers it from the context keys the auth middleware set), and `revalidate_resolved_auth(deps, resolved)`, the no-touch re-read a long-lived connection runs once it is registered: session row / token row (by id) still live and still on the account, account not soft-deleted; a daemon token re-reads its account only. Reuses the middleware's own queries and predicates. Called by the WS upgrade (`actions/register_action_ws.ts`) and the audit SSE route between registering a connection pending and admitting it. Twin of the Rust `revalidate_resolved_auth`.
 - `auth/bearer_auth.ts` — soft-fail bearer middleware; rejects when `Origin` or `Referer` present (browser context).
 - `auth/daemon_token_middleware.ts` — `create_daemon_token_middleware(state, deps, log)` — the credential **consumer** only (soft-fail validation, keeper account resolution). The producer (`write_daemon_token` / `start_daemon_token_rotation`) lives in `testing/daemon_token_rotation.ts` behind the dev-env guard — no production assembly mints daemon tokens, mirroring the Rust spine's `fuz_testing`-confined producer. Soft-fails — discards the credential (pass-through, no own 401/503) on **every** non-success path: browser context (`Origin`/`Referer` present), malformed/invalid token, and valid-token-but-no-keeper all `next()` through to the dispatcher's `credential_type_required` (403) gate, mirroring the bearer guard and the Rust spine's `resolve.rs`. Daemon tokens are loopback-only, so browser context never arises in practice — the discard is defense-in-depth.
 
@@ -586,11 +616,13 @@ Closure state:
   directly (`query_app_settings_load`/`query_app_settings_update`);
   `auth/signup_routes.ts` reads the current value fresh per request. There is no
   `options.app_settings` ref.
-- `options.connection_closer?` — handler-side eager WS close on
-  `admin_session_revoke_all` / `admin_token_revoke_all` BEFORE the audit
-  emit so revocation lands even on audit INSERT failure. Listener-based
-  close (`transports_ws_auth_guard`) stays as a fail-safe. Failure outcomes
-  skip the eager close.
+- `deps.connection_closer` (required, `RevokingActionFactoryDeps`) —
+  `admin_session_revoke_all` / `admin_token_revoke_all` / `account_delete` /
+  `account_purge` queue a close of the target account's live connections
+  (`queue_connection_close`), run after the handler's transaction commits and
+  dropped if it throws. The close does not depend on the audit write; the
+  audit listeners repeat it on the announced row. Failure outcomes queue no
+  close.
 
 Failure-outcome audit rows: `admin_session_revoke_all` and `_token_revoke_all`
 emit an `outcome: 'failure'` row on `ERROR_ACCOUNT_NOT_FOUND` for forensic
@@ -751,11 +783,14 @@ gated event also records `credential_type` in metadata (mirrors REST
 `password_change`).
 
 Options: `max_tokens?: number | null` (defaults to `DEFAULT_MAX_TOKENS`;
-`null` disables), `connection_closer?: ConnectionCloser | null`. Each handler
-fires `close_sockets_for_*` synchronously BEFORE the audit emit. Failure
-outcomes (`revoked: false`) skip the eager close — mirrors the listener's
+`null` disables). Deps: `RevokingActionFactoryDeps` — `log`, `audit`, and the
+required `connection_closer`. Each revoking handler queues its close
+(`queue_connection_close`: one session, one token, or the account), which runs
+after the handler's transaction commits and is dropped if it throws;
+`account_token_create` queues a token close for each token its cap evicts.
+Failure outcomes (`revoked: false`) queue no close — mirrors the listeners'
 `outcome === 'failure'` guard so attacker-guessable ids can't target
-arbitrary sockets.
+arbitrary connections.
 
 ### Standard RPC bundle
 
@@ -768,8 +803,8 @@ app-settings methods are always wired). Frontend mirror is
 
 Option routing — `roles` is shared between admin + role-grant-offer;
 `default_ttl_ms` + `authorize` → role-grant-offer
-only; `max_tokens` → account only; `connection_closer` → admin + account;
-`notification_sender` → role-grant-offer only.
+only; `max_tokens` → account only. On `deps`: `notification_sender` →
+role-grant-offer only; `connection_closer` (required) → admin + account.
 
 Pair with `create_app_server`'s `rpc_endpoints` factory form
 `(ctx) => Array<RpcEndpointSpec>` so the combined action list gets
@@ -841,13 +876,72 @@ drops the hand-maintained method-name mappings:
 
 ## Cleanup
 
-`auth/cleanup.ts` — `run_auth_cleanup(deps)` runs every sweep (expired
-sessions + expired offers) and returns counts. Re-throws sweep errors so the
-caller's scheduler can log/alert. Idempotency: audit log has no tombstone on
-`role_grant_offer_expire`, so concurrent runs double-audit — deploy a single
-scheduled invocation per instance. Expired offer rows are preserved (audit
-value for the history view).
-
-`AuthCleanupDeps` requires `audit: AuditEmitter` — production wiring always
-has a bound emitter; tests pass `create_test_audit_emitter()` from
-`testing/stubs.ts`.
+`auth/cleanup.ts` — twin of the Rust `fuz_auth::auth_cleanup` module.
+
+- `run_auth_cleanup(deps)` — one pass: `cleanup_expired_sessions`, then
+  `cleanup_expired_role_grant_offers`; returns `AuthCleanupResult`
+  (`{expired_sessions, expired_offers}`, the same shape on both spines).
+  Re-throws the first sweep's error. Expired offer rows are preserved (audit
+  value for the history view).
+- `start_auth_cleanup(deps, {interval_ms?})` → `{stop}` — the scheduler: a
+  pass at once, then one per interval (`DEFAULT_AUTH_CLEANUP_INTERVAL_MS`, ten
+  minutes), until `stop()`. `create_app_server`'s `auth_cleanup` option calls
+  it with `backend.deps` and chains `stop` into `AppServer.close`. **Off by
+  default** there; a production server turns it on, and an in-process test
+  harness leaves it off (a background pass deletes rows and writes audit rows
+  mid-test).
+
+`AuthCleanupDeps` is `{db, log, audit, connection_closer}`, all required —
+`AppDeps` satisfies it. Tests pass `create_test_audit_emitter()` from
+`testing/stubs.ts` and, where nothing is to be closed, `noop_connection_closer`.
+The sweep belongs in the process that holds the connections: run from another
+process against a live server's database, it deletes the rows that server's
+own pass would have closed for.
+
+**The session sweep closes what it sweeps.** A connection never re-reads its
+session, and once the sweep deletes an expired row `account_session_revoke`
+has nothing left to close for — so `cleanup_expired_sessions` closes each
+swept session's connections itself, by session id
+(`connection_closer.close_sockets_for_session`), which is why
+`query_session_cleanup_expired` returns the deleted ids. With the cleanup
+scheduled, a connection outlives its **session's** expiry by at most one
+interval. An expired API token's row is not swept and its connection is not
+closed (`account_token_revoke` still finds the row).
+
+- The delete runs in its own transaction and the closes follow the commit —
+  the rule every revocation close keeps (`actions/CLAUDE.md` §Connection
+  closer).
+- A transaction that fails once the delete has answered still closes: the
+  sessions are expired either way, the error is thrown after the closes, and
+  the next pass deletes the rows the commit left.
+- A closer that throws for one session is logged and the rest still close.
+- No audit row is written for a swept session, so no listener repeats the
+  close.
+
+**The schedule** is `start_periodic` (`periodic.ts`, twin of the Rust
+`fuz_sys::periodic::spawn_periodic`), which owns the loop's rules:
+`start_auth_cleanup` is that loop over `run_auth_cleanup` plus the swept-counts
+log. Passes never overlap, and a pass that overruns its interval delays the
+next one (which starts when the slow one ends, the one after a full interval
+later) rather than bursting. A failed pass is logged at `warn` with its error
+and retried on the next interval. The timer is unref'd. An interval that is
+not a positive finite number, or exceeds `PERIODIC_INTERVAL_MS_MAX` (the
+largest delay a timer honors), throws at the call. **Shutdown differs from
+Rust**: its task drops a pass in progress; `stop()` ends the schedule at once
+and its promise resolves when the pass in progress has finished — await it
+before closing the database. The wait has no bound of its own.
+
+**Offer idempotency.** `cleanup_expired_role_grant_offers` runs one transaction:
+`query_role_grant_offer_sweep_expired` claims the expired pending offers not
+yet audited by stamping `role_grant_offer.expire_audited_at` (`UPDATE …
+RETURNING`), and each claimed row's `role_grant_offer_expire` audit row is
+inserted in the same transaction; events fan out via `audit.notify` after the
+commit. Each expiry is audited exactly once — a second run finds nothing, and
+concurrent runs claim disjoint rows (a row another sweep holds blocks on its
+row lock, then fails the re-checked stamp). A failed audit insert rolls the
+stamps back and the next run retries, so the offer sweep can throw. The stamp
+is not a lifecycle state (outside the terminal CHECK and the pending
+predicate) and stays off the wire (`to_role_grant_offer_json` drops it); the
+create upsert's re-offer clears it, so a refreshed offer's own expiry is
+audited too. The `role_grant_offer_expire_sweep` partial index serves the
+claim.

package/dist/auth/account_actions.d.ts

@@ -17,14 +17,18 @@
  * so passing another account's session or token id returns `revoked: false`
  * rather than revealing whether the id exists.
  *
+ * Every handler that ends a credential closes the connections it opened,
+ * after the handler's transaction commits (`queue_connection_close` on
+ * `deps.connection_closer`): the two session revokes, the token revoke, and
+ * `account_token_create` for the tokens its cap evicts.
+ *
  * Counterpart to `auth/account_routes.ts`, which keeps the cookie-lifecycle flows
  * (`login`, `logout`, `password`, `signup`, `bootstrap`) on REST.
  *
  * @module
  */
 import { type RpcAction } from '../actions/action_rpc.js';
-import type { ConnectionCloser } from '../actions/connection_closer.js';
-import type { ActionFactoryDeps } from './deps.js';
+import type { RevokingActionFactoryDeps } from './deps.js';
 /** Options for `create_account_actions`. */
 export interface AccountActionOptions {
     /**
@@ -34,27 +38,17 @@ export interface AccountActionOptions {
      * `DEFAULT_MAX_TOKENS`; pass `null` to disable the cap.
      */
     max_tokens?: number | null;
-    /**
-     * Live-connection closer — when set, `account_session_revoke` /
-     * `_session_revoke_all` / `account_token_revoke` handlers eagerly close
-     * affected WebSocket sockets BEFORE emitting the corresponding audit
-     * event. Closes the audit-failure-leaks-WS surface: the listener-based
-     * close (`transports_ws_auth_guard`) only fires after the audit INSERT
-     * succeeds, so a DB error would leave live sockets stale. `BackendWebsocketTransport`
-     * satisfies this interface structurally; consumers pass their transport
-     * instance directly. When absent, only the listener-based close runs.
-     * Mirrors `zzz_server`'s handler-side `close_sockets_for_*` calls.
-     */
-    connection_closer?: ConnectionCloser | null;
 }
 /**
  * Create the self-service account RPC actions.
  *
- * @param deps - `ActionFactoryDeps` (`log`, `audit`). `audit.emit` writes
- *   audit rows via the captured pool; the bound emitter encapsulates
- *   `on_audit_event` fan-out and the optional `AuditLogConfig`.
+ * @param deps - `RevokingActionFactoryDeps` (`log`, `audit`,
+ *   `connection_closer`). `audit.emit` writes audit rows via the captured
+ *   pool; the bound emitter encapsulates `on_audit_event` fan-out and the
+ *   optional `AuditLogConfig`. `connection_closer` closes a revoked
+ *   credential's live connections after the revocation commits.
  * @param options - per-factory configuration
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
  */
-export declare const create_account_actions: (deps: ActionFactoryDeps, options?: AccountActionOptions) => Array<RpcAction>;
+export declare const create_account_actions: (deps: RevokingActionFactoryDeps, options?: AccountActionOptions) => Array<RpcAction>;
 //# sourceMappingURL=account_actions.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAqBxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAyBnD,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,iBAAiB,EACvB,UAAS,oBAAyB,KAChC,KAAK,CAAC,SAAS,CAwKjB,CAAC"}
+{"version":3,"file":"account_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAsB9F,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAyB3D,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,yBAAyB,EAC/B,UAAS,oBAAyB,KAChC,KAAK,CAAC,SAAS,CA8KjB,CAAC"}

package/dist/auth/account_actions.js

@@ -17,12 +17,18 @@
  * so passing another account's session or token id returns `revoked: false`
  * rather than revealing whether the id exists.
  *
+ * Every handler that ends a credential closes the connections it opened,
+ * after the handler's transaction commits (`queue_connection_close` on
+ * `deps.connection_closer`): the two session revokes, the token revoke, and
+ * `account_token_create` for the tokens its cap evicts.
+ *
  * Counterpart to `auth/account_routes.ts`, which keeps the cookie-lifecycle flows
  * (`login`, `logout`, `password`, `signup`, `bootstrap`) on REST.
  *
  * @module
  */
 import { rpc_action } from '../actions/action_rpc.js';
+import { queue_connection_close } from '../actions/connection_closer.js';
 import { to_session_account } from './account_schema.js';
 import { query_session_list_for_account, query_session_revoke_for_account, query_session_revoke_all_for_account } from './session_queries.js';
 import { query_api_token_enforce_limit, query_api_token_list_for_account, query_create_api_token, query_revoke_api_token_for_account } from './api_token_queries.js';
@@ -35,14 +41,17 @@ import { account_verify_action_spec, account_session_list_action_spec, account_s
 /**
  * Create the self-service account RPC actions.
  *
- * @param deps - `ActionFactoryDeps` (`log`, `audit`). `audit.emit` writes
- *   audit rows via the captured pool; the bound emitter encapsulates
- *   `on_audit_event` fan-out and the optional `AuditLogConfig`.
+ * @param deps - `RevokingActionFactoryDeps` (`log`, `audit`,
+ *   `connection_closer`). `audit.emit` writes audit rows via the captured
+ *   pool; the bound emitter encapsulates `on_audit_event` fan-out and the
+ *   optional `AuditLogConfig`. `connection_closer` closes a revoked
+ *   credential's live connections after the revocation commits.
  * @param options - per-factory configuration
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
  */
 export const create_account_actions = (deps, options = {}) => {
-    const { max_tokens = DEFAULT_MAX_TOKENS, connection_closer = null } = options;
+    const { max_tokens = DEFAULT_MAX_TOKENS } = options;
+    const { connection_closer } = deps;
     const verify_handler = (_input, ctx) => {
         return to_session_account(ctx.auth.account);
     };
@@ -52,20 +61,18 @@ export const create_account_actions = (deps, options = {}) => {
     };
     const session_revoke_handler = async (input, ctx) => {
         const revoked = await query_session_revoke_for_account(ctx, input.session_id, ctx.auth.account.id);
-        // Handler-side belt+suspenders: close the live WS socket bound to this
-        // session BEFORE the audit emit, so revocation lands even if the audit
-        // INSERT fails. The real ordering invariant is "before the transaction
-        // commits": this handler runs inside the dispatcher's transaction
-        // (side_effects: true), so any throw between this close and the return
-        // would roll back the DB revoke while leaving the socket severed. That
-        // is benign — the session is still valid, the client reconnects — but
-        // don't introduce a throw here without acknowledging the trade.
-        // Only fire on success — failure carries an attacker-guessable
-        // session_id and the listener-based close already ignores failure
-        // outcomes for the same reason. Idempotent — the audit listener runs a
-        // second close on success but matches no sockets the second time.
-        if (revoked && connection_closer) {
-            connection_closer.close_sockets_for_session(input.session_id);
+        // Close the connections this session opened, once the revoke has
+        // committed — queued, so it never runs before the commit or for a
+        // revoke that rolled back, and it does not depend on the audit write
+        // below. Only on success: a failed revoke carries a caller-supplied
+        // session_id, and closing on it would let any account close another's
+        // connections by guessing a hash. The audit listener repeats the close
+        // on the announced row; closing is idempotent.
+        if (revoked) {
+            queue_connection_close(ctx, connection_closer, {
+                kind: 'session',
+                session_token_hash: input.session_id
+            });
         }
         deps.audit.emit(ctx, {
             event_type: 'session_revoke',
@@ -79,17 +86,14 @@ export const create_account_actions = (deps, options = {}) => {
     };
     const session_revoke_all_handler = async (_input, ctx) => {
         const count = await query_session_revoke_all_for_account(ctx, ctx.auth.account.id);
-        // Handler-side belt+suspenders — see session_revoke_handler comment.
-        // Close fires regardless of `count` (today `count >= 1` always — the
-        // caller is using the session they're revoking; future bearer / daemon-
-        // token-credentialed callers may hit `count: 0`). Symmetric with the
-        // admin revoke-all handlers in `admin_actions.ts`, where `count: 0` is
-        // a real outcome (target account had no live sessions/tokens) and the
-        // eager close still fires to scrub sockets that the audit listener
-        // would otherwise miss when the INSERT fails. Idempotent at all counts.
-        if (connection_closer) {
-            connection_closer.close_sockets_for_account(ctx.auth.account.id);
-        }
+        // Post-commit close — see session_revoke_handler. Queued regardless of
+        // `count` (today `count >= 1` always — the caller is using a session
+        // it is revoking), symmetric with the admin revoke-all handlers in
+        // `admin_actions.ts`, where `count: 0` is a real outcome.
+        queue_connection_close(ctx, connection_closer, {
+            kind: 'account',
+            account_id: ctx.auth.account.id
+        });
         deps.audit.emit(ctx, {
             event_type: 'session_revoke_all',
             account_id: ctx.auth.account.id,
@@ -109,7 +113,14 @@ export const create_account_actions = (deps, options = {}) => {
         const expires_at = token_lifetime_to_expires_at(input.lifetime);
         await query_create_api_token(ctx, id, ctx.auth.account.id, input.name, token_hash, scope, expires_at);
         if (max_tokens != null) {
-            await query_api_token_enforce_limit(ctx, ctx.auth.account.id, max_tokens);
+            const evicted = await query_api_token_enforce_limit(ctx, ctx.auth.account.id, max_tokens);
+            // The cap deleted the evicted rows; the connections they opened end
+            // only when closed, and only after the commit — the same post-commit
+            // close the revocations use. No audit row: there is no eviction
+            // event, and `token_create` records the mint that caused it.
+            for (const api_token_id of evicted) {
+                queue_connection_close(ctx, connection_closer, { kind: 'token', api_token_id });
+            }
         }
         deps.audit.emit(ctx, {
             event_type: 'token_create',
@@ -145,9 +156,12 @@ export const create_account_actions = (deps, options = {}) => {
     };
     const token_revoke_handler = async (input, ctx) => {
         const revoked = await query_revoke_api_token_for_account(ctx, input.token_id, ctx.auth.account.id);
-        // Handler-side belt+suspenders — see session_revoke_handler comment.
-        if (revoked && connection_closer) {
-            connection_closer.close_sockets_for_token(input.token_id);
+        // Post-commit close, on success only — see session_revoke_handler.
+        if (revoked) {
+            queue_connection_close(ctx, connection_closer, {
+                kind: 'token',
+                api_token_id: input.token_id
+            });
         }
         deps.audit.emit(ctx, {
             event_type: 'token_revoke',

package/dist/auth/account_routes.d.ts

@@ -25,7 +25,6 @@ import type { SessionOptions } from './session_cookie.js';
 import { type RouteSpec } from '../http/route_spec.js';
 import { type RateLimiter } from '../rate_limiter.js';
 import type { RouteFactoryDeps } from './deps.js';
-import type { ConnectionCloser } from '../actions/connection_closer.js';
 /**
  * Create the account status route spec.
  *
@@ -112,15 +111,6 @@ export interface AccountRouteOptions extends AuthSessionRouteOptions {
      * jitter while keeping the floor. Default `DEFAULT_LOGIN_FAIL_JITTER_MS`.
      */
     login_fail_jitter_ms?: number;
-    /**
-     * Live-connection closer — when set, the `logout` and `password` handlers
-     * eagerly close affected WebSocket sockets for the account BEFORE
-     * emitting the corresponding audit event. Mirrors the self-service
-     * action surface (see `AccountActionOptions.connection_closer`). When
-     * absent, only the listener-based close (`transports_ws_auth_guard`
-     * registered via `audit.add_listener`) runs.
-     */
-    connection_closer?: ConnectionCloser | null;
     /**
      * Runtime bootstrap status for the bundled `GET /status` route — when
      * `available`, its unauthenticated 401 carries `bootstrap_available: true`
@@ -143,7 +133,11 @@ export interface AccountRouteOptions extends AuthSessionRouteOptions {
  * every account surface serves it, matching the Rust `account_router`.
  * Self-service session/token management is on `auth/account_actions.ts`.
  *
- * @param deps - stateless capabilities (keyring, password, log)
+ * `/login` closes the connections of the sessions its cap evicts, and
+ * `/logout` and `/password` close the account's, each after the route's
+ * transaction commits (`queue_connection_close` on `deps.connection_closer`).
+ *
+ * @param deps - stateless capabilities (keyring, password, log, audit, connection_closer)
  * @param options - per-factory configuration (session_options, login_ip_rate_limiter, login_account_rate_limiter, bootstrap_status)
  * @returns route specs (not yet applied to Hono)
  */

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

@@ -1 +1 @@
-{"version":3,"file":"account_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA4B1D,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAGxE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gCAAgC,GAAI,UAAU,oBAAoB,KAAG,SA4EhF,CAAC;AAEH,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,gBAAgB,CAAC,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAQ/C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,uBAAuB;IACvC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IACnE;;;;;;;OAOG;IACH,qBAAqB,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1C,4FAA4F;IAC5F,0BAA0B,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/C,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC5C;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1C;AAID;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,gBAAgB,EACtB,SAAS,mBAAmB,KAC1B,KAAK,CAAC,SAAS,CA6RjB,CAAC"}
+{"version":3,"file":"account_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA4B1D,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAIlD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gCAAgC,GAAI,UAAU,oBAAoB,KAAG,SA4EhF,CAAC;AAEH,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,gBAAgB,CAAC,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAQ/C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,uBAAuB;IACvC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IACnE;;;;;;;OAOG;IACH,qBAAqB,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1C,4FAA4F;IAC5F,0BAA0B,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/C,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1C;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,gBAAgB,EACtB,SAAS,mBAAmB,KAC1B,KAAK,CAAC,SAAS,CA2RjB,CAAC"}

package/dist/auth/account_routes.js

@@ -32,6 +32,7 @@ import { ACCOUNT_ID_KEY, CREDENTIAL_TYPE_KEY } from '../hono_context.js';
 import { get_route_input } from '../http/route_spec.js';
 import { get_client_ip } from '../http/client_ip.js';
 import { rate_limit_exceeded_response } from '../rate_limiter.js';
+import { queue_connection_close } from '../actions/connection_closer.js';
 import { ERROR_AUTHENTICATION_REQUIRED, ERROR_INVALID_CREDENTIALS } from '../http/error_schemas.js';
 /**
  * Create the account status route spec.
@@ -154,13 +155,17 @@ const login_fail_delay = (floor_ms, jitter_ms) => {
  * every account surface serves it, matching the Rust `account_router`.
  * Self-service session/token management is on `auth/account_actions.ts`.
  *
- * @param deps - stateless capabilities (keyring, password, log)
+ * `/login` closes the connections of the sessions its cap evicts, and
+ * `/logout` and `/password` close the account's, each after the route's
+ * transaction commits (`queue_connection_close` on `deps.connection_closer`).
+ *
+ * @param deps - stateless capabilities (keyring, password, log, audit, connection_closer)
  * @param options - per-factory configuration (session_options, login_ip_rate_limiter, login_account_rate_limiter, bootstrap_status)
  * @returns route specs (not yet applied to Hono)
  */
 export const create_account_route_specs = (deps, options) => {
-    const { keyring, password } = deps;
-    const { session_options, login_ip_rate_limiter, login_account_rate_limiter, max_sessions = DEFAULT_MAX_SESSIONS, login_fail_floor_ms = DEFAULT_LOGIN_FAIL_FLOOR_MS, login_fail_jitter_ms = DEFAULT_LOGIN_FAIL_JITTER_MS, connection_closer = null, bootstrap_status } = options;
+    const { keyring, password, connection_closer } = deps;
+    const { session_options, login_ip_rate_limiter, login_account_rate_limiter, max_sessions = DEFAULT_MAX_SESSIONS, login_fail_floor_ms = DEFAULT_LOGIN_FAIL_FLOOR_MS, login_fail_jitter_ms = DEFAULT_LOGIN_FAIL_JITTER_MS, bootstrap_status } = options;
     const [verify_shape, login_shape, logout_shape, password_shape] = create_account_route_shapes({
         login_account_rate_limited: login_account_rate_limiter !== null
     });
@@ -250,7 +255,7 @@ export const create_account_route_specs = (deps, options) => {
                 // that address. See `RateLimiter.reset`.
                 if (login_account_rate_limiter)
                     login_account_rate_limiter.reset(account_rate_key);
-                await create_session_and_set_cookie({
+                const evicted = await create_session_and_set_cookie({
                     keyring,
                     deps: route,
                     c,
@@ -258,6 +263,15 @@ export const create_account_route_specs = (deps, options) => {
                     session_options,
                     max_sessions
                 });
+                // The sessions the cap evicted are gone from the table, but not
+                // from the connections they opened — a WebSocket keeps the
+                // authority it resolved at upgrade, and an SSE stream never
+                // rechecks. Close them once the eviction has committed. No audit
+                // row: there is no eviction event, and the `login` row records
+                // the cause.
+                for (const session_token_hash of evicted) {
+                    queue_connection_close(route, connection_closer, { kind: 'session', session_token_hash });
+                }
                 deps.audit.emit(route, {
                     event_type: 'login',
                     account_id: account.id,
@@ -274,22 +288,18 @@ export const create_account_route_specs = (deps, options) => {
                 if (session_token) {
                     const token_hash = hash_session_token(session_token);
                     await query_session_revoke_by_hash_unscoped(route, token_hash);
-                    // Handler-side belt+suspenders: eagerly close this account's
-                    // live WS connections BEFORE the audit emit so revocation
-                    // lands even if the audit INSERT fails. Account-wide (not
-                    // session-targeted) to match the Rust `account_logout` handler
-                    // and the sibling `/password` handler — logout is a
-                    // self-initiated account-grain operation, and the audit
-                    // listener (`create_ws_logout_closer`) runs the same
-                    // account-wide close on the logout event afterward, so both
-                    // layers converge (idempotent). Same transaction-commit trade
-                    // as `password` / RPC `session_revoke`: a throw between this
-                    // close and the response rolls back the DB revoke while
-                    // leaving sockets severed; benign (client reconnects), but
-                    // don't introduce a throw here without acknowledging the trade.
-                    if (connection_closer) {
-                        connection_closer.close_sockets_for_account(ctx.account.id);
-                    }
+                    // Close this account's live connections once the revoke has
+                    // committed — queued, so it never runs before the commit or on
+                    // rollback, and it does not depend on the fail-open audit write
+                    // below. Account-wide (not session-targeted) to match the Rust
+                    // `account_logout` handler and the sibling `/password` handler
+                    // — logout is a self-initiated account-grain operation. The
+                    // audit listeners repeat the same close on the announced
+                    // `logout` row; closing is idempotent.
+                    queue_connection_close(route, connection_closer, {
+                        kind: 'account',
+                        account_id: ctx.account.id
+                    });
                 }
                 clear_session_cookie(c, session_options);
                 // Account-grain operation — no `actor_id` (which actor was
@@ -389,22 +399,16 @@ export const create_account_route_specs = (deps, options) => {
                 // revoke all sessions and API tokens (force re-auth everywhere)
                 const sessions_revoked = await query_session_revoke_all_for_account(route, ctx.account.id);
                 const tokens_revoked = await query_revoke_all_api_tokens_for_account(route, ctx.account.id);
-                // Handler-side belt+suspenders — close every live WS socket on
-                // this account BEFORE the audit emit so the revoke-all cascade
-                // lands even if the audit INSERT fails. The real ordering
-                // invariant is "before the transaction commits": this route
-                // runs with the default `transaction: true`, so a throw between
-                // this close and the response would roll back the password
-                // update + session/token revokes while leaving sockets severed.
-                // Benign — affected clients reconnect with their still-valid
-                // session — but don't introduce a throw here without
-                // acknowledging the trade. Listener-based close
-                // (`transports_ws_auth_guard` on the `password_change` event)
-                // runs the same close afterward; idempotent on the second pass.
-                // Mirrors `zzz_server::account::password_inner`.
-                if (connection_closer) {
-                    connection_closer.close_sockets_for_account(ctx.account.id);
-                }
+                // Close every live connection of this account once the password
+                // update and the revoke-all cascade have committed — this route
+                // runs with the default `transaction: true`, and the queued close
+                // never runs before that commit or on rollback. It does not
+                // depend on the fail-open audit write below; the audit listeners
+                // repeat it on the announced `password_change` row.
+                queue_connection_close(route, connection_closer, {
+                    kind: 'account',
+                    account_id: ctx.account.id
+                });
                 clear_session_cookie(c, session_options);
                 // Account-grain operation — no `actor_id`. The password is
                 // account-level state; which per-request actor was resolved