@fuzdev/fuz_app 0.54.0 → 0.56.0

package/dist/actions/register_action_ws.js

@@ -2,63 +2,64 @@
  * WebSocket JSON-RPC dispatch — the low-level WS transport binding.
  *
  * Most consumers should mount WS endpoints via `register_ws_endpoint`
- * (`actions/register_ws_endpoint.ts`), which wraps this function with the standard
- * upgrade stack (origin check + auth + optional role). This module stays
- * exported as the lower-level entry point for tests that drive the
- * dispatcher directly via `create_ws_test_harness`.
+ * (`actions/register_ws_endpoint.ts`), which wraps this function with the
+ * standard upgrade stack (origin check + auth + optional role). This
+ * module stays exported as the lower-level entry point for tests that
+ * drive the dispatcher directly via `create_ws_test_harness`.
  *
  * Symmetric to `create_rpc_endpoint` (from `actions/action_rpc.ts`):
- * consumer supplies action specs + a handler map, the dispatcher parses the
- * envelope, checks per-action auth, validates input, invokes the handler with
- * a per-request context, and writes the response.
- *
- * Extracted from zzz's `register_websocket_actions` to converge pattern drift
- * across consumers (zzz, tx, undying). Broadcast-style notifications remain
- * domain-shaped today — this module only covers per-request dispatch + the
- * socket-scoped `ctx.notify` + per-socket `ctx.signal`. See
- * `BackendWebsocketTransport.send` for broadcast.
+ * both transports parse their wire envelope, then call the shared
+ * `perform_action` core (`actions/perform_action.ts`) for the post-parse
+ * pipeline. WS-specific concerns — connection lifecycle, heartbeat,
+ * cancel-notification interception, socket-scoped notify — stay in this
+ * module; everything else (auth gates, input validation, authorization
+ * phase, rate limiting, transactional dispatch, DEV output validation,
+ * thrown-error normalization) is shared.
  *
  * ## Auth expectations
  *
- * The consumer is responsible for rejecting unauthenticated upgrades *before*
- * routing to this handler (fuz_app's `require_auth` middleware, or
- * `register_ws_endpoint` which wires it for you). Inside the dispatcher,
- * `get_request_context(c)` is treated as guaranteed non-null and per-action
- * auth is enforced on each message.
+ * The consumer is responsible for rejecting unauthenticated upgrades
+ * *before* routing to this handler (fuz_app's `require_auth` middleware,
+ * or `register_ws_endpoint` which wires it for you). Per-action auth
+ * runs inside `perform_action` on every message via the same gates HTTP
+ * RPC uses.
  *
  * @module
  */
-import { DEV } from 'esm-env';
 import { wait } from '@fuzdev/fuz_util/async.js';
 import { Logger } from '@fuzdev/fuz_util/log.js';
-import { get_request_context, has_role } from '../auth/request_context.js';
+import { get_request_context, require_request_context, } from '../auth/request_context.js';
 import { hash_session_token } from '../auth/session_queries.js';
-import { ROLE_KEEPER } from '../auth/role_schema.js';
 import { get_client_ip } from '../http/proxy.js';
