@fuzdev/fuz_app 0.64.0 → 0.65.0

package/dist/testing/bootstrap_success.d.ts

@@ -0,0 +1,28 @@
+import './assert_dev_env.js';
+import type { SessionOptions } from '../auth/session_cookie.js';
+import type { AppServerContext, BootstrapLiveOptions } from '../server/app_server.js';
+import type { RouteSpec } from '../http/route_spec.js';
+import type { RpcEndpointsSuiteOption } from './rpc_helpers.js';
+/** Options for `describe_bootstrap_success_tests`. */
+export interface BootstrapSuccessTestOptions {
+    session_options: SessionOptions<string>;
+    /** Same factory the consumer's production server uses. */
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** RPC endpoints — passed through to `create_app_server` for shape parity. */
+    rpc_endpoints?: RpcEndpointsSuiteOption;
+    /**
+     * Live bootstrap config — the suite drives `POST /bootstrap` against
+     * `bootstrap.token_path`. The suite does NOT assert on `on_bootstrap`
+     * callback invocation (Hono-coupled signature is in-process only);
+     * assertions land on observable DB state.
+     */
+    bootstrap: BootstrapLiveOptions;
+    /** Override the synthetic token text. Default deterministic. */
+    bootstrap_token?: string;
+}
+/**
+ * Run the bootstrap success-path test suite against the consumer's
+ * production-shaped wiring.
+ */
+export declare const describe_bootstrap_success_tests: (options: BootstrapSuccessTestOptions) => void;
+//# sourceMappingURL=bootstrap_success.d.ts.map

package/dist/testing/bootstrap_success.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap_success.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/bootstrap_success.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAE,oBAAoB,EAAC,MAAM,yBAAyB,CAAC;AACpF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAGrD,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,kBAAkB,CAAC;AAM9D,sDAAsD;AACtD,MAAM,WAAW,2BAA2B;IAC3C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,0DAA0D;IAC1D,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,8EAA8E;IAC9E,aAAa,CAAC,EAAE,uBAAuB,CAAC;IACxC;;;;;OAKG;IACH,SAAS,EAAE,oBAAoB,CAAC;IAChC,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,gCAAgC,GAAI,SAAS,2BAA2B,KAAG,IAyIvF,CAAC"}

package/dist/testing/bootstrap_success.js

