@fuzdev/fuz_app 0.140.0 → 0.141.0

package/dist/actions/register_action_ws.js

@@ -54,10 +54,19 @@
  * admits a revoked credential; `docs/security.md` §Connection Admission says
  * what that rests on.
  *
+ * An endpoint gated on `required_roles` re-reads them beside the credential:
+ * its upgrade passed the role gate before the socket registered, so a role
+ * revocation landing in between would close nothing (`close_sockets_for_role`
+ * matches registrations), and the socket would be admitted without the role
+ * for its lifetime. The re-read reads the acting actor's grants afresh and
+ * admits on a global grant of any listed role, as the gate did.
+ *
  * A refused upgrade is closed with `WS_CLOSE_SESSION_REVOKED` (4001, the
- * reason a revoked socket gets), or `WS_CLOSE_INTERNAL_ERROR` (1011) when the
- * re-read itself failed — fail closed, never admitted unchecked. The handshake
- * has already answered `101`, so a refusal can only be a close frame.
+ * reason a revoked socket gets) for a dead credential,
+ * `WS_CLOSE_PERMISSION_REVOKED` (4006) for a lost role, or
+ * `WS_CLOSE_INTERNAL_ERROR` (1011) when either re-read itself failed — fail
+ * closed, never admitted unchecked. The handshake has already answered `101`,
+ * so a refusal can only be a close frame.
  *
  * Once the server is shutting down (`AppServer.close` ran the transport's
  * `close_all_sockets`) a refusal is `WS_CLOSE_GOING_AWAY` instead, so the
@@ -75,8 +84,17 @@
  * `PRE_ADMISSION_QUEUE_BYTES_FACTOR` × `max_message_bytes` bytes; past either
  * the socket is closed.
  *
- * The upgrade's role gate is *not* re-read: a role revocation closes no
- * WebSocket in the first place (per-message dispatch re-reads role grants).
+ * ## Credential deadline
+ *
+ * Expiry writes nothing a revocation listener could hear, so the socket
+ * watches its own credential's expiry (`ResolvedAuth.credential_deadline`,
+ * the earlier of a session's cookie and row, an API token's row, none for a
+ * daemon token or an eternal token). From admission, a timer closes it at the
+ * deadline with `WS_CLOSE_SESSION_REVOKED` (4001) and
+ * `WS_CLOSE_CREDENTIAL_EXPIRED_REASON`. The wait is a chain of timers of at
+ * most an hour (`schedule_credential_deadline`), so a session's 30 days — past
+ * `setTimeout`'s ceiling — does not fire at once, and each wake-up checks the
+ * wall clock too, so a host suspend does not extend the deadline.
  *
  * ## A server-closed socket dispatches nothing
  *
@@ -96,8 +114,9 @@
  */
 import { wait } from '@fuzdev/fuz_util/async.ts';
 import { Logger } from '@fuzdev/fuz_util/log.ts';
-import { get_request_context, require_request_context, token_scope_surface_denial } from '../auth/request_context.js';
+import { get_request_context, has_any_scoped_role, refresh_role_grants, require_request_context, token_scope_surface_denial } from '../auth/request_context.js';
 import { get_resolved_auth, revalidate_resolved_auth } from '../auth/resolved_auth.js';
+import { schedule_credential_deadline } from '../auth/credential_deadline.js';
 import { get_client_ip } from '../http/client_ip.js';
 import { flush_pending_effects, flush_post_commit_effects } from '../http/pending_effects.js';
 import { JsonrpcRequest } from '../http/jsonrpc.js';
@@ -107,7 +126,7 @@ import { TOKEN_SCOPE_KEY, TEST_CONTEXT_PRESET_KEY } from '../hono_context.js';
 import {} from './action_types.js';
 import { compile_action_registry } from './compile_action_registry.js';
 import { cancel_action_spec, CancelNotificationParams } from './cancel.js';
