@fuzdev/fuz_app 0.146.1 → 0.148.0

package/dist/testing/cross_backend/in_process_setup.js

@@ -1,14 +1,14 @@
 import '../assert_dev_env.js';
 import { ROLE_KEEPER } from '../../auth/role_schema.js';
-import { query_create_actor } from '../../auth/account_queries.js';
+import { create_test_extra_actor } from '../db_entities.js';
 import { create_test_app, create_test_account_with_credentials, mint_test_session } from '../app_server.js';
 import { create_test_app_surface_spec } from '../stubs.js';
 import { http_transport } from '../rpc_helpers.js';
 import { in_process_capabilities } from './capabilities.js';
-import { build_extra_account_fixture, EXPIRED_SESSION_OFFSET_SECONDS } from './setup.js';
+import { EXPIRED_SESSION_OFFSET_SECONDS, to_test_account } from './setup.js';
 /**
  * Wrap a Hono-style app into a `FetchTransport`-shaped object so the
- * shared `TestFixtureBase.transport` type holds for both in-process and
+ * shared `TestFixture.transport` type holds for both in-process and
  * cross-process setups. In-process has no real cookie jar — the no-op
  * `cookies()` returns `[]`; in-process tests build cookies via
  * `fixture.create_session_headers()` instead.
@@ -60,15 +60,16 @@ export const default_in_process_setup = (options) => async () => {
             password_value: spec.password_value,
             roles: [...spec.roles]
         });
-        extra_accounts[spec.username] = build_extra_account_fixture(seeded, cookie_name);
+        extra_accounts[spec.username] = to_test_account(seeded, cookie_name);
     }
     // Seed additional keeper actors directly against the same DB. Mirrors
     // the cross-process `_testing_reset` `extra_actors` path; no production
     // wire mints a second actor, so this bootstrap-cradle insert is the
-    // only way into a multi-actor keeper state.
+    // only way into a multi-actor keeper state. Seeded at the wall clock,
+    // like the reset, so they sort after the bootstrap actor.
     const extra_actors = [];
     for (const name of options.extra_actors ?? []) {
-        const seeded_actor = await query_create_actor({ db: test_app.backend.deps.db }, test_app.backend.account.id, name);
+        const seeded_actor = await create_test_extra_actor(test_app.backend.deps.db, test_app.backend.account.id, name);
         extra_actors.push({ id: seeded_actor.id, name: seeded_actor.name });
     }
     return {
@@ -85,6 +86,7 @@ export const default_in_process_setup = (options) => async () => {
         create_account: test_app.create_account,
         extra_accounts,
         extra_actors,
+        reject_unknown_audit_metadata_keys: options.reject_unknown_audit_metadata_keys ?? false,
         // Forge directly against the live backend's DB + keyring — no wire
         // hop needed in-process.
         mint_expired_session: async () => {
@@ -147,7 +149,8 @@ export const default_in_process_suite_options = (options) => ({
         app_options: options.app_options,
         roles: [ROLE_KEEPER, ...(options.extra_keeper_roles ?? [])],
         extra_accounts: options.extra_accounts,
-        extra_actors: options.extra_actors
+        extra_actors: options.extra_actors,
+        reject_unknown_audit_metadata_keys: options.reject_unknown_audit_metadata_keys
     }),
     surface_source: options.surface_source ??
         create_test_app_surface_spec({

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

@@ -1 +1 @@
-{"version":3,"file":"login_security.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/login_security.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAsF9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C,mDAAmD;AACnD,MAAM,WAAW,6BAA6B;IAC7C,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAmDD,eAAO,MAAM,mCAAmC,GAC/C,SAAS,6BAA6B,KACpC,IA8XF,CAAC"}
+{"version":3,"file":"login_security.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/login_security.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAsF9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAO5C,mDAAmD;AACnD,MAAM,WAAW,6BAA6B;IAC7C,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAmDD,eAAO,MAAM,mCAAmC,GAC/C,SAAS,6BAA6B,KACpC,IA4VF,CAAC"}

package/dist/testing/cross_backend/login_security.js

@@ -78,9 +78,8 @@ import { describe, test, assert } from 'vitest';
 import { ERROR_RATE_LIMIT_EXCEEDED } from '../../http/error_schemas.js';
 import { raw_http_exchange, raw_http_parse_response } from '../transports/raw_http.js';
 import { default_login_account_rate_limit, default_login_ip_rate_limit } from '../../rate_limiter.js';
-import { AuditLogListOutput } from '../../auth/admin_action_specs.js';
-import { cross_rpc_call, expect_output } from './cell_cross_helpers.js';
-import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+import { list_audit_events } from './audit_cross_helpers.js';
+import { SPINE_ACCOUNT_LOGIN_PATH, SPINE_ACCOUNT_PASSWORD_PATH } from './spine_surface_constants.js';
 /**
  * RFC 5737 TEST-NET-3 (`203.0.113.0/24`) documentation addresses — guaranteed
  * non-routable, so they never collide with a real client IP. One per bucket the
@@ -116,13 +115,13 @@ const XFF_V6_OTHER_64 = '2001:db8:e3:2::1';
 const XFF_V6_PASSWORD_EXHAUST = '2001:db8:e3:5::1';
 const XFF_V6_PASSWORD_SAME_64 = '2001:db8:e3:5:8000::2';
 /** How long a raw exchange waits for the login's answer. */
