@fuzdev/fuz_app 0.140.0 → 0.141.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_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"}

package/dist/testing/cross_backend/ws_role_gated.js

@@ -0,0 +1,142 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process **role-gated WebSocket** suite — a socket admitted by an
+ * endpoint's role gate (`register_ws_endpoint`'s `required_roles`) loses it
+ * with the role.
+ *
+ * A role gate decides who may hold a socket, and so who receives the
+ * endpoint's server pushes, which reach every admitted connection with no
+ * per-recipient filter. So both spines record the gating roles on each
+ * registration and close the account's gated sockets when a global grant of a
+ * listed role is revoked — with `WS_CLOSE_PERMISSION_REVOKED`, not the
+ * session-revoked code, since the credential is still good — and send nothing
+ * after the close. The ungated sockets of the same account, on the same
+ * transport, stay open: the gate is per endpoint, not per account. A scoped
+ * grant never admits at a role gate, so revoking one closes nothing.
+ *
+ * Runs against a backend that mounts, beside its ungated `ws_path`, a second
+ * endpoint at `gated_ws_path` gated on `gated_roles` — which must include
+ * `ROLE_ADMIN` (the revoked global grant) and a role that can be granted both
+ * globally and scoped (the scoped revoke). fuz_app's spine binaries mount
+ * `SPINE_ROLE_GATED_WS_PATH` gated on `SPINE_ROLE_GATED_WS_ROLES`. Gated on
+ * `capabilities.ws` and `capabilities.ws_role_gated`; cross-process only.
+ *
+ * @module
+ */
+import { assert, describe } from 'vitest';
+import { assert_rejects } from '@fuzdev/fuz_util/testing.ts';
+import { heartbeat_action_spec } from '../../actions/heartbeat.js';
+import { WS_CLOSE_PERMISSION_REVOKED, WS_CLOSE_PERMISSION_REVOKED_REASON } from '../../actions/transports.js';
+import { ROLE_ADMIN } from '../../auth/role_schema.js';
+import { ROLE_GRANT_OFFER_RECEIVED_NOTIFICATION_METHOD } from '../../auth/role_grant_offer_notifications.js';
+import { rpc_call } from '../rpc_helpers.js';
+import { is_notification_with } from '../transports/ws_client.js';
+import { create_admitted_ws_transport, create_ws_transport } from '../transports/ws_transport.js';
+import { test_if } from './capabilities.js';
+import { create_active_role_grant, create_pending_role_grant_offer } from './role_grant_cross_helpers.js';
+import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+/** How long a socket that must stay open is watched for a close it must not get. */
+const STAYS_OPEN_MS = 1500;
+/**
+ * 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 const describe_ws_role_gated_cross_tests = (options) => {
+    const { setup_test, capabilities, base_url, ws_path, gated_ws_path, gated_roles, scoped_role, rpc_path = SPINE_RPC_PATH } = options;
+    const enabled = capabilities.ws && capabilities.ws_role_gated;
+    if (enabled && (!gated_roles.includes(ROLE_ADMIN) || !gated_roles.includes(scoped_role))) {
+        throw new Error(`describe_ws_role_gated_cross_tests: gated_roles must include ${ROLE_ADMIN} and ${scoped_role}`);
+    }
+    const rpc = (fixture, method, params, headers = fixture.create_session_headers()) => rpc_call({ app: fixture.transport, path: rpc_path, method, params, headers });
+    const cookie_of = (account) => {
+        const { cookie } = account.create_session_headers();
+        assert.ok(cookie, 'expected a session cookie for the WS upgrade');
+        return cookie;
+    };
+    const open = (path, account) => create_admitted_ws_transport({
+        base_url,
+        ws_path: path,
+        cookies: [cookie_of(account)],
+        origin: base_url
+    });
+    describe('role-gated websocket (cross-process)', () => {
+        test_if(enabled, 'revoking a global grant of a gating role closes the gated socket with WS_CLOSE_PERMISSION_REVOKED', async () => {
+            const fixture = await setup_test();
+            const target = await fixture.create_account({ roles: [ROLE_ADMIN] });
+            const role_grant_id = await create_active_role_grant(fixture, target, { rpc_path });
+            const gated = await open(gated_ws_path, target);
+            const ungated = await open(ws_path, target);
+            try {
+                const revoked = await rpc(fixture, 'role_grant_revoke', {
+                    actor_id: target.actor.id,
+                    role_grant_id
+                });
+                assert.isTrue(revoked.ok, `revoke failed: ${JSON.stringify(revoked)}`);
+                assert.ok(await gated.wait_for_close(5000), 'the gated socket did not close');
+                assert.strictEqual(gated.close_code, WS_CLOSE_PERMISSION_REVOKED);
+                assert.strictEqual(gated.close_reason, WS_CLOSE_PERMISSION_REVOKED_REASON);
+                // a push to the account still reaches its ungated socket, and the
+                // closed client records nothing more
+                const received_before = gated.messages.length;
+                await create_pending_role_grant_offer(fixture, target.account.id, fixture.create_session_headers(), { rpc_path });
+                await ungated.wait_for(is_notification_with(ROLE_GRANT_OFFER_RECEIVED_NOTIFICATION_METHOD, (p) => p.offer.to_account_id === target.account.id), 5000);
+                assert.strictEqual(gated.messages.length, received_before);
+                // the account's ungated socket on the same backend stays open
+                assert.strictEqual(ungated.close_code, null);
+                assert.deepStrictEqual(await ungated.request(2, heartbeat_action_spec.method, {}), {});
+                // and the gate refuses the account a new gated socket
+                await assert_rejects(() => create_ws_transport({
+                    base_url,
+                    ws_path: gated_ws_path,
+                    cookies: [cookie_of(target)],
+                    origin: base_url
+                }), /403/);
+            }
+            finally {
+                await gated.close();
+                await ungated.close();
+            }
+        });
+        test_if(enabled, 'a scoped revoke of a gating role closes nothing', async () => {
+            const fixture = await setup_test();
+            // a global grant of `scoped_role` admits the socket — which proves the
+            // endpoint lists it, so the scoped revoke below is one of a gating role
+            const target = await fixture.create_account();
+            const assign = async (scope) => {
+                const assigned = await rpc(fixture, 'role_grant_assign', {
+                    to_account_id: target.account.id,
+                    role: scoped_role,
+                    ...scope
+                });
+                if (!assigned.ok)
+                    assert.fail(`assign failed: ${JSON.stringify(assigned)}`);
+                return assigned.result.role_grant_id;
+            };
+            await assign({});
+            const role_grant_id = await assign({
+                scope_kind: 'space',
+                scope_id: '33333333-3333-4333-8333-333333333333'
+            });
+            const gated = await open(gated_ws_path, target);
+            try {
+                const revoked = await rpc(fixture, 'role_grant_revoke', {
+                    actor_id: target.actor.id,
+                    role_grant_id
+                });
+                assert.isTrue(revoked.ok, `revoke failed: ${JSON.stringify(revoked)}`);
+                assert.isFalse(await gated.wait_for_close(STAYS_OPEN_MS), `closed with ${gated.close_code} on a scoped revoke`);
+                assert.deepStrictEqual(await gated.request(2, heartbeat_action_spec.method, {}), {});
+            }
+            finally {
+                await gated.close();
+            }
+        });
+    });
+};

package/dist/testing/entities.d.ts

@@ -2,6 +2,7 @@ import './assert_dev_env.js';
 import type { Account, Actor, RoleGrant } from '../auth/account_schema.js';
 import type { AuditLogEvent } from '../auth/audit_log_schema.js';
 import type { RequestActorContext } from '../auth/request_context.js';
+import type { ValidatedApiToken } from '../auth/api_token_queries.js';
 /** Override type for `create_test_account` — id-like fields accept plain `string`. */
 export type TestAccountOverrides = Partial<Omit<Account, 'id' | 'created_by' | 'updated_by'>> & {
     id?: string;
@@ -45,4 +46,26 @@ export type TestAuditEventOverrides = Partial<Omit<AuditLogEvent, 'id' | 'actor_
 };
 /** Create a test `AuditLogEvent` with sensible defaults. */
 export declare const create_test_audit_event: (overrides?: TestAuditEventOverrides) => AuditLogEvent;