-import { DEFAULT_WS_MAX_MESSAGE_BYTES, WS_CLOSE_INTERNAL_ERROR, WS_CLOSE_MESSAGE_TOO_BIG, WS_CLOSE_POLICY_VIOLATION, WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON, utf8_length, utf8_length_over } from './transports.js';
+import { DEFAULT_WS_MAX_MESSAGE_BYTES, WS_CLOSE_GOING_AWAY, WS_CLOSE_INTERNAL_ERROR, WS_CLOSE_MESSAGE_TOO_BIG, WS_CLOSE_PERMISSION_REVOKED, WS_CLOSE_PERMISSION_REVOKED_REASON, WS_CLOSE_POLICY_VIOLATION, WS_CLOSE_CREDENTIAL_EXPIRED_REASON, WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON, utf8_length, utf8_length_over } from './transports.js';
 import { BackendWebsocketTransport } from './transports_ws_backend.js';
 import { audit_unmatched_peer_response } from './peer_request.js';
 import { perform_action, perform_action_result_to_envelope } from './perform_action.js';
@@ -247,8 +266,12 @@ const is_peer_response = (json) => {
  *   on the audit row.
  * - Admission re-reads the credential once, after the handshake: a socket
  *   whose session or token was revoked while it was upgrading closes with
- *   `WS_CLOSE_SESSION_REVOKED`, and one whose re-check failed with
+ *   `WS_CLOSE_SESSION_REVOKED`, one that lost a role `required_roles` lists
+ *   with `WS_CLOSE_PERMISSION_REVOKED`, and one whose re-check failed with
  *   `WS_CLOSE_INTERNAL_ERROR`. Frames sent before admission wait for it.
+ * - A revoked global grant of a role `required_roles` lists closes the
+ *   account's sockets on this endpoint with `WS_CLOSE_PERMISSION_REVOKED`,
+ *   through `create_ws_auth_guard`; nothing more is sent on them.
  * - A socket the server has closed dispatches nothing more, whether or not
  *   its client answers the close.
  * - Every frame sent — responses, error frames, notifications — goes through
@@ -279,7 +302,7 @@ export const register_action_ws = (options) => {
         throw new Error(`register_action_ws: outbound_queue_bytes configures the transport created for ${options.path}, ` +
             'but a transport was supplied — set the budget on that BackendWebsocketTransport instead');
     }
-    const { path, app, upgradeWebSocket, actions, db, heartbeat = true, artificial_delay = 0, max_message_bytes = DEFAULT_WS_MAX_MESSAGE_BYTES, log = new Logger('[ws]'), on_socket_open, on_socket_close, action_ip_rate_limiter, action_account_rate_limiter } = options;
+    const { path, app, upgradeWebSocket, actions, db, heartbeat = true, artificial_delay = 0, max_message_bytes = DEFAULT_WS_MAX_MESSAGE_BYTES, log = new Logger('[ws]'), on_socket_open, on_socket_close, action_ip_rate_limiter, action_account_rate_limiter, required_roles = [] } = options;
     const transport = options.transport ??
         new BackendWebsocketTransport({
             max_connections_per_account: options.max_connections_per_account,
@@ -402,7 +425,12 @@ export const register_action_ws = (options) => {
         // read it — by the time the hook runs the transport record is gone,
         // removed in `onClose` or earlier by a revocation, a connection-cap
         // eviction, or another server-side close.
-        const identity = { token_hash, account_id, api_token_id };
+        const identity = {
+            token_hash,
+            account_id,
+            api_token_id,
+            required_roles
+        };
         // Captured on open, consumed on close. Undefined before onOpen
         // fires or when a consumer never opens (e.g. immediate disconnect).
         let captured_connection_id;
@@ -420,6 +448,10 @@ export const register_action_ws = (options) => {
         // Whether the connection was ever admitted — gates `on_socket_close`,
         // the counterpart of an `on_socket_open` a refused socket never ran.
         let was_admitted = false;
+        // The code the transport closed the pending registration with, taken
+        // before `onClose` removes it: the client's answer to that close can
+        // arrive before the re-read returns.
+        let pending_close_code = null;
         // Frames received while `opening`, in arrival order — dispatched once
         // the socket is open, dropped if it ends first. Each carries the
         // settlers of the promise its `onMessage` call returned, so a caller
@@ -445,12 +477,22 @@ export const register_action_ws = (options) => {
                 heartbeat_timer = null;
             }
         };
+        // The credential deadline: the socket closes when the credential it
+        // upgraded on expires (4001, `WS_CLOSE_CREDENTIAL_EXPIRED_REASON`) —
+        // expiry writes nothing a revocation listener hears. Started at
+        // admission, cancelled when the socket ends.
+        let cancel_credential_deadline = null;
+        const stop_credential_deadline = () => {
+            cancel_credential_deadline?.();
+            cancel_credential_deadline = null;
+        };
         // The one place a socket's end is recorded, whoever ended it — the
         // transport (revocation, cap eviction), `end_socket`, or `onClose` all
         // abort this controller.
         socket_abort_controller.signal.addEventListener('abort', () => {
             phase = 'ended';
             stop_heartbeat_timer();
+            stop_credential_deadline();
             drop_queued_frames();
         }, { once: true });
         // End the socket from the server side: unregister it and abort its
@@ -505,7 +547,7 @@ export const register_action_ws = (options) => {
         // refusing — the socket is then already closed.
         const admit_upgrade = async (ws) => {
             // Pending first, synchronously: from here every revocation finds it.
-            const connection_id = transport.register_pending(ws, token_hash, account_id, api_token_id, socket_abort_controller);
+            const connection_id = transport.register_pending(ws, token_hash, account_id, api_token_id, socket_abort_controller, required_roles);
             captured_connection_id = connection_id;
             // Born closed — the server is shutting down, and the transport has
             // already closed the socket with `WS_CLOSE_GOING_AWAY` — or ended
@@ -520,10 +562,16 @@ export const register_action_ws = (options) => {
             }
             if (!upgrade_preset) {
                 let credential_is_live;
+                let role_is_held = true;
                 try {
                     // pool-level `db`: the statements must see every revocation
                     // committed before they start
                     credential_is_live = await revalidate_resolved_auth({ db }, resolved);
+                    // Global grants only, like the gate in front: a scoped grant
+                    // never admitted this socket.
+                    if (credential_is_live && required_roles.length > 0) {
+                        role_is_held = has_any_scoped_role(await refresh_role_grants(upgrade_context, { db }), required_roles, null);
+                    }
                 }
                 catch (error) {
                     // fail closed — never admitted unchecked. During shutdown the
@@ -533,7 +581,7 @@ export const register_action_ws = (options) => {
                         log.info('ws upgrade admission: re-check ended by the shutdown', error);
                     }
                     else {
-                        log.error('ws upgrade admission: credential re-check failed', error);
+                        log.error('ws upgrade admission: credential or role re-check failed', error);
                     }
                     refuse_upgrade(ws, WS_CLOSE_INTERNAL_ERROR, 'internal error');
                     return null;
@@ -543,16 +591,24 @@ export const register_action_ws = (options) => {
                     refuse_upgrade(ws, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON);
                     return null;
                 }
+                if (!role_is_held) {
+                    log.info('ws upgrade admission: role revoked during the upgrade', connection_id, account_id);
+                    refuse_upgrade(ws, WS_CLOSE_PERMISSION_REVOKED, WS_CLOSE_PERMISSION_REVOKED_REASON);
+                    return null;
+                }
             }
             // The cap's eviction happens here, after every gate and the re-read,
             // so a refused upgrade never closes someone else's socket.
             if (!transport.admit(connection_id)) {
-                // chosen from the transport's state now, not why the entry closed — the
-                // abort carries no per-entry reason, so an entry a revocation closed logs as
-                // closed by the shutdown when the shutdown began before this check
-                log.info(transport.is_closing()
-                    ? 'ws upgrade admission: closed by the shutdown while pending'
-                    : 'ws upgrade admission: closed by a revocation while pending', connection_id, account_id);
+                // why the entry closed, from the code the transport closed it with
+                const code = pending_close_code ?? transport.take_pending_close_code(connection_id);
+                log.info(code === WS_CLOSE_PERMISSION_REVOKED
+                    ? 'ws upgrade admission: closed by a permission revocation while pending'
+                    : code === WS_CLOSE_SESSION_REVOKED
+                        ? 'ws upgrade admission: closed by a credential revocation while pending'
+                        : code === WS_CLOSE_GOING_AWAY || transport.is_closing()
+                            ? 'ws upgrade admission: closed by the shutdown while pending'
+                            : 'ws upgrade admission: ended while pending', connection_id, account_id);
                 refuse_upgrade(ws, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON);
                 return null;
             }
@@ -564,6 +620,14 @@ export const register_action_ws = (options) => {
             if (connection_id === null)
                 return;
             log.debug('ws opened', connection_id);
+            // Not on a socket that ended in the tick since `admit`, for the same
+            // reason as the heartbeat timer below.
+            if (!phase_is('ended')) {
+                cancel_credential_deadline = schedule_credential_deadline(resolved.credential_deadline, () => {
+                    log.info('ws credential expired — closing', WS_CLOSE_SESSION_REVOKED, connection_id, identity.account_id);
+                    end_socket(ws, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_CREDENTIAL_EXPIRED_REASON);
+                });
+            }
             // Not on a socket that ended in the tick since `admit` (a revocation
             // can land there): its abort listener has already run, so nothing
             // would ever stop the timer.
@@ -894,8 +958,12 @@ export const register_action_ws = (options) => {
                 // the hook is awaited: the socket is gone, so a slow hook must not
                 // keep a dead entry that broadcasts still target and the
                 // per-account cap still counts.
-                if (captured_connection_id)
+                if (captured_connection_id) {
+                    if (!was_admitted) {
+                        pending_close_code = transport.take_pending_close_code(captured_connection_id);
+                    }
                     transport.remove_connection(captured_connection_id);
+                }
                 if (on_socket_close && captured_connection_id && was_admitted) {
                     try {
                         await on_socket_close({

package/dist/actions/register_ws_endpoint.d.ts

@@ -22,7 +22,10 @@
  *    Multi-actor accounts must supply `?acting` to pick a persona;
  *    single-actor accounts work without it.
  * 5. Optional `require_role(required_roles)` — for endpoints gated to a
- *    non-empty any-of set of roles.
+ *    non-empty any-of set of roles. `register_action_ws` records the roles on
+ *    each registration and re-reads them at admission, so the gate holds for
+ *    the socket's life (a revoked role closes it with
+ *    `WS_CLOSE_PERMISSION_REVOKED`).
  *
  * Then delegates to `register_action_ws` for per-message JSON-RPC
  * dispatch.
@@ -41,12 +44,18 @@ export interface RegisterWsEndpointOptions extends RegisterActionWsOptions {
     allowed_origins: ReadonlyArray<RegExp>;
     /**
      * Roles permitted to upgrade — any-of disjunction (matches the
-     * underlying `require_role` semantics). Omit (or pass `[]`) for any
-     * authenticated account (`require_auth` + actor resolution alone);
-     * set to e.g. `[ROLE_ADMIN]` to gate the endpoint behind a single role
-     * or `[ROLE_ADMIN, ROLE_KEEPER]` to permit either. The per-action
+     * underlying `require_role` semantics, global grants only). Omit (or pass
+     * `[]`) for any authenticated account (`require_auth` + actor resolution
+     * alone); set to e.g. `[ROLE_ADMIN]` to gate the endpoint behind a single
+     * role or `[ROLE_ADMIN, ROLE_KEEPER]` to permit either. The per-action
      * `auth` in each spec still applies at dispatch time — this is a coarse
-     * upgrade-time gate.
+     * upgrade-time gate on who may hold a socket, and so on who receives
+     * the endpoint's server pushes.
+     *
+     * It holds for the socket's life: `register_action_ws` re-reads it at
+     * admission, and a revoked global grant of a listed role closes the
+     * account's sockets here with `WS_CLOSE_PERMISSION_REVOKED` (any listed
+     * role — see `close_sockets_for_role` on the over-close).
      */
     required_roles?: ReadonlyArray<RoleName>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAaH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,0CAA0C;AAC1C,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACzE;;;;OAIG;IACH,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC;AAgDD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,yBAAyB,KAChC,sBAoBF,CAAC"}
+{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAaH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,0CAA0C;AAC1C,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACzE;;;;OAIG;IACH,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC;AAgDD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,yBAAyB,KAChC,sBAoBF,CAAC"}

package/dist/actions/register_ws_endpoint.js

@@ -22,7 +22,10 @@
  *    Multi-actor accounts must supply `?acting` to pick a persona;
  *    single-actor accounts work without it.
  * 5. Optional `require_role(required_roles)` — for endpoints gated to a
- *    non-empty any-of set of roles.
+ *    non-empty any-of set of roles. `register_action_ws` records the roles on
+ *    each registration and re-reads them at admission, so the gate holds for
+ *    the socket's life (a revoked role closes it with
+ *    `WS_CLOSE_PERMISSION_REVOKED`).
  *
  * Then delegates to `register_action_ws` for per-message JSON-RPC
  * dispatch.
@@ -99,5 +102,5 @@ export const register_ws_endpoint = (options) => {
     if (required_roles?.length) {
         app.use(path, require_role(required_roles));
     }
-    return register_action_ws({ app, path, db, log, ...rest });
+    return register_action_ws({ app, path, db, log, required_roles, ...rest });
 };

package/dist/actions/socket.svelte.d.ts

@@ -5,9 +5,11 @@
  * Drop into any SvelteKit frontend as the underlying connection for
  * `FrontendWebsocketTransport`. Handles auto-reconnect with exponential
  * backoff, respects `WS_CLOSE_SESSION_REVOKED` (no reconnect loop after the
- * server revokes auth) and `WS_CLOSE_CONNECTION_LIMIT` (no reconnect after the
+ * server revokes auth), `WS_CLOSE_CONNECTION_LIMIT` (no reconnect after the
  * server closes this socket to admit a newer one — closed until the user
- * acts), exposes reactive status for UI indicators, and ships three
+ * acts), and `WS_CLOSE_PERMISSION_REVOKED` (no reconnect after the account
+ * lost the role the endpoint requires — closed until the user acts), exposes
+ * reactive status for UI indicators, and ships three
  * correctness primitives default-on:
  *
  * - `FrontendWebsocketClient.request` — promise-based JSON-RPC with
@@ -76,7 +78,7 @@ export declare const DEFAULT_QUEUE_MAX_SIZE = 100;
  * - `reconnecting` — close fired; waiting out backoff before next attempt.
  * - `closed` — socket is not open, and nothing is scheduled to reopen it.
  *   Terminal only when `revoked` is `true`; otherwise `connect()` reopens,
- *   including after a `superseded` close.
+ *   including after a `superseded` or permission-revoked close.
  */
 export type SocketStatus = 'initial' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
 export type SocketMessageHandler = (event: MessageEvent) => void;
@@ -153,6 +155,13 @@ export interface FrontendWebsocketClientOptions {
  * closed with `superseded` set and no reconnect scheduled — the server closed
  * this socket to admit a newer one on the same account, and reconnecting
  * would close that one in turn. An explicit `connect()` reopens.
+ *
+ * A permission-revoked close (`WS_CLOSE_PERMISSION_REVOKED`) leaves the client
+ * closed with no reconnect scheduled, and neither `revoked` nor `superseded`
+ * set: the credential is still good, but the account lost the role the
+ * endpoint requires, so a reconnect would be refused at its role gate. Pending
+ * and queued requests reject `forbidden`. `last_close_code` says why; an
+ * explicit `connect()` reopens, for when the role has been granted again.
  */
 export declare class FrontendWebsocketClient implements WebsocketConnection, Disposable {
     #private;
@@ -339,6 +348,8 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      *   - `queue_overflow` — durable queue full
      *   - `service_unavailable` — socket not connected / closed / torn down
      *     mid-flight, including a `superseded` close
+     *   - `forbidden` — in flight or queued at a `WS_CLOSE_PERMISSION_REVOKED`
+     *     close
      *   - `internal_error` — `ws.send` threw (serialization, buffer full)
      *   - server's wire code verbatim — JSON-RPC error frame from peer
      */
@@ -361,7 +372,11 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
  * an explicit `connect()` reopens it; read `FrontendWebsocketClient.superseded`
  * to tell the user why, and before connecting on an `initial` status without
  * the user asking (connecting a superseded client on its own closes a newer
- * socket in turn, which is the loop the close code exists to stop).
+ * socket in turn, which is the loop the close code exists to stop). A
+ * `WS_CLOSE_PERMISSION_REVOKED` close reads as `initial` the same way, with
+ * neither flag set: check `FrontendWebsocketClient.last_close_code` before
+ * connecting on your own, since without the role the upgrade is refused at
+ * the gate.
  *
  * @param revoked - whether the session has been permanently revoked
  *   (typically `FrontendWebsocketClient.revoked`)

package/dist/actions/socket.svelte.d.ts.map

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

package/dist/actions/socket.svelte.js

@@ -5,9 +5,11 @@
  * Drop into any SvelteKit frontend as the underlying connection for
  * `FrontendWebsocketTransport`. Handles auto-reconnect with exponential
  * backoff, respects `WS_CLOSE_SESSION_REVOKED` (no reconnect loop after the
- * server revokes auth) and `WS_CLOSE_CONNECTION_LIMIT` (no reconnect after the
+ * server revokes auth), `WS_CLOSE_CONNECTION_LIMIT` (no reconnect after the
  * server closes this socket to admit a newer one — closed until the user
- * acts), exposes reactive status for UI indicators, and ships three
+ * acts), and `WS_CLOSE_PERMISSION_REVOKED` (no reconnect after the account
+ * lost the role the endpoint requires — closed until the user acts), exposes
+ * reactive status for UI indicators, and ships three
  * correctness primitives default-on:
  *
  * - `FrontendWebsocketClient.request` — promise-based JSON-RPC with
@@ -29,7 +31,7 @@
 import { BROWSER } from 'esm-env';
 import { JSONRPC_VERSION } from '../http/jsonrpc.js';
 import { JSONRPC_ERROR_CODES, ThrownJsonrpcError, jsonrpc_errors } from '../http/jsonrpc_errors.js';
-import { WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT, WS_CLOSE_CONNECTION_LIMIT, WS_CLOSE_SESSION_REVOKED } from './transports.js';
+import { WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT, WS_CLOSE_CONNECTION_LIMIT, WS_CLOSE_PERMISSION_REVOKED, WS_CLOSE_SESSION_REVOKED } from './transports.js';
 import { cancel_action_spec } from './cancel.js';
 import { heartbeat_action_spec } from './heartbeat.js';
 /** Default WebSocket close code (normal closure). */
@@ -84,6 +86,13 @@ export const DEFAULT_QUEUE_MAX_SIZE = 100;
  * closed with `superseded` set and no reconnect scheduled — the server closed
  * this socket to admit a newer one on the same account, and reconnecting
  * would close that one in turn. An explicit `connect()` reopens.
+ *
+ * A permission-revoked close (`WS_CLOSE_PERMISSION_REVOKED`) leaves the client
+ * closed with no reconnect scheduled, and neither `revoked` nor `superseded`
+ * set: the credential is still good, but the account lost the role the
+ * endpoint requires, so a reconnect would be refused at its role gate. Pending
+ * and queued requests reject `forbidden`. `last_close_code` says why; an
+ * explicit `connect()` reopens, for when the role has been granted again.
  */
 export class FrontendWebsocketClient {
     #url;
@@ -423,6 +432,8 @@ export class FrontendWebsocketClient {
      *   - `queue_overflow` — durable queue full
      *   - `service_unavailable` — socket not connected / closed / torn down
      *     mid-flight, including a `superseded` close
+     *   - `forbidden` — in flight or queued at a `WS_CLOSE_PERMISSION_REVOKED`
+     *     close
      *   - `internal_error` — `ws.send` threw (serialization, buffer full)
      *   - server's wire code verbatim — JSON-RPC error frame from peer
      */
@@ -743,6 +754,18 @@ export class FrontendWebsocketClient {
             this.#reject_all('connection superseded', jsonrpc_errors.service_unavailable);
             return;
         }
+        // The account lost a role the endpoint requires. Reconnecting would be
+        // refused at the role gate, so stay closed until `connect()` is called.
+        // Not a revocation: the credential is still good, and nothing will
+        // reopen the socket on its own, so the queue is rejected with the pending
+        // requests.
+        if (event.code === WS_CLOSE_PERMISSION_REVOKED) {
+            this.status = 'closed';
+            this.#cancel_reconnect();
+            this.#reset_reconnect_counters();
+            this.#reject_all('permission revoked', jsonrpc_errors.forbidden);
+            return;
+        }
         // Pending in-flight requests can't be correlated post-reconnect; reject
         // them. Queue stays so the flush on reopen replays unsent work.
         this.#reject_pending_only(`connection closed (code ${event.code})`, jsonrpc_errors.service_unavailable);
@@ -835,7 +858,11 @@ export class FrontendWebsocketClient {
  * an explicit `connect()` reopens it; read `FrontendWebsocketClient.superseded`
  * to tell the user why, and before connecting on an `initial` status without
  * the user asking (connecting a superseded client on its own closes a newer
- * socket in turn, which is the loop the close code exists to stop).
+ * socket in turn, which is the loop the close code exists to stop). A
+ * `WS_CLOSE_PERMISSION_REVOKED` close reads as `initial` the same way, with
+ * neither flag set: check `FrontendWebsocketClient.last_close_code` before
+ * connecting on your own, since without the role the upgrade is refused at
+ * the gate.
  *
  * @param revoked - whether the session has been permanently revoked
  *   (typically `FrontendWebsocketClient.revoked`)

package/dist/actions/transports.d.ts

@@ -9,7 +9,8 @@
 import { z } from 'zod';
 import type { JsonrpcMessageFromClientToServer, JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 /**
- * 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
@@ -22,6 +23,15 @@ export declare const WS_CLOSE_SESSION_REVOKED = 4001;
  * indistinguishable on the wire. The Rust spine sends the same text.
  */
 export declare 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 declare const WS_CLOSE_CREDENTIAL_EXPIRED_REASON = "Credential expired";
 /** WebSocket close code — client timed out waiting for a response. */
 export declare const WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002;
 /** WebSocket close code — server timed out with no incoming activity. */
@@ -62,6 +72,25 @@ export declare const WS_CLOSE_OUTBOUND_OVERFLOW = 4005;
  * sends the same text.
  */
 export declare 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 declare 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 declare 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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACX,gCAAgC,EAChC,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,oBAAoB,CAAC;AACjE,sEAAsE;AACtE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,yEAAyE;AACzE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAC/C;;;GAGG;AACH,eAAO,MAAM,iCAAiC,4BAA4B,CAAC;AAC3E;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,wDAAwD;AACxD,eAAO,MAAM,0BAA0B,yBAAyB,CAAC;AACjE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,QAAc,CAAC;AAIxD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,WAAW,MAAM,KAAG,MAAM,GAAG,IAI3E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAA8C,CAAC;AAK1F,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACzB,cAAc,EAAE,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/F,IAAI,CACH,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACxC,IAAI,CACH,OAAO,EAAE,gCAAgC,EACzC,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IACpD,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,qBAAa,UAAU;;IAItB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAQ;IAE/B;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAQ9C;;;;;OAKG;IACH,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,IAAI;IAM1D;;;;;;OAMG;IACH,aAAa,CAAC,cAAc,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;IAO/D,QAAQ,IAAI,OAAO,GAAG,IAAI;IAM1B,qBAAqB,IAAI,SAAS,GAAG,IAAI;IAIzC,0BAA0B,IAAI,aAAa,GAAG,IAAI;IAIlD,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;CAwCtE"}
+{"version":3,"file":"transports.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports.ts"],"names":[],"mappings":"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"}

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"}