@fuzdev/fuz_app 0.63.0 → 0.65.0

package/dist/actions/broadcast_api.d.ts

@@ -13,7 +13,7 @@
  * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
  *
  * Extracted from zzz's `backend_actions_api.ts` to stop the pattern from
- * drifting across zzz, zap, and undying.
+ * drifting across consumers.
  *
  * @module
  */

package/dist/actions/broadcast_api.js

@@ -13,7 +13,7 @@
  * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
  *
  * Extracted from zzz's `backend_actions_api.ts` to stop the pattern from
- * drifting across zzz, zap, and undying.
+ * drifting across consumers.
  *
  * @module
  */

package/dist/actions/cancel.d.ts

@@ -23,8 +23,8 @@
  * Wire format is snake_case `cancel` with `{request_id}`, not MCP's
  * `$/cancelRequest` with `{requestId}` — fuz_app's WS transport isn't MCP,
  * and adopting MCP's convention would leak protocol-specific framing into
- * the base transport. When MCP elicitation (Phase 5) lands, a translation
- * layer at the MCP adapter is the right seam.
+ * the base transport. If an MCP adapter is ever built, the translation
+ * layer at the adapter is the right seam.
  *
  * @module
  */

package/dist/actions/cancel.js

@@ -23,8 +23,8 @@
  * Wire format is snake_case `cancel` with `{request_id}`, not MCP's
  * `$/cancelRequest` with `{requestId}` — fuz_app's WS transport isn't MCP,
  * and adopting MCP's convention would leak protocol-specific framing into
- * the base transport. When MCP elicitation (Phase 5) lands, a translation
- * layer at the MCP adapter is the right seam.
+ * the base transport. If an MCP adapter is ever built, the translation
+ * layer at the adapter is the right seam.
  *
  * @module
  */