-import { JSONRPC_VERSION } from '../http/jsonrpc.js';
-import { jsonrpc_error_messages, ThrownJsonrpcError } from '../http/jsonrpc_errors.js';
-import { create_jsonrpc_error_response, create_jsonrpc_error_response_from_thrown, create_jsonrpc_notification, to_jsonrpc_message_id, to_jsonrpc_params, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
-import { CREDENTIAL_TYPE_KEY, AUTH_API_TOKEN_ID_KEY } from '../hono_context.js';
+import { flush_pending_effects, flush_post_commit_effects } from '../http/pending_effects.js';
+import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
+import { create_jsonrpc_error_response, create_jsonrpc_notification, to_jsonrpc_message_id, to_jsonrpc_params, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
+import { CREDENTIAL_TYPE_KEY, AUTH_API_TOKEN_ID_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 { WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT } from './transports.js';
 import { BackendWebsocketTransport } from './transports_ws_backend.js';
+import { perform_action, perform_action_result_to_envelope } from './perform_action.js';
 /** Default inactivity window before the server closes a silent socket. */
 export const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60_000;
 /**
- * Mount a JSON-RPC WebSocket endpoint that dispatches to the supplied handler
- * map. Per-request context is built from the base + consumer-provided
- * `RegisterActionWsOptions.extend_context`.
+ * Mount a JSON-RPC WebSocket endpoint that dispatches via the shared
+ * `perform_action` core.
  *
  * Wire behavior:
  * - Batch JSON-RPC is rejected (single-message only).
  * - Notifications (method + no id) are silently dropped per JSON-RPC spec.
- * - Per-action auth: `public` / `authenticated` pass through (upgrade auth
- *   already verified identity); `keeper` requires `daemon_token` credential
- *   type *and* the keeper role; role-based `{role}` requires the named role
- *   via `has_role`, matching the HTTP path in `actions/action_rpc.ts`.
- * - DEV mode validates handler output against the spec's `output` schema and
- *   warns on mismatches.
+ *   Exception: `cancel` notifications abort the matching pending request's
+ *   `ctx.signal` before bubbling out.
+ * - Per-message dispatch goes through `perform_action`: pre-validation
+ *   auth (401) → input validation (400) → authorization phase →
+ *   post-authorization auth (403) → rate limit (429) → handler (with
+ *   transaction wrap iff `spec.side_effects: true`) → DEV output validation.
+ * - Authorization phase runs **per message** — role_grant changes during a
+ *   connection lifetime are picked up on the next message without any
+ *   in-place refresh. Authentication invalidation closes the socket via
+ *   `create_ws_auth_guard`.
  *
  * @returns the transport (supplied or freshly created) — retain it to wire
  *   `create_ws_auth_guard` or broadcast on audit events.
@@ -67,23 +68,14 @@ export const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60_000;
  *   in the transport's internal maps via `add_connection` / `remove_connection`
  */
 export const register_action_ws = (options) => {
-    const { path, app, upgradeWebSocket, actions, extend_context, transport = new BackendWebsocketTransport(), heartbeat = true, artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, action_ip_rate_limiter = null, action_account_rate_limiter = null, } = options;
-    // Fan the unified actions array into the two lookups the dispatcher
-    // consults at message time. Keeping them internal means the composable
-    // `{spec, handler}` tuple remains the only shape consumers name.
-    const spec_by_method = new Map();
-    const handlers = {};
-    for (const action of actions) {
-        spec_by_method.set(action.spec.method, action.spec);
-        if (action.handler)
-            handlers[action.spec.method] = action.handler;
-        // Reject account-keyed rate limiting on public actions — the dispatcher
-        // has no actor to key on. Mirrors the HTTP RPC registration check.
-        if ((action.spec.rate_limit === 'account' || action.spec.rate_limit === 'both') &&
-            action.spec.auth === 'public') {
-            throw new Error(`WS action "${action.spec.method}" declares rate_limit: '${action.spec.rate_limit}' but auth: 'public' — no actor available for account-keyed limiting. Use 'ip' or change auth.`);
-        }
-    }
+    const { path, app, upgradeWebSocket, actions, db, transport = new BackendWebsocketTransport(), heartbeat = true, artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, action_ip_rate_limiter = null, action_account_rate_limiter = null, } = options;
+    // Build the dispatcher's per-method lookup. Only request_response
+    // specs with a handler reach `action_map` — perform_action is the
+    // only site that calls handlers, and it requires an `RpcAction`.
+    // Other kinds (`remote_notification` like `cancel`, `local_call`)
+    // are registry-only on WS; the cancel handler reads
+    // `cancel_action_spec.method` directly.
+    const { action_map } = compile_action_registry(actions, 'WS action');
     const heartbeat_enabled = heartbeat !== false;
     const heartbeat_config = typeof heartbeat === 'object' ? heartbeat : {};
     const heartbeat_timeout = heartbeat_config.timeout ?? DEFAULT_SERVER_HEARTBEAT_TIMEOUT;
@@ -92,14 +84,14 @@ export const register_action_ws = (options) => {
     // dead-because-unresponsive that closing is arguably correct.
     const heartbeat_tick_interval = Math.max(100, Math.floor(heartbeat_timeout / 2));
     app.get(path, upgradeWebSocket((c) => {
-        // Upgrade-time auth extraction — `require_auth` middleware has already
-        // rejected unauthenticated requests, so request_context is guaranteed
-        // non-null by the time we get here.
-        const request_context = get_request_context(c);
-        const account_id = request_context.account.id;
-        // Resolved at upgrade — every message on this socket shares the
-        // same client IP, so we capture once and reuse for rate-limit
-        // keying. `'unknown'` if the proxy middleware wasn't in the stack.
+        // Upgrade-time identity capture. `require_auth` middleware has
+        // already rejected unauthenticated upgrades, so request_context is
+        // non-null here. Per-message dispatch reads `account_id` +
+        // `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).
+        const upgrade_context = require_request_context(c);
+        const account_id = upgrade_context.account.id;
         const client_ip = get_client_ip(c);
         const credential_type = c.get(CREDENTIAL_TYPE_KEY);
         // Session-based connections have a token hash for targeted revocation.
@@ -110,6 +102,12 @@ export const register_action_ws = (options) => {
         // `close_sockets_for_token` to tear down just this socket on
         // `token_revoke` without affecting the account's other sockets.
         const api_token_id = c.get(AUTH_API_TOKEN_ID_KEY);
+        // Test escape hatch — captured once at upgrade. perform_action
+        // honors it per-message so harnesses with pre-baked
+        // `RequestContext` skip the live authorization phase.
+        const upgrade_preset = c.get(TEST_CONTEXT_PRESET_KEY)
+            ? { request_context: get_request_context(c) }
+            : undefined;
         // Per-socket abort controller — fires on socket close, chained into
         // every in-flight handler's per-request controller via
         // `AbortSignal.any`. Keeping both signals lets the client
@@ -128,9 +126,9 @@ export const register_action_ws = (options) => {
         // down; `BackendWebsocketTransport.#revoke_connection` clears the
         // identity map before Hono fires onClose.
         const identity = { token_hash, account_id, api_token_id };
-        // Captured on open, consumed on close. Null before onOpen fires or
-        // when a consumer never opens (e.g. immediate disconnect).
-        let captured_connection_id = null;
+        // Captured on open, consumed on close. Undefined before onOpen
+        // fires or when a consumer never opens (e.g. immediate disconnect).
+        let captured_connection_id;
         // Receive-silence watchdog. Seeded to open-time so the first window is
         // exempt (cold-start grace — avoid killing mid-handshake sockets).
         // Bumped by onMessage. Any incoming activity counts, not just
@@ -240,80 +238,19 @@ export const register_action_ws = (options) => {
                     return;
                 }
                 const { method, id, params } = json;
-                // Per-action auth check — enforce auth level from spec.
-                const spec = spec_by_method.get(method);
-                if (!spec) {
+                // Per-action method lookup — return method_not_found before
+                // we engage the dispatch machinery. Specs without a handler
+                // (client-only / dispatcher-handled) miss action_map and
+                // surface as method_not_found just like unknown methods.
+                const action = action_map.get(method);
+                if (!action) {
                     ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.method_not_found(method))));
                     return;
                 }
-                const { auth } = spec;
-                if (auth === 'keeper') {
-                    if (credential_type !== 'daemon_token' || !has_role(request_context, ROLE_KEEPER)) {
-                        ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.forbidden('keeper actions require daemon_token credential with keeper role'))));
-                        return;
-                    }
-                }
-                else if (typeof auth === 'object' && auth !== null) {
-                    if (!has_role(request_context, auth.role)) {
-                        ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.forbidden(`requires role: ${auth.role}`))));
-                        return;
-                    }
-                }
-                // Rate limit — throttle-requests semantics, mirrors the HTTP RPC
-                // dispatcher. Same limiters are shared across transports so an
-                // attacker can't bypass the budget by switching from RPC to WS.
-                const rate_limit = spec.rate_limit;
-                if (rate_limit) {
-                    const ip_check = action_ip_rate_limiter && (rate_limit === 'ip' || rate_limit === 'both');
-                    const account_check = action_account_rate_limiter && (rate_limit === 'account' || rate_limit === 'both');
-                    const send_rate_limited = (retry_after) => {
-                        ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.rate_limited('rate limited', { retry_after }))));
-                    };
-                    if (ip_check) {
-                        const result = action_ip_rate_limiter.check(client_ip);
-                        if (!result.allowed) {
-                            send_rate_limited(result.retry_after);
-                            return;
-                        }
-                    }
-                    if (account_check) {
-                        const result = action_account_rate_limiter.check(request_context.actor.id);
-                        if (!result.allowed) {
-                            send_rate_limited(result.retry_after);
-                            return;
-                        }
-                    }
-                    if (ip_check)
-                        action_ip_rate_limiter.record(client_ip);
-                    if (account_check)
-                        action_account_rate_limiter.record(request_context.actor.id);
-                }
-                // Look up handler — method is validated against spec_by_method above.
-                const handler = handlers[method];
-                if (!handler) {
-                    ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.method_not_found(method))));
-                    return;
-                }
-                // Validate input against spec schema.
-                const parsed = spec.input.safeParse(params);
-                if (!parsed.success) {
-                    ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.invalid_params(`invalid params for ${method}`, {
-                        issues: parsed.error.issues,
-                    }))));
-                    return;
-                }
-                const validated_input = parsed.data;
                 if (artificial_delay > 0) {
                     log.debug(`throttling ${artificial_delay}ms`);
                     await wait(artificial_delay);
                 }
