@fuzdev/fuz_app 0.93.0 → 0.95.0

package/dist/testing/cross_backend/conformance_table.js

@@ -16,11 +16,17 @@ import '../assert_dev_env.js';
  * row runs `as` resolves to a `TestFixture` accessor via
  * `resolve_principal` — no inline credential minting.
  *
+ * Every response also passes an always-on **no-fingerprint** invariant
+ * (`assert_no_fingerprint_headers` over `FINGERPRINT_HEADERS` — `Server` /
+ * `X-Powered-By` / `WWW-Authenticate` must stay absent on both spines), and
+ * a row may pin further header expectations via `expect.headers`. Headers are
+ * deliberately kept out of the equivalence-group `{status, body}` comparison.
+ *
  * @module
  */
 import { assert, describe, test } from 'vitest';
 import { find_auth_route, rest_auth_route_suffixes, } from '../integration_helpers.js';
-import { find_rpc_action, rpc_call, resolve_rpc_endpoints_for_setup, } from '../rpc_helpers.js';
+import { find_rpc_action, headers_to_record, rpc_call, resolve_rpc_endpoints_for_setup, } from '../rpc_helpers.js';
 import {} from './conformance_case.js';
 import { xfail_until } from './xfail.js';
 /**
@@ -91,19 +97,70 @@ const assert_fields = (actual, fields, label) => {
         assert.deepEqual(record[key], expected, `${label}: field '${key}'`);
     }
 };
+/**
+ * Response headers that fingerprint the backend implementation or framework.
+ * Neither spine emits these; the runner asserts they stay absent on EVERY
+ * conformance response so a framework upgrade or consumer middleware that adds
+ * (say) `Server:` to one spine can't silently become a backend-identifying
+ * oracle. Lowercased — matched against the lowercased-key snapshot
+ * `headers_to_record` produces.
+ */
+export const FINGERPRINT_HEADERS = [
+    'server',
+    'x-powered-by',
+    'www-authenticate',
+];
+/**
+ * Assert a response carries none of the `FINGERPRINT_HEADERS`. Run on every
+ * case unconditionally — the always-on no-fingerprint floor.
+ */
+export const assert_no_fingerprint_headers = (headers, label) => {
+    for (const name of FINGERPRINT_HEADERS) {
+        assert.ok(!(name in headers), `${label}: response leaked backend-fingerprinting header '${name}: ${headers[name]}' — ` +
+            `Server / X-Powered-By / WWW-Authenticate must stay absent on both spines.`);
+    }
+};
+/**
+ * Assert each declared header expectation: a string value must be present and
+ * equal (header name matched case-insensitively), `null` must be absent. The
+ * negative-space twin for headers — `expect.headers` pins a header beyond the
+ * always-on no-fingerprint floor.
+ */
+export const assert_expected_headers = (headers, expected, label) => {
+    for (const [name, value] of Object.entries(expected)) {
+        const key = name.toLowerCase();
+        if (value === null) {
+            assert.ok(!(key in headers), `${label}: header '${name}' expected absent but present as '${headers[key]}'`);
+        }
+        else {
+            assert.strictEqual(headers[key], value, `${label}: header '${name}'`);
+        }
+    }
+};
+/**
+ * Run a case's header invariants: the always-on no-fingerprint floor on every
+ * response plus any declared `expect.headers`. Header assertions are kept off
+ * the equivalence-group `{status, body}` normalized response — `Set-Cookie` /
+ * `Date` legitimately vary, so headers are never compared for byte-identity.
+ */
+const assert_response_headers = (headers, c) => {
+    assert_no_fingerprint_headers(headers, c.name);
+    if (c.expect.headers)
+        assert_expected_headers(headers, c.expect.headers, c.name);
+};
 const is_success_status = (status) => status >= 200 && status < 300;
 /**
  * Run one conformance case end-to-end: resolve the principal, dispatch the
- * request, and assert the expected status / reason / fields.
+ * request, and assert the expected status / reason / fields. Returns the
+ * normalized response so the caller can feed an equivalence group.
  */
 const run_case = async (c, options, resolved_rpc_endpoints) => {
     const fixture = await options.setup_test();
     const { transport, headers, suppress_default_origin } = await resolve_principal(fixture, c.request.as, options.principals);
     if (c.request.method.startsWith('/')) {
-        await run_rest_case(c, options, transport, headers);
-        return;
+        return run_rest_case(c, options, transport, headers);
     }
-    await run_rpc_case(c, transport, headers, suppress_default_origin, resolved_rpc_endpoints);
+    return run_rpc_case(c, transport, headers, suppress_default_origin, resolved_rpc_endpoints);
 };
 /** Dispatch + assert a case targeting an RPC method. */
 const run_rpc_case = async (c, transport, headers, suppress_default_origin, resolved_rpc_endpoints) => {
@@ -121,6 +178,7 @@ const run_rpc_case = async (c, transport, headers, suppress_default_origin, reso
         ...(c.request.verb && { verb: c.request.verb }),
         ...(suppress_default_origin && { suppress_default_origin: true }),
     });
