@fuzdev/fuz_app 0.62.0 → 0.64.0

package/dist/actions/transports_ws_auth_guard.d.ts

@@ -1,12 +1,26 @@
 /**
  * WebSocket auth guard — bridges audit events to `BackendWebsocketTransport`.
  *
- * Mirror of `realtime/sse_auth_guard.ts` for the backend WebSocket transport.
- * Dispatches audit events to the right `close_sockets_for_*` method so
- * consumers do not re-implement the switch themselves.
+ * **Why this exists.** `register_action_ws` captures `account_id` and
+ * `credential_type` at upgrade time and reuses them for every message.
+ * `perform_action`'s per-message authorization phase reloads role_grants
+ * from the DB, but session and token VALIDITY are not re-queried — that
+ * trade-off keeps chatty WS connections fast. The cost: nothing in the
+ * dispatch path notices when a session is revoked or a token is rotated.
+ * This guard is the enforcement mechanism — it listens on the audit
+ * chain and closes affected sockets when revocation events fire, so
+ * revocation actually takes effect on existing connections. Without it,
+ * `session_revoke` / `token_revoke` are no-ops for open WS connections.
  *
- * Consumers wire it as `on_audit_event` on their `AppBackend` (or compose
- * it with other callbacks via `create_app_server`'s `audit_log_sse` path).
+ * Mirror of `realtime/sse_auth_guard.ts` for the backend WebSocket
+ * transport. Dispatches audit events to the right `close_sockets_for_*`
+ * method so consumers do not re-implement the switch themselves.
+ *
+ * For standard WS endpoints mounted via `AppServerOptions.ws_endpoints`,
+ * `create_app_server` composes the guard automatically per
+ * `WsEndpointSpec.auth_guard`. For custom wiring, append the handler
+ * inside the consumer's `audit_factory` body (or via
+ * `audit.on_event_chain.push(...)` post-assembly).
  *
  * @module
  */
@@ -14,7 +28,7 @@ import type { Logger } from '@fuzdev/fuz_util/log.js';
 import type { AuditLogEvent } from '../auth/audit_log_schema.js';
 import type { BackendWebsocketTransport } from './transports_ws_backend.js';
 /**
- * Audit-event callback shape — the function `CreateAppBackendOptions.on_audit_event`
+ * Audit-event callback shape — the function `CreateAuditEmitterOptions.on_audit_event`
  * accepts and that the helpers in this module return.
  *
  * Exported so consumers composing multiple handlers (typically
@@ -46,8 +60,10 @@ export declare const ws_disconnect_event_types: ReadonlySet<string>;
  * user close another user's socket by guessing a session hash or token id.
  *
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`.
- *   The returned callback mutates `transport` (closing matching sockets via
+ * @returns an `on_audit_event` callback suitable for `create_audit_emitter`'s
+ *   `on_audit_event` slot, or for appending onto
+ *   `audit.on_event_chain` post-assembly. The returned callback mutates
+ *   `transport` (closing matching sockets via
  *   `close_sockets_for_session` / `_token` / `_account`) on every relevant event.
  */
 export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;