-                // Socket-scoped notification — routes to originator only, not
-                // broadcast. Same helper used in `on_socket_open` so both
-                // paths share one code path for send-and-log-on-failure.
-                // Future work: other audiences — account-scoped,
-                // ACL-filtered, broadcast — likely via a transport-level
-                // policy hook.
-                const notify = notify_socket(ws);
                 // Per-request controller — fires on explicit `cancel` or on
                 // socket close (via the socket_abort_controller chain below).
                 // Registered before dispatch so a cancel arriving mid-handler
@@ -322,40 +259,45 @@ export const register_action_ws = (options) => {
                 // null-abort the wrong handler.
                 const request_controller = new AbortController();
                 pending_controllers.set(id, request_controller);
-                const base = {
-                    request_id: id,
-                    // Populated in `onOpen` before any message can dispatch —
-                    // non-null assertion is safe.
-                    connection_id: captured_connection_id,
-                    notify,
-                    signal: AbortSignal.any([socket_abort_controller.signal, request_controller.signal]),
-                };
-                const ctx = extend_context(base, c);
+                // Per-message side-effect queues. `pending_effects` collects
+                // 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.
+                const pending_effects = [];
+                const post_commit_effects = [];
+                const notify = notify_socket(ws);
+                const signal = AbortSignal.any([
+                    socket_abort_controller.signal,
+                    request_controller.signal,
+                ]);
                 try {
-                    const output = await handler(validated_input, ctx);
-                    // DEV-only output validation — catches handler bugs during development.
-                    if (DEV) {
-                        const output_parsed = spec.output.safeParse(output);
-                        if (!output_parsed.success) {
-                            log.error(`output validation failed for ${method}:`, output_parsed.error.issues);
-                        }
-                    }
-                    // Send result directly — null stays null, matching the HTTP RPC path.
-                    ws.send(JSON.stringify({ jsonrpc: JSONRPC_VERSION, id, result: output }));
-                }
-                catch (error) {
-                    if (error instanceof ThrownJsonrpcError) {
-                        // Expected handler outcome (conflict, not_found, invalid_params, ...).
-                        // Log at debug without the stack — the throw site is part of protocol, not a bug.
-                        log.debug('handler error:', method, `${error.code} ${error.message}`);
-                    }
-                    else {
-                        log.error('handler error:', method, error);
-                    }
-                    ws.send(JSON.stringify(create_jsonrpc_error_response_from_thrown(id, error)));
+                    const result = await perform_action({
+                        action,
+                        raw_params: params,
+                        request_id: id,
+                        account_id,
+                        credential_type,
+                        client_ip,
+                        signal,
+                        notify,
+                        connection_id: captured_connection_id,
+                        preset: upgrade_preset,
+                    }, {
+                        db,
+                        pending_effects,
+                        post_commit_effects,
+                        log,
+                        action_ip_rate_limiter,
+                        action_account_rate_limiter,
+                    });
+                    ws.send(JSON.stringify(perform_action_result_to_envelope(id, result)));
                 }
                 finally {
                     pending_controllers.delete(id);
+                    await flush_pending_effects(pending_effects, log);
+                    await flush_post_commit_effects(post_commit_effects, log);
                 }
             },
             onClose: async (event, ws) => {

package/dist/actions/register_ws_endpoint.d.ts

@@ -7,7 +7,12 @@
  * 1. `verify_request_source(allowed_origins)` — reject disallowed origins
  *    before the upgrade handshake runs.
  * 2. `require_auth` — reject unauthenticated upgrades.
- * 3. Optional `require_role(required_role)` — for endpoints gated to a
+ * 3. **Authorization phase** — resolve the acting actor against the
+ *    authenticated account plus an optional `?acting=<uuid>` query string,
+ *    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.
  *
  * Then delegates to `register_action_ws` for per-message JSON-RPC
@@ -17,9 +22,8 @@
  */
 import type { RoleName } from '../auth/role_schema.js';
 import { type RegisterActionWsOptions, type RegisterActionWsResult } from './register_action_ws.js';
-import type { BaseHandlerContext } from './action_types.js';
 /** Options for `register_ws_endpoint`. */
-export interface RegisterWsEndpointOptions<TCtx extends BaseHandlerContext> extends RegisterActionWsOptions<TCtx> {
+export interface RegisterWsEndpointOptions extends RegisterActionWsOptions {
     /**
      * Origin allowlist regexes — typically parsed from the `ALLOWED_ORIGINS`
      * env var via `parse_allowed_origins`. Passed straight to
@@ -27,23 +31,24 @@ export interface RegisterWsEndpointOptions<TCtx extends BaseHandlerContext> exte
      */
     allowed_origins: Array<RegExp>;
     /**
-     * Role required to upgrade. Omit for any authenticated account (`require_auth`
-     * 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.
+     * 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.
      */
     required_role?: RoleName;
 }
 /**
  * Mount a WebSocket endpoint with the standard upgrade stack (origin check
- * + auth + optional role) and JSON-RPC dispatch.
+ * + auth + actor resolution + optional role) and JSON-RPC dispatch.
  *
  * Returns the `BackendWebsocketTransport` (supplied or freshly
  * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
  *
- * @mutates options.app - applies origin/auth/role middleware via `app.use`,
+ * @mutates options.app - applies origin/auth/authorization/role middleware via `app.use`,
  *   then registers the `GET path` route via the inner `register_action_ws`
  */
-export declare const register_ws_endpoint: <TCtx extends BaseHandlerContext>(options: RegisterWsEndpointOptions<TCtx>) => RegisterActionWsResult;
+export declare const register_ws_endpoint: (options: RegisterWsEndpointOptions) => RegisterActionWsResult;
 //# sourceMappingURL=register_ws_endpoint.d.ts.map

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;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAE1D,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB,CACzC,IAAI,SAAS,kBAAkB,CAC9B,SAAQ,uBAAuB,CAAC,IAAI,CAAC;IACtC;;;;OAIG;IACH,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,kBAAkB,EACnE,SAAS,yBAAyB,CAAC,IAAI,CAAC,KACtC,sBAUF,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,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"}

package/dist/actions/register_ws_endpoint.js

@@ -7,7 +7,12 @@
  * 1. `verify_request_source(allowed_origins)` — reject disallowed origins
  *    before the upgrade handshake runs.
  * 2. `require_auth` — reject unauthenticated upgrades.
- * 3. Optional `require_role(required_role)` — for endpoints gated to a
+ * 3. **Authorization phase** — resolve the acting actor against the
+ *    authenticated account plus an optional `?acting=<uuid>` query string,
+ *    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.
  *
  * Then delegates to `register_action_ws` for per-message JSON-RPC
@@ -16,26 +21,68 @@
  * @module
  */
 import { Logger } from '@fuzdev/fuz_util/log.js';
-import { require_auth, require_role } from '../auth/request_context.js';
+import { apply_authorization_phase, REQUEST_CONTEXT_KEY, require_auth, require_role, } from '../auth/request_context.js';
 import { verify_request_source } from '../http/origin.js';
+import { ACCOUNT_ID_KEY, TEST_CONTEXT_PRESET_KEY } from '../hono_context.js';
 import { register_action_ws, } from './register_action_ws.js';
+/** Synthesized auth shape for WS upgrade: account + actor both required. */
+const WS_UPGRADE_AUTH = {
+    account: 'required',
+    actor: 'required',
+};
+/**
+ * Upgrade-time authorization middleware. Resolves the acting actor for
+ * the WS connection (single-actor default; multi-actor must supply
+ * `?acting=<uuid>`) and builds the `RequestContext` that per-message
+ * dispatch reads. Returns 400 on resolution failure.
+ *
+ * Sets `REQUEST_CONTEXT_KEY` on resolved outcomes so the inner
+ * `register_action_ws` reads the upgrade-time context via
+ * `require_request_context(c)`. Honors the test-preset escape hatch the
+ * same way the REST and HTTP RPC binders do.
+ */
+const create_ws_authorization_middleware = (db) => {
+    return async (c, next) => {
+        // Test escape hatch — harnesses pre-populate `REQUEST_CONTEXT_KEY`
+        // + flag `TEST_CONTEXT_PRESET_KEY = true`. Production middleware
+        // never sets this flag.
+        if (c.get(TEST_CONTEXT_PRESET_KEY)) {
+            await next();
+            return;
+        }
+        const acting_param = c.req.query('acting');
+        const account_id = c.get(ACCOUNT_ID_KEY) ?? null;
+        const result = await apply_authorization_phase({ db }, account_id, WS_UPGRADE_AUTH, acting_param ?? undefined);
+        if (!result.ok)
+            return c.json(result.body, result.status);
+        if (result.request_context !== null) {
+            c.set(REQUEST_CONTEXT_KEY, result.request_context);
+        }
+        // `request_context: null` is unreachable here — `WS_UPGRADE_AUTH` is
+        // `account: 'required', actor: 'required'`, and `require_auth` ran
+        // upstream, so neither the public nor the unauthenticated branch
+        // resolves through this middleware.
+        await next();
+    };
+};
 /**
  * Mount a WebSocket endpoint with the standard upgrade stack (origin check
- * + auth + optional role) and JSON-RPC dispatch.
+ * + auth + actor resolution + optional role) and JSON-RPC dispatch.
  *
  * Returns the `BackendWebsocketTransport` (supplied or freshly
  * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
  *
- * @mutates options.app - applies origin/auth/role middleware via `app.use`,
+ * @mutates options.app - applies origin/auth/authorization/role middleware via `app.use`,
  *   then registers the `GET path` route via the inner `register_action_ws`
  */
 export const register_ws_endpoint = (options) => {
-    const { app, path, allowed_origins, required_role, log = new Logger('[ws]'), ...rest } = options;
+    const { app, path, allowed_origins, db, required_role, 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));
+        app.use(path, require_role([required_role]));
     }
-    return register_action_ws({ app, path, log, ...rest });
+    return register_action_ws({ app, path, db, log, ...rest });
 };

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,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EACX,gCAAgC,EAChC,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,sEAAsE;AACtE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,yEAAyE;AACzE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AAKtD,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;IAS9C;;;;;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;CA2CtE"}
+{"version":3,"file":"transports.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EACX,gCAAgC,EAChC,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,sEAAsE;AACtE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,yEAAyE;AACzE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AAKtD,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"}

