@fuzdev/fuz_app 0.140.0 → 0.142.0

package/dist/actions/transports.js

@@ -8,7 +8,8 @@
  */
 import { z } from 'zod';
 /**
- * WebSocket close code for session revocation.
+ * WebSocket close code for session revocation — and for a credential that
+ * expired while the socket was open (`WS_CLOSE_CREDENTIAL_EXPIRED_REASON`).
  *
  * Also the close for an upgrade refused at admission because its credential
  * was revoked while the upgrade was in flight (`register_action_ws`) — the
@@ -21,6 +22,15 @@ export const WS_CLOSE_SESSION_REVOKED = 4001;
  * indistinguishable on the wire. The Rust spine sends the same text.
  */
 export const WS_CLOSE_SESSION_REVOKED_REASON = 'Session revoked';
+/**
+ * The close reason sent with `WS_CLOSE_SESSION_REVOKED` when the socket's
+ * credential expired while it was open — its session or API token passed its
+ * expiry (`ResolvedAuth.credential_deadline`). The code is the revocation's on
+ * purpose: the client cannot reconnect on the credential either way, so
+ * `FrontendWebsocketClient` enters the same `revoked` state. The Rust spine
+ * sends the same text.
+ */
+export const WS_CLOSE_CREDENTIAL_EXPIRED_REASON = 'Credential expired';
 /** WebSocket close code — client timed out waiting for a response. */
 export const WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002;
 /** WebSocket close code — server timed out with no incoming activity. */
@@ -61,6 +71,25 @@ export const WS_CLOSE_OUTBOUND_OVERFLOW = 4005;
  * sends the same text.
  */
 export const WS_CLOSE_OUTBOUND_OVERFLOW_REASON = 'outbound queue overflow';
+/**
+ * WebSocket close code — the socket's account lost a role its endpoint
+ * requires (`register_ws_endpoint`'s `required_roles`): a global grant of one
+ * of those roles was revoked while the socket was open, or while its upgrade
+ * was in flight (the admission re-read, `register_action_ws`). Nothing more
+ * is sent on the socket.
+ *
+ * Distinct from `WS_CLOSE_SESSION_REVOKED`: the credential is still good, so
+ * a client must not enter its `revoked` state — but a reconnect would be
+ * refused at the role gate, so `FrontendWebsocketClient` stays closed until
+ * `connect()` is called and rejects its pending work as `forbidden`. The twin
+ * of the Rust spine's `WS_CLOSE_PERMISSION_REVOKED`.
+ */
+export const WS_CLOSE_PERMISSION_REVOKED = 4006;
+/**
+ * The close reason sent with `WS_CLOSE_PERMISSION_REVOKED`, mid-life and at
+ * admission alike. The Rust spine sends the same text.
+ */
+export const WS_CLOSE_PERMISSION_REVOKED_REASON = 'Permission revoked';
 /**
  * WebSocket close code — the server is shutting down (RFC 6455 §7.4.1 "Going
  * Away"). Sent to every live socket by `close_all_sockets`, which

package/dist/actions/transports_ws_auth_guard.d.ts

@@ -28,11 +28,16 @@
  * two cannot drift into closing a revoked token's socket while leaving its
  * stream open.
  *
- * `role` is the one scope this guard deliberately does not act on:
- * `perform_action` re-authorizes every message, so a socket whose account just
- * lost the gating role is refused at its next message, and closing it would
- * only change when the caller learns. A stream has no later check, so the SSE
- * guard closes there.
+ * `role` closes the target account's sockets whose endpoint gated the upgrade
+ * on the revoked role (`close_sockets_for_role`), with
+ * `WS_CLOSE_PERMISSION_REVOKED`, when the revoked grant was global
+ * (`to_global_role_revocation` — a role gate admits on global grants only).
+ * `perform_action` re-authorizes every *request* against its own action, but
+ * the role gate is the only check on what the socket *receives*: broadcasts
+ * and notifications reach every admitted connection of the endpoint with no
+ * per-recipient filter, so a socket left open past the revocation would keep
+ * receiving what the gate exists to withhold. The role is the only revocation
+ * no handler closes for, so this guard is its one closer.
  *
  * For standard WS endpoints mounted via `AppServerOptions.ws_endpoints`,
  * `create_app_server` registers the guard automatically per
@@ -66,7 +71,9 @@ export type AuditEventHandler = (event: AuditLogEvent) => void;
  * - `account` → `close_sockets_for_account(target_account_id ?? account_id)`
  *   — `logout`, `password_change`, `session_revoke_all`, `token_revoke_all`,
  *   `account_delete`, `account_purge`
- * - `role` → nothing, deliberately (module doc)
+ * - `role` → `close_sockets_for_role(target_account_id ?? account_id,
+ *   metadata.role)` when the revoked grant was global; a scoped revoke closes
+ *   nothing (module doc)
  * - `none` → nothing — every other event, and any event type fuz_app does not
  *   define
  *

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,gBAAgB,EAAE,KAAK,MAAM,KAAG,iBAoD5E,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,gBAAgB,EAAE,KAAK,MAAM,KAAG,iBA4D5E,CAAC"}

package/dist/actions/transports_ws_auth_guard.js

@@ -28,11 +28,16 @@
  * two cannot drift into closing a revoked token's socket while leaving its
  * stream open.
  *
- * `role` is the one scope this guard deliberately does not act on:
- * `perform_action` re-authorizes every message, so a socket whose account just
- * lost the gating role is refused at its next message, and closing it would
- * only change when the caller learns. A stream has no later check, so the SSE
- * guard closes there.
+ * `role` closes the target account's sockets whose endpoint gated the upgrade
+ * on the revoked role (`close_sockets_for_role`), with
+ * `WS_CLOSE_PERMISSION_REVOKED`, when the revoked grant was global
+ * (`to_global_role_revocation` — a role gate admits on global grants only).
+ * `perform_action` re-authorizes every *request* against its own action, but
+ * the role gate is the only check on what the socket *receives*: broadcasts
+ * and notifications reach every admitted connection of the endpoint with no
+ * per-recipient filter, so a socket left open past the revocation would keep
+ * receiving what the gate exists to withhold. The role is the only revocation
+ * no handler closes for, so this guard is its one closer.
  *
  * For standard WS endpoints mounted via `AppServerOptions.ws_endpoints`,
  * `create_app_server` registers the guard automatically per
@@ -45,7 +50,7 @@
  * @module
  */
 import { UnreachableError } from '@fuzdev/fuz_util/error.ts';
