@fuzdev/fuz_app 0.53.0 → 0.55.0

package/dist/actions/register_action_ws.js

@@ -23,15 +23,15 @@
  * 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.
+ * `require_request_context(c)` enforces the dispatcher invariant and
+ * per-action auth is enforced on each message.
  *
  * @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 { has_role, 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';
@@ -95,7 +95,7 @@ export const register_action_ws = (options) => {
         // 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 request_context = require_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
@@ -277,7 +277,7 @@ export const register_action_ws = (options) => {
                         }
                     }
                     if (account_check) {
-                        const result = action_account_rate_limiter.check(request_context.actor.id);
+                        const result = action_account_rate_limiter.check(request_context.account.id);
                         if (!result.allowed) {
                             send_rate_limited(result.retry_after);
                             return;
@@ -286,7 +286,7 @@ export const register_action_ws = (options) => {
                     if (ip_check)
                         action_ip_rate_limiter.record(client_ip);
                     if (account_check)
-                        action_account_rate_limiter.record(request_context.actor.id);
+                        action_account_rate_limiter.record(request_context.account.id);
                 }
                 // Look up handler — method is validated against spec_by_method above.
                 const handler = handlers[method];

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
@@ -16,6 +21,7 @@
  * @module
  */
 import type { RoleName } from '../auth/role_schema.js';
+import type { Db } from '../db/db.js';
 import { type RegisterActionWsOptions, type RegisterActionWsResult } from './register_action_ws.js';
 import type { BaseHandlerContext } from './action_types.js';
 /** Options for `register_ws_endpoint`. */
@@ -27,22 +33,29 @@ 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.
+     * Pool-level database used for upgrade-time actor resolution + permit
+     * load. Ran once per connection, then the result is reused for every
+     * message on the socket.
+     */
+    db: Db;
+    /**
+     * 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;

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;AAOH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AACpC,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;;;;OAIG;IACH,EAAE,EAAE,EAAE,CAAC;IACP;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;CACzB;AAqBD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,kBAAkB,EACnE,SAAS,yBAAyB,CAAC,IAAI,CAAC,KACtC,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,24 +21,44 @@
  * @module
  */
 import { Logger } from '@fuzdev/fuz_util/log.js';
-import { require_auth, require_role } from '../auth/request_context.js';
+import { apply_authorization_phase, require_auth, require_role } from '../auth/request_context.js';
 import { verify_request_source } from '../http/origin.js';
 import { register_action_ws, } from './register_action_ws.js';
+/**
+ * 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.
+ */
+const create_ws_authorization_middleware = (db) => {
+    return async (c, next) => {
+        const acting_param = c.req.query('acting');
+        // `apply_authorization_phase` is a no-op when the test-harness flag
+        // `TEST_CONTEXT_PRESET_KEY` is set (escape hatch for pre-baked
+        // `RequestContext`). Failure shape is `{status, body}`; the WS
+        // upgrade is a plain HTTP response, so bind it the same way REST does.
+        const failure = await apply_authorization_phase({ db }, c, true, acting_param ?? undefined);
+        if (failure)
+            return c.json(failure.body, failure.status);
+        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));
     }

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;