-const RAW_READ_TIMEOUT_MS = 5000;
+const LOGIN_RAW_READ_TIMEOUT_MS = 5000;
 /** A non-routable, non-existent identifier — login resolves to the not-found path (records the bucket, returns 401). */
 const PROBE_PASSWORD = 'login_security_wrong_password';
 export const describe_login_security_cross_tests = (options) => {
     const { setup_test } = options;
-    const login_path = options.login_path ?? '/api/account/login';
-    const password_path = options.password_path ?? '/api/account/password';
+    const login_path = options.login_path ?? SPINE_ACCOUNT_LOGIN_PATH;
+    const password_path = options.password_path ?? SPINE_ACCOUNT_PASSWORD_PATH;
     const concurrent_transactions = options.concurrent_transactions ?? false;
     const base_url = options.base_url ?? null;
     /** Per-IP cap shared by both impls (TS `default_login_ip_rate_limit`, Rust `DEFAULT_LOGIN_IP_RATE_LIMIT`). */
@@ -214,10 +213,8 @@ export const describe_login_security_cross_tests = (options) => {
             // that stops keys on the (loopback) connection IP → 401.
             const stopped = await attempt(fixture, `${XFF_MALFORMED_HOP}, ${XFF_PORT_SUFFIXED_HOP}`, 'probe_malformed_hop');
             assert.strictEqual(stopped.status, 401, 'the walk must stop at the malformed hop, not reach the entry left of it');
-            const drained = await cross_rpc_call(fixture.fresh_transport({ origin: null }), SPINE_RPC_PATH, '_testing_drain_effects', undefined, fixture.create_daemon_token_headers());
-            assert.ok(drained.ok, `_testing_drain_effects failed: ${JSON.stringify(drained.error)}`);
-            const listed = expect_output(await cross_rpc_call(fixture.transport, SPINE_RPC_PATH, 'audit_log_list', { event_type: 'login', outcome: 'failure' }, fixture.create_session_headers()), AuditLogListOutput);
-            const ips = listed.events.map((e) => e.ip);
+            const events = await list_audit_events(fixture, { event_type: 'login', outcome: 'failure' });
+            const ips = events.map((e) => e.ip);
             assert.ok(ips.some((ip) => ip === '127.0.0.1' || ip === '::1'), `the stopped walk must key on the loopback connection IP: ${JSON.stringify(ips)}`);
             assert.ok(!ips.includes(XFF_PORT_SUFFIXED_HOP), `a malformed entry is never a client IP: ${JSON.stringify(ips)}`);
         });