package/dist/actions/transports_ws_auth_guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAChC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBA6CF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBAaF,CAAC"}
+{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,GAChC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBA6CF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBAaF,CAAC"}

package/dist/actions/transports_ws_auth_guard.js

@@ -1,12 +1,26 @@
 /**
  * WebSocket auth guard — bridges audit events to `BackendWebsocketTransport`.
  *
- * Mirror of `realtime/sse_auth_guard.ts` for the backend WebSocket transport.
- * Dispatches audit events to the right `close_sockets_for_*` method so
- * consumers do not re-implement the switch themselves.
+ * **Why this exists.** `register_action_ws` captures `account_id` and
+ * `credential_type` at upgrade time and reuses them for every message.
+ * `perform_action`'s per-message authorization phase reloads role_grants
+ * from the DB, but session and token VALIDITY are not re-queried — that
+ * trade-off keeps chatty WS connections fast. The cost: nothing in the
+ * dispatch path notices when a session is revoked or a token is rotated.
+ * This guard is the enforcement mechanism — it listens on the audit
+ * chain and closes affected sockets when revocation events fire, so
+ * revocation actually takes effect on existing connections. Without it,
+ * `session_revoke` / `token_revoke` are no-ops for open WS connections.
  *
- * Consumers wire it as `on_audit_event` on their `AppBackend` (or compose
- * it with other callbacks via `create_app_server`'s `audit_log_sse` path).
+ * Mirror of `realtime/sse_auth_guard.ts` for the backend WebSocket
+ * transport. Dispatches audit events to the right `close_sockets_for_*`
+ * method so consumers do not re-implement the switch themselves.
+ *
+ * For standard WS endpoints mounted via `AppServerOptions.ws_endpoints`,
+ * `create_app_server` composes the guard automatically per
+ * `WsEndpointSpec.auth_guard`. For custom wiring, append the handler
+ * inside the consumer's `audit_factory` body (or via
+ * `audit.on_event_chain.push(...)` post-assembly).
  *
  * @module
  */
@@ -39,8 +53,10 @@ export const ws_disconnect_event_types = new Set([
  * user close another user's socket by guessing a session hash or token id.
  *
  * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback suitable for `CreateAppBackendOptions`.
- *   The returned callback mutates `transport` (closing matching sockets via
+ * @returns an `on_audit_event` callback suitable for `create_audit_emitter`'s
+ *   `on_audit_event` slot, or for appending onto
+ *   `audit.on_event_chain` post-assembly. The returned callback mutates
+ *   `transport` (closing matching sockets via
  *   `close_sockets_for_session` / `_token` / `_account`) on every relevant event.
  */
 export const create_ws_auth_guard = (transport, log) => {

package/dist/actions/ws_endpoint_spec.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `WsEndpointSpec` — the canonical WebSocket endpoint declaration consumed
+ * by `create_app_server`'s `ws_endpoints` option (mirror of `RpcEndpointSpec`
+ * for HTTP RPC).
+ *
+ * Lives in its own module so both `server/app_server.ts` (which mounts
+ * endpoints from these specs) and `http/surface.ts` (which threads the
+ * resolved spec list into surface generation) can import it without a
+ * cycle between the two.
+ *
+ * @module
+ */
+import type { Action } from './action_types.js';
+import type { RoleName } from '../auth/role_schema.js';
+import type { BackendWebsocketTransport } from './transports_ws_backend.js';
+import type { ServerHeartbeatOptions, SocketCloseContext, SocketOpenContext } from './register_action_ws.js';
+import type { AuditEventHandler } from './transports_ws_auth_guard.js';
+/**
+ * Declarative description of a WebSocket endpoint to be auto-mounted by
+ * `create_app_server`.
+ *
+ * Single source of truth for mount + surface — the same array drives
+ * `register_ws_endpoint`-style upgrade wiring AND the `surface.ws_endpoints`
+ * slot emitted into `AppSurface`, so consumers cannot drift their declared
+ * actions from what dispatch actually serves.
+ */
+export interface WsEndpointSpec {
+    /** Hono mount path (e.g. `/api/ws`). */
+    path: string;
+    /**
+     * Origin allowlist regexes — typically parsed via `parse_allowed_origins`.
+     * Passed straight to `verify_request_source` on upgrade.
+     */
+    allowed_origins: ReadonlyArray<RegExp>;
+    /**
+     * The actions registered on this endpoint. Spread `protocol_actions`
+     * from `actions/protocol.ts` first to complete the
+     * disconnect-detection + per-request cancel pairing with the frontend
+     * client.
+     */
+    actions: ReadonlyArray<Action>;
+    /**
+     * Roles permitted to upgrade — any-of disjunction. Omit (or pass `[]`)
+     * to skip the upgrade-time role gate; per-action `auth` on each spec
+     * still applies at dispatch time via `perform_action`. Pass
+     * `[ROLE_ADMIN]` for a zap-style admin-only WS endpoint.
+     */
+    required_roles?: ReadonlyArray<RoleName>;
+    /**
+     * Existing transport to register connections with. Auto-created when
+     * omitted. Either way the mounted transport is reachable on
+     * `AppServer.ws_endpoints[path]` for broadcast / fan-out.
+     */
+    transport?: BackendWebsocketTransport;
+    /**
+     * Server-side heartbeat policy. Default-on (60s receive-silence
+     * timeout). Set `false` only when an upstream stack (TCP keepalive,
+     * Cloudflare idle timeout) already owns disconnect detection.
+     */
+    heartbeat?: boolean | ServerHeartbeatOptions;
+    /** Optional per-message delay for testing loading states. */
+    artificial_delay?: number;
+    /**
+     * Called once per socket after `transport.add_connection` but before
+     * the first message dispatches. See
+     * `RegisterActionWsOptions.on_socket_open`.
+     */
+    on_socket_open?: (ctx: SocketOpenContext) => void | Promise<void>;
+    /**
+     * Called once per socket on close, before `transport.remove_connection`.
+     * See `RegisterActionWsOptions.on_socket_close`.
+     */
+    on_socket_close?: (ctx: SocketCloseContext) => void | Promise<void>;
+    /**
+     * Default `true` — auto-composes `create_ws_auth_guard` +
+     * `create_ws_logout_closer` against this endpoint's transport and
+     * appends them to `deps.audit.on_event_chain`. Wiring is deduped by
+     * transport **reference identity** (`WeakSet<BackendWebsocketTransport>`),
+     * so two `WsEndpointSpec`s sharing the exact same instance get a
+     * single pair of listeners.
+     *
+     * **Shared-transport OR-semantics.** When multiple `WsEndpointSpec`s
+     * share one transport, the guard is wired iff **any** of those specs
+     * has `auth_guard !== false`. To opt out for a shared transport,
+     * every sibling spec must pass `auth_guard: false`. The default is
+     * "fail safe" — easier to enable than disable, and predictable
+     * regardless of spec order.
+     *
+     * Reference-identity dedupe means **wrapped or proxied transports
+     * dedupe as separate entries** — a consumer threading every
+     * transport through a tracing / DI / metrics shim will get a fresh
+     * pair of listeners per shimmed reference, even when the underlying
+     * transport is the same. If you wrap or proxy, set `auth_guard:
+     * false` on the duplicate `WsEndpointSpec`s and compose
+     * `create_ws_auth_guard` / `create_ws_logout_closer` against the
+     * underlying transport once.
+     *
+     * Set `false` when a consumer needs to compose their own callback
+     * from scratch — or to opt out of the auto-wiring entirely.
+     *
+     * NOTE: does NOT close sockets on `role_grant_revoke` — that omission
+     * is deliberate (per-connection role tracking is out of scope). A user
+     * whose admin role is revoked keeps their socket open; the next message
+     * gets `forbidden` from the per-message authorization phase. Consumers
+     * wanting role-revoke disconnection use `extra_audit_handlers`.
+     */
+    auth_guard?: boolean;
+    /**
+     * Extra audit-event handlers appended to `deps.audit.on_event_chain`
+     * AFTER the standard `auth_guard` wiring (when enabled). By the time
+     * these run, the standard guards may have already closed sockets. Use
+     * for role-revoke disconnection, custom analytics, etc.
+     *
+     * Never deduped — consumer-owned; pass the same handler twice and it
+     * fires twice.
+     */
+    extra_audit_handlers?: ReadonlyArray<AuditEventHandler>;
+}
+//# sourceMappingURL=ws_endpoint_spec.d.ts.map

package/dist/actions/ws_endpoint_spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws_endpoint_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/ws_endpoint_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAC1E,OAAO,KAAK,EACX,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,+BAA+B,CAAC;AAErE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;OAKG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACxD"}

package/dist/actions/ws_endpoint_spec.js

@@ -0,0 +1,13 @@
+/**
+ * `WsEndpointSpec` — the canonical WebSocket endpoint declaration consumed
+ * by `create_app_server`'s `ws_endpoints` option (mirror of `RpcEndpointSpec`
+ * for HTTP RPC).
+ *
+ * Lives in its own module so both `server/app_server.ts` (which mounts
+ * endpoints from these specs) and `http/surface.ts` (which threads the
+ * resolved spec list into surface generation) can import it without a
+ * cycle between the two.
+ *
+ * @module
+ */
+export {};

package/dist/auth/CLAUDE.md

@@ -2,16 +2,18 @@
 
 > Auth domain: identity, crypto primitives, schema + DDL, queries, middleware, routes, RPC actions, cleanup.
 
-Grouped below by theme. For design rationale and threat
-model, see `../../../docs/identity.md` and `../../../docs/security.md`. For the
+Grouped below by theme. For design rationale and threat model, see
+../../../docs/identity.md and ../../../docs/security.md. For the
 subsystem's place in server assembly and middleware ordering, see
-`../../../docs/architecture.md` and the root `../../../CLAUDE.md`.
+../../../docs/architecture.md and the root ../../../CLAUDE.md. For
+the workspace-wide DI vocabulary (capabilities / options / runtime
+state), see Skill(fuz-stack) dependency-injection.
 
-The DI vocabulary is the stack standard: stateless capabilities in
-`AppDeps` / `RouteFactoryDeps`; static config in `*Options`; runtime state
-(e.g. `DaemonTokenState`, mutable `AppSettings` ref, `BootstrapStatus`) is
-inline, never in `deps`. All `query_*` functions take `deps: QueryDeps = {db}`
-as their first arg.
+Auth-specific instances: stateless capabilities in `AppDeps` /
+`RouteFactoryDeps`; static config in `*Options`; runtime state
+(`DaemonTokenState`, mutable `AppSettings` ref, `BootstrapStatus`) is
+inline, never in `deps`. All `query_*` functions take
+`deps: QueryDeps = {db}` as their first arg.
 
 ## Crypto primitives
 
@@ -373,10 +375,11 @@ Zod enum; `AuditOutcome` is `'success' | 'failure'`.
 - **Consumer extensibility**: `create_audit_log_config({extra_events})`
   builds an `AuditLogConfig` merging builtins with consumer event-type
   strings keyed to a Zod schema (validates metadata) or `null` (registers
-  without validation). Pass the result to `create_app_backend({audit_log_config})`
-  — it gets captured inside the bound `AppDeps.audit` emitter, and every
-  call to `audit.emit` validates against it (defaults to
-  `builtin_audit_log_config` when absent). `query_audit_log` still accepts
+  without validation). Pass the result into the consumer's `audit_factory`
+  body — typically `({db, log}) => create_audit_emitter({db, log,
+audit_log_config, on_audit_event})` — so it gets captured inside the
+  bound `AppDeps.audit` emitter; every call to `audit.emit` validates
+  against it (defaults to `builtin_audit_log_config` when absent). `query_audit_log` still accepts
   the trailing `config` positional arg for in-transaction emit sites that
   hold a transaction-scoped DB only. Builtin collisions and
   `AuditEventTypeName` format failures throw at construction. The DB
@@ -754,7 +757,9 @@ run'` if the seed somehow missed (defensive — migrations always seed).
 - `query_audit_log_list_role_grant_history` (filters to `role_grant_create` / `role_grant_revoke`).
 - `query_audit_log_cleanup_before`.
 - **Audit fan-out runs through `AppDeps.audit`** (the bound emitter built
-  by `create_audit_emitter` at backend assembly — see §`audit_emitter.ts`).
+  by the consumer's `audit_factory` callback on `CreateAppBackendOptions`,
+  typically a one-liner over `create_audit_emitter` — see
+  §`audit_emitter.ts`).
   `audit.emit(ctx, input)` writes via the captured pool, so audit entries
   persist even when the request transaction rolls back. The emitter
   closes over `on_audit_event` + `audit_log_config` so handlers can never
@@ -765,7 +770,11 @@ run'` if the seed somehow missed (defensive — migrations always seed).
 ### `audit_emitter.ts`
 
 `AuditEmitter` is the bound capability that lives on `AppDeps.audit`,
-built once at `create_app_backend` time.
+built once by the consumer's `audit_factory` callback on
+`CreateAppBackendOptions`. `create_app_backend` invokes the callback
+with its constructed `{db, log}` after migrations run; the canonical
+body is `({db, log}) => create_audit_emitter({db, log, on_audit_event,
+audit_log_config})`.
 
 Four methods:
 
@@ -789,7 +798,7 @@ Per-call `ctx` shape:
 - `emit` requires `{pending_effects: Array<Promise<void>>}` — the eager
   queue only. Both `RouteContext` and `ActionContext` satisfy this
   structurally; `audit.emit` pushes its in-flight pool-write promise
-  onto the eager queue. See `../http/CLAUDE.md` §Pending Effects for
+  onto the eager queue. See `http/CLAUDE.md` §Pending Effects for
   the eager / deferred split.
 - `emit_role_grant_target` adds `client_ip: string` (also on `ActionContext`;
   REST handlers pass `{pending_effects, client_ip: get_client_ip(c)}`).
@@ -919,7 +928,7 @@ consciously violate the contract.
 
 ## Middleware
 
-See the root `../../../CLAUDE.md` §Middleware Ordering for the canonical
+See the root ../../../CLAUDE.md §Middleware Ordering for the canonical
 assembly order. Two-phase identity:
 
 - **Authentication** runs in middleware (session / bearer / daemon
@@ -974,7 +983,7 @@ assembly order. Two-phase identity:
   actor row was deleted between credential validation and the
   follow-up read). The named per-error shape `AuthorizationFailureBody`
   is still exported for callers that want to bind the failure body
-  by type. See the root `../../../CLAUDE.md` § Cleanest architecture
+  by type. See the root ../../../CLAUDE.md §Cleanest architecture
   takes priority for the rationale.
 
 Session parsing is separate from auth enforcement — login / bootstrap
@@ -1141,6 +1150,8 @@ Session-based auth route specs. Factory: `create_account_route_specs(deps, optio
 - `POST /logout` — revokes session by hash, clears cookie.
 - **`POST /password`** — `current_password: PasswordProvided` +
   `new_password: Password`. Per-IP + per-account rate limited.
+  Declares `credential_types: ['session']` (see
+  `docs/security.md` §Credential-channel gating).
   **Revokes all sessions + all API tokens** (force re-auth everywhere);
   clears cookie.
 - **`GET /verify`** — empty-body session-validity probe for nginx
@@ -1212,7 +1223,7 @@ gets `require_auth` when `account === 'required'` or `actor === 'required'`;
 `post_authorization` gets `require_credential_types(types)` when
 `credential_types?.length` and `require_role(roles)` when `roles?.length`.
 Injected into `apply_route_specs` so the generic HTTP framework stays
-auth-agnostic (see `../http/CLAUDE.md` §Validation pipeline for where it plugs in).
+auth-agnostic (see `http/CLAUDE.md` §Validation pipeline for where it plugs in).
 
 ### `audit_log_routes.ts`
 
@@ -1232,7 +1243,7 @@ module produces is now just the optional SSE stream:
 ## RPC actions (SAES)
 
 Three action surfaces that mount on a consumer's JSON-RPC endpoint via
-`create_rpc_endpoint` (see `../actions/CLAUDE.md` §Single JSON-RPC 2.0 endpoint).
+`create_rpc_endpoint` (see `actions/CLAUDE.md` §Single JSON-RPC 2.0 endpoint).
 Each surface is split across two files:
 
 - `*_action_specs.ts` — Input/Output Zod schemas (paired with `z.infer` type
@@ -1327,6 +1338,19 @@ Closure state:
   When absent, those two specs are still present in `all_admin_action_specs`
   (surface-wise) but the handlers are not wired — RPC dispatch returns
   `method_not_found`.
+- `options.connection_closer?: ConnectionCloser | null` — when set,
+  `admin_session_revoke_all` and `admin_token_revoke_all` handlers
+  eagerly close the target account's live WS sockets via
+  `close_sockets_for_account(input.account_id)` BEFORE emitting the
+  audit event. Failure outcomes (404 account-not-found) skip the
+  eager close. Listener-based close
+  (`transports_ws_auth_guard` on `audit.on_event_chain`) stays as a
+  fail-safe; primitives are idempotent. Symmetric with the
+  self-service surface (see `AccountActionOptions.connection_closer`
+  below). `BackendWebsocketTransport` satisfies the interface
+  structurally. Mirrors `zzz_server`'s parity pass — fuz_app widens
+  to admin-side too (Rust port's catch-up tracked in
+  `~/dev/zzz/TODO_RUST_SERVER_DETAILS.md`).
 
 `all_admin_action_specs: Array<RequestResponseActionSpec>` — codegen-ready
 registry of all eleven specs (always includes the two app-settings specs).
@@ -1413,16 +1437,16 @@ Error reason constants (exported as `as const` literals):
 - `ERROR_ROLE_GRANT_OFFER_ACTOR_MISMATCH` (`'role_grant_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_ROLE_GRANT_NOT_FOUND`,
+Plus re-uses from `http/error_schemas.ts`: `ERROR_ROLE_GRANT_NOT_FOUND`,
 `ERROR_ROLE_NOT_WEB_GRANTABLE`, `ERROR_INSUFFICIENT_PERMISSIONS`,
 `ERROR_ACCOUNT_NOT_FOUND`.
 
 Each spec declares the reason codes its handler may surface (see
-`../actions/CLAUDE.md` §Action specs for the field semantics). Only
+`actions/CLAUDE.md` §Action specs for the field semantics). Only
 domain reasons returned via `error.data.reason` are listed; standard
 transport errors (validation, auth, rate-limit) stay implicit. Drift
 between declared reasons and handler throws is caught by
-`../../test/auth/role_grant_offer_actions.error_reasons.test.ts`.
+../../test/auth/role_grant_offer_actions.error_reasons.test.ts.
 
 Failure-outcome audit events emitted (success and failure rows both carry
 `ip: ctx.client_ip` — uniform with the admin and self-service surfaces):
@@ -1442,8 +1466,8 @@ Failure-outcome audit events emitted (success and failure rows both carry
   role_grant).
 
 WS notifications (post-commit via `emit_after_commit` from
-`../http/pending_effects.js` — swallows exceptions so one failed send
-can't starve others; see `../http/CLAUDE.md` §Pending Effects):
+`http/pending_effects.js` — swallows exceptions so one failed send
+can't starve others; see `http/CLAUDE.md` §Pending Effects):
 
 - Create → `role_grant_offer_received` to recipient.
 - Retract → `role_grant_offer_retracted` to recipient.
@@ -1490,6 +1514,8 @@ surface drop down to the per-domain factories directly.
 Option routing: `roles` is shared between admin and role-grant-offer;
 `app_settings` flows to admin only; `default_ttl_ms` and `authorize`
 flow to role-grant-offer only; `max_tokens` flows to account only;
+`connection_closer` is shared between admin and account (handler-side
+eager WS close on revoke; role-grant-offer ignores);
 `notification_sender` is wired through to role-grant-offer (admin +
 account ignore it).
 
@@ -1506,7 +1532,7 @@ Pair this with `create_app_server`'s `rpc_endpoints` factory form
 (`(ctx) => Array<RpcEndpointSpec>`) so the combined action list gets
 `ctx.deps` + `ctx.app_settings` — `create_app_server` auto-mounts the
 endpoint via `create_rpc_endpoint`, so consumers don't need to mount it
-again in `create_route_specs`. See `../../../docs/usage.md` §Server
+again in `create_route_specs`. See ../../../docs/usage.md §Server
 Assembly.
 
 Pre-bundle consumers spread `create_admin_actions` and
@@ -1519,20 +1545,43 @@ consumer wiring the admin surface without account actions will hit
 `method not found` on first admin-suite run.
 
 Frontend mirror: `all_standard_action_specs` (in
-`./standard_action_specs.ts`) bundles `all_admin_action_specs +
+`auth/standard_action_specs.ts`) bundles `all_admin_action_specs +
 all_role_grant_offer_action_specs + all_account_action_specs` into one
 `ReadonlyArray<RequestResponseActionSpec>` for typed-client codegen
 and `create_frontend_rpc_client({specs})` wiring. Self-service role
 specs are not included (opt-in, app-specific `eligible_roles`) —
 spread `all_self_service_role_action_specs` separately when needed.
 
+To expose the standard surface over WebSocket as well as HTTP RPC,
+spread `protocol_actions` and `create_standard_rpc_actions(ctx.deps,
+opts)` into `create_app_server`'s `ws_endpoints` factory alongside the
+matching `rpc_endpoints` entry:
+
+```ts
+ws_endpoints: (ctx) => [{
+  path: '/api/ws',
+  allowed_origins,
+  actions: [
+    ...protocol_actions,
+    ...create_standard_rpc_actions(ctx.deps, opts),
+    ...consumer_local_actions,
+  ],
+}],
+```
+
+The same action factory powers both surfaces; per-message authorization
+and rate limiting fire identically across HTTP RPC and WS. With both
+endpoints mounted, a typed frontend client can route per-method via
+`transport_for_method` (e.g. `account_*` over WS for live revocation
+detection, admin reads over HTTP).
+
 ### `all_action_spec_registries.ts` — walker-only registry-of-registries
 
 `all_fuz_auth_action_spec_registries` — walker/codegen entry for every
 fuz-auth action-spec bundle (`admin`, `role_grant_offer`, `account`,
 `self_service_role`, `actor_lookup`, `actor_search`). Not a mounting
 surface; protocol specs are excluded. Iterated by registry-wide
-invariant tests in `../../test/auth/`.
+invariant tests in ../../test/auth/.
 
 ### `account_action_specs.ts` + `account_actions.ts` — seven self-service RPC actions
 
@@ -1553,6 +1602,18 @@ operations are account-scoped via `query_session_revoke_for_account` /
 or token id returns `revoked: false` rather than revealing whether the id
 exists.
 
+**Credential-channel gating** — `account_token_create`,
+`account_token_revoke`, `account_session_revoke`, and
+`account_session_revoke_all` declare `credential_types: ['session']`
+on their `auth` axis (same gate as REST `POST /password`).
+`account_session_revoke` is gated alongside `_revoke_all` because a
+leaked bearer can otherwise compose `account_session_list` + N×revoke
+to reach the same lockout. Admin token/session revoke specs in
+`admin_action_specs.ts` deliberately stay unrestricted (admin
+scripting from CLI/bearer is legitimate operator workflow). For the
+threat model, the trust-bar rationale, and the defense-in-depth audit
+metadata see `docs/security.md` §Credential-channel gating.
+
 | Spec                                     | Side effects | Rate limit  | Input          | Output                  |
 | ---------------------------------------- | ------------ | ----------- | -------------- | ----------------------- |
 | `account_verify_action_spec`             | false        |             | `z.void()`     | `SessionAccountJson`    |
@@ -1577,11 +1638,31 @@ vector, so rate caps are symmetry-only and skipped.
 Audit events emitted (via `deps.audit.emit` with `ip: ctx.client_ip`):
 `session_revoke`, `session_revoke_all`, `token_create`, `token_revoke`. The
 IP is the resolved trusted-proxy value from `ActionContext.client_ip`,
-matching the REST handler convention.
+matching the REST handler convention. Every gated event additionally
+records `credential_type` (read from `ActionContext.credential_type`)
+in metadata — defense in depth so forensics survive if the
+`credential_types: ['session']` spec gate is ever loosened or bypassed.
+The REST `password_change` audit row mirrors the same field on all
+three outcomes (success, wrong-password, concurrent-change).
 
 Deps: `Pick<RouteFactoryDeps, 'log' | 'audit'>`.
-Options: `{max_tokens?: number | null}` — defaults to `DEFAULT_MAX_TOKENS`
-from `account_routes.ts`; `null` disables the cap.
+Options: `{max_tokens?: number | null, connection_closer?: ConnectionCloser | null}`.
+`max_tokens` defaults to `DEFAULT_MAX_TOKENS` from `account_routes.ts`;
+`null` disables the cap. `connection_closer` (from
+`actions/connection_closer.ts`) wires handler-side eager WS socket
+closure: `account_session_revoke` calls `close_sockets_for_session(input.session_id)`,
+`_session_revoke_all` calls `close_sockets_for_account(account.id)`,
+`account_token_revoke` calls `close_sockets_for_token(input.token_id)` —
+each fires synchronously BEFORE the audit emit so revocation lands even
+when the audit INSERT fails. Listener-based close
+(`transports_ws_auth_guard` on `audit.on_event_chain`) stays as a
+fail-safe; close primitives are idempotent. Failure outcomes
+(`revoked: false`) skip the eager close — mirrors the listener's
+`outcome === 'failure'` guard so attacker-guessable ids can't be used to
+target arbitrary sockets. `BackendWebsocketTransport` satisfies
+`ConnectionCloser` structurally — consumers pass the WS transport
+instance directly. Mirrors `zzz_server::handlers/account.rs` (landed
+2026-05-16).
 
 `all_account_action_specs: Array<RequestResponseActionSpec>` — codegen-ready
 registry of all seven specs.
@@ -1698,7 +1779,7 @@ One static `request_response` action — `actor_search({query, scope_ids?, limit
 powers person-target pickers. Sibling to `actor_lookup`: that resolves a
 batch of known ids to labels; this resolves a partial name to candidate
 actors. Reuses `ActorLookupEntryJson` from
-`./actor_lookup_action_specs.ts` so the labels arc on the consumer side
+`auth/actor_lookup_action_specs.ts` so the labels arc on the consumer side
 stays uniform. Default limit `ACTOR_SEARCH_LIMIT_DEFAULT = 20`, hard cap
 `ACTOR_SEARCH_LIMIT_MAX = 50`. Query string capped at
 `ACTOR_SEARCH_QUERY_LENGTH_MAX = 50`.
@@ -1789,15 +1870,19 @@ resulting role_grant.
   - `db: Db` — pool-level instance (middleware uses this; route handlers
     get a transaction-scoped `Db` via `RouteContext`).
   - `log: Logger`.
-  - `audit: AuditEmitter` — bound emitter built once at `create_app_backend`
-    via `create_audit_emitter`. Closes over the pool, the
+  - `audit: AuditEmitter` — bound emitter built once by the consumer's
+    `audit_factory` callback on `CreateAppBackendOptions`. The factory
+    runs after `create_db` resolves and migrations apply;
+    `create_app_backend` invokes it with `{db, log}` and lands the
+    returned emitter on `deps.audit`. The canonical body is one line
+    over `create_audit_emitter` (closes over the pool, the
     `on_audit_event` subscriber chain, and the optional
-    `AuditLogConfig` so handlers reach `audit.emit(ctx, input)` /
+    `AuditLogConfig`); consumers wrap or replace it for tests. Handlers
+    reach `audit.emit(ctx, input)` /
     `audit.emit_role_grant_target(ctx, auth, input)` and never see the
-    pool. Pass `on_audit_event` and `audit_log_config` to
-    `create_app_backend` — both fold into `audit`'s closure and the slot
-    is the single seam for SSE/WS fan-out (additional listeners append
-    via `audit.on_event_chain.push(...)` at server assembly).
+    pool. The slot is the single seam for SSE/WS fan-out — additional
+    listeners append via `audit.on_event_chain.push(...)` at server
+    assembly.
 - **`RouteFactoryDeps = Omit<AppDeps, 'db'>`** — for route factories. Route
   handlers receive DB access via `RouteContext`, so factories don't capture
   a pool-level `Db`.
@@ -1805,5 +1890,5 @@ resulting role_grant.
 Action factories take `Pick<RouteFactoryDeps, 'log' | 'audit'>` directly
 (role-grant-offer adds `notification_sender?` inline).
 
-See root `../../../CLAUDE.md` §AppDeps Vocabulary for the
+See root ../../../CLAUDE.md §AppDeps Vocabulary for the
 capability / options / runtime-state split across the whole project.

package/dist/auth/account_action_specs.d.ts

@@ -98,7 +98,7 @@ export declare const account_verify_action_spec: {
     input: z.ZodVoid;
     output: z.ZodObject<{
         id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
-        username: z.ZodString;
+        username: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
         email: z.ZodNullable<z.ZodEmail>;
         email_verified: z.ZodBoolean;
         created_at: z.ZodString;
@@ -135,6 +135,7 @@ export declare const account_session_revoke_action_spec: {
     auth: {
         account: "required";
         actor: "none";
+        credential_types: string[];
     };
     side_effects: true;
     input: z.ZodObject<{
@@ -154,6 +155,7 @@ export declare const account_session_revoke_all_action_spec: {
     auth: {
         account: "required";
         actor: "none";
+        credential_types: string[];
     };
     side_effects: true;
     input: z.ZodVoid;
@@ -165,6 +167,8 @@ export declare const account_session_revoke_all_action_spec: {
     description: string;
 };
 /**
+ * `credential_types: ['session']` — see `docs/security.md` §Credential-channel gating.
+ *
  * `rate_limit: 'account'` bounds the burn rate of API-token creates. The
  * outstanding-token count is already capped by `max_tokens` (via
  * `query_api_token_enforce_limit`), but the per-account *rate* of churn
@@ -179,6 +183,7 @@ export declare const account_token_create_action_spec: {
     auth: {
         account: "required";
         actor: "none";
+        credential_types: string[];
     };
     side_effects: true;
     input: z.ZodPrefault<z.ZodObject<{
@@ -225,6 +230,7 @@ export declare const account_token_revoke_action_spec: {
     auth: {
         account: "required";
         actor: "none";
+        credential_types: string[];
     };
     side_effects: true;
     input: z.ZodObject<{

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

@@ -1 +1 @@
-{"version":3,"file":"account_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_action_specs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"account_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_action_specs.ts"],"names":[],"mappings":"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"}