@@ -0,0 +1,144 @@
+import './assert_dev_env.js';
+/**
+ * Bootstrap success-path suite for consumer projects.
+ *
+ * Exercises `POST /bootstrap` against an empty DB (no pre-keeper, lock
+ * unflipped) through the real `bootstrap_account` flow. Asserts on
+ * observable state — account exists, `bootstrap_lock.bootstrapped` is
+ * true, audit row emitted, response body shape — rather than
+ * `on_bootstrap` callback invocation, so the suite stays cross-impl
+ * friendly when Phase 3 cross-process testing wires it against a
+ * spawned Rust backend.
+ *
+ * Folded into `describe_standard_tests` with a `bootstrap.mode === 'live'`
+ * silent-skip gate; consumers wiring live bootstrap pick up success-path
+ * coverage by default.
+ *
+ * @module
+ */
+import { describe, test, assert } from 'vitest';
+import { ERROR_ALREADY_BOOTSTRAPPED, ERROR_INVALID_TOKEN } from '../http/error_schemas.js';
+import { create_test_app_for_bootstrap } from './app_server.js';
+const DEFAULT_TEST_TOKEN = 'test-bootstrap-token-value-deterministic';
+const TEST_USERNAME = 'keeper';
+const TEST_PASSWORD = 'test-password-with-min-12-chars';
+/**
+ * Run the bootstrap success-path test suite against the consumer's
+ * production-shaped wiring.
+ */
+export const describe_bootstrap_success_tests = (options) => {
+    const token = options.bootstrap_token ?? DEFAULT_TEST_TOKEN;
+    const route_prefix = options.bootstrap.route_prefix ?? '/api/account';
+    const bootstrap_path = `${route_prefix}/bootstrap`;
+    describe('bootstrap success path', () => {
+        test('POST /bootstrap with valid token creates the keeper account and flips the lock', async () => {
+            const test_app = await create_test_app_for_bootstrap({
+                session_options: options.session_options,
+                create_route_specs: options.create_route_specs,
+                rpc_endpoints: options.rpc_endpoints,
+                bootstrap: options.bootstrap,
+                bootstrap_token: token,
+            });
+            try {
+                const response = await test_app.app.request(bootstrap_path, {
+                    method: 'POST',
+                    headers: test_app.create_request_headers({ 'content-type': 'application/json' }),
+                    body: JSON.stringify({
+                        token,
+                        username: TEST_USERNAME,
+                        password: TEST_PASSWORD,
+                    }),
+                });
+                // Response shape
+                assert.strictEqual(response.status, 200);
+                const body = (await response.json());
+                assert.strictEqual(body.ok, true);
+                assert.strictEqual(body.account.username, TEST_USERNAME);
+                assert.ok(body.account.id);
+                assert.ok(body.actor.id);
+                // Observable state: account exists in DB
+                const account = await test_app.backend.deps.db.query_one('SELECT username FROM account WHERE username = $1', [TEST_USERNAME]);
+                assert.ok(account);
+                // Observable state: bootstrap_lock flipped to true
+                const lock = await test_app.backend.deps.db.query_one('SELECT bootstrapped FROM bootstrap_lock WHERE id = 1');
+                assert.ok(lock);
+                assert.strictEqual(lock.bootstrapped, true);
+                // Observable state: audit row emitted
+                const audit_row = await test_app.backend.deps.db.query_one("SELECT event_type, account_id FROM audit_log WHERE event_type = 'bootstrap' AND outcome = 'success' LIMIT 1");
+                assert.ok(audit_row);
+                assert.strictEqual(audit_row.account_id, body.account.id);
+            }
+            finally {
+                await test_app.cleanup();
+            }
+        });
+        test('second POST /bootstrap returns 403 ALREADY_BOOTSTRAPPED', async () => {
+            const test_app = await create_test_app_for_bootstrap({
+                session_options: options.session_options,
+                create_route_specs: options.create_route_specs,
+                rpc_endpoints: options.rpc_endpoints,
+                bootstrap: options.bootstrap,
+                bootstrap_token: token,
+            });
+            try {
+                // First bootstrap succeeds
+                const first = await test_app.app.request(bootstrap_path, {
+                    method: 'POST',
+                    headers: test_app.create_request_headers({ 'content-type': 'application/json' }),
+                    body: JSON.stringify({
+                        token,
+                        username: TEST_USERNAME,
+                        password: TEST_PASSWORD,
+                    }),
+                });
+                assert.strictEqual(first.status, 200);
+                // Second attempt blocked by lock
+                const second = await test_app.app.request(bootstrap_path, {
+                    method: 'POST',
+                    headers: test_app.create_request_headers({ 'content-type': 'application/json' }),
+                    body: JSON.stringify({
+                        token,
+                        username: 'another_user',
+                        password: TEST_PASSWORD,
+                    }),
+                });
+                assert.strictEqual(second.status, 403);
+                const body = (await second.json());
+                assert.strictEqual(body.error, ERROR_ALREADY_BOOTSTRAPPED);
+            }
+            finally {
+                await test_app.cleanup();
+            }
+        });
+        test('POST /bootstrap with wrong token returns 401 INVALID_TOKEN', async () => {
+            const test_app = await create_test_app_for_bootstrap({
+                session_options: options.session_options,
+                create_route_specs: options.create_route_specs,
+                rpc_endpoints: options.rpc_endpoints,
+                bootstrap: options.bootstrap,
+                bootstrap_token: token,
+            });
+            try {
+                const response = await test_app.app.request(bootstrap_path, {
+                    method: 'POST',
+                    headers: test_app.create_request_headers({ 'content-type': 'application/json' }),
+                    body: JSON.stringify({
+                        token: 'wrong-token-value-that-does-not-match',
+                        username: TEST_USERNAME,
+                        password: TEST_PASSWORD,
+                    }),
+                });
+                assert.strictEqual(response.status, 401);
+                const body = (await response.json());
+                assert.strictEqual(body.error, ERROR_INVALID_TOKEN);
+                // Observable state: lock NOT flipped (transaction rolled back on auth failure)
+                const lock = await test_app.backend.deps.db.query_one('SELECT bootstrapped FROM bootstrap_lock WHERE id = 1');
+                assert.ok(lock);
+                assert.strictEqual(lock.bootstrapped, false);
+            }
+            finally {
+                await test_app.cleanup();
+            }
+        });
+    });
+};

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