+/**
+ * Create a well-formed raw API token for tests that need a bearer value to
+ * pass the `is_api_token_shaped` precheck and reach token validation. The
+ * body is `label` padded with `A` to the generated length, so distinct labels
+ * give distinct tokens and a token in a failure message reads back to its
+ * test. Not a real credential — it authenticates only where a test mocks the
+ * lookup.
+ *
+ * @param label - base64url characters (`A-Z a-z 0-9 - _`) that start the token body
+ * @returns `API_TOKEN_PREFIX` plus an `API_TOKEN_BODY_LENGTH`-char body
+ * @throws Error when `label` is longer than the body or not base64url
+ */
+export declare const create_test_raw_api_token: (label?: string) => string;
+/** Override type for `create_test_validated_api_token` — `account_id` accepts plain `string`. */
+export type TestValidatedApiTokenOverrides = Partial<Omit<ValidatedApiToken, 'account_id'>> & {
+    account_id?: string;
+};
+/**
+ * Create a test `ValidatedApiToken` — what `query_validate_api_token` returns
+ * for a live token — with a `full` scope by default.
+ */
+export declare const create_test_validated_api_token: (overrides?: TestValidatedApiTokenOverrides) => ValidatedApiToken;
 //# sourceMappingURL=entities.d.ts.map