@fuzdev/fuz_app 0.146.1 → 0.148.0

package/dist/testing/cross_backend/rust_spine_consumer_surface.js

@@ -0,0 +1,113 @@
+import '../assert_dev_env.js';
+import { is_protocol_action_method } from '../../actions/action_codegen.js';
+import { account_status_route_shape, create_account_route_shapes } from '../../auth/account_route_schema.js';
+import { create_signup_route_shape } from '../../auth/signup_route_schema.js';
+import { create_standard_rpc_actions } from '../../auth/standard_rpc_actions.js';
+import { create_health_route_spec } from '../../http/common_routes.js';
+import { prefix_route_specs } from '../../http/route_spec.js';
+import { create_test_app_surface_spec, stub_handler, stub_mw } from '../stubs.js';
+import { SPINE_ACCOUNT_PATH_PREFIX, SPINE_RPC_PATH } from './spine_surface_constants.js';
+/**
+ * The routes `fuz_auth::account_router` mounts, relative to `/api/account`. An
+ * allowlist rather than every account route shape: `/verify` is a TS-only
+ * route the Rust router doesn't serve, so declaring it would have the suites
+ * probe a 404. A shape fuz_app renames or drops fails the surface build; one
+ * it adds stays off the surface until the Rust router mounts it and this list
+ * names it.
+ */
+export const ACCOUNT_ROUTER_PATHS = ['/status', '/login', '/logout', '/password'];
+/** Surface generation never invokes handlers — see the module doc. */
+const noop_action_handler = (async () => undefined);
+const to_route_spec = (shape) => ({
+    ...shape,
+    handler: stub_handler
+});
+/**
+ * The RPC endpoints a Rust spine consumer mounts: the standard admin /
+ * role-grant-offer / account actions, the extra families, then the domain
+ * specs — what `describe_spine_cross_suites` takes as `rpc_endpoints`.
+ *
+ * @param options - the consumer's action specs, extras and roles
+ * @returns the endpoints, as a factory of the stub context
+ * @throws Error when an `exclude_methods` entry names no domain spec
+ */
+export const create_rust_spine_consumer_rpc_endpoints = (options) => {
+    const { domain_action_specs, extra_rpc_actions, roles, exclude_methods = [], rpc_path = SPINE_RPC_PATH } = options;
+    const excluded = new Set(exclude_methods);
+    for (const method of excluded) {
+        if (!domain_action_specs.some((spec) => spec.method === method)) {
+            throw new Error(`create_rust_spine_consumer_rpc_endpoints: exclude_methods names '${method}', ` +
+                'which is not among the domain action specs');
+        }
+    }
+    const domain_actions = domain_action_specs
+        .filter((spec) => spec.kind === 'request_response')
+        .filter((spec) => !is_protocol_action_method(spec.method) && !excluded.has(spec.method))
+        .map((spec) => ({ spec, handler: noop_action_handler }));
+    return (ctx) => [
+        {
+            path: rpc_path,
+            actions: [
+                ...create_standard_rpc_actions(ctx.deps, roles ? { roles } : {}),
+                ...(extra_rpc_actions?.(ctx) ?? []),
+                ...domain_actions
+            ]
+        }
+    ];
+};
+/**
+ * The spine routes a Rust spine consumer serves, outside the RPC endpoint:
+ * `/health`, the `ACCOUNT_ROUTER_PATHS` under `/api/account`, and signup
+ * beside them (bootstrap is added by `create_test_app_surface_spec`).
+ */
+const create_spine_consumer_route_specs = (ctx) => {
+    const shapes = [
+        account_status_route_shape,
+        ...create_account_route_shapes({
+            login_account_rate_limited: ctx.login_account_rate_limiter !== null
+        })
+    ];
+    const account_router_shapes = ACCOUNT_ROUTER_PATHS.map((path) => {
+        const shape = shapes.find((candidate) => candidate.path === path);
+        if (!shape)
+            throw new Error(`fuz_app's account route shapes have no '${path}'`);
+        return shape;
+    });
+    return [
+        create_health_route_spec(),
+        ...prefix_route_specs(SPINE_ACCOUNT_PATH_PREFIX, [
+            ...account_router_shapes,
+            create_signup_route_shape({
+                signup_account_rate_limited: ctx.signup_account_rate_limiter !== null
+            })
+        ].map(to_route_spec))
+    ];
+};
+/**
+ * Build the declared surface of a Rust spine consumer for its cross suites,
+ * on `create_test_app_surface_spec`: the spine routes (health, the account
+ * router's paths, signup, and bootstrap as a `surface_only` shape), the RPC
+ * endpoint from `create_rust_spine_consumer_rpc_endpoints`, the daemon-token
+ * layer every consumer test binary wires, and — with `host_gate` — the
+ * `host_validation` layer at the head of the middleware list.
+ *
+ * @param options - the consumer's session config, action specs, extras and roles
+ * @returns the surface spec, for `describe_spine_cross_suites`'s `surface_source`
+ * @throws Error when an account route shape the Rust router mounts is missing,
+ *   or an `exclude_methods` entry names no domain spec
+ */
+export const create_rust_spine_consumer_surface_spec = (options) => create_test_app_surface_spec({
+    session_options: options.session_options,
+    create_route_specs: create_spine_consumer_route_specs,
+    rpc_endpoints: create_rust_spine_consumer_rpc_endpoints(options),
+    // the binaries mount `bootstrap_router`; `surface_only` declares its shape
+    bootstrap: { mode: 'surface_only' },
+    // consumer test binaries wire a daemon-token state (production ones don't)
+    daemon_token: true,
+    transform_middleware: options.host_gate
+        ? (specs) => [
+            { name: 'host_validation', path: '*', handler: stub_mw },
+            ...specs
+        ]
+        : undefined
+});

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