+    assert_response_headers(res.headers, c);
     if (is_success_status(c.expect.status)) {
         assert.ok(res.ok, `${c.name}: expected success (${c.expect.status}) but got error ${JSON.stringify(res.ok ? undefined : res.error)}`);
         assert.strictEqual(res.status, c.expect.status, `${c.name}: status`);
@@ -128,7 +186,7 @@ const run_rpc_case = async (c, transport, headers, suppress_default_origin, reso
         assert.ok(parsed.success, `${c.name}: result does not match spec.output: ${JSON.stringify(parsed.success ? undefined : parsed.error.issues)}`);
         if (c.expect.fields)
             assert_fields(res.result, c.expect.fields, c.name);
-        return;
+        return { status: res.status, body: res.result };
     }
     assert.ok(!res.ok, `${c.name}: expected error status ${c.expect.status} but got success`);
     assert.strictEqual(res.status, c.expect.status, `${c.name}: error status`);
@@ -145,6 +203,7 @@ const run_rpc_case = async (c, transport, headers, suppress_default_origin, reso
     }
     if (c.expect.fields)
         assert_fields(res.error.data, c.expect.fields, c.name);
+    return { status: res.status, body: res.error };
 };
 /** Dispatch + assert a case targeting one of the 6 REST auth routes. */
 const run_rest_case = async (c, options, transport, headers) => {
@@ -165,6 +224,7 @@ const run_rest_case = async (c, options, transport, headers) => {
             c.request.params !== undefined && { body: JSON.stringify(c.request.params) }),
     };
     const response = await transport(route.path, init);