-import { to_revocation_scope } from '../auth/audit_log_schema.js';
+import { to_global_role_revocation, to_revocation_scope } from '../auth/audit_log_schema.js';
 /**
  * Create an audit event handler that closes connections on a successful
  * revocation row, dispatching on the event's `RevocationScope`:
@@ -55,7 +60,9 @@ import { to_revocation_scope } from '../auth/audit_log_schema.js';
  * - `account` → `close_sockets_for_account(target_account_id ?? account_id)`
  *   — `logout`, `password_change`, `session_revoke_all`, `token_revoke_all`,
  *   `account_delete`, `account_purge`
- * - `role` → nothing, deliberately (module doc)
+ * - `role` → `close_sockets_for_role(target_account_id ?? account_id,
+ *   metadata.role)` when the revoked grant was global; a scoped revoke closes
+ *   nothing (module doc)
  * - `none` → nothing — every other event, and any event type fuz_app does not
  *   define
  *
@@ -81,10 +88,17 @@ export const create_ws_auth_guard = (closer, log) => {
         switch (scope) {
             case 'none':
                 return;
-            // A decision, not a fallthrough: per-message dispatch re-authorizes,
-            // so the next message is refused. The SSE guard closes on this scope.
-            case 'role':
+            case 'role': {
+                // global grants only — a role gate never admitted on a scoped one
+                const revoked = to_global_role_revocation(event);
+                if (!revoked)
+                    return;
+                const closed = closer.close_sockets_for_role(revoked.account_id, revoked.role);
+                if (closed > 0) {
+                    log.info(`WS auth guard: closed ${closed} socket(s) gated on ${revoked.role} for account ${revoked.account_id} (${event.event_type})`);
+                }
                 return;
+            }
             case 'session': {
                 const session_id = event.metadata?.session_id;
                 if (typeof session_id !== 'string' || session_id.length === 0)

package/dist/actions/transports_ws_backend.d.ts

@@ -124,7 +124,10 @@ import { type PeerRequestOptions, type PeerRequestOutcome } from './peer_request
  * One record per connection. `token_hash` is set for cookie-session
  * connections, `api_token_id` for bearer (`api_token`) connections, and
  * both are null for daemon-token connections (reachable only via
- * `BackendWebsocketTransport.close_sockets_for_account`).
+ * `BackendWebsocketTransport.close_sockets_for_account`). `required_roles`
+ * is what the connection's endpoint gated the upgrade on, kept per
+ * registration because endpoints with different gates can share one
+ * transport.
  */
 export interface ConnectionIdentity {
     /** Blake3 session token hash, or null for non-session credentials. */
@@ -133,6 +136,11 @@ export interface ConnectionIdentity {
     account_id: Uuid;
     /** `api_token.id` for bearer-authenticated connections, else null. */
     api_token_id: string | null;
+    /**
+     * The roles the endpoint required at upgrade (any-of), or empty for an
+     * ungated endpoint — what `close_sockets_for_role` matches on.
+     */
+    required_roles: ReadonlyArray<string>;
 }
 /**
  * Structural capability for transports that can broadcast with a
@@ -227,8 +235,9 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      *
      * The entry is closeable at once: a `close_sockets_for_*` matching
      * `token_hash` / `account_id` / `api_token_id` removes it, aborts
-     * `abort_controller`, and closes `ws` with `WS_CLOSE_SESSION_REVOKED`; the
-     * later `admit` then refuses. Until admitted it evicts nothing, is not
+     * `abort_controller`, and closes `ws` with `WS_CLOSE_SESSION_REVOKED`
+     * (`close_sockets_for_role`, matching `required_roles`, with
+     * `WS_CLOSE_PERMISSION_REVOKED`); the later `admit` then refuses. Until admitted it evicts nothing, is not
      * counted toward the per-account cap, and receives no message.
      *
      * The caller owns the entry until it is admitted: a refusal closes it with
@@ -246,11 +255,27 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * @param api_token_id - `api_token.id` for bearer connections, else `null`
      * @param abort_controller - the socket-scoped controller to abort when the
      *   transport closes this connection (revocation or cap eviction)
+     * @param required_roles - the roles the endpoint gated the upgrade on, for
+     *   `close_sockets_for_role`; empty for an ungated endpoint
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
      * @mutates this - inserts an un-admitted entry into `#connections`, unless
      *   the transport is closing
      */
-    register_pending(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null): Uuid;
+    register_pending(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null, required_roles?: ReadonlyArray<string>): Uuid;
+    /**
+     * The close code the transport closed a still-pending registration with —
+     * `WS_CLOSE_SESSION_REVOKED` for a credential revocation,
+     * `WS_CLOSE_PERMISSION_REVOKED` for a role close, `WS_CLOSE_GOING_AWAY`
+     * for the shutdown — read once: the record is dropped by this call (and by
+     * `remove_connection`). `null` when the transport did not close it while
+     * pending. For a caller whose `admit` was refused, to say why; the twin of
+     * the reason the Rust `ConnectionRegistry::admit` refuses with.
+     *
+     * @param connection_id - the id `register_pending` returned
+     * @returns the close code, or `null`
+     * @mutates this - drops the recorded code
+     */
+    take_pending_close_code(connection_id: Uuid): number | null;
     /**
      * Admit a pending connection — phase two (module doc).
      *
@@ -294,12 +319,14 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * connection is always admitted — unless the transport is closing: then it
      * is born closed, as in `register_pending`, and evicts nothing.
      *
+     * @param required_roles - the roles the endpoint gated the connection on,
+     *   for `close_sockets_for_role`; empty for an ungated one
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
      * @mutates this - inserts an admitted entry into `#connections`; past the
      *   cap, first removes the account's oldest admitted connections and closes
      *   their `WSContext`
      */
-    add_connection(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null): Uuid;
+    add_connection(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null, required_roles?: ReadonlyArray<string>): Uuid;
     /**
      * Remove a connection and its auth tracking data, pending or admitted, by
      * the id `register_pending` / `add_connection` returned. Idempotent — safe
@@ -376,6 +403,25 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      *   `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_token(api_token_id: string): number;
+    /**
+     * Close the sockets of `account_id` whose endpoint required `role`,
+     * including a registration still pending admission — the close for a
+     * revoked global grant of a role the upgrade gate admitted on. Each closes
+     * with `WS_CLOSE_PERMISSION_REVOKED`, not a revocation's code: the
+     * credential is still good.
+     *
+     * **Over-closes an any-of gate.** An endpoint gated on several roles admits
+     * an account holding any one of them, but this closes on the loss of any
+     * listed role, without checking whether the account still holds another.
+     * The client can reconnect when it still qualifies. The account's sockets
+     * on endpoints that did not list `role`, and on ungated ones, stay open.
+     *
+     * @returns the number of sockets closed
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_PERMISSION_REVOKED`
+     */
+    close_sockets_for_role(account_id: Uuid, role: string): number;
     /**
      * Close every connection, pending or admitted, with `WS_CLOSE_GOING_AWAY` —
      * the shutdown close `AppServer.close` runs. Not a revocation: the client

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

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiHG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,KAAK,EAEX,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,EASN,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,MAAM,mBAAmB,CAAC;AAU3B;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA6B,SAAQ,SAAS;IAC9D,kBAAkB,EAAE,CACnB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,KAChD,MAAM,CAAC;CACZ;AAED,qDAAqD;AACrD,eAAO,MAAM,iCAAiC,GAC7C,WAAW,SAAS,KAClB,SAAS,IAAI,4BAEqE,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mCAAmC,KAAK,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,+BAA+B,QAAkB,CAAC;AAE/D,+CAA+C;AAC/C,MAAM,WAAW,gCAAgC;IAChD;;;;;;;;;;;;;;OAcG;IACH,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAuBD,qBAAa,yBAA0B,YAAW,4BAA4B;;IAC7E,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IA8B3D;;;OAGG;gBACS,OAAO,CAAC,EAAE,gCAAgC;IAuBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,gBAAgB,CACf,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,EAClC,gBAAgB,GAAE,eAAe,GAAG,IAAW,GAC7C,IAAI;IAKP;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,aAAa,EAAE,IAAI,GAAG,OAAO;IAanC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,EAClC,gBAAgB,GAAE,eAAe,GAAG,IAAW,GAC7C,IAAI;IAgCP;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,iBAAiB,CAAC,aAAa,EAAE,IAAI,GAAG,IAAI;IAW5C;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAqD5E;;;;;;;;OAQG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;;;;;OAQG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;;;;;OAYG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,IAAI,MAAM;IAQ3B;;;;;OAKG;IACH,UAAU,IAAI,OAAO;IA2If,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA2CvC;;;;;;;;;;;;;OAaG;IACH,kBAAkB,CACjB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,GAClD,MAAM;IAYT;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,gCAAgC,GAAG,MAAM;IAIpF;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,aAAa,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAMpD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAAkB,CACjB,aAAa,EAAE,IAAI,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,oBAAoB,GAAG,SAAS,EACxC,OAAO,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,kBAAkB,CAAC;IA2B9B;;;;;;;;;;OAUG;IACH,qBAAqB,CACpB,aAAa,EAAE,IAAI,EACnB,QAAQ,EAAE,eAAe,GAAG,oBAAoB,GAC9C,OAAO;IAIV;;;;;;;;;OASG;IACH,aAAa,CAAC,aAAa,EAAE,IAAI,GAAG,OAAO;IAI3C,QAAQ,IAAI,OAAO;IAInB;;;;;;;;OAQG;IACH,oBAAoB,IAAI,MAAM;IAQ9B;;;;;OAKG;IACH,4BAA4B,IAAI,MAAM;CAOtC"}
+{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"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"}

package/dist/actions/transports_ws_backend.js

@@ -117,7 +117,7 @@ import { Logger } from '@fuzdev/fuz_util/log.ts';
 import { create_uuid } from '../primitive_schemas.js';
 import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, create_jsonrpc_request, to_jsonrpc_message_id, is_jsonrpc_request } from '../http/jsonrpc_helpers.js';
-import { WS_CLOSE_CONNECTION_LIMIT, WS_CLOSE_GOING_AWAY, WS_CLOSE_GOING_AWAY_REASON, WS_CLOSE_OUTBOUND_OVERFLOW, WS_CLOSE_OUTBOUND_OVERFLOW_REASON, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON, utf8_length } from './transports.js';
+import { WS_CLOSE_CONNECTION_LIMIT, WS_CLOSE_GOING_AWAY, WS_CLOSE_GOING_AWAY_REASON, WS_CLOSE_OUTBOUND_OVERFLOW, WS_CLOSE_OUTBOUND_OVERFLOW_REASON, WS_CLOSE_PERMISSION_REVOKED, WS_CLOSE_PERMISSION_REVOKED_REASON, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON, utf8_length } from './transports.js';
 import { PendingPeerRequests } from './peer_request.js';
 import { WsOutboundWriter } from './ws_outbound_writer.js';
 /** Type guard for `FilterableBroadcastTransport`. */
@@ -163,6 +163,10 @@ export class BackendWebsocketTransport {
     // close arrives (`remove_connection`) or the close deadline passes — so the
     // deadline timer is cleared when the socket goes.
     #closing_writers = new Map();
+    // The close code each registration the transport closed while it was still
+    // pending got, until `take_pending_close_code` or `remove_connection` drops
+    // it — so a refused admission can say why it was refused.
+    #pending_close_codes = new Map();
     // set once by `close_all_sockets`, never cleared — every later
     // registration is born closed (module doc, "Shutdown")
     #closing = false;
@@ -197,8 +201,9 @@ export class BackendWebsocketTransport {
      *
      * The entry is closeable at once: a `close_sockets_for_*` matching
      * `token_hash` / `account_id` / `api_token_id` removes it, aborts
-     * `abort_controller`, and closes `ws` with `WS_CLOSE_SESSION_REVOKED`; the
-     * later `admit` then refuses. Until admitted it evicts nothing, is not
+     * `abort_controller`, and closes `ws` with `WS_CLOSE_SESSION_REVOKED`
+     * (`close_sockets_for_role`, matching `required_roles`, with
+     * `WS_CLOSE_PERMISSION_REVOKED`); the later `admit` then refuses. Until admitted it evicts nothing, is not
      * counted toward the per-account cap, and receives no message.
      *
      * The caller owns the entry until it is admitted: a refusal closes it with
@@ -216,14 +221,36 @@ export class BackendWebsocketTransport {
      * @param api_token_id - `api_token.id` for bearer connections, else `null`
      * @param abort_controller - the socket-scoped controller to abort when the
      *   transport closes this connection (revocation or cap eviction)
+     * @param required_roles - the roles the endpoint gated the upgrade on, for
+     *   `close_sockets_for_role`; empty for an ungated endpoint
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
      * @mutates this - inserts an un-admitted entry into `#connections`, unless
      *   the transport is closing
      */
-    register_pending(ws, token_hash, account_id, api_token_id = null, abort_controller = null) {
+    register_pending(ws, token_hash, account_id, api_token_id = null, abort_controller = null, required_roles = []) {
         if (this.#closing)
             return this.#close_born_closed(ws, abort_controller);
-        return this.#insert(ws, token_hash, account_id, api_token_id, abort_controller, false);
+        return this.#insert(ws, { token_hash, account_id, api_token_id, required_roles }, abort_controller, false);
+    }
+    /**
+     * The close code the transport closed a still-pending registration with —
+     * `WS_CLOSE_SESSION_REVOKED` for a credential revocation,
+     * `WS_CLOSE_PERMISSION_REVOKED` for a role close, `WS_CLOSE_GOING_AWAY`
+     * for the shutdown — read once: the record is dropped by this call (and by
+     * `remove_connection`). `null` when the transport did not close it while
+     * pending. For a caller whose `admit` was refused, to say why; the twin of
+     * the reason the Rust `ConnectionRegistry::admit` refuses with.
+     *
+     * @param connection_id - the id `register_pending` returned
+     * @returns the close code, or `null`
+     * @mutates this - drops the recorded code
+     */
+    take_pending_close_code(connection_id) {
+        const code = this.#pending_close_codes.get(connection_id);
+        if (code === undefined)
+            return null;
+        this.#pending_close_codes.delete(connection_id);
+        return code;
     }
     /**
      * Admit a pending connection — phase two (module doc).
@@ -281,24 +308,26 @@ export class BackendWebsocketTransport {
      * connection is always admitted — unless the transport is closing: then it
      * is born closed, as in `register_pending`, and evicts nothing.
      *
+     * @param required_roles - the roles the endpoint gated the connection on,
+     *   for `close_sockets_for_role`; empty for an ungated one
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
      * @mutates this - inserts an admitted entry into `#connections`; past the
      *   cap, first removes the account's oldest admitted connections and closes
      *   their `WSContext`
      */
-    add_connection(ws, token_hash, account_id, api_token_id = null, abort_controller = null) {
+    add_connection(ws, token_hash, account_id, api_token_id = null, abort_controller = null, required_roles = []) {
         if (this.#closing)
             return this.#close_born_closed(ws, abort_controller);
         if (this.#max_connections_per_account !== null) {
             this.#evict_oldest_for_account(account_id, this.#max_connections_per_account);
         }
-        return this.#insert(ws, token_hash, account_id, api_token_id, abort_controller, true);
+        return this.#insert(ws, { token_hash, account_id, api_token_id, required_roles }, abort_controller, true);
     }
-    #insert(ws, token_hash, account_id, api_token_id, abort_controller, admitted) {
+    #insert(ws, identity, abort_controller, admitted) {
         const connection_id = create_uuid();
         this.#connections.set(connection_id, {
             ws,
-            identity: { token_hash, account_id, api_token_id },
+            identity,
             admitted,
             abort_controller,
             writer: new WsOutboundWriter({
@@ -333,6 +362,7 @@ export class BackendWebsocketTransport {
      *   requests as `connection_gone`
      */
     remove_connection(connection_id) {
+        this.#pending_close_codes.delete(connection_id);
         this.#connections.get(connection_id)?.writer.dispose();
         // a connection the transport closed: its socket is gone now
         const closing = this.#closing_writers.get(connection_id);
@@ -451,6 +481,27 @@ export class BackendWebsocketTransport {
     close_sockets_for_token(api_token_id) {
         return this.#close_where((id) => id.api_token_id === api_token_id);
     }
+    /**
+     * Close the sockets of `account_id` whose endpoint required `role`,
+     * including a registration still pending admission — the close for a
+     * revoked global grant of a role the upgrade gate admitted on. Each closes
+     * with `WS_CLOSE_PERMISSION_REVOKED`, not a revocation's code: the
+     * credential is still good.
+     *
+     * **Over-closes an any-of gate.** An endpoint gated on several roles admits
+     * an account holding any one of them, but this closes on the loss of any
+     * listed role, without checking whether the account still holds another.
+     * The client can reconnect when it still qualifies. The account's sockets
+     * on endpoints that did not list `role`, and on ungated ones, stay open.
+     *
+     * @returns the number of sockets closed
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_PERMISSION_REVOKED`
+     */
+    close_sockets_for_role(account_id, role) {
+        return this.#close_where((id) => id.account_id === account_id && id.required_roles.includes(role), WS_CLOSE_PERMISSION_REVOKED, WS_CLOSE_PERMISSION_REVOKED_REASON);
+    }
     /**
      * Close every connection, pending or admitted, with `WS_CLOSE_GOING_AWAY` —
      * the shutdown close `AppServer.close` runs. Not a revocation: the client
@@ -511,6 +562,8 @@ export class BackendWebsocketTransport {
     }
     #end_connection(connection_id, entry, code, reason, backlog = 'flush') {
         this.#cleanup_connection(connection_id);
+        if (!entry.admitted)
+            this.#pending_close_codes.set(connection_id, code);
         // abort before the close so a handler observing `ctx.signal` bails out
         // without waiting for the close handshake
         entry.abort_controller?.abort();

package/dist/actions/ws_endpoint_spec.d.ts

@@ -46,10 +46,12 @@ export interface WsEndpointSpec {
      */
     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 an admin-only WS endpoint.
+     * Roles permitted to upgrade — any-of disjunction, global grants only.
+     * 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 an admin-only WS endpoint.
+     * Held for the socket's life — see `register_ws_endpoint`'s
+     * `required_roles`.
      */
     required_roles?: ReadonlyArray<RoleName>;
     /**
@@ -133,18 +135,17 @@ export interface WsEndpointSpec {
      * 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`.
+     * The guard is also the one closer of a role revocation: a revoked
+     * global grant of a role in `required_roles` closes the account's
+     * sockets on this endpoint with `WS_CLOSE_PERMISSION_REVOKED`. With the
+     * guard off for a transport, nothing closes them.
      */
     auth_guard?: boolean;
     /**
      * Extra audit-event handlers registered via `deps.audit.add_listener`
      * AFTER the standard `auth_guard` wiring (when enabled). By the time
      * these run, the standard guard may have already closed sockets. Use
-     * for role-revoke disconnection, custom analytics, etc.
+     * for custom analytics, a consumer's own revocation events, etc.
      *
      * Never deduped — consumer-owned; pass the same handler twice and it
      * fires twice.

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

@@ -1 +1 @@
-{"version":3,"file":"ws_endpoint_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/ws_endpoint_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EACX,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;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;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACxD;AAED,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG;IAAE,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAEjG;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAChC,cAAc,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,EACvD,iBAAiB,aAAa,CAAC,MAAM,CAAC,KACpC,KAAK,CAAC,sBAAsB,CAAC,GAAG,SAI/B,CAAC"}
+{"version":3,"file":"ws_endpoint_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/ws_endpoint_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EACX,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACxD;AAED,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG;IAAE,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAEjG;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAChC,cAAc,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,EACvD,iBAAiB,aAAa,CAAC,MAAM,CAAC,KACpC,KAAK,CAAC,sBAAsB,CAAC,GAAG,SAI/B,CAAC"}

package/dist/auth/CLAUDE.md

@@ -35,7 +35,7 @@ over the pool so rows persist when request transactions roll back. See root
 - `auth/session_cookie.ts` — `SessionOptions<T>`, `parse_session`, `process_session_cookie` (`'none' | 'clear'` — no refresh action; the 30-day lifetime is an absolute cap signed once at mint), `create_session_config`, `fuz_session_config`, `SESSION_AGE_MAX`.
 - `auth/password.ts` — `Password`, `PasswordProvided`, `PasswordHashDeps`, `PASSWORD_LENGTH_MIN` (12, OWASP), `PASSWORD_LENGTH_MAX` (300).
 - `auth/password_argon2.ts` — `hash_password`, `verify_password`, `verify_dummy`, `argon2_password_deps`.
-- `auth/api_token.ts` — `API_TOKEN_PREFIX` (`secret_fuz_token_`), `hash_api_token`, `generate_api_token`.
+- `auth/api_token.ts` — `API_TOKEN_PREFIX` (`secret_fuz_token_`), `hash_api_token`, `generate_api_token`, and the shape precheck `is_api_token_shaped` (`API_TOKEN_REGEX`: the prefix plus exactly `API_TOKEN_BODY_LENGTH` = 43 base64url chars).
 - `auth/daemon_token.ts` — `DaemonToken`, `DAEMON_TOKEN_HEADER` (`X-Daemon-Token`), `generate_daemon_token`, `validate_daemon_token`, `DaemonTokenState`.
 - `auth/bootstrap_account.ts` — `bootstrap_account` (one-shot, `bootstrap_lock`-protected).
 
@@ -74,7 +74,7 @@ Convention — `*_schema.ts` is Zod-only; `*_ddl.ts` holds DDL strings.
 
 ### Queries
 
-All take `deps: QueryDeps = {db}` first; `query_validate_api_token` adds `log`.
+All take `deps: QueryDeps = {db}` first; `query_validate_api_token` adds `log` and returns a `ValidatedApiToken` — the row with `scope` parsed, refusing (returning `undefined` for) a row whose stored scope is unreadable.
 
 - `auth/account_queries.ts` — account CRUD, actor resolution, password update with verify-write race guard, paged `query_admin_account_list`.
 - `auth/actor_lookup_queries.ts` — batched `actor` ⨝ `account` for the labels arc.
@@ -219,11 +219,12 @@ Everything else listed under §RPC action surfaces.
 
 ### Middleware
 
-- `auth/middleware.ts` — `create_auth_middleware_specs(deps, options)` assembles `[origin, session, request_context, bearer_auth]` + optional `daemon_token` (the content-type refusal isn't a middleware: `apply_route_specs` checks every `POST` route, see `http/simple_request.ts`). `AUTH_MIDDLEWARE_PATH` (`'/api/*'`) is where `create_app_server` mounts the stack; two assembly asserts lean on it: `assert_endpoint_in_auth_scope` (an `rpc_endpoints` / `ws_endpoints` path, or the bootstrap route under `bootstrap.route_prefix`, must sit inside it) and `assert_middleware_stack_mounted(stack_specs, middleware_specs)`, run on a `transform_middleware` result against the pre-transform stack (`[proxy, ...auth]`) — each stack spec, matched by its `handler` closure (not its spoofable `name`), mounted exactly once at its original path (`'*'` for the trusted proxy, `AUTH_MIDDLEWARE_PATH` for auth), in its original order; other specs may sit anywhere, including before the proxy and between the auth layers. The proxy is in the stack because dropping it turns every `get_client_ip` into `'unknown'`, one shared bucket for every IP-keyed limiter. The transform receives shallow copies in a fresh array, so an in-place mutation can't rewrite the originals the check reads. The check pins where those layers sit, not what added layers do — a layer you add runs with full context access. Both run in `create_test_app_surface_spec` too.
+- `auth/middleware.ts` — `create_auth_middleware_specs(deps, options)` assembles `[origin, session, request_context, bearer_auth]` + optional `daemon_token` (the content-type refusal isn't a middleware: `apply_route_specs` checks every `POST` route, see `http/simple_request.ts`). The origin check mounts on every path (`ORIGIN_MIDDLEWARE_PATH`, `'*'`), less its `origin_carve_outs` — each a `MiddlewareCarveOut` (`{path, reason}`, copied and frozen at assembly by `freeze_origin_carve_outs`, refused by `assert_origin_carve_outs_valid` without a reason or when it overlaps the auth scope — `middleware_paths_overlap` against `AUTH_MIDDLEWARE_PATH`, which holds every credential-reading and credential-minting route — and recorded on the origin spec so the surface leaves its `403` off the carved routes); `AUTH_MIDDLEWARE_PATH` (`'/api/*'`) is where `create_app_server` mounts the rest of the stack; assembly asserts lean on it: `assert_endpoint_in_auth_scope` (an `rpc_endpoints` / `ws_endpoints` path, or the bootstrap route under `bootstrap.route_prefix`, must sit inside it — so no carve-out can reach one), `assert_credential_routes_in_auth_scope(route_specs)` (every registered route that reads a credential — `auth.account` not `'none'`, or marked `reads_credential`, as account status is — or is marked `mints_credential` — login, signup, bootstrap — must sit inside it too, so a consumer prefixing the relative account or signup specs outside `/api/` is refused), and `assert_middleware_stack_mounted(stack_specs, middleware_specs)`, run on a `transform_middleware` result against the pre-transform stack (`[proxy, ...auth]`) — each stack spec, matched by its `handler` closure (not its spoofable `name`), mounted exactly once at its original path (`'*'` for the trusted proxy and the origin check, `AUTH_MIDDLEWARE_PATH` for the rest of auth), in its original order; other specs may sit anywhere, including before the proxy and between the auth layers. The proxy is in the stack because dropping it turns every `get_client_ip` into `'unknown'`, one shared bucket for every IP-keyed limiter. The transform receives shallow copies in a fresh array, so an in-place mutation can't rewrite the originals the check reads. The check pins where those layers sit, not what added layers do — a layer you add runs with full context access. Both run in `create_test_app_surface_spec` too.
 - `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; 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/resolved_auth.ts` — `ResolvedAuth` (the resolved credential as one value: `account_id`, `credential_type`, `token_hash`, `api_token_id`, `credential_deadline`), `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/credential_deadline.ts` — when a resolved credential stops authenticating, which a WebSocket or audit stream opened on it closes at (expiry writes nothing a revocation listener hears): `credential_deadline_after` (the earliest remaining lifetime, anchored to `performance.now()`), `EXPIRES_IN_MS_SQL` (a row's `expires_at - NOW()`, read on the database clock in the statement that checks it, so the session and token validation queries return `expires_in_ms`), and `schedule_credential_deadline` (a chain of timers of at most `CREDENTIAL_DEADLINE_TIMER_CAP_MS`, an hour — a 30-day session is past `setTimeout`'s ceiling — each wake-up also checking a wall-clock copy of the deadline, so a host suspend, which stops the monotonic clock, delays the close by at most one timer after the resume). The middleware sets `CREDENTIAL_DEADLINE_KEY`: session — the earlier of the cookie's signed expiry (`SESSION_COOKIE_EXPIRES_AT_KEY`, set by the session middleware) and the row's; bearer — the row's, none for an eternal token; daemon token — none. Twin of the Rust `ResolvedAuth::credential_deadline`.
+- `auth/bearer_auth.ts` — soft-fail bearer middleware; rejects when `Origin` or `Referer` present (browser context), and soft-fails a value that is not `is_api_token_shaped` before any query. The scope it sets is the one the query parsed — there is no fallback.
 - `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.
 
 See root ../../../CLAUDE.md §Middleware Ordering for canonical assembly
@@ -268,16 +269,33 @@ delete / list / clone / moderate`), error reasons, and `all_cell_action_specs`
   manage grants or read the audit timeline. NULL
   `created_by` (system origin) is admin-only for edit/manage (explicit
   defense-in-depth). "Admin" on every tier is the **global** grant — a
-  scoped `admin` row bypasses nothing.
-- `auth/cell_relation_visibility.ts` — `filter_visible_target_ids(deps,
-auth, ids)`: batched strict relation-read filter. Every relation read —
-  the `cell_get` bundle, **forward and reverse** `cell_field_list` /
-  `cell_item_list`, and the deep-clone walk (children bulk-loaded via
-  `query_cell_load_many`) — drops edges whose far endpoint the caller can't
-  view, so a viewer of a parent can't enumerate private linked cells by id.
-  Two queries for the whole id-set (avoids the N+1 of a per-row check). The
-  reverse list verbs additionally cap the fetch by the wire `limit` so a
-  heavily inbound-linked target can't force an unbounded scan.
+  scoped `admin` row bypasses nothing. `can_view_cell`'s public and grant
+  arms also require the cell's `moderation` to admit an audience
+  (`db/cell_moderation.ts`: unmoderated or `approved`), so a pending or
+  rejected contribution is its author's and admins' alone; `can_edit_cell`'s
+  editor-grant arm requires the same admission. `can_steward_cell`
+  is the separate moderator read: the governing root's manager on a pending or
+  rejected contribution under a live root.
+- `auth/cell_steward.ts` — `cell_steward_admits(deps, auth, cell)`: the steward
+  arm with its governing-root load, run only after `can_view_cell` denies. Its
+  module doc names where the arm applies (`cell_get`, `cell_moderate`, the
+  cell-scoped fact route, `cell_list`'s SQL) and where it must not (clone,
+  contribution parents, relation reads, `shared_with`, grant recompute).
+- Strict relation-read visibility — every relation read drops edges whose far
+  endpoint the caller can't view, so a viewer of a parent can't enumerate
+  private linked cells by id. **Forward and reverse** `cell_field_list` /
+  `cell_item_list` filter in SQL before their limit
+  (`db/cell_view_sql.ts`'s `can_view_cell_sql`, bound through
+  `cell_viewer_from_auth`), so a page is up to `limit` edges whose other end
+  the caller can view — `CELL_RELATION_LIST_LIMIT_DEFAULT` (50) when omitted,
+  `CELL_RELATION_LIST_LIMIT_MAX` (500) at most
+  (`auth/cell_relation_list_limit.ts`), and hidden ends never crowd out
+  visible ones. The `cell_get` bundle (whose `*_truncated` counts raw edges)
+  and the clone walk read with `CELL_VIEWER_UNRESTRICTED` and filter after,
+  through `auth/cell_relation_visibility.ts`'s `filter_visible_target_ids(deps,
+auth, ids)`: two queries for the whole id-set, the cells read through the
+  narrow `CELL_VIEW_COLUMNS` projection (`query_cell_view_load_many`), never
+  the payload.
 - `auth/cell_actions.ts` — `create_cell_actions(deps)`, the generic
   handlers. `cell_create` stamps `created_by` + writes the top-level `kind`
   column; `path` writes are admin-only. It also resolves the directory tree:
@@ -295,7 +313,9 @@ auth, ids)`: batched strict relation-read filter. Every relation read —
   parent-aware `authorize_create` dep (`CellCreateAuthorize` — wider input
   `{kind, data, parent_id, root_id, root_data, scope_id}` than `validate_data`,
   returning a `CellCreateVerdict` `{allow:false} | {allow:true, moderation_required}`)
-  gates create by capability; it runs after the validator + the parent-resolve.
+  gates create by capability; it runs after the validator + the parent-resolve
+  (which **404**s `cell_not_found` on a missing or soft-deleted root as on a
+  missing parent, authorizer or not).
   A **viewable**-parent / root-creation deny is **403** `cell_create_forbidden`
   (the create-path **404** mask is reserved for a hidden parent); `Allow` folds
   the moderation outcome (born `pending`+private vs `approved`+author-visibility).
@@ -305,7 +325,8 @@ auth, ids)`: batched strict relation-read filter. Every relation read —
   single-connection deadlock of the in-memory drivers). `None`/omitted = open create (the default;
   mirrors `validate_data`). `cell_moderate` is the `pending → approved | rejected`
   transition, gated on `can_manage_cell` of the **governing root** (admin / root
-  owner — the author lands a 403, the anti-self-approval guard); approve flips
+  owner — the author lands a 403, the anti-self-approval guard; a root owner
+  reaches the check through the steward arm); approve flips
   `moderation → approved` + `visibility → public`, reject sets `rejected`.
 - `auth/cell_grant_actions.ts` / `cell_field_actions.ts` /
   `cell_item_actions.ts` / `cell_audit_actions.ts` — the relation + ACL +
@@ -587,7 +608,7 @@ reactivation has no self path because a soft-deleted account can't
 authenticate.
 
 - `admin_account_list_action_spec` — read; input `{limit?, offset?, include_deleted?}`; output `{accounts, grantable_roles}`. `include_deleted` (default false) surfaces soft-deleted rows (with `account.deleted_at` set) for the admin UI's reactivation view.
-- `account_delete_action_spec` — mutation (soft delete); self-or-admin (`{account, actor}`, handler elevates to admin when `account_id` ≠ self); input `{account_id?}`; output `{ok, deleted}`. Tombstones account + actor(s), revokes sessions/tokens, emits `account_delete` + per-actor `actor_delete`. Refuses a keeper-role target (`ERROR_CANNOT_DELETE_KEEPER`) or the sole active admin (`ERROR_CANNOT_DELETE_LAST_ADMIN`) — both fail-loud with a failure-audit row.
+- `account_delete_action_spec` — mutation (soft delete); self-or-admin (`{account, actor}`, handler elevates to admin when `account_id` ≠ self); the self path is session-only, handler-enforced ahead of the target guards (an API or daemon token gets the dispatcher's `ERROR_CREDENTIAL_TYPE_REQUIRED` 403 via `credential_type_required_error`), while an admin deleting another account keeps any credential; input `{account_id?}`; output `{ok, deleted}`. Tombstones account + actor(s), revokes sessions/tokens, emits `account_delete` + per-actor `actor_delete`. Refuses a keeper-role target (`ERROR_CANNOT_DELETE_KEEPER`) or the sole active admin (`ERROR_CANNOT_DELETE_LAST_ADMIN`) — both fail-loud with a failure-audit row.
 - `account_purge_action_spec` — mutation (hard purge); keeper-only (`credential_types: ['daemon_token']` + `roles: ['keeper']`) + `confirm: true` + WARN; input `{account_id, confirm?}`; output `{ok, purged}`. Cascading delete; emits `account_purge` + per-actor `actor_purge` (identity snapshot survives in metadata since `audit_log` ids carry no FK). Refuses a keeper-role target (`ERROR_CANNOT_DELETE_KEEPER`) or the sole active admin (`ERROR_CANNOT_DELETE_LAST_ADMIN`).
 - `account_undelete_action_spec` — mutation (reactivation, inverse of soft delete); admin-only (`roles: ['admin']` — no self path, a tombstoned account can't authenticate); input `{account_id}`; output `{ok, undeleted}`. Clears the `deleted_at` tombstone on the account + its actor(s), emits `account_undelete` + per-actor `actor_undelete`. Does not restore revoked sessions/tokens.
 - `admin_session_list_action_spec` — read; input `{acting?}` (`.default({})`); output `{sessions}`.
@@ -913,10 +934,11 @@ 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).
+`query_session_cleanup_expired` returns the deleted ids. The close repeats
+one already made: every connection closes at its credential's deadline
+(`auth/credential_deadline.ts`) in the process holding it, sweep or no sweep.
+An expired API token's row is not swept; its connections close at their
+deadline (`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