@fuzdev/fuz_app 0.140.0 → 0.142.0

package/dist/testing/cross_backend/transport_composition.js

@@ -0,0 +1,364 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-backend front-door contract: what every transport answers before its
+ * request reaches per-action dispatch.
+ *
+ * Each spine composes its front door differently. The TS spine mounts one
+ * stack at `/api/*` — body limit, then origin, then session and bearer — and
+ * each surface adds its own gates behind it. The Rust spine stacks global
+ * layers (body limit, then origin) and has each handler resolve its credential
+ * and run its own gates. Two compositions can agree on every per-surface suite
+ * and still disagree on which refusal answers when a request trips several, so
+ * this suite pins the answer per transport as a table:
+ *
+ * | surface | foreign `Origin` | unreadable `Origin` | duplicated `Origin` | over cap + foreign `Origin` | no credential | narrowed token |
+ * | --- | --- | --- | --- | --- | --- | --- |
+ * | REST `POST` (`/logout`) | 403 `forbidden_origin` | 403 `forbidden_origin` | 403 `forbidden_origin` | 413 `payload_too_large` | 401 `authentication_required` | 403 `credential_type_required` |
+ * | REST `POST` (`/password`) | — | — | — | — | 401 `authentication_required` | — |
+ * | RPC `POST` | 403 `forbidden_origin` | 403 `forbidden_origin` | 403 `forbidden_origin` | 413 `payload_too_large` | 401 `authentication_required` | 403 `token_scope_required` (`rpc:<method>`) |
+ * | RPC `GET` | 403 `forbidden_origin` | 403 `forbidden_origin` | 403 `forbidden_origin` | — | 401 `authentication_required` | 403 `token_scope_required` (`rpc:<method>`) |
+ * | WS upgrade | 403 `forbidden_origin` | 403 `forbidden_origin` | 403 `forbidden_origin` | — | 401 `authentication_required` | 403 `token_scope_required` (`surface:ws_upgrade`) |
+ * | SSE (audit stream) | 403 `forbidden_origin` | 403 `forbidden_origin` | 403 `forbidden_origin` | — | 401 `authentication_required` | 403 `credential_type_required` |
+ *
+ * - **foreign `Origin`** carries the keeper's session cookie, so only the
+ *   origin check can refuse it — a front door missing that check answers the
+ *   surface's success instead.
+ * - **unreadable `Origin`** is the allowed origin with a byte past ASCII
+ *   (`0xE9`), with the keeper's session — a check that reads such a value as
+ *   absent lets it through.
+ * - **duplicated `Origin`** sends the allowed origin on two header lines, with
+ *   the keeper's session — refused whether a backend sees the two lines (the
+ *   Rust spine) or one value joined from them (the TS runtimes), so a check that
+ *   reads only the first lets it through.
+ * - **over cap + foreign `Origin`** declares a `Content-Length` one byte over
+ *   the shared 1 MiB cap and carries no credential: the cap answers on the
+ *   header, ahead of both the origin check and auth. Only the surfaces that
+ *   take a body have the column.
+ * - **no credential** sends an allowed `Origin` and nothing else.
+ * - **narrowed token** sends a bearer minted with a method-scoped scope, and no
+ *   `Origin` (a bearer in a browser context is discarded, not refused). The RPC
+ *   probe calls a method the scope doesn't name. A narrowed token reaches no
+ *   non-RPC surface, but on a session-only surface the credential gate answers
+ *   first — the REST probe is session-only `/logout`, and the audit stream is
+ *   session-only on both spines.
+ *
+ * Each case asserts the status and the refusal body: a flat `{error}` (plus
+ * its named fields) or, past the RPC front door, the JSON-RPC error envelope
+ * with the reason on `error.data.reason`. A WebSocket refusal's body is
+ * required where the backend declares `capabilities.ws_refusal_body`; where it
+ * doesn't (Node's `@hono/node-ws` drops a refused upgrade's body), an empty
+ * body passes on its status and a body that is sent is still asserted.
+ *
+ * **Transport.** Given a `base_url`, every probe is written to the socket
+ * (`raw_http_exchange`): an upgrade has to be, and an over-cap request sends
+ * its head alone, as `body_size.ts` explains — the 413 must arrive without a
+ * body byte. With `base_url: null` the probes go through the fixture's
+ * in-process transport, whole bodies included, and the WebSocket rows skip
+ * (there is no socket to upgrade).
+ *
+ * Wire it for any backend that serves the spine's account routes, RPC
+ * endpoint, WebSocket endpoint and audit stream; the WS and SSE rows gate on
+ * `capabilities.ws` and `capabilities.sse`.
+ *
+ * @module
+ */
+import { assert, describe } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { account_verify_action_spec } from '../../auth/account_action_specs.js';
+import { ERROR_AUTHENTICATION_REQUIRED, ERROR_CREDENTIAL_TYPE_REQUIRED, ERROR_FORBIDDEN_ORIGIN, ERROR_PAYLOAD_TOO_LARGE, ERROR_TOKEN_SCOPE_REQUIRED } from '../../http/error_schemas.js';
+import { create_rpc_get_url } from '../rpc_helpers.js';
+import { raw_http_exchange, raw_http_parse_response } from '../transports/raw_http.js';
+import { test_if } from './capabilities.js';
+import { mint_narrowed_api_token } from './narrowed_api_token.js';
+import { SPINE_RPC_PATH, SPINE_SSE_PATH } from './spine_surface_constants.js';
+/** The RPC method the narrowed token admits. */
+const NARROWED_ADMITTED_METHOD = account_verify_action_spec.method;
+/**
+ * The RPC method the narrowed-token probe calls — one its scope doesn't name.
+ * A read with no credential-type or role gate, so the scope gate is the only
+ * one that can refuse it, over `GET` as over `POST`.
+ */
+const NARROWED_REFUSED_METHOD = 'account_session_list';
+const FORBIDDEN_ORIGIN = { status: 403, error: ERROR_FORBIDDEN_ORIGIN };
+const PAYLOAD_TOO_LARGE = {
+    status: 413,
+    error: ERROR_PAYLOAD_TOO_LARGE
+};
+const SESSION_ONLY = {
+    status: 403,
+    error: ERROR_CREDENTIAL_TYPE_REQUIRED,
+    fields: { required_credential_types: ['session'] }
+};
+const RPC_UNAUTHENTICATED = {
+    status: 401,
+    error: ERROR_AUTHENTICATION_REQUIRED,
+    envelope: true
+};
+const RPC_SCOPE_REFUSED = {
+    status: 403,
+    error: ERROR_TOKEN_SCOPE_REQUIRED,
+    fields: { required_scope: `rpc:${NARROWED_REFUSED_METHOD}` },
+    envelope: true
+};
+const UNAUTHENTICATED = {
+    status: 401,
+    error: ERROR_AUTHENTICATION_REQUIRED
+};
+/** The front-door table — one case per cell of the module doc's matrix. */
+export const transport_composition_cases = [
+    { surface: 'rest_post', probe: 'foreign_origin', expect: FORBIDDEN_ORIGIN },
+    { surface: 'rest_post', probe: 'unreadable_origin', expect: FORBIDDEN_ORIGIN },
+    { surface: 'rest_post', probe: 'duplicated_origin', expect: FORBIDDEN_ORIGIN },
+    { surface: 'rest_post', probe: 'over_cap_foreign_origin', expect: PAYLOAD_TOO_LARGE },
+    { surface: 'rest_post', probe: 'no_credential', expect: UNAUTHENTICATED },
+    { surface: 'rest_post', probe: 'narrowed_token', expect: SESSION_ONLY },
+    // the other session-only REST route that resolves its own credential on the
+    // Rust spine, so its 401 is pinned beside `/logout`'s
+    { surface: 'rest_password', probe: 'no_credential', expect: UNAUTHENTICATED },
+    { surface: 'rpc_post', probe: 'foreign_origin', expect: FORBIDDEN_ORIGIN },
+    { surface: 'rpc_post', probe: 'unreadable_origin', expect: FORBIDDEN_ORIGIN },
+    { surface: 'rpc_post', probe: 'duplicated_origin', expect: FORBIDDEN_ORIGIN },
+    { surface: 'rpc_post', probe: 'over_cap_foreign_origin', expect: PAYLOAD_TOO_LARGE },
+    { surface: 'rpc_post', probe: 'no_credential', expect: RPC_UNAUTHENTICATED },
+    { surface: 'rpc_post', probe: 'narrowed_token', expect: RPC_SCOPE_REFUSED },
+    { surface: 'rpc_get', probe: 'foreign_origin', expect: FORBIDDEN_ORIGIN },
+    { surface: 'rpc_get', probe: 'unreadable_origin', expect: FORBIDDEN_ORIGIN },
+    { surface: 'rpc_get', probe: 'duplicated_origin', expect: FORBIDDEN_ORIGIN },
+    { surface: 'rpc_get', probe: 'no_credential', expect: RPC_UNAUTHENTICATED },
+    { surface: 'rpc_get', probe: 'narrowed_token', expect: RPC_SCOPE_REFUSED },
+    { surface: 'ws_upgrade', probe: 'foreign_origin', expect: FORBIDDEN_ORIGIN, gate: 'ws' },
+    { surface: 'ws_upgrade', probe: 'unreadable_origin', expect: FORBIDDEN_ORIGIN, gate: 'ws' },
+    { surface: 'ws_upgrade', probe: 'duplicated_origin', expect: FORBIDDEN_ORIGIN, gate: 'ws' },
+    { surface: 'ws_upgrade', probe: 'no_credential', expect: UNAUTHENTICATED, gate: 'ws' },
+    {
+        surface: 'ws_upgrade',
+        probe: 'narrowed_token',
+        expect: {
+            status: 403,
+            error: ERROR_TOKEN_SCOPE_REQUIRED,
+            fields: { required_scope: 'surface:ws_upgrade' }
+        },
+        gate: 'ws'
+    },
+    { surface: 'sse', probe: 'foreign_origin', expect: FORBIDDEN_ORIGIN, gate: 'sse' },
+    { surface: 'sse', probe: 'unreadable_origin', expect: FORBIDDEN_ORIGIN, gate: 'sse' },
+    { surface: 'sse', probe: 'duplicated_origin', expect: FORBIDDEN_ORIGIN, gate: 'sse' },
+    { surface: 'sse', probe: 'no_credential', expect: UNAUTHENTICATED, gate: 'sse' },
+    { surface: 'sse', probe: 'narrowed_token', expect: SESSION_ONLY, gate: 'sse' }
+];
+/** The shared 1 MiB default cap both spines ship, as in `body_size.ts`. */
+const BODY_LIMIT_DEFAULT_BYTES = 1024 * 1024;
+/** An `Origin` no backend's allowlist admits. */
+const DISALLOWED_ORIGIN = 'http://evil.com';
+/** How long a raw exchange waits for the refusal. */
+const RAW_READ_TIMEOUT_MS = 2000;
+const rpc_envelope = (method, id) => JSON.stringify({ jsonrpc: '2.0', method, id });
+/** A JSON object body of exactly `bytes` ASCII bytes. */
+const sized_json = (bytes) => {
+    const base = JSON.stringify({ pad: '' });
+    return JSON.stringify({ pad: 'x'.repeat(Math.max(0, bytes - base.length)) });
+};
+const to_header_lines = (headers) => Object.entries(headers)
+    .map(([name, value]) => `${name}: ${value}\r\n`)
+    .join('');
+const parse_json = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const case_name = (c) => `${c.surface} × ${c.probe} → ${c.expect.status} ${c.expect.error}`;
+/**
+ * Read the refusal reason and fields out of a body, by the shape the case
+ * expects. An envelope expectation fails on a flat body and the other way
+ * round, so a spine answering from the wrong layer fails here.
+ */
+const assert_refusal_body = (c, body, text) => {
+    const label = case_name(c);
+    assert.ok(body !== null && typeof body === 'object', `${label}: expected a JSON body, got ${JSON.stringify(text.slice(0, 200))}`);
+    let refusal;
+    if (c.expect.envelope) {
+        const envelope = body;
+        assert.strictEqual(envelope.jsonrpc, '2.0', `${label}: expected a JSON-RPC envelope: ${text}`);
+        const data = envelope.error?.data;
+        assert.ok(data !== null && typeof data === 'object', `${label}: expected error.data on the envelope: ${text}`);
+        refusal = data;
+        assert.strictEqual(refusal.reason, c.expect.error, `${label}: error.data.reason`);
+    }
+    else {
+        refusal = body;
+        assert.ok(!('jsonrpc' in refusal), `${label}: expected a flat body, got an envelope: ${text}`);
+        assert.strictEqual(refusal.error, c.expect.error, `${label}: body.error`);
+    }
+    for (const [key, expected] of Object.entries(c.expect.fields ?? {})) {
+        assert.deepStrictEqual(refusal[key], expected, `${label}: ${key}`);
+    }
+};
+/**
+ * Register the front-door table's cases — one test per cell, each on a fresh
+ * fixture.
+ *
+ * This is the front-door contract: a backend that wires it answers each
+ * transport's probes as the table says — when one request trips several
+ * refusals, the one the table names answers.
+ */
+export const describe_transport_composition_cross_tests = (options) => {
+    const { setup_test, capabilities, base_url } = options;
+    const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
+    const rest_path = options.rest_path ?? '/api/account/logout';
+    const password_path = options.password_path ?? '/api/account/password';
+    const ws_path = options.ws_path ?? '/api/ws';
+    const sse_path = options.sse_path ?? SPINE_SSE_PATH;
+    const allowed_origin = options.origin ?? (base_url === null ? 'http://localhost:5173' : new URL(base_url).origin);
+    /** The request line, headers and body a case's probe sends. */
+    const build_probe = async (c, fixture) => {
+        const over_cap = c.probe === 'over_cap_foreign_origin';
+        let credential;
+        let repeated_headers;
+        switch (c.probe) {
+            case 'foreign_origin':
+                credential = { ...fixture.create_session_headers(), origin: DISALLOWED_ORIGIN };
+                break;
+            case 'unreadable_origin':
+                // latin1 on the socket — the byte 0xE9
+                credential = { ...fixture.create_session_headers(), origin: `${allowed_origin}\u00e9` };
+                break;
+            case 'duplicated_origin':
+                credential = { ...fixture.create_session_headers(), origin: allowed_origin };
+                repeated_headers = [['origin', allowed_origin]];
+                break;
+            case 'over_cap_foreign_origin':
+                // no credential either: the cap answers ahead of the origin check and auth
+                credential = { origin: DISALLOWED_ORIGIN };
+                break;
+            case 'no_credential':
+                credential = { origin: allowed_origin };
+                break;
+            case 'narrowed_token': {
+                const token = await mint_narrowed_api_token({
+                    app: fixture.transport,
+                    rpc_path,
+                    session_headers: fixture.create_session_headers(),
+                    methods: [NARROWED_ADMITTED_METHOD]
+                });
+                // no `Origin` — a bearer in a browser context is discarded
+                credential = { authorization: `Bearer ${token}` };
+                break;
+            }
+        }
+        const rpc_method = c.probe === 'narrowed_token' ? NARROWED_REFUSED_METHOD : account_verify_action_spec.method;
+        const id = `${c.surface}-${c.probe}`;
+        switch (c.surface) {
+            case 'rest_post':
+            case 'rest_password':
+                return {
+                    method: 'POST',
+                    path: c.surface === 'rest_post' ? rest_path : password_path,
+                    headers: { ...credential, 'content-type': 'application/json' },
+                    body: over_cap ? sized_json(BODY_LIMIT_DEFAULT_BYTES + 1) : '{}',
+                    over_cap,
+                    repeated_headers
+                };
+            case 'rpc_post': {
+                return {
+                    method: 'POST',
+                    path: rpc_path,
+                    headers: { ...credential, 'content-type': 'application/json' },
+                    body: over_cap ? sized_json(BODY_LIMIT_DEFAULT_BYTES + 1) : rpc_envelope(rpc_method, id),
+                    over_cap,
+                    repeated_headers
+                };
+            }
+            case 'rpc_get':
+                return {
+                    method: 'GET',
+                    path: create_rpc_get_url(rpc_path, rpc_method, undefined, id),
+                    headers: credential,
+                    body: null,
+                    over_cap,
+                    repeated_headers
+                };
+            case 'ws_upgrade':
+                return {
+                    method: 'GET',
+                    path: ws_path,
+                    headers: {
+                        ...credential,
+                        upgrade: 'websocket',
+                        connection: 'Upgrade',
+                        'sec-websocket-key': randomBytes(16).toString('base64'),
+                        'sec-websocket-version': '13'
+                    },
+                    body: null,
+                    over_cap,
+                    repeated_headers
+                };
+            case 'sse':
+                return {
+                    method: 'GET',
+                    path: sse_path,
+                    headers: { ...credential, accept: 'text/event-stream' },
+                    body: null,
+                    over_cap,
+                    repeated_headers
+                };
+        }
+    };
+    /** Put a probe on the socket, or through the in-process transport. */
+    const send_probe = async (fixture, probe) => {
+        if (base_url === null) {
+            const headers = new Headers(probe.headers);
+            // in-process there is no wire: a repeated header joins, as the runtimes join it
+            for (const [name, value] of probe.repeated_headers ?? [])
+                headers.append(name, value);
+            const res = await fixture.fresh_transport()(probe.path, {
+                method: probe.method,
+                headers,
+                ...(probe.body === null ? {} : { body: probe.body })
+            });
+            return { status: res.status, text: await res.text() };
+        }
+        const url = new URL(base_url);
+        const body = probe.over_cap ? '' : (probe.body ?? '');
+        const length_header = probe.over_cap
+            ? { 'content-length': String(BODY_LIMIT_DEFAULT_BYTES + 1) }
+            : probe.body === null
+                ? {}
+                : { 'content-length': String(body.length) };
+        const request = `${probe.method} ${probe.path} HTTP/1.1\r\n` +
+            to_header_lines({ host: url.host, ...probe.headers, ...length_header }) +
+            (probe.repeated_headers ?? []).map(([name, value]) => `${name}: ${value}\r\n`).join('') +
+            `\r\n` +
+            body;
+        const { received, closed_by_server } = await raw_http_exchange(base_url, request, {
+            read_timeout_ms: RAW_READ_TIMEOUT_MS,
+            until: 'response'
+        });
+        const response = raw_http_parse_response(received);
+        assert.ok(response, `${probe.method} ${probe.path}: expected a whole response; ` +
+            (closed_by_server
+                ? 'the server closed the connection first'
+                : `none arrived within ${RAW_READ_TIMEOUT_MS}ms`) +
+            `. Received: ${received ? received.slice(0, 200) : 'nothing'}`);
+        return { status: response.status, text: response.body };
+    };
+    describe('transport composition (front door)', () => {
+        for (const c of transport_composition_cases) {
+            const gated = c.gate === undefined || capabilities[c.gate];
+            // an upgrade needs a socket; in-process there is none
+            const reachable = c.surface !== 'ws_upgrade' || base_url !== null;
+            test_if(gated && reachable, case_name(c), async () => {
+                const fixture = await setup_test();
+                const res = await send_probe(fixture, await build_probe(c, fixture));
+                assert.strictEqual(res.status, c.expect.status, `${case_name(c)}: status (body: ${res.text.slice(0, 200)})`);
+                // a backend that declares no WS refusal body (Node's `@hono/node-ws`)
+                // may answer with an empty one; a body it does send is still asserted
+                if (c.surface === 'ws_upgrade' && !capabilities.ws_refusal_body && res.text === '')
+                    return;
+                assert_refusal_body(c, parse_json(res.text), res.text);
+            });
+        }
+    });
+};

