@fuzdev/fuz_app 0.125.0 → 0.127.0

package/dist/testing/cross_backend/ws_action_rate_limit.js

@@ -0,0 +1,261 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-backend parity suite for **action rate limiting over a real
+ * WebSocket**, and its budget shared with HTTP RPC.
+ *
+ * An action spec's `rate_limit` class (`'ip'` / `'account'` / `'both'`) is
+ * charged by the dispatcher on both transports, and a server holds one
+ * limiter per axis, so an action's budget is per caller, not per transport.
+ * The in-process tests pin that through an assembled app; this suite pins it
+ * over the wire, against backends spawned with small shared limiters (the
+ * action rate-limit toggles — `ACTION_RATE_LIMIT_ENABLED_ENV` and
+ * `ACTION_RATE_LIMIT_MAX_ATTEMPTS_ENV` — see `global_setup_login_security.ts`):
+ *
+ * - **account axis over WS** — `account_token_create` (`rate_limit:
+ *   'account'` on both spines) with malformed params: the first `max_attempts`
+ *   calls each answer `invalid_params` (the throttle runs before params
+ *   validation, so a malformed call still charges), and the next answers
+ *   `rate_limited` with a `retry_after`.
+ * - **one account bucket across transports** — calls split between HTTP RPC and
+ *   WS exhaust one budget: the call past the cap is refused on WS and on HTTP
+ *   (`429`).
+ * - **IP axis, keyed by the resolved client IP** — `peer/ping` (`rate_limit:
+ *   'ip'`, public) with malformed params, from one `X-Forwarded-For` address
+ *   over anonymous HTTP and over a WS whose upgrade carried the same header:
+ *   the call past the cap is refused on both, while a second address keeps its
+ *   own budget on both.
+ * - **account axis at the dispatchers** — `cell_create` (`rate_limit:
+ *   'account'`, on both spines' RPC and WS mounts) with malformed params: the
+ *   call past the cap answers `429` over HTTP and `rate_limited` over WS, calls
+ *   split between the two transports exhaust one budget, and a budget split
+ *   between `cell_create` and `account_token_create` is one bucket.
+ *
+ * **Charge sites.** The TS spine charges every classed action in its
+ * dispatcher. The Rust stub has two sites holding the same limiters: the auth
+ * families (`account_token_create`) charge inside their handlers, and the
+ * dispatcher states charge every other classed spec. So the
+ * `account_token_create` cases pin the Rust in-handler site, `peer/ping` pins
+ * the Rust WS dispatcher's IP axis, and `cell_create` pins the account axis of
+ * both Rust dispatchers, RPC and WS.
+ *
+ * **Isolation.** Limiter state is in-memory and `_testing_reset` wipes only
+ * the database, so every case reads a bucket no other case touched: the
+ * account cases each run on the fresh keeper the reset seeds (a new account
+ * id), and the IP case uses addresses no other case sends. Login limiters are
+ * also on in this project; nothing here logs in.
+ *
+ * Cross-process only: the composition under test is the spawned binary's
+ * (`create_app_server` threading one limiter pair to both mounts on TS; the
+ * stub's dispatcher states plus its auth-family builders on Rust).
+ *
+ * `$lib`-free by contract (relative specifiers only), like the sibling
+ * cross-backend suites.
+ *
+ * @module
+ */
+import { assert, describe, test } from 'vitest';
+import { create_jsonrpc_request } from '../../http/jsonrpc_helpers.js';
+import { create_ws_transport } from '../transports/ws_transport.js';
+import { is_response_for } from '../transports/ws_client.js';
+// Wire literals are deliberate independent copies of the producers'
+// constants (`JSONRPC_ERROR_CODES` on TS, the `JsonrpcError` taxonomy on
+// Rust) — parity by test, so a renamed or renumbered code fails here.
+/** JSON-RPC `invalid_params`. */
+const CODE_INVALID_PARAMS = -32602;
+/** JSON-RPC `rate_limited` — the spines' server-side throttle code. */
+const CODE_RATE_LIMITED = -32006;
+/** An `account`-classed action on both spines (session-only, side-effecting). */
+const ACCOUNT_LIMITED_METHOD = 'account_token_create';
+/** Unknown key — refused by both spines' strict params decode, after the throttle. */
+const ACCOUNT_LIMITED_BAD_PARAMS = { not_a_param: true };
+/**
+ * An `account`-classed action the Rust stub charges at its dispatchers (not
+ * in-handler, unlike `ACCOUNT_LIMITED_METHOD`), mounted on both spines' RPC
+ * and WS. Actor-grain, so the keeper's actor resolves before the throttle; the same
+ * unknown-key params are refused by both spines' strict decode, after it.
+ */
+const DISPATCHER_ACCOUNT_LIMITED_METHOD = 'cell_create';
+/** The `ip`-classed public protocol action on both spines. */
+const IP_LIMITED_METHOD = 'peer/ping';
+/** Wrong-typed `nonce` — refused by both spines' params decode, after the throttle. */
+const IP_LIMITED_BAD_PARAMS = { nonce: 'not_a_number' };
+/**
+ * RFC 5737 TEST-NET-2 (`198.51.100.0/24`) documentation addresses, spoofed
+ * via `X-Forwarded-For` (both spines trust the loopback peer in this project).
+ * Distinct from `login_security.ts`'s TEST-NET-3 addresses, though the login
+ * and action limiters keep separate buckets anyway.
+ */
+const XFF_IP_EXHAUSTED = '198.51.100.1';
+const XFF_IP_FRESH = '198.51.100.2';
+/** Generous per-response wait — the cases assert the server's answer, not a timeout. */
+const RESPONSE_TIMEOUT_MS = 5000;
+const outcome_from_frame = (status, frame) => ({
+    status,
+    code: frame?.error?.code ?? null,
+    retry_after: frame?.error?.data?.retry_after
+});
+/**
+ * Register the action rate-limit suite: the account axis over WS, one account
+ * bucket across HTTP RPC and WS, the per-IP axis keyed by `X-Forwarded-For`
+ * across both transports, and the account axis at the RPC and WS dispatchers.
+ */
+export const describe_ws_action_rate_limit_cross_tests = (options) => {
+    const { setup_test, base_url, ws_path, max_attempts } = options;
+    const rpc_path = options.rpc_path ?? '/api/rpc';
+    assert(Number.isInteger(max_attempts) && max_attempts >= 2, 'ws_action_rate_limit needs max_attempts >= 2 to split a budget across transports');
+    let next_id = 1;
+    /** POST one JSON-RPC call on a fresh (cookie-jar-free) transport. */
+    const call_http = async (fixture, method, params, headers) => {
+        const res = await fixture.fresh_transport()(rpc_path, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...headers },
+            body: JSON.stringify(create_jsonrpc_request(method, params, next_id++))
+        });
+        const body = (await res.json().catch(() => undefined));
+        return outcome_from_frame(res.status, body);
+    };
+    /** Send one JSON-RPC call over an open socket and read its response. */
+    const call_ws = async (ws, method, params) => {
+        const id = next_id++;
+        await ws.send(create_jsonrpc_request(method, params, id));
+        const frame = await ws.wait_for(is_response_for(id), RESPONSE_TIMEOUT_MS);
+        return outcome_from_frame(null, frame);
+    };
+    /** Open a socket on the keeper's session, optionally behind a forwarded IP. */
+    const open_ws = (fixture, forwarded_for) => {
+        const cookie = fixture.create_session_headers().cookie;
+        assert.ok(cookie, 'expected a session cookie for the WS upgrade');
+        return create_ws_transport({
+            base_url,
+            ws_path,
+            cookies: [cookie],
+            origin: base_url,
+            headers: forwarded_for ? { 'x-forwarded-for': forwarded_for } : undefined
+        });
+    };
+    const assert_charged_not_limited = (outcome, label) => {
+        assert.strictEqual(outcome.code, CODE_INVALID_PARAMS, `${label}: expected invalid_params (charged, under the cap), got ${JSON.stringify(outcome)}`);
+        if (outcome.status !== null)
+            assert.strictEqual(outcome.status, 400, `${label}: HTTP status`);
+    };
+    const assert_rate_limited = (outcome, label) => {
+        assert.strictEqual(outcome.code, CODE_RATE_LIMITED, `${label}: expected rate_limited, got ${JSON.stringify(outcome)}`);
+        assert.ok(typeof outcome.retry_after === 'number' && outcome.retry_after > 0, `${label}: rate_limited carries a positive data.retry_after, got ${String(outcome.retry_after)}`);
+        if (outcome.status !== null)
+            assert.strictEqual(outcome.status, 429, `${label}: HTTP status`);
+    };
+    describe('action rate limiting (cross-process, real socket)', () => {
+        test(`an account-limited action is refused on the WS call past the cap`, async () => {
+            const fixture = await setup_test();
+            const ws = await open_ws(fixture);
+            try {
+                for (let i = 1; i <= max_attempts; i++) {
+                    assert_charged_not_limited(await call_ws(ws, ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS), `WS call ${i}`);
+                }
+                assert_rate_limited(await call_ws(ws, ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS), `WS call ${max_attempts + 1}`);
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test('HTTP RPC and WS calls draw one account budget', async () => {
+            const fixture = await setup_test();
+            const session = fixture.create_session_headers();
+            const http_calls = Math.floor(max_attempts / 2);
+            for (let i = 1; i <= http_calls; i++) {
+                assert_charged_not_limited(await call_http(fixture, ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS, session), `HTTP call ${i}`);
+            }
+            const ws = await open_ws(fixture);
+            try {
+                for (let i = http_calls + 1; i <= max_attempts; i++) {
+                    assert_charged_not_limited(await call_ws(ws, ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS), `WS call ${i}`);
+                }
+                assert_rate_limited(await call_ws(ws, ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS), 'WS call past the shared cap');
+            }
+            finally {
+                await ws.close();
+            }
+            assert_rate_limited(await call_http(fixture, ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS, session), 'HTTP call past the shared cap');
+        });
+        test('an account-limited action is refused at the RPC dispatcher past the cap', async () => {
+            const fixture = await setup_test();
+            const session = fixture.create_session_headers();
+            for (let i = 1; i <= max_attempts; i++) {
+                assert_charged_not_limited(await call_http(fixture, DISPATCHER_ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS, session), `HTTP call ${i}`);
+            }
+            assert_rate_limited(await call_http(fixture, DISPATCHER_ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS, session), `HTTP call ${max_attempts + 1}`);
+        });
+        test('an account-limited action is refused at the WS dispatcher past the cap', async () => {
+            const fixture = await setup_test();
+            const ws = await open_ws(fixture);
+            try {
+                for (let i = 1; i <= max_attempts; i++) {
+                    assert_charged_not_limited(await call_ws(ws, DISPATCHER_ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS), `WS call ${i}`);
+                }
+                assert_rate_limited(await call_ws(ws, DISPATCHER_ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS), `WS call ${max_attempts + 1}`);
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test('the dispatchers draw one account budget across HTTP RPC and WS', async () => {
+            const fixture = await setup_test();
+            const session = fixture.create_session_headers();
+            const http_calls = Math.floor(max_attempts / 2);
+            for (let i = 1; i <= http_calls; i++) {
+                assert_charged_not_limited(await call_http(fixture, DISPATCHER_ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS, session), `HTTP call ${i}`);
+            }
+            const ws = await open_ws(fixture);
+            try {
+                for (let i = http_calls + 1; i <= max_attempts; i++) {
+                    assert_charged_not_limited(await call_ws(ws, DISPATCHER_ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS), `WS call ${i}`);
+                }
+                assert_rate_limited(await call_ws(ws, DISPATCHER_ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS), 'WS call past the shared cap');
+            }
+            finally {
+                await ws.close();
+            }
+            assert_rate_limited(await call_http(fixture, DISPATCHER_ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_BAD_PARAMS, session), 'HTTP call past the shared cap');
+        });
+        test('two account-limited actions draw one account budget', async () => {
+            const fixture = await setup_test();
+            const session = fixture.create_session_headers();
+            const first_calls = Math.floor(max_attempts / 2);
+            for (let i = 1; i <= max_attempts; i++) {
+                const method = i <= first_calls ? DISPATCHER_ACCOUNT_LIMITED_METHOD : ACCOUNT_LIMITED_METHOD;
+                assert_charged_not_limited(await call_http(fixture, method, ACCOUNT_LIMITED_BAD_PARAMS, session), `HTTP ${method} call ${i}`);
+            }
+            for (const method of [DISPATCHER_ACCOUNT_LIMITED_METHOD, ACCOUNT_LIMITED_METHOD]) {
+                assert_rate_limited(await call_http(fixture, method, ACCOUNT_LIMITED_BAD_PARAMS, session), `HTTP ${method} call past the shared cap`);
+            }
+        });
+        test('an IP-limited action is keyed by the forwarded client IP on both transports', async () => {
+            // the addresses are fixed per process and their bucket outlives
+            // `_testing_reset`, so a vitest retry of this case would start
+            // exhausted and fail
+            const fixture = await setup_test();
+            const exhausted = { 'x-forwarded-for': XFF_IP_EXHAUSTED };
+            // anonymous HTTP — `peer/ping` is public, so only the IP axis applies
+            for (let i = 1; i < max_attempts; i++) {
+                assert_charged_not_limited(await call_http(fixture, IP_LIMITED_METHOD, IP_LIMITED_BAD_PARAMS, exhausted), `HTTP call ${i} from ${XFF_IP_EXHAUSTED}`);
+            }
+            const ws_exhausted = await open_ws(fixture, XFF_IP_EXHAUSTED);
+            const ws_fresh = await open_ws(fixture, XFF_IP_FRESH);
+            try {
+                assert_charged_not_limited(await call_ws(ws_exhausted, IP_LIMITED_METHOD, IP_LIMITED_BAD_PARAMS), `WS call ${max_attempts} from ${XFF_IP_EXHAUSTED}`);
+                assert_rate_limited(await call_ws(ws_exhausted, IP_LIMITED_METHOD, IP_LIMITED_BAD_PARAMS), `WS call past the cap from ${XFF_IP_EXHAUSTED}`);
+                assert_rate_limited(await call_http(fixture, IP_LIMITED_METHOD, IP_LIMITED_BAD_PARAMS, exhausted), `HTTP call past the cap from ${XFF_IP_EXHAUSTED}`);
+                // a second address has its own bucket, on both transports, even on
+                // the same account's session
+                assert_charged_not_limited(await call_ws(ws_fresh, IP_LIMITED_METHOD, IP_LIMITED_BAD_PARAMS), `WS call from ${XFF_IP_FRESH}`);
+                assert_charged_not_limited(await call_http(fixture, IP_LIMITED_METHOD, IP_LIMITED_BAD_PARAMS, {
+                    'x-forwarded-for': XFF_IP_FRESH
+                }), `HTTP call from ${XFF_IP_FRESH}`);
+            }
+            finally {
+                await ws_exhausted.close();
+                await ws_fresh.close();
+            }
+        });
+    });
+};

package/dist/testing/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;GAQG;AAEH,OAAO,EAAE,EAAE,EAA0B,MAAM,QAAQ,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAe7B,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AA2BtF,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACrC,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oEAAoE;IACpE,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,4CAA4C;IAC5C,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,0CAA0C;IAC1C,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,+DAA+D;IAC/D,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,gFAAgF;IAChF,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+GAA+G;IAC/G,qBAAqB,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAClC;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAChE,+EAA+E;IAC/E,oBAAoB,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC9C,2FAA2F;IAC3F,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mGAAmG;IACnG,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mGAAmG;IACnG,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,uEAAuE;IACvE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAChD;AAID,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC/B,aAAa,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IACxC,eAAe,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1C,qBAAqB,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IAChD,2BAA2B,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IACtD,0BAA0B,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;CACrD;AAKD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GAAI,IAAI,qBAAqB,KAAG,eAoCpE,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,cAAc,cAAc,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GACvC,IAAI,qBAAqB,KACvB;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAwDrC,CAAC;AAIF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GACtC,YAAY,MAAM,EAClB,OAAO,KAAK,CAAC,kBAAkB,CAAC,KAC9B,IAyEF,CAAC;AAIF,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD,sDAAsD;AACtD,MAAM,WAAW,0BAA0B;IAC1C,iDAAiD;IACjD,eAAe,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAChC,oFAAoF;IACpF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC;CACpD;AAED,yDAAyD;AACzD,MAAM,WAAW,sBAAsB;IACtC,GAAG,EAAE,IAAI,CAAC;IACV,aAAa,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IACxC,eAAe,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1C,qBAAqB,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IAChD,2BAA2B,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IACtD,0BAA0B,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;CACrD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,GAC5C,UAAU,0BAA0B,KAClC,sBAwDF,CAAC"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/middleware.ts"],"names":[],"mappings":"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"}

package/dist/testing/middleware.js

@@ -12,6 +12,7 @@ import { vi, test, assert, describe } from 'vitest';
 import { Hono } from 'hono';
 import { Logger } from '@fuzdev/fuz_util/log.ts';
 import { create_bearer_auth_middleware } from '../auth/bearer_auth.js';
+import { AUTH_MIDDLEWARE_PATH } from '../auth/middleware.js';
 import { query_validate_api_token } from '../auth/api_token_queries.js';
 import { query_account_by_id, query_actor_by_id, query_active_actors_by_account } from '../auth/account_queries.js';
 import { query_role_grant_find_active_for_actor } from '../auth/role_grant_queries.js';
@@ -117,7 +118,7 @@ export const create_bearer_auth_test_app = (tc) => {
         c.set('client_ip', TEST_CLIENT_IP);
         await next();
     });
-    app.use('/api/*', bearer_middleware);
+    app.use(AUTH_MIDDLEWARE_PATH, bearer_middleware);
     // route handler echoes the account-grain identity the middleware writes
     // (bearer auth sets `ACCOUNT_ID_KEY` + `CREDENTIAL_TYPE_KEY` +
     // `AUTH_API_TOKEN_ID_KEY`; it never builds the full request context —
@@ -230,8 +231,8 @@ export const create_test_middleware_stack_app = (options) => {
     const bearer_mw = create_bearer_auth_middleware(STUB_DEPS, new Logger('test', { level: 'off' }));
     const app = new Hono();
     app.use('*', proxy_mw);
-    app.use('/api/*', origin_mw);
-    app.use('/api/*', bearer_mw);
+    app.use(AUTH_MIDDLEWARE_PATH, origin_mw);
+    app.use(AUTH_MIDDLEWARE_PATH, bearer_mw);
     // echo route for assertions — exposes the account-grain identity bearer
     // auth writes (`ACCOUNT_ID_KEY`); the full request context is the
     // dispatcher's authorization phase concern, not middleware.

package/dist/testing/stubs.d.ts

@@ -9,7 +9,7 @@ import type { AppServerContext } from '../server/app_server_context.js';
 import { Db } from '../db/db.js';
 import { type RouteSpec } from '../http/route_spec.js';
 import { type AppSurfaceSpec, type RpcEndpointSpec } from '../http/surface.js';
-import type { WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
+import { type WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
 import type { EventSpec } from '../realtime/sse.js';
 import { type AuditLogSse } from '../realtime/sse_auth_guard.js';
 /**
@@ -124,10 +124,18 @@ export interface CreateTestAppSurfaceSpecOptions {
      * to both entry points so the attack surface tests see the same WS
      * endpoints production auto-mounts. The factory runs once against
      * the stub `AppServerContext` this helper already builds. No
-     * `upgradeWebSocket` needed — this helper produces an `AppSurfaceSpec`
-     * only, never mounts.
+     * `create_upgrade_websocket` needed — this helper produces an
+     * `AppSurfaceSpec` only, never mounts.
      */
     ws_endpoints?: ReadonlyArray<WsEndpointSpec> | ((ctx: AppServerContext) => ReadonlyArray<WsEndpointSpec>);
+    /**
+     * The server's origin allowlist — `AppServerOptions.allowed_origins`.
+     * Read only as the default for a `ws_endpoints` spec that declares no
+     * `allowed_origins`, as `create_app_server` does; required when any spec
+     * omits its own — without it, such a spec throws, since the surface records
+     * the exact patterns the upgrade gate matches.
+     */
+    allowed_origins?: ReadonlyArray<RegExp>;
     /** Transform middleware array (e.g., zap's `extend_middleware_for_zap_binary`). */
     transform_middleware?: (specs: Array<MiddlewareSpec>) => Array<MiddlewareSpec>;
     /**
@@ -152,12 +160,17 @@ export interface CreateTestAppSurfaceSpecOptions {
  * file.
  *
  * Mirrors `create_app_server`'s route assembly: consumer routes +
- * factory-managed bootstrap routes + surface generation. If
+ * factory-managed bootstrap routes + surface generation — including its
+ * refusal of an `rpc_endpoints` or `ws_endpoints` path outside the auth
+ * middleware's scope (`assert_endpoint_in_auth_scope`). If
  * `create_app_server` changes how it wires routes, update this helper
  * to stay in sync (single source of truth for all consumers).
  *
  * @param options - surface spec options
  * @returns the surface spec for the standard suites
+ * @throws Error when an endpoint path is outside `AUTH_MIDDLEWARE_PATH`, or a
+ *   `ws_endpoints` spec declares no `allowed_origins` and no `allowed_origins`
+ *   option is given
  */
 export declare const create_test_app_surface_spec: (options: CreateTestAppSurfaceSpecOptions) => AppSurfaceSpec;
 //# sourceMappingURL=stubs.d.ts.map

package/dist/testing/stubs.d.ts.map

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

package/dist/testing/stubs.js

@@ -15,9 +15,11 @@ import { prefix_route_specs } from '../http/route_spec.js';
 import { bootstrap_route_shape } from '../auth/bootstrap_route_schema.js';
 import { create_rpc_endpoint } from '../actions/action_rpc.js';
 import { create_app_surface_spec } from '../http/surface.js';
+import { resolve_ws_endpoints } from '../actions/ws_endpoint_spec.js';
 import { AUDIT_LOG_SSE_MAX_PER_SCOPE } from '../realtime/sse_auth_guard.js';
 import { SubscriberRegistry } from '../realtime/subscriber_registry.js';
 import { BaseServerEnv } from '../server/env.js';
+import { AUTH_MIDDLEWARE_PATH, assert_endpoint_in_auth_scope } from '../auth/middleware.js';
 /**
  * Create a Proxy that throws descriptive errors on any property access or method call.
  *
@@ -160,12 +162,12 @@ export const create_stub_app_deps = () => ({
 /** Create the API middleware stub array matching `create_auth_middleware_specs` output. */
 export const create_stub_api_middleware = (options) => {
     const specs = [
-        { name: 'origin', path: '/api/*', handler: stub_mw, errors: { 403: ApiError } },
-        { name: 'session', path: '/api/*', handler: stub_mw },
-        { name: 'request_context', path: '/api/*', handler: stub_mw },
+        { name: 'origin', path: AUTH_MIDDLEWARE_PATH, handler: stub_mw, errors: { 403: ApiError } },
+        { name: 'session', path: AUTH_MIDDLEWARE_PATH, handler: stub_mw },
+        { name: 'request_context', path: AUTH_MIDDLEWARE_PATH, handler: stub_mw },
         {
             name: 'bearer_auth',
-            path: '/api/*',
+            path: AUTH_MIDDLEWARE_PATH,
             handler: stub_mw,
             errors: { 401: ApiError, 403: ApiError, 429: RateLimitError }
         }
@@ -173,7 +175,7 @@ export const create_stub_api_middleware = (options) => {
     if (options?.include_daemon_token) {
         specs.push({
             name: 'daemon_token',
-            path: '/api/*',
+            path: AUTH_MIDDLEWARE_PATH,
             handler: stub_mw,
             errors: { 401: ApiError, 500: ApiError, 503: ApiError }
         });
@@ -211,6 +213,21 @@ export const create_stub_app_server_context = (session_options) => {
         audit_sse: null
     };
 };
+/**
+ * Narrow a WS endpoint spec that carries its own `allowed_origins` — the only
+ * way it resolves when no server list is given to default from.
+ *
+ * @throws Error when the spec declares no `allowed_origins`
+ */
+const to_self_resolved_ws_endpoint = (endpoint) => {
+    const { allowed_origins } = endpoint;
+    if (!allowed_origins) {
+        throw new Error(`create_test_app_surface_spec: ws endpoint ${endpoint.path} has no allowed_origins — ` +
+            "pass the server's list as create_test_app_surface_spec's allowed_origins option, " +
+            'or set allowed_origins on the spec');
+    }
+    return { ...endpoint, allowed_origins };
+};
 /**
  * Create an `AppSurfaceSpec` for the standard testing suites.
  *
@@ -222,12 +239,17 @@ export const create_stub_app_server_context = (session_options) => {
  * file.
  *
  * Mirrors `create_app_server`'s route assembly: consumer routes +
- * factory-managed bootstrap routes + surface generation. If
+ * factory-managed bootstrap routes + surface generation — including its
+ * refusal of an `rpc_endpoints` or `ws_endpoints` path outside the auth
+ * middleware's scope (`assert_endpoint_in_auth_scope`). If
  * `create_app_server` changes how it wires routes, update this helper
  * to stay in sync (single source of truth for all consumers).
  *
  * @param options - surface spec options
  * @returns the surface spec for the standard suites
+ * @throws Error when an endpoint path is outside `AUTH_MIDDLEWARE_PATH`, or a
+ *   `ws_endpoints` spec declares no `allowed_origins` and no `allowed_origins`
+ *   option is given
  */
 export const create_test_app_surface_spec = (options) => {
     const ctx = create_stub_app_server_context(options.session_options);
@@ -237,14 +259,25 @@ export const create_test_app_surface_spec = (options) => {
     const resolved_rpc_endpoints = typeof options.rpc_endpoints === 'function'
         ? options.rpc_endpoints(ctx)
         : options.rpc_endpoints;
-    const rpc_route_specs = resolved_rpc_endpoints?.flatMap((endpoint) => create_rpc_endpoint({
-        path: endpoint.path,
-        actions: endpoint.actions,
-        log: ctx.deps.log
-    })) ?? [];
+    const rpc_route_specs = resolved_rpc_endpoints?.flatMap((endpoint) => {
+        assert_endpoint_in_auth_scope('rpc_endpoints', endpoint.path);
+        return create_rpc_endpoint({
+            path: endpoint.path,
+            actions: endpoint.actions,
+            log: ctx.deps.log,
+            action_ip_rate_limiter: ctx.action_ip_rate_limiter,
+            action_account_rate_limiter: ctx.action_account_rate_limiter
+        });
+    }) ?? [];
     // Resolve ws endpoints (mirrors create_app_server). Surface-only —
-    // no `register_ws_endpoint` call here, so no `upgradeWebSocket` needed.
-    const resolved_ws_endpoints = typeof options.ws_endpoints === 'function' ? options.ws_endpoints(ctx) : options.ws_endpoints;
+    // no `register_ws_endpoint` call here, so no `create_upgrade_websocket` needed.
+    const declared_ws_endpoints = typeof options.ws_endpoints === 'function' ? options.ws_endpoints(ctx) : options.ws_endpoints;
+    const resolved_ws_endpoints = options.allowed_origins
+        ? resolve_ws_endpoints(declared_ws_endpoints, options.allowed_origins)
+        : declared_ws_endpoints?.map(to_self_resolved_ws_endpoint);
+    for (const endpoint of resolved_ws_endpoints ?? []) {
+        assert_endpoint_in_auth_scope('ws_endpoints', endpoint.path);
+    }
     // Bootstrap routes mirror `create_app_server`: mounted for `surface_only`
     // and `live` modes; omitted for `disabled` / undefined. Surface generation
     // uses an `available: false` placeholder regardless of mode — the handler

package/dist/testing/transports/ws_transport.d.ts

@@ -34,6 +34,13 @@ export interface WsTransportOptions {
      * behavior).
      */
     readonly on_request?: WsRequestResponder;
+    /**
+     * Extra headers for the upgrade request — e.g. an `X-Forwarded-For` that a
+     * backend trusting the loopback proxy resolves as the connection's client
+     * IP, which keys the per-IP action rate limiter for every message on the
+     * socket. `cookies` and `origin` set their own headers.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
 }
 /**
  * Build a real-upgrade WS client pinned to `options.base_url` + `ws_path`.

package/dist/testing/transports/ws_transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws_transport.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/ws_transport.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,OAAO,EAMN,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAEvB,MAAM,gBAAgB,CAAC;AAIxB,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IAClC,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,mBAAmB,GAAU,SAAS,kBAAkB,KAAG,OAAO,CAAC,QAAQ,CAwJvF,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,kBAAkB,KACzB,OAAO,CAAC,QAAQ,CASlB,CAAC"}
+{"version":3,"file":"ws_transport.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/ws_transport.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,OAAO,EAMN,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAEvB,MAAM,gBAAgB,CAAC;AAIxB,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IAClC,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,mBAAmB,GAAU,SAAS,kBAAkB,KAAG,OAAO,CAAC,QAAQ,CAwJvF,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,kBAAkB,KACzB,OAAO,CAAC,QAAQ,CASlB,CAAC"}

package/dist/testing/transports/ws_transport.js

@@ -45,7 +45,7 @@ export const create_ws_transport = async (options) => {
     const { base_url, ws_path, cookies, origin, default_timeout_ms, on_request } = options;
     const default_timeout = default_timeout_ms ?? WS_CLIENT_DEFAULT_TIMEOUT_MS;
     const ws_url = `${base_url.replace(/^http/i, 'ws')}${ws_path}`;
-    const headers = {};
+    const headers = { ...options.headers };
     if (cookies.length > 0)
         headers.Cookie = cookies.join('; ');
     const socket = new WebSocket(ws_url, {

package/dist/testing/ws_round_trip.d.ts

@@ -9,28 +9,27 @@ import './assert_dev_env.js';
  * token id), and exposes a `connect()` factory returning a `WsClient`
  * per connection.
  *
- * Three layers are exported:
+ * Two layers are exported:
  *
  *   - **Primitives** (`create_fake_ws`, `create_fake_hono_context`,
  *     `create_stub_upgrade`, `MinimalActionEnvironment`,
  *     `dispatch_ws_message`) — used by fuz_app's own dispatcher tests
  *     and by consumers wiring tight one-off tests.
- *   - **Harness** (`create_ws_test_harness`, `keeper_identity`) — the
- *     high-level driver. Give it specs + handlers, get back
+ *   - **Harness** (`create_ws_test_harness`) — the high-level driver.
+ *     Give it specs + handlers, get back
  *     `{transport, connect()}`. `connect()` is async and resolves after
  *     `on_socket_open` completes, so broadcasts sent immediately after
  *     `await harness.connect()` reach the client. Returns a `WsClient`
  *     (shared interface — see `transports/ws_client.ts`); the same
  *     interface is implemented by `transports/ws_transport.ts` for
  *     cross-process tests.
- *   - **Broadcast wiring** — `build_broadcast_api` for wiring a typed
- *     broadcast API against the harness's transport. Wire-frame types
- *     + predicates (`is_notification`, `is_response_for`,
- *     `JsonrpcNotificationFrame`, ...) live in `transports/ws_client.ts`
- *     so both in-process and cross-process drivers reference one source.
  *
- * Hono's wire upgrade is skipped — the Node test runtime has no
- * `@hono/node-ws` adapter — but the full dispatch path is exercised
+ * Wire-frame types + predicates (`is_notification`, `is_response_for`,
+ * `JsonrpcNotificationFrame`, ...) live in `transports/ws_client.ts` so
+ * both in-process and cross-process drivers reference one source.
+ *
+ * Hono's wire upgrade is skipped — there is no server, so no runtime
+ * adapter — but the full dispatch path is exercised
  * (per-action auth, input validation, `ctx.notify` back to the
  * originating socket, broadcast via `BackendWebsocketTransport`, and
  * close-on-revoke).
@@ -87,15 +86,45 @@ export interface FakeHonoContextOptions {
  * Only `.get()` is populated — no other Hono context surface is simulated.
  */
 export declare const create_fake_hono_context: (opts: FakeHonoContextOptions) => Context;
-/** The return of `create_stub_upgrade` — fake `upgradeWebSocket` + factory capture. */
+/** One upgrade that reached a `create_stub_upgrade` route. */
+export interface StubUpgradeRecord {
+    /**
+     * The real Hono `Context` the request carried through the app's
+     * middleware chain — session, request context, client IP, and every
+     * other value the middleware set.
+     */
+    c: Context;
+    /** The events factory of the endpoint the upgrade reached. */
+    create_events: (c: Context) => WSEvents | Promise<WSEvents>;
+}
+/** The return of `create_stub_upgrade` — fake `upgradeWebSocket` + factory and upgrade capture. */
 export interface StubUpgrade {
     upgradeWebSocket: UpgradeWebSocket;
+    /**
+     * The events factory of the most recently mounted endpoint, for tests
+     * that build events from a hand-made context. Throws when no endpoint
+     * was mounted.
+     */
     get_create_events: () => (c: Context) => WSEvents | Promise<WSEvents>;
+    /**
+     * Every upgrade request that reached a stub route, in arrival order —
+     * what `app.request(path, {headers: {upgrade: 'websocket', ...}})`
+     * leaves behind once the app's middleware passed it. Build the socket's
+     * events with `record.create_events(record.c)`.
+     */
+    upgrades: ReadonlyArray<StubUpgradeRecord>;
 }
 /**
- * Build a fake `upgradeWebSocket` that captures the `createEvents`
- * callback. The returned middleware is inert — tests drive
- * `createEvents` directly.
+ * Build a fake `upgradeWebSocket` that stands in for a runtime adapter's.
+ *
+ * Like the real adapters, the middleware it returns passes a request
+ * without an `Upgrade: websocket` header to `next()`. An upgrade request
+ * is recorded in `upgrades` — its real `Context` and the endpoint's events
+ * factory — and answered `200` with no body (a `Response` cannot carry the
+ * `101` an adapter answers). No socket is opened: tests drive the recorded
+ * factory, so an upgrade sent through `app.request` exercises the app's
+ * whole middleware chain — origin, session or bearer, client IP — before
+ * the dispatcher sees it.
  */
 export declare const create_stub_upgrade: () => StubUpgrade;
 /**
@@ -193,27 +222,4 @@ export interface WsTestHarness {
  * `onOpen`/`onMessage`/`onClose` path against a real `WSContext`.
  */
 export declare const create_ws_test_harness: (options: CreateWsTestHarnessOptions) => WsTestHarness;
-/** Convenience: default identity for keeper-authenticated connections. */
-export declare const keeper_identity: () => WsConnectIdentity;
-/**
- * Wire a typed broadcast API against the harness's transport, matching
- * how a consumer's real backend composes the stack. Returns the typed
- * API so tests can call `.zap_run_created(...)` / `.workspace_changed(...)`
- * etc. directly.
- *
- * ```ts
- * const harness = create_ws_test_harness({actions});
- * const broadcast = build_broadcast_api<MyBackendActionsApi>({
- *   harness,
- *   specs: my_broadcast_action_specs,
- * });
- * const client = await harness.connect(keeper_identity());
- * await broadcast.zap_run_created({run_id: '...', ...});
- * await client.wait_for(is_notification('zap_run_created'));
- * ```
- */
-export declare const build_broadcast_api: <TApi extends object>(options: {
-    harness: WsTestHarness;
-    specs: ReadonlyArray<ActionSpecUnion>;
-}) => TApi;
 //# sourceMappingURL=ws_round_trip.d.ts.map