@@ -0,0 +1,64 @@
+import '../assert_dev_env.js';
+/**
+ * Optional behaviors a backend may support. Each flag's TSDoc names the
+ * tests that gate on it; add a new flag here before referencing it from
+ * a suite body, and document the gating tests inline.
+ */
+export interface BackendCapabilities {
+    /**
+     * Bearer token auth (`Authorization: Bearer <token>`) is wired through
+     * the backend's middleware stack. Gates the bearer-token cases in
+     * `describe_standard_integration_tests` and `describe_rate_limiting_tests`.
+     */
+    readonly bearer_auth: boolean;
+    /**
+     * Trusted-proxy XFF parsing is wired (`X-Forwarded-For` etc.). Gates
+     * the proxy-resolution cases in `describe_standard_integration_tests`
+     * and the future cross-process proxy integration suite.
+     */
+    readonly trusted_proxy: boolean;
+    /**
+     * Per-account login rate limiting is wired. Gates the per-account
+     * rate-limit cases in `describe_rate_limiting_tests`.
+     */
+    readonly login_rate_limit: boolean;
+    /**
+     * WebSocket transport is reachable end-to-end. Gates the cross-process
+     * WS round-trip suite; the in-process `describe_ws_round_trip_tests`
+     * runs against `register_action_ws` directly and ignores this flag.
+     */
+    readonly ws: boolean;
+    /**
+     * SSE transport is reachable end-to-end. Gates the cross-process SSE
+     * close-detection cases; in-process SSE uses the
+     * `on_audit_event` hook and ignores this flag.
+     */
+    readonly sse: boolean;
+    /**
+     * Test has direct access to backend-internal state (keyring for
+     * signing cookies, DB pool for FK-structural raw queries). Always
+     * `true` for in-process Hono via `default_in_process_setup`; always
+     * `false` cross-process. Gates the 3 keyring reads in
+     * `describe_standard_integration_tests` (expired-cookie generation)
+     * and the FK-structural raw query in `describe_audit_completeness_tests`.
+     */
+    readonly in_process_only: boolean;
+}
+/**
+ * Capability declarations for the in-process Hono transport. Every flag
+ * is `true` because in-process testing exercises the full backend with
+ * no missing optional behaviors. Cross-process consumers
+ * declare each flag explicitly per backend.
+ */
+export declare const in_process_capabilities: BackendCapabilities;
+/**
+ * Conditional `test()` wrapper — registers a vitest case only when
+ * `cond` is true; otherwise registers it as `.skip` so the run still
+ * surfaces the gated coverage in the report.
+ *
+ * Thin wrapper around vitest's `test.skipIf(!cond)` with the argument
+ * order flipped to match the more readable `test_if(capabilities.bearer_auth, ...)`
+ * call pattern.
+ */
+export declare const test_if: (cond: boolean, name: string, fn: () => void | Promise<void>) => void;
+//# sourceMappingURL=capabilities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAmB9B;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAOpC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,EAAE,MAAM,MAAM,EAAE,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,IAMrF,CAAC"}

package/dist/testing/cross_backend/capabilities.js

@@ -0,0 +1,47 @@
+import '../assert_dev_env.js';
+/**
+ * Capability vocabulary for cross-backend integration testing.
+ *
+ * Backends declare which optional behaviors they support; suite bodies
+ * call `test_if(capabilities.X, ...)` to skip cases the backend doesn't
+ * implement. No `if (config.name === 'rust')` branches anywhere — name-
+ * checking is a code smell that says capability vocabulary is missing.
+ *
+ * In-process Hono via `default_in_process_setup` declares every
+ * capability `true` (see `in_process_capabilities`). Cross-process
+ * backends opt in per-flag on their `BackendConfig`.
+ *
+ * @module
+ */
+import { test } from 'vitest';
+/**
+ * Capability declarations for the in-process Hono transport. Every flag
+ * is `true` because in-process testing exercises the full backend with
+ * no missing optional behaviors. Cross-process consumers
+ * declare each flag explicitly per backend.
+ */
+export const in_process_capabilities = Object.freeze({
+    bearer_auth: true,
+    trusted_proxy: true,
+    login_rate_limit: true,
+    ws: true,
+    sse: true,
+    in_process_only: true,
+});
+/**
+ * Conditional `test()` wrapper — registers a vitest case only when
+ * `cond` is true; otherwise registers it as `.skip` so the run still
+ * surfaces the gated coverage in the report.
+ *
+ * Thin wrapper around vitest's `test.skipIf(!cond)` with the argument
+ * order flipped to match the more readable `test_if(capabilities.bearer_auth, ...)`
+ * call pattern.
+ */
+export const test_if = (cond, name, fn) => {
+    if (cond) {
+        test(name, fn);
+    }
+    else {
+        test.skip(name, fn);
+    }
+};

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