@@ -233,13 +230,11 @@ export const describe_login_security_cross_tests = (options) => {
             // the next /64 has its own
             const other = await attempt(fixture, XFF_V6_OTHER_64, 'probe_v6');
             assert.strictEqual(other.status, 401, 'the next /64 must keep its own budget');
-            // The limiter keys the /64; the audit trail keeps the address. Drain
-            // the fire-and-forget audit writes, then read this test's login rows
-            // (`_testing_reset` wiped the log at setup).
-            const drained = await cross_rpc_call(fixture.fresh_transport({ origin: null }), SPINE_RPC_PATH, '_testing_drain_effects', undefined, fixture.create_daemon_token_headers());
-            assert.ok(drained.ok, `_testing_drain_effects failed: ${JSON.stringify(drained.error)}`);
-            const listed = expect_output(await cross_rpc_call(fixture.transport, SPINE_RPC_PATH, 'audit_log_list', { event_type: 'login', outcome: 'failure' }, fixture.create_session_headers()), AuditLogListOutput);
-            const ips = listed.events.map((e) => e.ip);
+            // The limiter keys the /64; the audit trail keeps the address. Read
+            // this test's login rows behind the drain barrier (`_testing_reset`
+            // wiped the log at setup).
+            const events = await list_audit_events(fixture, { event_type: 'login', outcome: 'failure' });
+            const ips = events.map((e) => e.ip);
             assert.ok(ips.includes(XFF_V6_EXHAUST), `audit ips: ${JSON.stringify(ips)}`);
             assert.ok(ips.includes(XFF_V6_OTHER_64), `audit ips: ${JSON.stringify(ips)}`);
             assert.ok(ips.every((ip) => ip === null || !ip.includes('/')), `no audit row may carry a rate-limit key: ${JSON.stringify(ips)}`);
@@ -320,7 +315,7 @@ export const describe_login_security_cross_tests = (options) => {
                 `\r\n` +
                 body;
             const { received } = await raw_http_exchange(base_url, request, {
-                read_timeout_ms: RAW_READ_TIMEOUT_MS,
+                read_timeout_ms: LOGIN_RAW_READ_TIMEOUT_MS,
                 until: 'response'
             });
             const response = raw_http_parse_response(received);

package/dist/testing/cross_backend/origin.js

@@ -16,7 +16,7 @@ import '../assert_dev_env.js';
  *
  * Runs both legs via the shared `setup_test` protocol: the
  * in-process leg (`auth/origin_parity.db.test.ts`, plain `gro test`) and the
- * cross-process leg (`cross_backend/origin.cross.test.ts`, the TS spine
+ * cross-process leg (`cross_backend/spine_suites.cross.test.ts`, the TS spine
  * binaries + Rust `testing_spine_stub` over real HTTP). Origin middleware is
  * on every spine, so the suite is ungated.
  *

package/dist/testing/cross_backend/origin_conformance.js

@@ -24,7 +24,7 @@ import { readFileSync } from 'node:fs';
 import { assert, describe, test } from 'vitest';
 import { z } from 'zod';
 import { AllowedOriginsErrorKind } from '../../http/origin.js';
-import { cross_rpc_call } from './cell_cross_helpers.js';
+import { cross_rpc_call } from './cross_rpc.js';
 import { SPINE_RPC_PATH } from './spine_surface_constants.js';
 import { TestingOriginCheckOutput, testing_origin_check_action_spec } from './testing_origin_check.js';
 /** One expected refusal of a parse row. */

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

@@ -11,6 +11,12 @@ export interface OriginScopeCrossTestOptions extends CapabilityGatedCrossSuiteOp
      * default) sends the whole body through the fixture's in-process transport.
      */
     readonly base_url?: string | null;
+    /**
+     * The status the backend's fallback answers an unrouted `GET` with, once
+     * the origin check has passed it. Default `404`; a backend serving an SPA
+     * shell from its fallback passes `200`.
+     */
+    readonly unrouted_status?: number;
 }
 export declare const describe_origin_scope_cross_tests: (options: OriginScopeCrossTestOptions) => void;
 //# sourceMappingURL=origin_scope.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"origin_scope.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/origin_scope.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA4C9B,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,YAAY,CAAC;AAcnE,iDAAiD;AACjD,MAAM,WAAW,2BAA4B,SAAQ,gCAAgC;IACpF,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,eAAO,MAAM,iCAAiC,GAAI,SAAS,2BAA2B,KAAG,IAmGxF,CAAC"}
+{"version":3,"file":"origin_scope.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/origin_scope.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAmD9B,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,YAAY,CAAC;AASnE,iDAAiD;AACjD,MAAM,WAAW,2BAA4B,SAAQ,gCAAgC;IACpF,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,eAAO,MAAM,iCAAiC,GAAI,SAAS,2BAA2B,KAAG,IAwGxF,CAAC"}

package/dist/testing/cross_backend/origin_scope.js

@@ -20,8 +20,11 @@ import '../assert_dev_env.js';
  *
  * And on a path neither server routes, which reaches each spine's fallback:
  *
- * - **foreign `Origin` → 403 `forbidden_origin`**, **absent → 404** — the
- *   fallback is behind the check, not attached after it.
+ * - **foreign `Origin` → 403 `forbidden_origin`**, **absent → the fallback's
+ *   own answer** — the fallback is behind the check, not attached after it.
+ *   The absent row pins that the check let the request through to the
+ *   fallback: `404` by default, or `unrouted_status` for a backend whose
+ *   fallback serves an SPA shell (`200`).
  * - **an over-cap `POST` with a declared `Content-Length` and a foreign
  *   `Origin` → 413 `payload_too_large`** — the body cap comes ahead of the
  *   origin check on the fallback too (413-first holds for a declared length).
@@ -30,27 +33,25 @@ import '../assert_dev_env.js';
  * server advertises; the unrouted rows run on every backend.
  * Runs both legs via the shared `{setup_test, capabilities}` protocol: the
  * in-process leg (`cross_backend/origin_scope_parity.db.test.ts`, plain `gro
- * test`) and the cross-process leg (`cross_backend/origin_scope.cross.test.ts`,
+ * test`) and the cross-process leg (`cross_backend/spine_suites.cross.test.ts`,
  * the TS spine binaries + Rust `testing_spine_stub` over real HTTP).
  *
  * @module
  */
 import { describe, assert, test } from 'vitest';
 import { ERROR_FORBIDDEN_ORIGIN, ERROR_PAYLOAD_TOO_LARGE } from '../../http/error_schemas.js';
-import { raw_http_exchange, raw_http_parse_response } from '../transports/raw_http.js';
+import { raw_http_exchange, raw_http_parse_response, RAW_HTTP_READ_TIMEOUT_MS } from '../transports/raw_http.js';
 import { test_if } from './capabilities.js';
+import { SPINE_BODY_LIMIT_DEFAULT_BYTES } from './spine_surface_constants.js';
 /** An origin no spine test server allows. */
 const FOREIGN_ORIGIN = 'https://evil.example';
 /** A path no spine test server routes — it reaches the fallback. */
 const UNROUTED_PATH = '/origin-scope-unrouted';
-/** The shared 1 MiB default cap both spines ship, as in `body_size.ts`. */
-const BODY_LIMIT_DEFAULT_BYTES = 1024 * 1024;
-/** How long a raw exchange waits for the refusal. */
-const RAW_READ_TIMEOUT_MS = 2000;
 export const describe_origin_scope_cross_tests = (options) => {
     const { setup_test, capabilities } = options;
     const probe_path = options.probe_path ?? '/ready';
     const base_url = options.base_url ?? null;
+    const unrouted_status = options.unrouted_status ?? 404;
     describe('origin check scope parity', () => {
         test_if(capabilities.ready, `a foreign Origin on ${probe_path} → 403 forbidden_origin (the check covers every path)`, async () => {
             const fixture = await setup_test();
@@ -86,15 +87,15 @@ export const describe_origin_scope_cross_tests = (options) => {
             const body = (await res.json().catch(() => undefined));
             assert.strictEqual(body?.error, ERROR_FORBIDDEN_ORIGIN);
         });
-        test('an absent Origin on an unrouted path → 404', async () => {
+        test(`an absent Origin on an unrouted path → passes to the fallback (${unrouted_status})`, async () => {
             const fixture = await setup_test();
             const res = await fixture.fresh_transport({ origin: null })(UNROUTED_PATH, {
                 method: 'GET'
             });
-            assert.strictEqual(res.status, 404, 'the fallback answers its own 404 past the check');
+            assert.strictEqual(res.status, unrouted_status, 'a request with no Origin must pass the check and reach the fallback');
         });
         test('an over-cap POST to an unrouted path with a foreign Origin → 413 payload_too_large', async () => {
-            const over = BODY_LIMIT_DEFAULT_BYTES + 1;
+            const over = SPINE_BODY_LIMIT_DEFAULT_BYTES + 1;
             let status;
             let text;
             if (base_url === null) {
@@ -117,7 +118,7 @@ export const describe_origin_scope_cross_tests = (options) => {
                     `content-length: ${over}\r\n` +
                     `\r\n`;
                 const { received } = await raw_http_exchange(base_url, request, {
-                    read_timeout_ms: RAW_READ_TIMEOUT_MS,
+                    read_timeout_ms: RAW_HTTP_READ_TIMEOUT_MS,
                     until: 'response'
                 });
                 const response = raw_http_parse_response(received);

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

@@ -1,16 +1,13 @@
 import '../assert_dev_env.js';
 import { type BackendCapabilities } from './capabilities.js';
 import type { SetupTest } from './setup.js';
+import { type WsEndpointTarget } from './ws_endpoint.js';
 /** Configuration for `describe_peer_ping_ws_tests`. */
-export interface PeerPingWsTestOptions {
+export interface PeerPingWsTestOptions extends WsEndpointTarget {
     /** 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

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

@@ -1 +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,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAuB5C,uDAAuD;AACvD,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,IA8O5E,CAAC"}
+{"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;AAiD9B,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAEzD,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAoB1E,uDAAuD;AACvD,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC9D,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GAAI,SAAS,qBAAqB,KAAG,IAmO5E,CAAC"}

package/dist/testing/cross_backend/peer_ping_ws.js

@@ -36,10 +36,11 @@ import '../assert_dev_env.js';
  */
 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';
+import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+import { open_session_ws } from './ws_endpoint.js';
 // The wire literals below are deliberate independent copies of the
 // producers' constants (`actions/peer_ping.ts` on TS, `REASON_PEER_*` /
 // `PEER_PING_METHOD` on Rust) — parity by test, not codegen. The harness
@@ -52,8 +53,6 @@ const PEER_PING_METHOD = 'peer/ping';
 const REASON_PEER_TIMEOUT = 'peer_timeout';
 const REASON_PEER_PING_INVALID_REPLY = 'peer_ping_invalid_reply';
 const REASON_PEER_NO_TRANSPORT = 'peer_no_transport';
-/** JSON-RPC endpoint path — matches the spine's `/api/rpc` (and the forge's). */
-const RPC_PATH = '/api/rpc';
 /** A reply payload that satisfies the Rust `PingResponse` shape. */
 const valid_reply = (nonce) => ({ nonce, protocol_version: 1 });
 /**
@@ -64,19 +63,10 @@ const valid_reply = (nonce) => ({ nonce, protocol_version: 1 });
  * 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;
+    const { setup_test, capabilities } = 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
-        });
-    };
+    /** Open a WS transport on the fixture's session, with an optional responder. */
+    const open_ws = (fixture, on_request) => open_session_ws(options, fixture, { admitted: false, on_request });
     /** A responder that echoes a valid `PingResponse` for every `peer/ping`. */
     const echo_responder = (req) => {
         const nonce = req.params?.nonce ?? 0;
@@ -96,7 +86,7 @@ export const describe_peer_ping_ws_tests = (options) => {
     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);
+            const ws = await open_ws(fixture, 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');
@@ -109,7 +99,7 @@ export const describe_peer_ping_ws_tests = (options) => {
         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);
+            const ws = await open_ws(fixture, () => undefined);
             try {
                 // Short server-side deadline so the negative runs fast.
                 const frame = await ping_raw(ws, 2, { nonce: 1, timeout_ms: 300 });
@@ -124,7 +114,7 @@ export const describe_peer_ping_ws_tests = (options) => {
             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, () => ({
+            const ws = await open_ws(fixture, () => ({
                 result: { nonce: 'not-a-number' }
             }));
             try {
@@ -141,7 +131,7 @@ export const describe_peer_ping_ws_tests = (options) => {
         // and return only the declared shape.
         test_if(capabilities.peer_request, 'a reply with an undeclared key is accepted and the key is dropped', async () => {
             const fixture = await setup_test();
-            const ws = await open_ws(fixture.create_session_headers().cookie, (req) => {
+            const ws = await open_ws(fixture, (req) => {
                 const nonce = req.params?.nonce ?? 0;
                 return { result: { ...valid_reply(nonce), added_later: true } };
             });
@@ -156,7 +146,7 @@ export const describe_peer_ping_ws_tests = (options) => {
         });
         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, () => ({
+            const ws = await open_ws(fixture, () => ({
                 error: { code: -32603, message: 'client refused', data: { reason: 'client_says_no' } }
             }));
             try {
@@ -171,7 +161,7 @@ export const describe_peer_ping_ws_tests = (options) => {
         });
         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);
+            const ws = await open_ws(fixture, 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) });
@@ -189,8 +179,8 @@ export const describe_peer_ping_ws_tests = (options) => {
             // 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);
+            const ws_a = await open_ws(fixture);
+            const ws_b = await open_ws(fixture, echo_responder);
             try {
                 // A invokes peer/ping with a short server-side deadline; don't
                 // await yet — observe the server→client request first.
@@ -217,7 +207,7 @@ export const describe_peer_ping_ws_tests = (options) => {
             const fixture = await setup_test();
             const res = await rpc_call({
                 app: fixture.transport,
-                path: RPC_PATH,
+                path: SPINE_RPC_PATH,
                 method: PEER_PING_METHOD,
                 params: { nonce: 1 },
                 headers: fixture.create_session_headers()

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

@@ -0,0 +1,85 @@
+import '../assert_dev_env.js';
+/** The URL protocols a Postgres connection string carries. */
+export declare const POSTGRES_URL_PROTOCOLS: ReadonlySet<string>;
+/**
+ * Whether `url` parses as a `postgres:` / `postgresql:` URL. `URL.canParse`
+ * alone admits a scheme-less `localhost:5432/db`, which it reads as protocol
+ * `localhost:`.
+ *
+ * @param url - the candidate connection string
+ */
+export declare const is_postgres_url: (url: string) => boolean;
+/**
+ * `database_url` with its database replaced by `database` — how a setup that
+ * spawns a second backend lands on the same server under a database nothing
+ * else uses.
+ *
+ * @param database_url - a `postgres://` URL on the target server
+ * @param database - the database name to put in it
+ * @returns the URL naming `database` on the same server
+ */
+export declare const with_database_name: (database_url: string, database: string) => string;
+/**
+ * The URL `createdb` connects through to create a database on the server
+ * `server_url` names — the same URL with its database replaced by `postgres`.
+ *
+ * @param server_url - a `postgres://` URL on the target server
+ * @returns the URL of that server's `postgres` maintenance database
+ */
+export declare const to_maintenance_database_url: (server_url: string) => string;
+/**
+ * A database URL fit to print: the password, when there is one, replaced —
+ * in the userinfo and in the `password` query parameter `pg` and libpq also
+ * take. The whole URL rather than its host, which is empty for a socket URL
+ * that names its server in the query string.
+ *
+ * @param database_url - a `postgres://` URL
+ * @returns the URL with any password replaced by `REDACTED`
+ */
+export declare const redact_database_url: (database_url: string) => string;
+/**
+ * Whether `createdb`'s stderr is its refusal of a database that already
+ * exists — Postgres's `database "<name>" already exists`, which `createdb`
+ * prints after `database creation failed: ERROR:`.
+ *
+ * @param stderr - what `createdb` wrote to stderr
+ * @param database - the database it was asked to create
+ */
+export declare const is_createdb_already_exists: (stderr: string, database: string) => boolean;
+/** Dependencies of `ensure_database` — the warning a failed `createdb` is reported with. */
+export interface EnsureDatabaseDeps {
+    readonly warn: (message: string) => void;
+}
+/**
+ * Create a Postgres database when it is missing, with `createdb`.
+ *
+ * Which server it lands on depends on `server_url`. Given one, the database is
+ * created on the server that URL names: `createdb` connects through the URL
+ * with its database swapped for the `postgres` maintenance database, so host,
+ * port, role and query parameters all come from the URL, and a password goes
+ * to `createdb` in its environment, never its arguments. Without one,
+ * `createdb` reads the libpq environment (`PGHOST` / `PGPORT` / `PGUSER`).
+ *
+ * Idempotent and never throws: a database that already exists is the quiet
+ * success case (`is_createdb_already_exists`). Any other failure — no
+ * `createdb` on PATH, no server, a role that may not create databases — is
+ * reported through `deps.warn` with `createdb`'s own stderr, and whatever
+ * connects next reports a database that is really missing.
+ *
+ * @param database - the database name
+ * @param server_url - a `postgres://` URL on the server to create it on; its database name is ignored
+ * @param deps - where a failure is reported, `console.warn` by default
+ * @returns whether the database exists now (created, or already there)
+ */
+export declare const ensure_database: (database: string, server_url?: string, deps?: EnsureDatabaseDeps) => boolean;
+/**
+ * Create the database a Postgres URL names, on the server it names, when it
+ * is missing (`ensure_database`). A URL that is not `postgres:` — `memory://`,
+ * `file://` — or that names no database is left alone.
+ *
+ * @param database_url - the URL a backend connects to
+ * @param deps - where a failure is reported, `console.warn` by default
+ * @returns whether the URL named a Postgres database to ensure
+ */
+export declare const ensure_database_for_url: (database_url: string, deps?: EnsureDatabaseDeps) => boolean;
+//# sourceMappingURL=postgres_database.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"postgres_database.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/postgres_database.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAgB9B,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAAyC,CAAC;AAEjG;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,OACyB,CAAC;AAExE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,cAAc,MAAM,EAAE,UAAU,MAAM,KAAG,MAI3E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GAAI,YAAY,MAAM,KAAG,MACtB,CAAC;AAE5C;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,MAK1D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,OACrB,CAAC;AAE1D,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAC3B,UAAU,MAAM,EAChB,aAAa,MAAM,EACnB,OAAM,kBAAiD,KACrD,OAyBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,GACnC,cAAc,MAAM,EACpB,OAAO,kBAAkB,KACvB,OAMF,CAAC"}

package/dist/testing/cross_backend/postgres_database.js

@@ -0,0 +1,140 @@
+import '../assert_dev_env.js';
+/**
+ * Postgres database helpers for cross-backend global setups — creating the
+ * database a backend's URL names, and printing such a URL safely.
+ *
+ * The harness never creates a database by itself: a setup opts in
+ * (`create_cross_backend_global_setup`'s `ensure_databases`, or a call to
+ * `ensure_database_for_url`), so a test role without `CREATEDB` is never
+ * required by default.
+ *
+ * @module
+ */
+import { execFileSync } from 'node:child_process';
+/** The URL protocols a Postgres connection string carries. */
+export const POSTGRES_URL_PROTOCOLS = new Set(['postgres:', 'postgresql:']);
+/**
+ * Whether `url` parses as a `postgres:` / `postgresql:` URL. `URL.canParse`
+ * alone admits a scheme-less `localhost:5432/db`, which it reads as protocol
+ * `localhost:`.
+ *
+ * @param url - the candidate connection string
+ */
+export const is_postgres_url = (url) => URL.canParse(url) && POSTGRES_URL_PROTOCOLS.has(new URL(url).protocol);
+/**
+ * `database_url` with its database replaced by `database` — how a setup that
+ * spawns a second backend lands on the same server under a database nothing
+ * else uses.
+ *
+ * @param database_url - a `postgres://` URL on the target server
+ * @param database - the database name to put in it
+ * @returns the URL naming `database` on the same server
+ */
+export const with_database_name = (database_url, database) => {
+    const url = new URL(database_url);
+    url.pathname = `/${database}`;
+    return url.href;
+};
+/**
+ * The URL `createdb` connects through to create a database on the server
+ * `server_url` names — the same URL with its database replaced by `postgres`.
+ *
+ * @param server_url - a `postgres://` URL on the target server
+ * @returns the URL of that server's `postgres` maintenance database
+ */
+export const to_maintenance_database_url = (server_url) => with_database_name(server_url, 'postgres');
+/**
+ * A database URL fit to print: the password, when there is one, replaced —
+ * in the userinfo and in the `password` query parameter `pg` and libpq also
+ * take. The whole URL rather than its host, which is empty for a socket URL
+ * that names its server in the query string.
+ *
+ * @param database_url - a `postgres://` URL
+ * @returns the URL with any password replaced by `REDACTED`
+ */
+export const redact_database_url = (database_url) => {
+    const url = new URL(database_url);
+    if (url.password)
+        url.password = 'REDACTED';
+    if (url.searchParams.has('password'))
+        url.searchParams.set('password', 'REDACTED');
+    return url.href;
+};
+/**
+ * Whether `createdb`'s stderr is its refusal of a database that already
+ * exists — Postgres's `database "<name>" already exists`, which `createdb`
+ * prints after `database creation failed: ERROR:`.
+ *
+ * @param stderr - what `createdb` wrote to stderr
+ * @param database - the database it was asked to create
+ */
+export const is_createdb_already_exists = (stderr, database) => stderr.includes(`database "${database}" already exists`);
+const default_ensure_database_deps = {
+    warn: (message) => console.warn(message)
+};
+/**
+ * Create a Postgres database when it is missing, with `createdb`.
+ *
+ * Which server it lands on depends on `server_url`. Given one, the database is
+ * created on the server that URL names: `createdb` connects through the URL
+ * with its database swapped for the `postgres` maintenance database, so host,
+ * port, role and query parameters all come from the URL, and a password goes
+ * to `createdb` in its environment, never its arguments. Without one,
+ * `createdb` reads the libpq environment (`PGHOST` / `PGPORT` / `PGUSER`).
+ *
+ * Idempotent and never throws: a database that already exists is the quiet
+ * success case (`is_createdb_already_exists`). Any other failure — no
+ * `createdb` on PATH, no server, a role that may not create databases — is
+ * reported through `deps.warn` with `createdb`'s own stderr, and whatever
+ * connects next reports a database that is really missing.
+ *
+ * @param database - the database name
+ * @param server_url - a `postgres://` URL on the server to create it on; its database name is ignored
+ * @param deps - where a failure is reported, `console.warn` by default
+ * @returns whether the database exists now (created, or already there)
+ */
+export const ensure_database = (database, server_url, deps = default_ensure_database_deps) => {
+    const args = [database];
+    const env = { ...process.env };
+    if (server_url !== undefined) {
+        const url = new URL(to_maintenance_database_url(server_url));
+        // any local user can read the process list
+        const password = url.searchParams.get('password') ?? decodeURIComponent(url.password);
+        if (password)
+            env.PGPASSWORD = password;
+        url.password = '';
+        url.searchParams.delete('password');
+        args.unshift(`--maintenance-db=${url.href}`);
+    }
+    try {
+        execFileSync('createdb', args, { stdio: ['ignore', 'ignore', 'pipe'], env, encoding: 'utf-8' });
+        return true;
+    }
+    catch (error) {
+        const failure = error;
+        const stderr = (failure.stderr ?? '').trim();
+        if (is_createdb_already_exists(stderr, database))
+            return true;
+        deps.warn(`ensure_database: createdb ${database} failed — ` +
+            (failure.code === 'ENOENT' ? 'createdb is not on PATH' : stderr || failure.message));
+        return false;
+    }
+};
+/**
+ * Create the database a Postgres URL names, on the server it names, when it
+ * is missing (`ensure_database`). A URL that is not `postgres:` — `memory://`,
+ * `file://` — or that names no database is left alone.
+ *
+ * @param database_url - the URL a backend connects to
+ * @param deps - where a failure is reported, `console.warn` by default
+ * @returns whether the URL named a Postgres database to ensure
+ */
+export const ensure_database_for_url = (database_url, deps) => {
+    if (!is_postgres_url(database_url))
+        return false;
+    const database = decodeURIComponent(new URL(database_url).pathname.slice(1));
+    if (!database)
+        return false;
+    ensure_database(database, database_url, deps);
+    return true;
+};