@@ -63,7 +63,7 @@ export const cancel_action_spec = {
  * tuple shape; the dispatcher short-circuits cancel notifications before any
  * handler lookup happens.
  */
-export const cancel_handler = () => { }; // eslint-disable-line @typescript-eslint/no-empty-function
+export const cancel_handler = () => { };
 /**
  * Protocol-action tuple — spread into the server's `actions` array (or via
  * `protocol_actions` from `actions/protocol.ts`) so the dispatcher registers the

package/dist/actions/connection_closer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Narrow structural capability for closing live WebSocket connections
+ * tied to a session token hash, API token id, or account id.
+ *
+ * **Why this exists.** Per-message authorization phase on WebSocket
+ * (`actions/perform_action.ts`) reloads role_grants from the DB on every
+ * message but does NOT re-query session / token validity — that
+ * trade-off keeps chatty connections fast. The cost: revocation
+ * doesn't actually disconnect open sockets unless something closes
+ * them. `transports_ws_auth_guard.ts` is the listener-based seam
+ * (audit-event → close), but it only fires after the audit INSERT
+ * succeeds — if the INSERT fails (DB error, pool exhausted, handler
+ * dies mid-flight) the listener never runs and the live socket keeps
+ * working with a stale `RequestContext` until disconnect.
+ *
+ * Used by self-service revocation handlers (`account_session_revoke` /
+ * `_revoke_all`, `account_token_revoke`, `logout`, `password`) and the
+ * admin revoke-all handlers (`admin_session_revoke_all`,
+ * `admin_token_revoke_all`) to eagerly drop affected sockets BEFORE
+ * emitting the corresponding audit event. The audit listener stays as
+ * a fail-safe for out-of-band emit sites (admin tools, scheduled
+ * jobs, SSE-driven flows). `close_sockets_for_*` is idempotent so the
+ * second pass is a no-op.
+ *
+ * Mirrors `zzz_server`'s `close_sockets_for_*` calls in
+ * `account.rs::logout_inner` / `_password_inner` /
+ * `handlers/account.rs::handle_account_session_revoke[_all]` /
+ * `_token_revoke` (landed 2026-05-16).
+ *
+ * `BackendWebsocketTransport` satisfies this interface structurally,
+ * so consumers pass their transport instance directly (same shape as
+ * `NotificationSender`). The interface stays local so handlers don't
+ * couple to the concrete transport, and tests can inject a capturing
+ * stub with no WS machinery.
+ *
+ * @module
+ */
+/**
+ * Narrow capability — three idempotent socket-close methods, each
+ * returning the number of sockets actually closed (zero when none
+ * matched). Callers typically ignore the return value (used by
+ * telemetry / tests).
+ */
+export interface ConnectionCloser {
+    /**
+     * Close every connection authenticated with a session whose blake3
+     * hash matches `session_token_hash`. Idempotent — calling on an
+     * already-closed session is a no-op.
+     */
+    close_sockets_for_session: (session_token_hash: string) => number;
+    /**
+     * Close every connection authenticated with the given API token id.
+     * Idempotent — calling on an already-revoked token is a no-op.
+     */
+    close_sockets_for_token: (api_token_id: string) => number;
+    /**
+     * Close every connection bound to `account_id`, regardless of
+     * credential type (session / api_token / daemon_token). Coarse
+     * closure used when every credential on an account is invalidated
+     * — password change, session-revoke-all, token-revoke-all, logout.
+     * Idempotent.
+     */
+    close_sockets_for_account: (account_id: string) => number;
+}
+//# sourceMappingURL=connection_closer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection_closer.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/connection_closer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,yBAAyB,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,MAAM,CAAC;IAClE;;;OAGG;IACH,uBAAuB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1D;;;;;;OAMG;IACH,yBAAyB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1D"}

package/dist/actions/connection_closer.js

@@ -0,0 +1,38 @@
+/**
+ * Narrow structural capability for closing live WebSocket connections
+ * tied to a session token hash, API token id, or account id.
+ *
+ * **Why this exists.** Per-message authorization phase on WebSocket
+ * (`actions/perform_action.ts`) reloads role_grants from the DB on every
+ * message but does NOT re-query session / token validity — that
+ * trade-off keeps chatty connections fast. The cost: revocation
+ * doesn't actually disconnect open sockets unless something closes
+ * them. `transports_ws_auth_guard.ts` is the listener-based seam
+ * (audit-event → close), but it only fires after the audit INSERT
+ * succeeds — if the INSERT fails (DB error, pool exhausted, handler
+ * dies mid-flight) the listener never runs and the live socket keeps
+ * working with a stale `RequestContext` until disconnect.
+ *
+ * Used by self-service revocation handlers (`account_session_revoke` /
+ * `_revoke_all`, `account_token_revoke`, `logout`, `password`) and the
+ * admin revoke-all handlers (`admin_session_revoke_all`,
+ * `admin_token_revoke_all`) to eagerly drop affected sockets BEFORE
+ * emitting the corresponding audit event. The audit listener stays as
+ * a fail-safe for out-of-band emit sites (admin tools, scheduled
+ * jobs, SSE-driven flows). `close_sockets_for_*` is idempotent so the
+ * second pass is a no-op.
+ *
+ * Mirrors `zzz_server`'s `close_sockets_for_*` calls in
+ * `account.rs::logout_inner` / `_password_inner` /
+ * `handlers/account.rs::handle_account_session_revoke[_all]` /
+ * `_token_revoke` (landed 2026-05-16).
+ *
+ * `BackendWebsocketTransport` satisfies this interface structurally,
+ * so consumers pass their transport instance directly (same shape as
+ * `NotificationSender`). The interface stays local so handlers don't
+ * couple to the concrete transport, and tests can inject a capturing
+ * stub with no WS machinery.
+ *
+ * @module
+ */
+export {};

package/dist/actions/register_action_ws.d.ts

@@ -42,8 +42,8 @@ export declare const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60000;
  *
  * Fires after the transport has registered the new connection (so
  * `connection_id` is valid) but before any client message can dispatch.
- * Consumers use this to bootstrap per-socket domain state — e.g. undying
- * spawns the per-account spirit unit and pushes an initial state snapshot.
+ * Consumers use this to bootstrap per-socket domain state — e.g.
+ * spawning a per-account unit and pushing an initial state snapshot.
  */
 export interface SocketOpenContext {
     /** The raw WebSocket context — exposed for edge cases; prefer `notify` for sends. */

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

@@ -1 +1 @@
-{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,MAAM,CAAC;AAC/B,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAUjD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAgBpD,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AACpC,OAAO,EAAC,KAAK,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAI9C,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAG9F,YAAY,EAAC,MAAM,EAAC,CAAC;AAErB,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB;IACvC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;;OAOG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;;;;;OASG;IACH,EAAE,EAAE,EAAE,CAAC;IACP;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACjD;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,uBAAuB,KAAG,sBAuUrE,CAAC"}
+{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,MAAM,CAAC;AAC/B,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAUjD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAgBpD,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AACpC,OAAO,EAAC,KAAK,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAI9C,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAG9F,YAAY,EAAC,MAAM,EAAC,CAAC;AAErB,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB;IACvC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;;OAOG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;;;;;OASG;IACH,EAAE,EAAE,EAAE,CAAC;IACP;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACjD;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,uBAAuB,KAAG,sBA4VrE,CAAC"}

package/dist/actions/register_action_ws.js

@@ -90,6 +90,14 @@ export const register_action_ws = (options) => {
         // `credential_type` from this closure; the live request_context is
         // only used by the test-preset escape hatch (perform_action runs
         // the authorization phase fresh on every message in production).
+        //
+        // Per-message dispatch reloads role_grants via the authorization
+        // phase but does NOT re-query session / token validity — those
+        // are checked once at upgrade. Revocation enforcement therefore
+        // lives outside this dispatcher, in the audit-driven WS auth
+        // guard (`transports_ws_auth_guard.ts`). Without that guard wired
+        // into the audit chain, `session_revoke` / `token_revoke` are
+        // no-ops for existing WS connections.
         const upgrade_context = require_request_context(c);
         const account_id = upgrade_context.account.id;
         const client_ip = get_client_ip(c);
@@ -263,8 +271,21 @@ export const register_action_ws = (options) => {
                 // eager fire-and-forget pool writes (audit emits, etc.);
                 // `post_commit_effects` collects deferred thunks pushed
                 // via `emit_after_commit` (WS notifications). Both flush
-                // in the same try/finally so the next message sees a clean
-                // slate.
+                // in the `finally` so the next message sees a clean slate.
+                //
+                // Ordering invariant — reply-before-flush is load-bearing.
+                // Handlers that revoke their own credential
+                // (`session_revoke_all`, `token_revoke` of the calling
+                // bearer) audit-emit events whose listener chain — wired
+                // by the WS auth guard in `transports_ws_auth_guard.ts` —
+                // closes this socket when the audit row writes. The
+                // synchronous `ws.send` on the success path returns
+                // before any close can fire (the DB write that triggers
+                // the chain is async — even in production with
+                // `await_pending_effects: false`, the listener chain only
+                // runs after the row lands). Inverting the order —
+                // flushing the queues before the send — would silently
+                // strand the caller without a reply.
                 const pending_effects = [];
                 const post_commit_effects = [];
                 const notify = notify_socket(ws);

package/dist/actions/register_ws_endpoint.d.ts

@@ -12,8 +12,8 @@
  *    and build the `RequestContext` that per-message dispatch reads.
  *    Multi-actor accounts must supply `?acting` to pick a persona;
  *    single-actor accounts work without it.
- * 4. Optional `require_role(required_role)` — for endpoints gated to a
- *    specific role.
+ * 4. Optional `require_role(required_roles)` — for endpoints gated to a
+ *    non-empty any-of set of roles.
  *
  * Then delegates to `register_action_ws` for per-message JSON-RPC
  * dispatch.
@@ -25,19 +25,21 @@ import { type RegisterActionWsOptions, type RegisterActionWsResult } from './reg
 /** Options for `register_ws_endpoint`. */
 export interface RegisterWsEndpointOptions extends RegisterActionWsOptions {
     /**
-     * Origin allowlist regexes — typically parsed from the `ALLOWED_ORIGINS`
+     * Origin allowlist regexes — typically parsed from the `FUZ_ALLOWED_ORIGINS`
      * env var via `parse_allowed_origins`. Passed straight to
      * `verify_request_source`.
      */
-    allowed_origins: Array<RegExp>;
+    allowed_origins: ReadonlyArray<RegExp>;
     /**
-     * Role required to upgrade. Omit for any authenticated account
-     * (`require_auth` + actor resolution alone); set to e.g. `ROLE_ADMIN`
-     * to gate the endpoint behind a role. The per-action `auth` in each
-     * spec still applies at dispatch time — this is a coarse upgrade-time
-     * gate.
+     * 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
+     * `auth` in each spec still applies at dispatch time — this is a coarse
+     * upgrade-time gate.
      */
-    required_role?: RoleName;
+    required_roles?: ReadonlyArray<RoleName>;
 }
 /**
  * Mount a WebSocket endpoint with the standard upgrade stack (origin check

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;;;;;;;;;;;;;;;;;;;;;GAqBG;AAYH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AAGrD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,0CAA0C;AAC1C,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACzE;;;;OAIG;IACH,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;CACzB;AAgDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,yBAAyB,KAChC,sBAmBF,CAAC"}
+{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAYH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AAGrD,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;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,yBAAyB,KAChC,sBAmBF,CAAC"}

package/dist/actions/register_ws_endpoint.js

@@ -12,8 +12,8 @@
  *    and build the `RequestContext` that per-message dispatch reads.
  *    Multi-actor accounts must supply `?acting` to pick a persona;
  *    single-actor accounts work without it.
- * 4. Optional `require_role(required_role)` — for endpoints gated to a
- *    specific role.
+ * 4. Optional `require_role(required_roles)` — for endpoints gated to a
+ *    non-empty any-of set of roles.
  *
  * Then delegates to `register_action_ws` for per-message JSON-RPC
  * dispatch.
@@ -77,12 +77,12 @@ const create_ws_authorization_middleware = (db) => {
  *   then registers the `GET path` route via the inner `register_action_ws`
  */
 export const register_ws_endpoint = (options) => {
-    const { app, path, allowed_origins, db, required_role, log = new Logger('[ws]'), ...rest } = options;
+    const { app, path, allowed_origins, db, required_roles, log = new Logger('[ws]'), ...rest } = options;
     app.use(path, verify_request_source(allowed_origins));
     app.use(path, require_auth);
     app.use(path, create_ws_authorization_middleware(db));
-    if (required_role !== undefined) {
-        app.use(path, require_role([required_role]));
+    if (required_roles?.length) {
+        app.use(path, require_role(required_roles));
     }
     return register_action_ws({ app, path, db, log, ...rest });
 };

package/dist/actions/transports_ws_auth_guard.d.ts

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

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

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

package/dist/actions/transports_ws_auth_guard.js

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

package/dist/actions/ws_endpoint_spec.d.ts

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

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

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

package/dist/actions/ws_endpoint_spec.js

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