@@ -0,0 +1,215 @@
+import '../assert_dev_env.js';
+/**
+ * Per-test fixture protocol shared by in-process and cross-process
+ * transports.
+ *
+ * Each standard suite body takes a required
+ * `setup_test: () => Promise<TestFixture>` callback and invokes it once
+ * per test. The fixture carries everything a test needs to fire requests
+ * and assert on a single bootstrapped keeper account — transport,
+ * account / actor identity, three header builders, a multi-account mint
+ * factory, and (in-process only) the in-memory keyring + raw backend.
+ *
+ * `default_in_process_setup(options)` wraps `create_test_app` into the
+ * `SetupTest` contract. The cross-process sibling
+ * (`default_cross_process_setup`) lands alongside the spawn-a-backend
+ * transport plumbing — it implements the same contract by spawning a
+ * binary and bootstrapping over real HTTP.
+ *
+ * @module
+ */
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { Keyring } from '../../auth/keyring.js';
+import type { RouteSpec } from '../../http/route_spec.js';
+import type { AppServerContext, BootstrapServerOptions } from '../../server/app_server.js';
+import type { SessionOptions } from '../../auth/session_cookie.js';
+import { type CreateTestAppOptions, type SuiteAppOptions, type TestAccount, type TestAppServer } from '../app_server.js';
+import { type RpcTestTransport, type RpcEndpointsSuiteOption } from '../rpc_helpers.js';
+import { type BackendCapabilities } from './capabilities.js';
+import type { SurfaceSource } from '../transports/surface_source.js';
+/**
+ * Options for `TestFixture.create_account` — mints an additional
+ * bootstrapped account alongside the keeper. Matches the existing
+ * `TestApp.create_account` signature so the migration to fixture-style
+ * reads is a one-site call rewrite per use.
+ */
+export interface CreateTestAccountOptions {
+    readonly username?: string;
+    readonly password_value?: string;
+    readonly roles?: Array<string>;
+}
+/**
+ * Shape returned by `TestFixture.create_account`. Aliased to the
+ * existing `TestAccount` interface from `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;
+/**
+ * Fields shared by every `TestFixture` regardless of transport. The
+ * discriminated union below adds in-process-only fields conditionally.
+ */
+export interface TestFixtureBase {
+    /** Transport for this test's HTTP requests (cookie-threaded cross-process). */
+    readonly transport: RpcTestTransport;
+    /** The freshly-bootstrapped keeper account. */
+    readonly account: {
+        readonly id: Uuid;
+        readonly username: string;
+    };
+    /** The actor linked to the keeper account. */
+    readonly actor: {
+        readonly id: Uuid;
+    };
+    /** Build request headers with the keeper's session cookie. */
+    readonly create_session_headers: (extra?: Record<string, string>) => Record<string, string>;
+    /** Build request headers with the keeper's bearer token. */
+    readonly create_bearer_headers: (extra?: Record<string, string>) => Record<string, string>;
+    /** Build request headers with the daemon token (keeper auth). */
+    readonly create_daemon_token_headers: (extra?: Record<string, string>) => Record<string, string>;
+    /**
+     * Mint an additional bootstrapped account for cross-account / multi-user
+     * tests. In-process: re-uses `create_test_account_with_credentials` against the same DB;
+     * cross-process: goes through the consumer-supplied DB-admin
+     * channel.
+     */
+    readonly create_account: (options?: CreateTestAccountOptions) => Promise<TestAccountFixture>;
+}
+/**
+ * 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.
+ *
+ * Discriminated by `in_process`: when `true`, `keyring` and
+ * `backend_internals` are present (compile-time narrowed); when `false`,
+ * they're absent and the suite body must either run via the public wire
+ * (cross-process) or gate the test with
+ * `test_if(capabilities.in_process_only, ...)`. The discriminant value
+ * mirrors `BackendCapabilities.in_process_only` — both source from the
+ * same producer (`default_in_process_setup` vs. cross-process variant).
+ *
+ * Suite bodies narrow with `assert(fixture.in_process)` after
+ * `setup_test()`; sites that reach for `keyring` or `backend_internals`
+ * are in-process-only by structure and the assertion surfaces a clear
+ * failure if a future cross-process consumer reaches them without a
+ * `test_if` gate.
+ */
+export type TestFixture = (TestFixtureBase & {
+    readonly in_process: true;
+    /**
+     * Test-only keyring access — in-process only. Used for
+     * expired-cookie generation in `describe_standard_integration_tests`.
+     */
+    readonly keyring: Keyring;
+    /**
+     * Raw backend access (`deps.db`, etc.) — in-process only. Used by
+     * `create_test_role_grant_direct` seed sites in
+     * `describe_standard_admin_integration_tests` and the
+     * origin-verification cookie-composition sites in
+     * `describe_standard_integration_tests`.
+     */
+    readonly backend_internals: TestAppServer;
+}) | (TestFixtureBase & {
+    readonly in_process: false;
+});
+/**
+ * Per-test fixture-producing function. Invoked once inside every
+ * `test()` body. 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.
+ */
+export type SetupTest = () => Promise<TestFixture>;
+/**
+ * Build a `SetupTest` that creates a fresh `TestApp` per call via
+ * `create_test_app` and projects it into the `TestFixture` shape.
+ *
+ * Same factory inputs `create_test_app` already takes — this helper
+ * is a projection layer, not a new lifecycle. fuz_app's own `src/test/`
+ * and consumer suites pass `default_in_process_setup({...factory_inputs})`
+ * in place of the old per-suite factory-input bundle.
+ *
+ * The describe-level `auth_integration_truncate_tables` / pglite WASM
+ * cache lifecycle stays in `create_pglite_factory` / `create_describe_db`
+ * (`testing/db.js`) — `default_in_process_setup` doesn't manage db state
+ * beyond what `create_test_app` already does.
+ */
+export declare const default_in_process_setup: (options: CreateTestAppOptions) => SetupTest;
+/**
+ * Consumer-facing options for `default_in_process_suite_options` — the
+ * minimal factory inputs both `default_in_process_setup` and
+ * `create_test_app_surface_spec` consume to produce the
+ * `{setup_test, surface_source, capabilities}` bundle.
+ */
+export interface DefaultInProcessSuiteOptions {
+    session_options: SessionOptions<string>;
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    rpc_endpoints?: RpcEndpointsSuiteOption;
+    /**
+     * Bootstrap config — top-level slot, single source of truth for both
+     * surface generation and live dispatch. Same precedent as
+     * `rpc_endpoints`. Discriminated by `mode`; omit for the default (no
+     * bootstrap route mounted).
+     */
+    bootstrap?: BootstrapServerOptions;
+    app_options?: SuiteAppOptions;
+    /**
+     * Additional roles to grant the bootstrapped keeper alongside
+     * `ROLE_KEEPER` — additive, never replaces. The keeper account
+     * always holds `ROLE_KEEPER` (otherwise daemon-token auth breaks);
+     * pass extras here for suites that need additional role coverage.
+     *
+     * Admin-suite consumers pass `[ROLE_ADMIN]` so the default keeper
+     * can hit admin-gated RPC methods.
+     * `describe_standard_admin_integration_tests` and
+     * `describe_audit_completeness_tests` need this.
+     */
+    extra_keeper_roles?: Array<string>;
+    /**
+     * Pre-built `SurfaceSource` — overrides the default which calls
+     * `create_test_app_surface_spec` against the same factory inputs.
+     * Pass when surface assembly needs fields outside the shared subset
+     * (e.g. `env_schema`, `event_specs`, `ws_endpoints`, `transform_middleware`).
+     */
+    surface_source?: SurfaceSource;
+}
+/**
+ * Build the full in-process suite bundle in a single helper invocation.
+ * Output covers `{setup_test, surface_source, capabilities}` plus every
+ * factory input the Tier 1 suites read at their top level
+ * (`session_options`, `create_route_specs`, `rpc_endpoints`) — so the
+ * call site spreads once and adds only suite-specific extras
+ * (`roles`, `skip_routes`, `input_overrides`, `db_factories`, ...).
+ *
+ * ```ts
+ * // Suite-extras-free call: helper output is the entire options bag.
+ * describe_round_trip_validation(default_in_process_suite_options({
+ *   session_options,
+ *   create_route_specs,
+ *   rpc_endpoints: [rpc_endpoint_spec],
+ * }));
+ *
+ * // With suite-specific extras: spread and add.
+ * describe_standard_admin_integration_tests({
+ *   ...default_in_process_suite_options({
+ *     session_options, create_route_specs, rpc_endpoints,
+ *     extra_keeper_roles: [ROLE_ADMIN],
+ *   }),
+ *   roles,
+ * });
+ * ```
+ *
+ * Suites that don't read `session_options` / `rpc_endpoints` at their
+ * top level (`round_trip`, `data_exposure`) accept the spread anyway —
+ * excess properties on spread sources aren't checked by TS, and the
+ * uniform shape keeps consumer call sites mechanical.
+ */
+export declare const default_in_process_suite_options: <const O extends DefaultInProcessSuiteOptions>(options: O) => {
+    setup_test: SetupTest;
+    surface_source: SurfaceSource;
+    capabilities: BackendCapabilities;
+    session_options: O["session_options"];
+    create_route_specs: O["create_route_specs"];
+    rpc_endpoints: O["rpc_endpoints"];
+};
+//# sourceMappingURL=setup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/setup.ts"],"names":[],"mappings":"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"}