+    assert_response_headers(headers_to_record(response.headers), c);
     assert.strictEqual(response.status, c.expect.status, `${c.name}: status`);
     const body = await response.json().catch(() => undefined);
     if (is_success_status(c.expect.status)) {
@@ -177,6 +237,7 @@ const run_rest_case = async (c, options, transport, headers) => {
     }
     if (c.expect.fields)
         assert_fields(body, c.expect.fields, c.name);
+    return { status: response.status, body };
 };
 /**
  * Register a `describe` block running every `ConformanceCase` as a
@@ -186,10 +247,28 @@ const run_rest_case = async (c, options, transport, headers) => {
  */
 export const describe_conformance_table_tests = (options) => {
     const resolved_rpc_endpoints = resolve_rpc_endpoints_for_setup(options.rpc_endpoints, options.session_options);
+    // Per-group normalized responses, populated as the member case tests run
+    // and consulted by the per-group byte-identity assertions registered after
+    // the case loop — vitest runs a describe's tests in registration order, so
+    // the group assertions execute last, after every member has recorded.
+    const equivalence_groups = new Map();
+    const group_names = new Set();
+    for (const c of options.cases) {
+        if (c.expect.equivalence_group)
+            group_names.add(c.expect.equivalence_group);
+    }
     describe(options.suite_name ?? 'conformance table', () => {
         for (const c of options.cases) {
             const label = c.note ? `${c.name} — ${c.note}` : c.name;
-            const body = () => run_case(c, options, resolved_rpc_endpoints);
+            const group = c.expect.equivalence_group;
+            const body = async () => {
+                const normalized = await run_case(c, options, resolved_rpc_endpoints);
+                if (group) {
+                    const members = equivalence_groups.get(group) ?? [];
+                    members.push({ name: c.name, normalized });
+                    equivalence_groups.set(group, members);
+                }
+            };
             if (c.xfail) {
                 xfail_until(c.xfail.tracking_id, c.xfail.reason, label, body);
             }
@@ -197,5 +276,28 @@ export const describe_conformance_table_tests = (options) => {
                 test(label, body);
             }
         }
+        // Negative-space gate: every member of an equivalence group must have
+        // produced a byte-identical `{status, body}`. This holds the impl under
+        // test to "a prober cannot distinguish these masked paths" — the
+        // promotion of a masked pair (wrong-password ≡ account-not-found,
+        // found-but-unauthorized ≡ not-found) from "same status + reason" to
+        // "wire-indistinguishable". Runs per impl, so each spine is held to it.
+        for (const group of group_names) {
+            test(`equivalence group '${group}' — members are wire-indistinguishable`, () => {
+                const members = equivalence_groups.get(group) ?? [];
+                assert.ok(members.length >= 2, `equivalence group '${group}': expected >= 2 members to have recorded, got ` +
+                    `${members.length} — a group pins indistinguishability between paths, so it ` +
+                    `needs at least a pair (check the member cases ran and weren't all xfail).`);
+                const [first, ...rest] = members;
+                // `members.length >= 2` guarantees `first` is defined; the explicit
+                // assert narrows it for the typechecker (noUncheckedIndexedAccess).
+                assert.ok(first);
+                for (const member of rest) {
+                    assert.deepStrictEqual(member.normalized, first.normalized, `equivalence group '${group}': '${member.name}' is distinguishable from ` +
+                        `'${first.name}' — a prober could tell these masked paths apart. The ` +
+                        `normalized {status, body} must be byte-identical across all members.`);
+                }
+            });
+        }
     });
 };

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

@@ -13,7 +13,7 @@ import '../assert_dev_env.js';
  *
  * ```ts
  * import {create_cross_backend_global_setup} from
- *   '@fuzdev/fuz_app/testing/cross_backend/create_cross_backend_global_setup.js';
+ *   '@fuzdev/fuz_app/testing/cross_backend/create_cross_backend_global_setup.ts';
  * import {deno_backend_config, rust_backend_config} from './my_backend_config.js';
  * import './cross_test_types.js'; // augments inject('backend_handle')
  *

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

@@ -17,7 +17,7 @@ import '../assert_dev_env.js';
  *
  * ```ts
  * import {create_dual_spawn_global_setup} from
- *   '@fuzdev/fuz_app/testing/cross_backend/create_dual_spawn_global_setup.js';
+ *   '@fuzdev/fuz_app/testing/cross_backend/create_dual_spawn_global_setup.ts';
  * import {deno_backend_config, rust_backend_config} from './my_backend_config.js';
  * import './cross_test_types.js'; // augments the two provide keys
  *

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

@@ -1 +1 @@
-{"version":3,"file":"default_backend_configs.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_backend_configs.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAC,sBAAsB,EAAE,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAC,mBAAmB,EAAE,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAA2B,KAAK,gBAAgB,EAAC,MAAM,+BAA+B,CAAC;AAQ9F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAiBpC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,mBAgBtC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAInC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAIrC,CAAC;AAeH,MAAM,WAAW,iCAAiC;IACjD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,iCAAiC,KACrC,aAoCF,CAAC;AAEF,MAAM,WAAW,mCAAmC;IACnD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,mCAAmC,KACvC,aA4CF,CAAC"}
+{"version":3,"file":"default_backend_configs.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_backend_configs.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAC,sBAAsB,EAAE,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAC,mBAAmB,EAAE,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAA2B,KAAK,gBAAgB,EAAC,MAAM,+BAA+B,CAAC;AAQ9F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAqBpC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,mBAmBtC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAInC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAIrC,CAAC;AAeH,MAAM,WAAW,iCAAiC;IACjD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,iCAAiC,KACrC,aAoCF,CAAC;AAEF,MAAM,WAAW,mCAAmC;IACnD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,mCAAmC,KACvC,aA4CF,CAAC"}