@@ -18,6 +18,8 @@ export declare const RUST_SPINE_STUB_DATABASE_URL_ENV = "FUZ_TESTING_RUST_SPINE_
 export declare const RUST_SPINE_STUB_EXPECTED_SCHEMA_PATH_ENV = "FUZ_RUST_SPINE_STUB_EXPECTED_SCHEMA_PATH";
 /** Default listening port — slots beside zzz's 1175/1176; matches the binary's `DEFAULT_PORT`. */
 export declare const RUST_SPINE_STUB_DEFAULT_PORT = 1177;
+/** The preset's default backend name — its spawn label and temp directory. */
+export declare const RUST_SPINE_STUB_DEFAULT_NAME = "spine_stub";
 /** Default Postgres database — real PG (PGlite isn't reachable from `tokio-postgres`). */
 export declare const RUST_SPINE_STUB_DEFAULT_DATABASE_URL = "postgres://localhost/fuz_app_test_rust_spine_stub";
 export interface SpineStubBackendConfigOptions {
@@ -28,6 +30,14 @@ export interface SpineStubBackendConfigOptions {
      * then `RUST_SPINE_STUB_DEFAULT_DATABASE_URL`.
      */
     readonly database_url?: string;
+    /**
+     * Backend name — labels the spawn in errors and logs, and names its
+     * directory under `os.tmpdir()` (`build_test_backend_paths`), which holds
+     * the bootstrap token, the daemon token and the fact store. Default
+     * `RUST_SPINE_STUB_DEFAULT_NAME`. Give each stub spawned alongside another its own name, so
+     * those files don't collide.
+     */
+    readonly name?: string;
     /**
      * Prebuilt binary path. Overrides the `FUZ_TESTING_RUST_SPINE_STUB_BIN` env
      * var. When neither is set the preset throws.

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

@@ -1 +1 @@
-{"version":3,"file":"rust_spine_stub_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/rust_spine_stub_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA0C9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAYzD,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,oCAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,6CAA6C,CAAC;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,6CAA6C,CAAC;AAuBnG,kGAAkG;AAClG,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,sDACG,CAAC;AAErD,MAAM,WAAW,6BAA6B;IAC7C,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,MAAM,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,GAC1C,UAAS,6BAAkC,KACzC,aAmDF,CAAC"}
+{"version":3,"file":"rust_spine_stub_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/rust_spine_stub_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAwC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAazD,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,oCAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,6CAA6C,CAAC;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,6CAA6C,CAAC;AAiCnG,kGAAkG;AAClG,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,sDACG,CAAC;AAErD,MAAM,WAAW,6BAA6B;IAC7C,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,MAAM,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,GAC1C,UAAS,6BAAkC,KACzC,aAmDF,CAAC"}

package/dist/testing/cross_backend/rust_spine_stub_backend_config.js

@@ -13,17 +13,15 @@ import '../assert_dev_env.js';
  * path in. `FUZ_TESTING_RUST_SPINE_STUB_BIN` (or the `binary_path` option) must
  * point at a prebuilt binary; the preset throws a clear error when neither
  * is set rather than guessing. Build once with
- * `cargo build -p testing_spine_stub --release` and point the env var at
- * the resulting `target/release/testing_spine_stub`; operators / CI cache
- * the binary across runs for fast spawns.
+ * `cargo build -p testing_spine_stub --profile cross-test` (the workspace's
+ * non-LTO test profile; `--release` works too, slower to rebuild) and point
+ * the env var at the resulting `target/cross-test/testing_spine_stub`;
+ * operators / CI cache the binary across runs for fast spawns.
  *
  * **Operator setup** — the target Postgres database must exist before the
- * harness runs (the harness never issues `CREATE DATABASE`, to avoid
- * forcing a `CREATEDB` grant on the test role):
- *
- * ```bash
- * createdb fuz_app_test_rust_spine_stub 2>/dev/null || true
- * ```
+ * stub boots. The harness creates it only when a setup asks
+ * (`ensure_database_for_url`, or `create_cross_backend_global_setup`'s
+ * `ensure_databases`), so a test role needs no `CREATEDB` grant otherwise.
  *
  * `FUZ_TESTING_RUST_SPINE_STUB_DATABASE_URL` points the stub at another
  * server (e.g. a scratch cluster on a spare port).
@@ -58,7 +56,11 @@ export const RUST_SPINE_STUB_DATABASE_URL_ENV = 'FUZ_TESTING_RUST_SPINE_STUB_DAT
 export const RUST_SPINE_STUB_EXPECTED_SCHEMA_PATH_ENV = 'FUZ_RUST_SPINE_STUB_EXPECTED_SCHEMA_PATH';
 /**
  * Capabilities for the Rust `testing_spine_stub` — `rust_default_capabilities`
- * plus `sse` (the stub serves `GET /api/admin/audit/stream` over the spine
+ * with every `MountFlag` stated, all `true`: `ws` (it mounts `/api/ws`), `peer_request` (its registry carries
+ * `peer/ping` on both transports), `cell_crud` + `cell_relations` (it mounts the
+ * full cell surface over the `fuz_cell` namespace), `fact_serving` (the
+ * cell-gated serve route, the `fuz_facts` namespace and `_testing_put_fact`),
+ * `fact_serving_admin_hash` (the admin bare-hash route), `sse` (the stub serves `GET /api/admin/audit/stream` over the spine
  * `fuz_realtime::SseRegistry` + audit listener), `ready` (it live-mounts
  * `/ready` over the env-supplied fixture path), `ws_account_actions` (it
  * serves one action registry on `/api/rpc` and `/api/ws`), `cell_gated_create`
@@ -70,7 +72,13 @@ export const RUST_SPINE_STUB_EXPECTED_SCHEMA_PATH_ENV = 'FUZ_RUST_SPINE_STUB_EXP
  */
 const rust_spine_stub_capabilities = Object.freeze({
     ...rust_default_capabilities,
+    ws: true,
+    peer_request: true,
     sse: true,
+    cell_crud: true,
+    cell_relations: true,
+    fact_serving: true,
+    fact_serving_admin_hash: true,
     ready: true,
     ws_account_actions: true,
     cell_gated_create: true,
@@ -78,6 +86,8 @@ const rust_spine_stub_capabilities = Object.freeze({
 });
 /** Default listening port — slots beside zzz's 1175/1176; matches the binary's `DEFAULT_PORT`. */
 export const RUST_SPINE_STUB_DEFAULT_PORT = 1177;
+/** The preset's default backend name — its spawn label and temp directory. */
+export const RUST_SPINE_STUB_DEFAULT_NAME = 'spine_stub';
 /** Default Postgres database — real PG (PGlite isn't reachable from `tokio-postgres`). */
 export const RUST_SPINE_STUB_DEFAULT_DATABASE_URL = 'postgres://localhost/fuz_app_test_rust_spine_stub';
 /**
@@ -93,13 +103,12 @@ export const RUST_SPINE_STUB_DEFAULT_DATABASE_URL = 'postgres://localhost/fuz_ap
  */
 export const rust_spine_stub_backend_config = (options = {}) => {
     const { port = RUST_SPINE_STUB_DEFAULT_PORT, database_url = process.env[RUST_SPINE_STUB_DATABASE_URL_ENV] ||
-        RUST_SPINE_STUB_DEFAULT_DATABASE_URL, binary_path = process.env[RUST_SPINE_STUB_BIN_ENV], enable_login_rate_limit, trusted_proxies } = options;
+        RUST_SPINE_STUB_DEFAULT_DATABASE_URL, binary_path = process.env[RUST_SPINE_STUB_BIN_ENV], enable_login_rate_limit, trusted_proxies, name = RUST_SPINE_STUB_DEFAULT_NAME } = options;
     if (!binary_path) {
         throw new Error(`rust_spine_stub_backend_config: no binary path — set ${RUST_SPINE_STUB_BIN_ENV} to a prebuilt ` +
-            '`testing_spine_stub` binary (build it with `cargo build -p testing_spine_stub --release`) ' +
+            '`testing_spine_stub` binary (build it with `cargo build -p testing_spine_stub --profile cross-test`) ' +
             'or pass `binary_path`.');
     }
-    const name = 'spine_stub';
     const paths = build_test_backend_paths(name);
     return make_default_rust_backend_config({
         name,
@@ -113,12 +122,12 @@ export const rust_spine_stub_backend_config = (options = {}) => {
         port_env_var: 'FUZ_RUST_SPINE_STUB_PORT',
         rust_log: 'info,testing_spine_stub=info',
         paths,
+        // The binary writes its daemon-token JSON to
+        // `{FUZ_RUST_SPINE_STUB_DIR}/run/daemon_token`; the builder anchors the
+        // dir to `paths.root`, which makes that `paths.daemon_token_path`, the
+        // file `spawn_backend` reads after the health probe.
+        daemon_token_dir_env: 'FUZ_RUST_SPINE_STUB_DIR',
         extra_env: {
-            // The binary writes its daemon-token JSON to
-            // `{FUZ_RUST_SPINE_STUB_DIR}/run/daemon_token`; anchoring the dir to
-            // `paths.root` makes that equal `paths.daemon_token_path`, which
-            // `spawn_backend` reads after the health probe.
-            FUZ_RUST_SPINE_STUB_DIR: paths.root,
             // Absolute path to the committed spine `expected_schema.json` — the
             // stub's `/ready` gate introspects the live DB against it. The SAME
             // file the TS spine reads, so the two backends share one cross-impl

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

@@ -1,5 +1,6 @@
 import '../assert_dev_env.js';
 import type { SetupTest } from './setup.js';
+import type { WsEndpointTarget } from './ws_endpoint.js';
 /** Options for the session-cap parity suite. */
 export interface SessionCapCrossTestOptions {
     /** Per-test fixture producer (cross-process only — see the module doc). */
@@ -19,14 +20,14 @@ export interface SessionCapCrossTestOptions {
      * session's socket is closed. Pass it when the backend has a WS transport
      * (`capabilities.ws`); omitted, that case is skipped.
      */
-    readonly ws?: {
-        /** Base URL the backend is reachable at (e.g. `http://localhost:1178`). */
-        readonly base_url: string;
-        /** WebSocket endpoint path on the backend (e.g. `/api/ws`). */
-        readonly ws_path: string;
-        /** Origin for the upgrade. Defaults to `base_url`. */
-        readonly origin?: string;
-    };
+    readonly ws?: WsEndpointTarget;
+    /**
+     * The roles the account whose socket the `ws` case watches is created with, for a
+     * backend whose WS upgrade requires a role (an admin-gated `/api/ws`
+     * refuses a roleless account's upgrade). Each must be admin-grantable — the
+     * fixture offers it. Default none.
+     */
+    readonly ws_account_roles?: ReadonlyArray<string>;
 }
 export declare const describe_session_cap_cross_tests: (options: SessionCapCrossTestOptions) => void;
 //# sourceMappingURL=session_cap.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"session_cap.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/session_cap.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA0D9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,gDAAgD;AAChD,MAAM,WAAW,0BAA0B;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE;QACb,2EAA2E;QAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,+DAA+D;QAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,sDAAsD;QACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACF;AAED,eAAO,MAAM,gCAAgC,GAAI,SAAS,0BAA0B,KAAG,IA4FtF,CAAC"}
+{"version":3,"file":"session_cap.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/session_cap.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA0D9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,gDAAgD;AAChD,MAAM,WAAW,0BAA0B;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAClD;AAED,eAAO,MAAM,gCAAgC,GAAI,SAAS,0BAA0B,KAAG,IAgGtF,CAAC"}

package/dist/testing/cross_backend/session_cap.js

@@ -52,11 +52,12 @@ import { DEFAULT_MAX_SESSIONS } from '../../auth/account_route_schema.js';
 import { DEFAULT_TEST_PASSWORD } from '../test_credentials.js';
 import { create_ws_transport } from '../transports/ws_transport.js';
 import { test_if } from './capabilities.js';
+import { SPINE_ACCOUNT_LOGIN_PATH, SPINE_ACCOUNT_STATUS_PATH } from './spine_surface_constants.js';
 export const describe_session_cap_cross_tests = (options) => {
-    const { setup_test, ws } = options;
+    const { setup_test, ws, ws_account_roles = [] } = options;
     const max_sessions = options.max_sessions ?? DEFAULT_MAX_SESSIONS;
-    const login_path = options.login_path ?? '/api/account/login';
-    const status_path = options.status_path ?? '/api/account/status';
+    const login_path = options.login_path ?? SPINE_ACCOUNT_LOGIN_PATH;
+    const status_path = options.status_path ?? SPINE_ACCOUNT_STATUS_PATH;
     // Fresh-keeper-per-test wipes the DB between tests, so a literal username
     // never collides (see `setup.ts`).
     const username = 'session_cap_user';
@@ -100,7 +101,11 @@ export const describe_session_cap_cross_tests = (options) => {
         // held before it (`create_account` seeds one on some cradles).
         test_if(ws !== undefined, 'a session the cap evicts has its open socket closed', async () => {
             const fixture = await setup_test();
-            await fixture.create_account({ username, password_value: DEFAULT_TEST_PASSWORD });
+            await fixture.create_account({
+                username,
+                password_value: DEFAULT_TEST_PASSWORD,
+                roles: [...ws_account_roles]
+            });
             const victim = await login(fixture, 'the login whose socket is watched');
             const client = await create_ws_transport({
                 base_url: ws.base_url,

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

@@ -0,0 +1,19 @@
+import '../assert_dev_env.js';
+import type { SetupTest } from './setup.js';
+/** Options for the session cookie codec parity suite. */
+export interface SessionCookieCodecCrossTestOptions {
+    /** Per-test fixture producer (cross-process). */
+    readonly setup_test: SetupTest;
+    /** The spine's session cookie name (`handle.config.cookie_name`). */
+    readonly cookie_name: string;
+    /**
+     * The backend's `SECRET_FUZ_COOKIE_KEYS` value
+     * (`handle.config.env.SECRET_FUZ_COOKIE_KEYS`) — the suite signs with its
+     * primary key.
+     */
+    readonly cookie_keys: string;
+    /** JSON-RPC endpoint path. Default `SPINE_RPC_PATH`. */
+    readonly rpc_path?: string;
+}
+export declare const describe_session_cookie_codec_cross_tests: (options: SessionCookieCodecCrossTestOptions) => void;
+//# sourceMappingURL=session_cookie_codec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session_cookie_codec.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/session_cookie_codec.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAkC9B,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAGzD,yDAAyD;AACzD,MAAM,WAAW,kCAAkC;IAClD,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AA2BD,eAAO,MAAM,yCAAyC,GACrD,SAAS,kCAAkC,KACzC,IAsGF,CAAC"}

package/dist/testing/cross_backend/session_cookie_codec.js

@@ -0,0 +1,128 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-backend parity suite for the **signed session cookie codec** over real
+ * HTTP: which spellings of a correctly signed cookie each spine accepts.
+ *
+ * The cookie is `${token}:${expires_at}.${signature}`, the signature the padded
+ * standard base64 of an HMAC-SHA256 MAC. Both spines must accept exactly one
+ * spelling of a given signed payload, or a cookie that one spine refuses would
+ * authenticate on the other. The suite holds the test keyring, so it signs
+ * payloads itself and sends variants a lenient decoder would take:
+ *
+ * - **signature spelling** — the last data character bumped so the trailing
+ *   bits are non-zero (`atob` decodes the same MAC), and the `=` padding
+ *   dropped. Both must be refused.
+ * - **`expires_at` spelling** — `+N`, ` N`, `N.0`, and an all-digit value past
+ *   `u64::MAX` (the Rust spine parses it as `u64`), each signed with the real
+ *   key. All must be refused. A leading-zero `0N` reads as `N` on both, so it
+ *   still authenticates — the bound is on the value, not the digit count.
+ *
+ * The positive controls run first: re-signing the keeper cookie's payload
+ * reproduces the cookie byte for byte (the suite's keyring is the backend's),
+ * and that cookie authenticates. Authentication is probed with the
+ * `account_verify` RPC action. The per-impl unit tests cover each codec
+ * directly; this suite is what catches the two drifting apart.
+ *
+ * @module
+ */
+import { describe, test, assert } from 'vitest';
+import { create_keyring } from '../../auth/keyring.js';
+import { ERROR_AUTHENTICATION_REQUIRED } from '../../http/error_schemas.js';
+import { cross_rpc_call, error_reason } from './cross_rpc.js';
+import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+/** The base64 alphabet, in index order. */
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** `u64::MAX + 1`, the smallest all-digit `expires_at` the Rust spine cannot parse. */
+const U64_MAX_PLUS_ONE = '18446744073709551616';
+/** Split a signed cookie value on its last `.` into payload and signature. */
+const split_signed = (signed) => {
+    const dot = signed.lastIndexOf('.');
+    assert.ok(dot !== -1, `signed cookie value has no '.' separator: ${signed}`);
+    return { payload: signed.slice(0, dot), signature: signed.slice(dot + 1) };
+};
+/**
+ * Bump the signature's last data character (index 42, which carries the MAC's
+ * final 4 bits and 2 zero padding bits) to the next base64 character. That sets
+ * a padding bit, which `atob` ignores, so the decoded MAC is unchanged.
+ */
+const bump_trailing_bits = (signature) => {
+    const last_data = signature[42];
+    const index = BASE64_ALPHABET.indexOf(last_data);
+    assert.ok(index !== -1 && index % 4 === 0, `unexpected final signature character: ${last_data}`);
+    return signature.slice(0, 42) + BASE64_ALPHABET[index + 1] + signature.slice(43);
+};
+export const describe_session_cookie_codec_cross_tests = (options) => {
+    const { setup_test, cookie_name, cookie_keys } = options;
+    const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
+    const keyring_result = create_keyring(cookie_keys);
+    if (!keyring_result.ok) {
+        throw new Error(`cookie_keys is not a valid keyring: ${keyring_result.errors.join('; ')}`);
+    }
+    const keyring = keyring_result.keyring;
+    /** The keeper's signed cookie value, with its verified `token` and `expires_at`. */
+    const keeper_cookie = async (fixture) => {
+        const header = fixture.create_session_headers().cookie;
+        assert.ok(header, 'the keeper session headers carry a cookie');
+        const prefix = `${cookie_name}=`;
+        assert.ok(header.startsWith(prefix), `the keeper cookie is named '${cookie_name}'`);
+        const signed = header.slice(prefix.length);
+        const verified = await keyring.verify(signed);
+        assert.ok(verified, 'the keeper cookie verifies under cookie_keys');
+        const sep = verified.value.lastIndexOf(':');
+        assert.ok(sep !== -1, 'the keeper cookie payload is `token:expires_at`');
+        return {
+            signed,
+            token: verified.value.slice(0, sep),
+            expires_at: verified.value.slice(sep + 1)
+        };
+    };
+    const verify_with = (fixture, signed) => cross_rpc_call(fixture.fresh_transport(), rpc_path, 'account_verify', undefined, {
+        cookie: `${cookie_name}=${signed}`
+    });
+    const assert_unauthenticated = async (fixture, signed, label) => {
+        const result = await verify_with(fixture, signed);
+        assert.strictEqual(result.ok, false, `${label}: must not authenticate`);
+        assert.strictEqual(error_reason(result), ERROR_AUTHENTICATION_REQUIRED, label);
+    };
+    describe('session cookie codec parity', () => {
+        test('controls: re-signing the keeper payload reproduces its cookie, which authenticates', async () => {
+            const fixture = await setup_test();
+            const { signed, token, expires_at } = await keeper_cookie(fixture);
+            assert.strictEqual(await keyring.sign(`${token}:${expires_at}`), signed, 'the suite keyring signs as the backend does');
+            const result = await verify_with(fixture, signed);
+            assert.ok(result.ok, `the keeper cookie authenticates: ${JSON.stringify(result.error)}`);
+        });
+        test('a signature with non-zero trailing bits is refused', async () => {
+            const fixture = await setup_test();
+            const { payload, signature } = split_signed((await keeper_cookie(fixture)).signed);
+            await assert_unauthenticated(fixture, `${payload}.${bump_trailing_bits(signature)}`, 'non-zero trailing bits');
+        });
+        test('an unpadded signature is refused', async () => {
+            const fixture = await setup_test();
+            const { payload, signature } = split_signed((await keeper_cookie(fixture)).signed);
+            assert.ok(signature.endsWith('='), 'the canonical signature is padded');
+            await assert_unauthenticated(fixture, `${payload}.${signature.slice(0, -1)}`, 'unpadded');
+        });
+        test('a non-canonical expires_at is refused even when signed', async () => {
+            const fixture = await setup_test();
+            const { token, expires_at } = await keeper_cookie(fixture);
+            const variants = [
+                ['plus sign', `+${expires_at}`],
+                ['leading space', ` ${expires_at}`],
+                ['decimal', `${expires_at}.0`],
+                ['past u64::MAX', U64_MAX_PLUS_ONE]
+            ];
+            for (const [label, value] of variants) {
+                const signed = await keyring.sign(`${token}:${value}`);
+                await assert_unauthenticated(fixture, signed, `expires_at ${label} (${JSON.stringify(value)})`);
+            }
+        });
+        test('a leading-zero expires_at reads as its value and authenticates', async () => {
+            const fixture = await setup_test();
+            const { token, expires_at } = await keeper_cookie(fixture);
+            const signed = await keyring.sign(`${token}:0${expires_at}`);
+            const result = await verify_with(fixture, signed);
+            assert.ok(result.ok, `a leading zero authenticates: ${JSON.stringify(result.error)}`);
+        });
+    });
+};

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

@@ -26,14 +26,6 @@ export interface CreateTestAccountOptions {
      */
     readonly email?: string;
 }
-/**
- * Shape returned by `TestFixture.create_account`. Aliased to the
- * existing `TestAccount` interface from `testing/app_server.ts` — same shape,
- * stable name on the cross-backend testing surface so call sites read
- * `fixture.create_account(...)` returning `TestAccountFixture` without
- * crossing module boundaries.
- */
-export type TestAccountFixture = TestAccount;
 /**
  * Spec for a bootstrap-time secondary account seeded alongside the
  * keeper by `_testing_reset` (cross-process) or `create_test_app`
@@ -52,32 +44,21 @@ export interface ExtraAccountSpec {
     readonly password_value?: string;
     readonly roles: ReadonlyArray<string>;
 }
-/** Bootstrap-time-seeded secondary account exposed on the fixture. */
-export interface ExtraAccountFixture {
-    readonly account: {
-        readonly id: Uuid;
-        readonly username: string;
-    };
-    readonly actor: {
-        readonly id: Uuid;
-    };
-    readonly api_token: string;
-    readonly session_cookie: string;
-    readonly create_session_headers: (extra?: Record<string, string>) => Record<string, string>;
-    readonly create_bearer_headers: (extra?: Record<string, string>) => Record<string, string>;
-}
 /**
- * Build an `ExtraAccountFixture` from a seeded `{account, actor,
- * api_token, session_cookie}` bundle and the session cookie name.
+ * Build a `TestAccount` from a seeded `{account, actor, api_token,
+ * session_cookie}` bundle and the session cookie name — the header builders
+ * close over its credentials.
+ *
+ * Every fixture path that hands out a secondary account builds it here: the
+ * bootstrap-time `extra_accounts` (in-process via
+ * `create_test_account_with_credentials`, cross-process from the
+ * `_testing_reset` output) and the cross-process `fixture.create_account`.
  *
- * Same shape produced by either path that seeds bootstrap-time
- * secondaries: in-process via `create_test_account_with_credentials`
- * against the live backend's DB, or cross-process via the
- * `_testing_reset` RPC's `extra_accounts` output. Both call this
- * helper so the fixture-side header builders + field plumbing stays
- * in one place.
+ * @param seeded - the account's identity and credentials
+ * @param cookie_name - the backend's session cookie name
+ * @returns the account with its header builders
  */
-export declare const build_extra_account_fixture: (seeded: {
+export declare const to_test_account: (seeded: {
     account: {
         id: Uuid;
         username: string;
@@ -87,10 +68,18 @@ export declare const build_extra_account_fixture: (seeded: {
     };
     api_token: string;
     session_cookie: string;
-}, cookie_name: string) => ExtraAccountFixture;
+}, cookie_name: string) => TestAccount;
 /**
- * Fields shared by every `TestFixture` regardless of transport. The
- * discriminated union below adds in-process-only fields conditionally.
+ * The per-test bundle returned by `SetupTest`. Every Tier 1 suite body
+ * reads exclusively from this shape — no `test_app.backend.*` reads remain
+ * in the suite bodies.
+ *
+ * Transport-agnostic: in-process and cross-process producers return the
+ * same shape. Behaviors that once needed raw backend access (keyring for
+ * forging cookies) are reached through wire-shaped seams instead —
+ * `mint_expired_session()` mints over the `_testing_mint_session` channel
+ * cross-process and directly in-process, so suite bodies never branch on
+ * the transport.
  *
  * **Keeper ≠ admin.** `fixture.account` / `fixture.actor` refer to the
  * **fresh keeper** seeded per test. The keeper account holds
@@ -102,7 +91,7 @@ export declare const build_extra_account_fixture: (seeded: {
  * via `extra_accounts: [{username, roles: [ROLE_KEEPER]}]` and read it
  * from `fixture.extra_accounts[username]`.
  */
-export interface TestFixtureBase {
+export interface TestFixture {
     /**
      * Transport for this test's HTTP requests. Typed as `FetchTransport`
      * so cross-process tests can call `transport.cookies()` for WS upgrade
@@ -159,14 +148,14 @@ export interface TestFixtureBase {
      * cross-process: goes through the consumer-supplied DB-admin
      * channel.
      */
-    readonly create_account: (options?: CreateTestAccountOptions) => Promise<TestAccountFixture>;
+    readonly create_account: (options?: CreateTestAccountOptions) => Promise<TestAccount>;
     /**
      * Bootstrap-time-seeded secondaries, keyed by their declared
      * `username`. Populated from the `extra_accounts` option passed to
      * `default_in_process_setup` / `default_cross_process_setup`. Empty
      * for suites that don't declare any.
      */
-    readonly extra_accounts: Readonly<Record<string, ExtraAccountFixture>>;
+    readonly extra_accounts: Readonly<Record<string, TestAccount>>;
     /**
      * Additional actors seeded on the **keeper** account (beyond its single
      * bootstrap `actor`), in declaration order. Populated from the
@@ -192,23 +181,18 @@ export interface TestFixtureBase {
      * RPC over the keeper's daemon-token channel (the driver has no keyring).
      */
     readonly mint_expired_session: () => Promise<string>;
+    /**
+     * Whether the suites' audit reads refuse metadata keys an event type
+     * doesn't declare — the setup's `reject_unknown_audit_metadata_keys`.
+     * `list_audit_events` and the admin suite's readers pass it to
+     * `assert_audit_event_metadata`.
+     */
+    readonly reject_unknown_audit_metadata_keys?: boolean;
 }
 /**
- * The per-test bundle returned by `SetupTest`. Every Tier 1 suite body
- * reads exclusively from this shape — no `test_app.backend.*` reads remain
- * in the suite bodies.
- *
- * Transport-agnostic: in-process and cross-process producers return the
- * same shape. Behaviors that once needed raw backend access (keyring for
- * forging cookies) are reached through wire-shaped seams instead —
- * `mint_expired_session()` mints over the `_testing_mint_session` channel
- * cross-process and directly in-process, so suite bodies never branch on
- * the transport.
- */
-export type TestFixture = TestFixtureBase;
-/**
- * Per-test fixture-producing function. Invoked once inside every
- * `test()` body. The implementation captures factory inputs (in-process)
+ * Fixture-producing function. Invoked once inside every `test()` body by
+ * default; a suite whose cases share no state past the reset may call it once
+ * in `beforeAll` instead. The implementation captures factory inputs (in-process)
  * or a long-running backend handle (cross-process) and creates
  * a fresh per-test bundle on each call.
  */
@@ -244,7 +228,7 @@ export interface CapabilityGatedCrossSuiteOptions extends CrossSuiteOptions {
 /**
  * `CrossSuiteOptions` plus the RPC endpoint path the suite dispatches
  * against — the shape every JSON-RPC-driven imperative suite takes (cell
- * verbs, origin, body-size, actor lookup/search, account lifecycle, app
+ * verbs, origin, body-size, actor lookup, account lifecycle, app
  * settings, testing backdoor). Suites alias this under a self-documenting
  * per-suite name (e.g. `OriginCrossTestOptions = RpcPathCrossSuiteOptions`).
  */
@@ -396,9 +380,27 @@ export interface CrossProcessSetupOptions {
      * single bootstrap actor — exposed on `fixture.extra_actors`. Declare
      * to put the keeper into a multi-actor state so the `actor_required` /
      * explicit-`acting` branches are reachable cross-process. See
-     * `TestFixtureBase.extra_actors`.
+     * `TestFixture.extra_actors`.
      */
     readonly extra_actors?: ReadonlyArray<string>;
+    /**
+     * Hold every audit row the fixture's readers parse to a closed world:
+     * metadata keys its event type doesn't declare are refused, not just
+     * mistyped or missing ones (`assert_audit_event_metadata`'s
+     * `reject_unknown_keys`). Off by default, since the builtin schemas are
+     * open for consumer-added fields; a backend's own spine suite turns it on
+     * so neither spine can add an undeclared key. Exposed on
+     * `fixture.reject_unknown_audit_metadata_keys`.
+     */
+    readonly reject_unknown_audit_metadata_keys?: boolean;
+    /**
+     * REST signup route `fixture.create_account` mints through. Default
+     * `SPINE_ACCOUNT_SIGNUP_PATH`; set it for a backend mounting the account
+     * routes under another prefix.
+     */
+    readonly signup_path?: string;
+    /** REST login route `fixture.create_account` logs in through. Default `SPINE_ACCOUNT_LOGIN_PATH`. */
+    readonly login_path?: string;
 }
 /**
  * Capture a backend's schema snapshot over the `_testing_schema_snapshot`