package/dist/testing/cross_backend/setup.js

@@ -0,0 +1,101 @@
+import '../assert_dev_env.js';
+import { ROLE_KEEPER } from '../../auth/role_schema.js';
+import { create_test_app, } 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';
+/**
+ * Build a `SetupTest` that creates a fresh `TestApp` per call via
+ * `create_test_app` and projects it into the `TestFixture` shape.
+ *
+ * Same factory inputs `create_test_app` already takes — this helper
+ * is a projection layer, not a new lifecycle. fuz_app's own `src/test/`
+ * and consumer suites pass `default_in_process_setup({...factory_inputs})`
+ * in place of the old per-suite factory-input bundle.
+ *
+ * The describe-level `auth_integration_truncate_tables` / pglite WASM
+ * cache lifecycle stays in `create_pglite_factory` / `create_describe_db`
+ * (`testing/db.js`) — `default_in_process_setup` doesn't manage db state
+ * beyond what `create_test_app` already does.
+ */
+export const default_in_process_setup = (options) => async () => {
+    const test_app = await create_test_app(options);
+    return {
+        in_process: true,
+        transport: http_transport(test_app.app),
+        account: test_app.backend.account,
+        actor: test_app.backend.actor,
+        create_session_headers: test_app.create_session_headers,
+        create_bearer_headers: test_app.create_bearer_headers,
+        create_daemon_token_headers: test_app.create_daemon_token_headers,
+        create_account: test_app.create_account,
+        keyring: test_app.backend.keyring,
+        backend_internals: test_app.backend,
+    };
+};
+// NOTE: bootstrap config is read from `options.bootstrap` — top-level slot,
+// single source of truth for both the surface spec (so the route appears in
+// `expected_public_routes` / attack-surface iteration) AND the live
+// `create_test_app` (so the route exists at dispatch time and returns 403
+// `ERROR_ALREADY_BOOTSTRAPPED` matching its declared 403 schema). Same
+// precedent as `rpc_endpoints`. Discriminated union shape (`mode: 'disabled'`
+// | `'surface_only'` | `'live'`) replaces the old `token_path: string | null`
+// overload that conflated three deployment intents on one channel.
+/**
+ * Build the full in-process suite bundle in a single helper invocation.
+ * Output covers `{setup_test, surface_source, capabilities}` plus every
+ * factory input the Tier 1 suites read at their top level
+ * (`session_options`, `create_route_specs`, `rpc_endpoints`) — so the
+ * call site spreads once and adds only suite-specific extras
+ * (`roles`, `skip_routes`, `input_overrides`, `db_factories`, ...).
+ *
+ * ```ts
+ * // Suite-extras-free call: helper output is the entire options bag.
+ * describe_round_trip_validation(default_in_process_suite_options({
+ *   session_options,
+ *   create_route_specs,
+ *   rpc_endpoints: [rpc_endpoint_spec],
+ * }));
+ *
+ * // With suite-specific extras: spread and add.
+ * describe_standard_admin_integration_tests({
+ *   ...default_in_process_suite_options({
+ *     session_options, create_route_specs, rpc_endpoints,
+ *     extra_keeper_roles: [ROLE_ADMIN],
+ *   }),
+ *   roles,
+ * });
+ * ```
+ *
+ * Suites that don't read `session_options` / `rpc_endpoints` at their
+ * top level (`round_trip`, `data_exposure`) accept the spread anyway —
+ * excess properties on spread sources aren't checked by TS, and the
+ * uniform shape keeps consumer call sites mechanical.
+ */
+export const default_in_process_suite_options = (options) => ({
+    setup_test: default_in_process_setup({
+        session_options: options.session_options,
+        create_route_specs: options.create_route_specs,
+        rpc_endpoints: options.rpc_endpoints,
+        bootstrap: options.bootstrap,
+        app_options: options.app_options,
+        roles: [ROLE_KEEPER, ...(options.extra_keeper_roles ?? [])],
+    }),
+    surface_source: options.surface_source ??
+        {
+            kind: 'inline',
+            spec: create_test_app_surface_spec({
+                session_options: options.session_options,
+                create_route_specs: options.create_route_specs,
+                rpc_endpoints: options.rpc_endpoints,
+                // Mirror what `create_test_app` → `create_app_server` will mount.
+                // Both helpers read from the top-level `bootstrap` slot so surface
+                // and live app stay in sync by construction.
+                bootstrap: options.bootstrap,
+            }),
+        },
+    capabilities: in_process_capabilities,
+    session_options: options.session_options,
+    create_route_specs: options.create_route_specs,
+    rpc_endpoints: options.rpc_endpoints,
+});