package/dist/testing/cross_backend/default_backend_configs.js

@@ -35,6 +35,10 @@ export const ts_default_capabilities = Object.freeze({
     // posture). A Bun-served consumer overrides to `false` (see the bun spine
     // config) — fail-loud rather than silently skipping the smuggle detector.
     oversized_reject_closes_connection: true,
+    // The TS server can't yet initiate server→client requests (the
+    // `BackendWebsocketTransport.send()` request path is the deferred
+    // twin-impl convergence), so the TS family skips the peer/ping suite.
+    peer_request: false,
 });
 /**
  * Capabilities for the Rust family. The non-gating wiring facts live in
@@ -57,6 +61,9 @@ export const rust_default_capabilities = Object.freeze({
     // hyper sends an RST on the oversized-body reject — the connection closes
     // and the pipelined request is never reached.
     oversized_reject_closes_connection: true,
+    // Server-initiated requests landed Rust-first canonical — the Rust spine
+    // drives the `peer/ping` round-trip, so the family opts into the suite.
+    peer_request: true,
 });
 /**
  * Shape notes for TS-family backends — wiring facts, not gating flags.

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

@@ -23,7 +23,7 @@ import '../assert_dev_env.js';
  *
  * @module
  */
-import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import type { NotificationSender } from '../../auth/role_grant_offer_notifications.js';
 import { type RoleSchemaResult } from '../../auth/role_schema.js';
 import { type SessionOptions } from '../../auth/session_cookie.js';

package/dist/testing/cross_backend/fact_serving.js

@@ -38,7 +38,7 @@ import '../assert_dev_env.js';
  */
 import { describe, assert } from 'vitest';
 import { z } from 'zod';
-import { FactHashSchema } from '@fuzdev/fuz_util/fact_hash.js';
+import { FactHashSchema } from '@fuzdev/fuz_util/fact_hash.ts';
 import { CellCreateOutput } from '../../auth/cell_action_specs.js';
 import { test_if } from './capabilities.js';
 import { cross_rpc_call, expect_output } from './cell_cross_helpers.js';

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

@@ -0,0 +1,23 @@
+import '../assert_dev_env.js';
+import { type BackendCapabilities } from './capabilities.js';
+import type { SetupTest } from './setup.js';
+/** Configuration for {@link describe_peer_ping_ws_tests}. */
+export interface PeerPingWsTestOptions {
+    /** Per-test fixture producer (`default_cross_process_setup(handle, ...)`). */
+    readonly setup_test: SetupTest;
+    /** Backend capability flags; every case gates on `capabilities.peer_request`. */
+    readonly capabilities: BackendCapabilities;
+    /** Base URL the backend is reachable at (e.g. `http://localhost:1177`). */
+    readonly base_url: string;
+    /** WebSocket endpoint path on the backend (e.g. `/api/ws`). */
+    readonly ws_path: string;
+}
+/**
+ * Register the server-initiated `peer/ping` suite — a positive round-trip
+ * plus the security negatives the design doc's §Security surface mandates
+ * (unsolicited-response rejection, per-connection id isolation, never-reply
+ * `Timeout`, wrong-shape reply rejection, plus client-error forwarding and
+ * the HTTP no-transport path). Gated on `capabilities.peer_request`.
+ */
+export declare const describe_peer_ping_ws_tests: (options: PeerPingWsTestOptions) => void;
+//# sourceMappingURL=peer_ping_ws.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"peer_ping_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/peer_ping_ws.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAkD9B,OAAO,EAAC,KAAK,mBAAmB,EAAU,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,YAAY,CAAC;AAkB1C,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GAAI,SAAS,qBAAqB,KAAG,IAmN5E,CAAC"}