package/dist/actions/transports.js

@@ -32,7 +32,6 @@ export class Transports {
      */
     register_transport(transport) {
         this.#transport_by_name.set(transport.transport_name, transport); // TODO maybe ensure unregistering of any previous transport?
-        // Set current transport if not already set
         if (!this.#current_transport) {
             this.#current_transport = transport;
         }
@@ -87,7 +86,6 @@ export class Transports {
         return null;
     }
     #get_first_ready(transport_name) {
-        // First try the specified transport(s) if provided
         if (transport_name) {
             const transport_names = Array.isArray(transport_name) ? transport_name : [transport_name];
             for (const transport_name of transport_names) {
@@ -97,11 +95,9 @@ export class Transports {
                 }
             }
         }
-        // Then try the current transport if it's ready
         if (this.#current_transport?.is_ready()) {
             return this.#current_transport;
         }
-        // Finally, try any other available transport
         for (const transport of this.#transport_by_name.values()) {
             if (transport.is_ready()) {
                 return transport;

package/dist/actions/transports_ws_auth_guard.d.ts

@@ -31,7 +31,7 @@ export type AuditEventHandler = (event: AuditLogEvent) => void;
  * - `session_revoke_all` / `token_revoke_all` / `password_change` — close every socket
  *   for the affected account (all credentials invalidated).
  *
- * `permit_revoke` is intentionally omitted: the WS transport does not track
+ * `role_grant_revoke` is intentionally omitted: the WS transport does not track
  * per-connection role requirements, so role-scoped disconnection would
  * require either closing all sockets (too aggressive) or new tracking
  * (out of scope). Consumers that need it compose their own callback.

package/dist/actions/transports_ws_auth_guard.js

@@ -18,7 +18,7 @@
  * - `session_revoke_all` / `token_revoke_all` / `password_change` — close every socket
  *   for the affected account (all credentials invalidated).
  *
- * `permit_revoke` is intentionally omitted: the WS transport does not track
+ * `role_grant_revoke` is intentionally omitted: the WS transport does not track
  * per-connection role requirements, so role-scoped disconnection would
  * require either closing all sockets (too aggressive) or new tracking
  * (out of scope). Consumers that need it compose their own callback.

package/dist/actions/transports_ws_backend.d.ts

@@ -97,7 +97,7 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * Broadcast to connections whose identity satisfies a predicate.
      *
      * Used by the broadcast API when a consumer supplies a subscription ACL hook
-     * (e.g. tx's `tx_run_created` only reaches the account that owns the run).
+     * (e.g. zap's `zap_run_created` only reaches the account that owns the run).
      * When no ACL is needed, callers should prefer `send(message)` / `#broadcast`
      * to skip the per-connection predicate overhead.
      *

package/dist/actions/transports_ws_backend.js

@@ -146,7 +146,7 @@ export class BackendWebsocketTransport {
      * Broadcast to connections whose identity satisfies a predicate.
      *
      * Used by the broadcast API when a consumer supplies a subscription ACL hook
-     * (e.g. tx's `tx_run_created` only reaches the account that owns the run).
+     * (e.g. zap's `zap_run_created` only reaches the account that owns the run).
      * When no ACL is needed, callers should prefer `send(message)` / `#broadcast`
      * to skip the per-connection predicate overhead.
      *