package/dist/testing/data_exposure.d.ts

@@ -1,9 +1,8 @@
 import './assert_dev_env.js';
-import type { AppSurface, AppSurfaceSpec } from '../http/surface.js';
-import type { RouteSpec } from '../http/route_spec.js';
-import type { AppServerContext, AppServerOptions } from '../server/app_server.js';
-import type { SessionOptions } from '../auth/session_cookie.js';
-import { type DbFactory } from './db.js';
+import type { AppSurface } from '../http/surface.js';
+import type { BackendCapabilities } from './cross_backend/capabilities.js';
+import type { SetupTest } from './cross_backend/setup.js';
+import type { SurfaceSource } from './transports/surface_source.js';
 /**
  * Recursively collect all property names from a JSON Schema.
  *
@@ -21,20 +20,20 @@ export declare const assert_output_schemas_no_sensitive_fields: (surface: AppSur
 export declare const assert_non_admin_schemas_no_admin_fields: (surface: AppSurface, admin_only_fields?: ReadonlyArray<string>) => void;
 /** Options for `describe_data_exposure_tests`. */
 export interface DataExposureTestOptions {
-    /** Build the app surface spec (for schema-level checks). */
-    build: () => AppSurfaceSpec;
-    /** Session config for runtime tests. */
-    session_options: SessionOptions<string>;
-    /** Route spec factory for runtime tests. */
-    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** Per-test fixture-producing function (per-describe cadence). */
+    setup_test: SetupTest;
+    /**
+     * Source of the app surface for schema-level + route-iteration checks.
+     * Currently requires `kind: 'inline'` — the cross-process snapshot
+     * variant lands alongside the spawned-backend transport plumbing.
+     */
+    surface_source: SurfaceSource;
+    /** Backend capability declarations. */
+    capabilities: BackendCapabilities;
     /** Fields that must never appear in any response. Default: `sensitive_field_blocklist`. */
     sensitive_fields?: ReadonlyArray<string>;
     /** Fields that must not appear in non-admin responses. Default: `admin_only_field_blocklist`. */
     admin_only_fields?: ReadonlyArray<string>;
-    /** Optional overrides for `AppServerOptions`. */
-    app_options?: Partial<Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>>;
-    /** Database factories to run tests against. Default: pglite only. */
-    db_factories?: Array<DbFactory>;
     /** Routes to skip, in `'METHOD /path'` format. */
     skip_routes?: Array<string>;
 }