package/dist/testing/cross_backend/ts_spine_backend_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts_spine_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ts_spine_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAiDzD,6FAA6F;AAC7F,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,iDAAiD;AACjD,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,gDAAgD;AAChD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,uDAAuD,CAAC;AAEvF,MAAM,WAAW,2BAA2B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,MAAM,CAAC;CACjD;AAWD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAoBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GACvC,UAAS,2BAAgC,KACvC,aAoBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAiCF,CAAC"}
+{"version":3,"file":"ts_spine_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ts_spine_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAiEzD,6FAA6F;AAC7F,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,iDAAiD;AACjD,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,gDAAgD;AAChD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,uDAAuD,CAAC;AAEvF,MAAM,WAAW,2BAA2B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,MAAM,CAAC;CACjD;AAWD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAoBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GACvC,UAAS,2BAAgC,KACvC,aAoBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAiCF,CAAC"}

package/dist/testing/cross_backend/ts_spine_backend_config.js

@@ -9,8 +9,11 @@ import { LOGIN_RATE_LIMIT_ENABLED_ENV, SPINE_SSE_PATH, TS_SPINE_DIR_ENV } from '
  * WS transport's `request_connection` path drives server→client `peer/ping`),
  * `ws_account_actions` (the binary mounts its full action set on `/api/ws`,
  * the account actions among them),