package/dist/testing/cross_backend/peer_ping_ws.js

@@ -0,0 +1,209 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process **server-initiated `peer/ping`** suite — the machinery
+ * proof for `ActionPeer` (a backend initiating a JSON-RPC request to a
+ * connected client and awaiting its typed reply). The sibling of the
+ * one-way notification suite (`role_grant_offer_notification_ws.ts`),
+ * extended from server→client *notifications* to server→client
+ * *request/response*.
+ *
+ * `peer/ping` is `initiator: both`: the client→server direction already
+ * exists as `heartbeat`; the new server→client direction is what this
+ * exercises. The observable trigger is the client invoking the `peer/ping`
+ * **action** over its own socket — the handler turns around and *initiates*
+ * a `peer/ping` request back to that socket, awaits the client's echo,
+ * validates it against `PingResponse`, and returns the validated shape. So
+ * one client RPC drives the whole round-trip, and every outcome
+ * (success / `Timeout` / wrong-shape / client-error) surfaces as that RPC's
+ * wire response — directly assertable.
+ *
+ * The client side attaches an `on_request` responder **at construction**
+ * (via `create_ws_transport`'s seam) so the server-initiated request is
+ * answered as soon as it arrives. Security negatives use the raw
+ * `WsClient.send` to inject unsolicited / cross-connection frames.
+ *
+ * **Per-spec auth.** `peer/ping` is `auth: public` (a liveness echo is
+ * non-sensitive — see the design doc); the WS upgrade itself still
+ * authenticates, so the suite drives it over the keeper's session.
+ *
+ * Gated on `capabilities.peer_request` — `true` only for the Rust spine
+ * (server-initiated requests landed Rust-first canonical); the TS family
+ * skips until its server transport's request path lands (deferred twin-impl
+ * convergence). Cross-process only: `create_ws_transport` needs a real bound
+ * socket, so wire it from a `*.cross.test.ts`.
+ *
+ * @module
+ */
+import { assert, describe } from 'vitest';
+import { rpc_call } from '../rpc_helpers.js';
+import { create_ws_transport } from '../transports/ws_transport.js';
+import { is_response_for, } from '../transports/ws_client.js';
+import { create_jsonrpc_request, is_jsonrpc_request } from '../../http/jsonrpc_helpers.js';
+import { test_if } from './capabilities.js';
+/** JSON-RPC endpoint path — matches the spine's `/api/rpc` (and the forge's). */
+const RPC_PATH = '/api/rpc';
+/** Wire method (both directions). Mirrors the Rust `PEER_PING_METHOD`. */
+const PEER_PING_METHOD = 'peer/ping';
+// Stable `data.reason` discriminators — the cross-impl wire contract, kept
+// as an independent TS-side copy of the Rust `REASON_PEER_*` constants
+// (parity by test, not codegen).
+const REASON_PEER_TIMEOUT = 'peer_timeout';
+const REASON_PEER_INVALID_REPLY = 'peer_ping_invalid_reply';
+const REASON_PEER_NO_TRANSPORT = 'peer_no_transport';
+/** A reply payload that satisfies the Rust `PingResponse` shape. */
+const valid_reply = (nonce) => ({ nonce, protocol_version: 1 });
+/**
+ * Register the server-initiated `peer/ping` suite — a positive round-trip
+ * plus the security negatives the design doc's §Security surface mandates
+ * (unsolicited-response rejection, per-connection id isolation, never-reply
+ * `Timeout`, wrong-shape reply rejection, plus client-error forwarding and
+ * the HTTP no-transport path). Gated on `capabilities.peer_request`.
+ */
+export const describe_peer_ping_ws_tests = (options) => {
+    const { setup_test, capabilities, base_url, ws_path } = options;
+    // -- shared helpers -------------------------------------------------------
+    /** Open a WS transport for a session cookie, with an optional responder. */
+    const open_ws = (cookie, on_request) => {
+        assert.ok(cookie, 'expected a session cookie for the WS upgrade');
+        return create_ws_transport({
+            base_url,
+            ws_path,
+            cookies: [cookie],
+            origin: base_url,
+            on_request,
+        });
+    };
+    /** A responder that echoes a valid `PingResponse` for every `peer/ping`. */
+    const echo_responder = (req) => {
+        const nonce = req.params?.nonce ?? 0;
+        return { result: valid_reply(nonce) };
+    };
+    /**
+     * Invoke `peer/ping` over the socket and return the **raw** response
+     * frame (success or error) so the negatives can assert on
+     * `error.data.reason`. The client wait is generous (longer than any
+     * server-side `timeout_ms`) so the server's own outcome is what we read.
+     */
+    const ping_raw = (ws, id, params) => ws
+        .send(create_jsonrpc_request(PEER_PING_METHOD, params, id))
+        .then(() => ws.wait_for(is_response_for(id), 8000));
+    const error_reason = (frame) => frame.error.data?.reason;
+    // -- tests ----------------------------------------------------------------
+    describe('peer/ping server-initiated request (cross-process)', () => {
+        test_if(capabilities.peer_request, 'a client peer/ping round-trips: server pings back, validates the echo, returns it', async () => {
+            const fixture = await setup_test();
+            const ws = await open_ws(fixture.create_session_headers().cookie, echo_responder);
+            try {
+                const result = await ws.request(1, PEER_PING_METHOD, { nonce: 42 }, 8000);
+                assert.strictEqual(result.nonce, 42, 'the server echoes the issued nonce back');
+                assert.strictEqual(typeof result.protocol_version, 'number');
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'a never-replying client yields a server-side Timeout (the liveness signal)', async () => {
+            const fixture = await setup_test();
+            // Responder swallows the ping (returns nothing) — the half-open peer.
+            const ws = await open_ws(fixture.create_session_headers().cookie, () => undefined);
+            try {
+                // Short server-side deadline so the negative runs fast.
+                const frame = await ping_raw(ws, 2, { nonce: 1, timeout_ms: 300 });
+                assert.ok('error' in frame, 'a swallowed ping must error, not succeed');
+                assert.strictEqual(error_reason(frame), REASON_PEER_TIMEOUT);
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'a wrong-shape reply is rejected at the validation boundary, never handed to the caller', async () => {
+            const fixture = await setup_test();
+            // Reply that fails `PingResponse` validation (nonce wrong type,
+            // protocol_version missing).
+            const ws = await open_ws(fixture.create_session_headers().cookie, () => ({
+                result: { nonce: 'not-a-number' },
+            }));
+            try {
+                const frame = await ping_raw(ws, 3, { nonce: 1, timeout_ms: 2000 });
+                assert.ok('error' in frame, 'a malformed reply must error, not return garbage');
+                assert.strictEqual(error_reason(frame), REASON_PEER_INVALID_REPLY);
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'a client JSON-RPC error reply surfaces as the action error (ClientError forwarded)', async () => {
+            const fixture = await setup_test();
+            const ws = await open_ws(fixture.create_session_headers().cookie, () => ({
+                error: { code: -32603, message: 'client refused', data: { reason: 'client_says_no' } },
+            }));
+            try {
+                const frame = await ping_raw(ws, 4, { nonce: 1, timeout_ms: 2000 });
+                assert.ok('error' in frame, 'a client error reply must surface as an error');
+                assert.strictEqual(frame.error.code, -32603);
+                assert.strictEqual(error_reason(frame), 'client_says_no');
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'an unsolicited response is dropped: it resolves nothing and the socket survives', async () => {
+            const fixture = await setup_test();
+            const ws = await open_ws(fixture.create_session_headers().cookie, echo_responder);
+            try {
+                // Inject a reply for an id the server never issued on this socket.
+                await ws.send({ jsonrpc: '2.0', id: 's999999', result: valid_reply(7) });
+                // A legitimate round-trip still works → the junk frame neither
+                // crashed the read loop nor corrupted the pending registry.
+                const result = await ws.request(5, PEER_PING_METHOD, { nonce: 99 }, 8000);
+                assert.strictEqual(result.nonce, 99);
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'a reply on socket B never resolves a request issued on socket A (per-connection isolation)', async () => {
+            const fixture = await setup_test();
+            // A has NO responder, so the inbound server-initiated request is
+            // surfaced as a message A can observe (to learn its server id);
+            // A never answers it.
+            const ws_a = await open_ws(fixture.create_session_headers().cookie);
+            const ws_b = await open_ws(fixture.create_session_headers().cookie, echo_responder);
+            try {
+                // A invokes peer/ping with a short server-side deadline; don't
+                // await yet — observe the server→client request first.
+                const ping_promise = ping_raw(ws_a, 6, { nonce: 1, timeout_ms: 1200 });
+                // The server-initiated request A received (id "sN", nonce 1).
+                const inbound = await ws_a.wait_for((m) => is_jsonrpc_request(m) && m.method === PEER_PING_METHOD, 5000);
+                // B replies for A's id — a cross-connection echo. Correct
+                // isolation drops it (not pending on B), so A still times out.
+                await ws_b.send({
+                    jsonrpc: '2.0',
+                    id: inbound.id,
+                    result: valid_reply(inbound.params.nonce),
+                });
+                const frame = await ping_promise;
+                assert.ok('error' in frame, "B's cross-connection reply must not resolve A's request");
+                assert.strictEqual(error_reason(frame), REASON_PEER_TIMEOUT);
+            }
+            finally {
+                await ws_a.close();
+                await ws_b.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'peer/ping over HTTP (no return socket) is rejected as no-transport', async () => {
+            const fixture = await setup_test();
+            const res = await rpc_call({
+                app: fixture.transport,
+                path: RPC_PATH,
+                method: PEER_PING_METHOD,
+                params: { nonce: 1 },
+                headers: fixture.create_session_headers(),
+            });
+            assert.isFalse(res.ok, 'HTTP peer/ping has no socket to ping');
+            if (!res.ok) {
+                assert.strictEqual(res.error.data?.reason, REASON_PEER_NO_TRANSPORT);
+            }
+        });
+    });
+};

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

@@ -1,5 +1,5 @@
 import '../assert_dev_env.js';
-import { Uuid } from '@fuzdev/fuz_util/id.js';
+import { Uuid } from '@fuzdev/fuz_util/id.ts';
 import type { TestAccount } from '../app_server.js';
 import type { BackendCapabilities } from './capabilities.js';
 import { type FetchTransport } from '../transports/fetch_transport.js';

package/dist/testing/cross_backend/setup.js

@@ -22,7 +22,7 @@ import '../assert_dev_env.js';
  * @module
  */
 import { z } from 'zod';
-import { Uuid } from '@fuzdev/fuz_util/id.js';
+import { Uuid } from '@fuzdev/fuz_util/id.ts';
 import { DAEMON_TOKEN_HEADER } from '../../auth/daemon_token.js';
 import { USERNAME_LENGTH_MAX } from '../../primitive_schemas.js';
 import { DEFAULT_TEST_PASSWORD } from '../test_credentials.js';

package/dist/testing/cross_backend/testing_reset_actions.js

@@ -66,8 +66,8 @@ import '../assert_dev_env.js';
  * @module
  */
 import { z } from 'zod';
-import { Uuid } from '@fuzdev/fuz_util/id.js';
-import { fact_hash_bytes, FactHashSchema } from '@fuzdev/fuz_util/fact_hash.js';
+import { Uuid } from '@fuzdev/fuz_util/id.ts';
+import { fact_hash_bytes, FactHashSchema } from '@fuzdev/fuz_util/fact_hash.ts';
 import { rpc_action } from '../../actions/action_rpc.js';
 import { query_put_fact } from '../../db/fact_queries.js';
 import { ROLE_ADMIN, ROLE_KEEPER } from '../../auth/role_schema.js';

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

@@ -28,7 +28,7 @@ import '../assert_dev_env.js';
  */
 import type { Context, Hono } from 'hono';
 import type { UpgradeWebSocket } from 'hono/ws';
-import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
+import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.ts';
 import type { RuntimeDeps } from '../../runtime/deps.js';
 /**
  * Adapter-built handle to a bound HTTP server.

package/dist/testing/cross_backend/testing_server_core.js

@@ -1,5 +1,5 @@
 import '../assert_dev_env.js';
-import { Logger } from '@fuzdev/fuz_util/log.js';
+import { Logger } from '@fuzdev/fuz_util/log.ts';
 import { write_daemon_info, read_daemon_info, is_daemon_running } from '../../cli/daemon.js';
 /**
  * Loopback bind hosts — the only ones the test binary may serve on. It ships

package/dist/testing/cross_backend/ws_round_trip.js

@@ -41,7 +41,7 @@ import '../assert_dev_env.js';
  * @module
  */
 import { assert, describe } from 'vitest';
-import { assert_rejects } from '@fuzdev/fuz_util/testing.js';
+import { assert_rejects } from '@fuzdev/fuz_util/testing.ts';
 import { heartbeat_action_spec } from '../../actions/heartbeat.js';
 import { account_session_revoke_all_action_spec } from '../../auth/account_action_specs.js';
 import { create_ws_transport } from '../transports/ws_transport.js';

package/dist/testing/db.js

@@ -8,9 +8,9 @@ import './assert_dev_env.js';
  *
  * @example
  * ```ts
- * import {create_pglite_factory, create_pg_factory} from '@fuzdev/fuz_app/testing/db.js';
- * import {run_migrations} from '@fuzdev/fuz_app/db/migrate.js';
- * import {auth_migration_ns} from '@fuzdev/fuz_app/auth/migrations.js';
+ * import {create_pglite_factory, create_pg_factory} from '@fuzdev/fuz_app/testing/db.ts';
+ * import {run_migrations} from '@fuzdev/fuz_app/db/migrate.ts';
+ * import {auth_migration_ns} from '@fuzdev/fuz_app/auth/migrations.ts';
  *
  * const init_schema = async (db) => {
  *   await run_migrations(db, [auth_migration_ns]);
@@ -23,7 +23,7 @@ import './assert_dev_env.js';
  * @module
  */
 import { describe, beforeAll, beforeEach, afterAll } from 'vitest';
-import { to_error_message } from '@fuzdev/fuz_util/error.js';
+import { to_error_message } from '@fuzdev/fuz_util/error.ts';
 import { create_pglite_db } from '../db/db_pglite.js';
 import { assert_valid_sql_identifier } from '../db/sql_identifier.js';
 import { create_pg_db } from '../db/db_pg.js';

package/dist/testing/middleware.js

@@ -10,7 +10,7 @@ import './assert_dev_env.js';
  */
 import { vi, test, assert, describe } from 'vitest';
 import { Hono } from 'hono';
-import { Logger } from '@fuzdev/fuz_util/log.js';
+import { Logger } from '@fuzdev/fuz_util/log.ts';
 import { create_bearer_auth_middleware } from '../auth/bearer_auth.js';
 import { query_validate_api_token } from '../auth/api_token_queries.js';
 import { query_account_by_id, query_actor_by_id, query_actors_by_account, } from '../auth/account_queries.js';

package/dist/testing/role_grant_helpers.d.ts

@@ -1,5 +1,5 @@
 import './assert_dev_env.js';
-import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { Uuid } from '@fuzdev/fuz_util/id.ts';
 import type { TestAccount, TestApp } from './app_server.js';
 import type { TestFixture } from './cross_backend/setup.js';
 import { type RpcCallArgs } from './rpc_helpers.js';