- * and `cell_gated_create` (the binary's `full_spine_mount` mounts the
- * `test_cell_gated_create_authorize` policy).
+ * `cell_gated_create` (the binary's `full_spine_mount` mounts the
+ * `test_cell_gated_create_authorize` policy), and `ws_role_gated` (the binary
+ * mounts the role-gated WS endpoint at `SPINE_ROLE_GATED_WS_PATH`). The Node
+ * binary's preset; `ws_refusal_body` stays `false`, as `@hono/node-ws` drops a
+ * refused upgrade's body.
  */
 const ts_spine_capabilities = Object.freeze({
     ...ts_default_capabilities,
@@ -18,11 +21,22 @@ const ts_spine_capabilities = Object.freeze({
     ready: true,
     peer_request: true,
     ws_account_actions: true,
-    cell_gated_create: true
+    cell_gated_create: true,
+    ws_role_gated: true
+});
+/**
+ * Capabilities for the **Deno** spine binary — `ts_spine_capabilities` with
+ * `ws_refusal_body: true` (`Deno.upgradeWebSocket` leaves a refused upgrade's
+ * response to Hono, body included).
+ */
+const ts_spine_deno_capabilities = Object.freeze({
+    ...ts_spine_capabilities,
+    ws_refusal_body: true
 });
 /**
  * Capabilities for the **Bun** spine binary — `ts_spine_capabilities` with
- * `ws_handshake_pipelining: false`.
+ * `ws_handshake_pipelining: false` and `ws_refusal_body: true` (`Bun.serve`
+ * sends a refused upgrade's response as built).
  *
  * `Bun.serve` answers `400` to an upgrade request that carries WebSocket
  * frames in the same TCP write when the handler upgrades after an await that
@@ -34,7 +48,8 @@ const ts_spine_capabilities = Object.freeze({
  */
 const ts_spine_bun_capabilities = Object.freeze({
     ...ts_spine_capabilities,
-    ws_handshake_pipelining: false
+    ws_handshake_pipelining: false,
+    ws_refusal_body: true
 });
 /** Default port for the Node TS spine binary — slots beside the Rust `spine_stub` (1177). */
 export const TS_SPINE_NODE_DEFAULT_PORT = 1178;
@@ -148,7 +163,7 @@ export const ts_spine_deno_backend_config = (options = {}) => {
                 ...login_rate_limit_env(enable_login_rate_limit),
                 ...action_rate_limit_env(options)
             },
-            capabilities: ts_spine_capabilities
+            capabilities: ts_spine_deno_capabilities
         }),
         sse_path: SPINE_SSE_PATH
     };

package/dist/testing/cross_backend/ws_action_rate_limit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws_action_rate_limit.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_action_rate_limit.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAgE9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAyC5C,+DAA+D;AAC/D,MAAM,WAAW,iCAAiC;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAkBD;;;;GAIG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,iCAAiC,KACxC,IAqRF,CAAC"}
+{"version":3,"file":"ws_action_rate_limit.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_action_rate_limit.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAkE9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgD5C,+DAA+D;AAC/D,MAAM,WAAW,iCAAiC;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAkBD;;;;GAIG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,iCAAiC,KACxC,IAwSF,CAAC"}

package/dist/testing/cross_backend/ws_action_rate_limit.js

@@ -23,7 +23,9 @@ import '../assert_dev_env.js';
  *   '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.
+ *   own budget on both. Over HTTP, IPv6 addresses bucket by their `/64`:
+ *   another address in the same `/64` is refused once one has spent the
+ *   budget, while one in the next `/64` keeps its own.
  * - **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
@@ -84,6 +86,13 @@ const IP_LIMITED_BAD_PARAMS = { nonce: 'not_a_number' };
  */
 const XFF_IP_EXHAUSTED = '198.51.100.1';
 const XFF_IP_FRESH = '198.51.100.2';
+/**
+ * RFC 3849 documentation addresses: two in one `/64` — the second differs past
+ * bit 64 only — and one in the next `/64`. Distinct from `login_security.ts`'s.
+ */
+const XFF_V6_EXHAUSTED = '2001:db8:e3a:1::1';
+const XFF_V6_SAME_64 = '2001:db8:e3a:1:8000::2';
+const XFF_V6_OTHER_64 = '2001:db8:e3a:2::1';
 /** 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) => ({
@@ -254,5 +263,16 @@ export const describe_ws_action_rate_limit_cross_tests = (options) => {
                 await ws_fresh.close();
             }
         });
+        test('an IP-limited action buckets IPv6 clients by /64', async () => {
+            const fixture = await setup_test();
+            const call = (forwarded_for) => call_http(fixture, IP_LIMITED_METHOD, IP_LIMITED_BAD_PARAMS, {
+                'x-forwarded-for': forwarded_for
+            });
+            for (let i = 1; i <= max_attempts; i++) {
+                assert_charged_not_limited(await call(XFF_V6_EXHAUSTED), `call ${i} from ${XFF_V6_EXHAUSTED}`);
+            }
+            assert_rate_limited(await call(XFF_V6_SAME_64), `a call from ${XFF_V6_SAME_64}, same /64`);
+            assert_charged_not_limited(await call(XFF_V6_OTHER_64), `a call from ${XFF_V6_OTHER_64}, the next /64`);
+        });
     });
 };

package/dist/testing/cross_backend/ws_role_gated.d.ts

@@ -0,0 +1,38 @@
+import '../assert_dev_env.js';
+import { type BackendCapabilities } from './capabilities.js';
+import type { SetupTest } from './setup.js';
+/** Configuration for `describe_ws_role_gated_cross_tests`. */
+export interface WsRoleGatedCrossTestOptions {
+    /** Per-test fixture producer (`default_cross_process_setup(handle)`). */
+    readonly setup_test: SetupTest;
+    /** Backend capability flags; every case gates on `ws` and `ws_role_gated`. */
+    readonly capabilities: BackendCapabilities;
+    /** Base URL the backend is reachable at. */
+    readonly base_url: string;
+    /** The ungated WebSocket endpoint path (e.g. `/api/ws`). */
+    readonly ws_path: string;
+    /** The role-gated WebSocket endpoint path. */
+    readonly gated_ws_path: string;
+    /**
+     * The roles `gated_ws_path` requires: `ROLE_ADMIN` and `scoped_role`
+     * among them.
+     */
+    readonly gated_roles: ReadonlyArray<string>;
+    /** A role in `gated_roles` an admin can grant both globally and scoped. */
+    readonly scoped_role: string;
+    /** JSON-RPC endpoint path. Default `SPINE_RPC_PATH`. */
+    readonly rpc_path?: string;
+}
+/**
+ * Register the role-gated WebSocket suite: a revoked global grant of a gating
+ * role closes the account's gated socket with `WS_CLOSE_PERMISSION_REVOKED`,
+ * its ungated socket stays open and still receives the account's pushes, and
+ * a re-upgrade is refused at the gate; a scoped revoke of a gating role
+ * closes nothing.
+ *
+ * That the closed registration is sent nothing more is beyond what a client
+ * can observe once it has read the close frame, so the suite does not claim
+ * it: each spine's own transport tests pin it.
+ */
+export declare const describe_ws_role_gated_cross_tests: (options: WsRoleGatedCrossTestOptions) => void;
+//# sourceMappingURL=ws_role_gated.d.ts.map

package/dist/testing/cross_backend/ws_role_gated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws_role_gated.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_role_gated.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAwC9B,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AAKtE,OAAO,KAAK,EAAE,SAAS,EAAmC,MAAM,YAAY,CAAC;AAM7E,8DAA8D;AAC9D,MAAM,WAAW,2BAA2B;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,GAAI,SAAS,2BAA2B,KAAG,IA2IzF,CAAC"}