@fuzdev/fuz_app 0.63.0 → 0.65.0

package/dist/testing/audit_drift_guard.d.ts

@@ -0,0 +1,116 @@
+import './assert_dev_env.js';
+import { type AuditEmitter, type CreateAuditEmitterOptions } from '../auth/audit_emitter.js';
+import type { AuditLogInput } from '../auth/audit_log_schema.js';
+import type { AuditFactory } from '../server/app_backend.js';
+/**
+ * Register per-test `beforeEach` + `afterEach` hooks that catch any audit
+ * emission with a metadata shape that fails its `audit_metadata_schemas`
+ * entry, or an `event_type` not present in the active `AuditLogConfig`.
+ *
+ * The production validation in `query_audit_log` is fail-open — it bumps
+ * process-wide counters and proceeds, so a regression that emits an
+ * undeclared metadata field or a typo'd event-type lands a row that
+ * passes downstream queries but breaks forensics. Tests that exercise
+ * audit emits should fail loudly when this happens.
+ *
+ * Call at the top of every `describe` / `describe_db` block that fires
+ * audit writes through `deps.audit.emit`. Resets counters before each
+ * test and asserts zero on completion.
+ *
+ * Pair with `await_pending_effects: true` (the default for
+ * `create_test_app`) so fire-and-forget audit writes have completed by
+ * the time the after-each check observes counter state.
+ */
+export declare const install_audit_drift_guard: () => void;
+/**
+ * Marker pushed into a shared sequence array by an emit-recording
+ * `audit_factory`. Pair with `RecordedClose` from
+ * `connection_closer_helpers.ts` to test close-vs-emit ordering at
+ * handler call sites — see `create_emit_ordering_audit_factory` below.
+ */
+export interface AuditEmitMarker {
+    kind: 'emit';
+    at: number;
+}
+/**
+ * Pair returned by {@link create_recording_audit_emitter} — the
+ * `AuditEmitter` to inject as `deps.audit`, plus the shared `calls`
+ * array that records every captured emission. Both fields are live —
+ * callers read `calls` after exercising the handler to assert on the
+ * audit metadata shape.
+ */
+export interface RecordingAuditEmitter {
+    emitter: AuditEmitter;
+    calls: Array<AuditLogInput>;
+}
+/**
+ * Build a no-op `AuditEmitter` that records every `emit`, `emit_pool`, and
+ * `emit_role_grant_target` call into `calls` as an `AuditLogInput`. Use to
+ * capture audit metadata shapes in unit tests (e.g. password change failure
+ * outcome, role-grant create denial) without standing up the full PGlite +
+ * `query_audit_log` pipeline.
+ *
+ * **Capture scope — all four production fan-out shapes.**
+ * `emit_role_grant_target` mirrors `create_audit_emitter`'s lift logic in
+ * place — `actor_id` / `account_id` / `ip` are populated from `auth` + `ctx`
+ * and the `event_type` / `outcome` / `target_*_id` / `metadata` fields
+ * forward from the input envelope. Tests asserting on role-grant-shape
+ * emissions read out of the same homogeneous `calls` array.
+ * `notify` is a no-op; `on_event_chain` is an empty array.
+ *
+ * `emit` AND `emit_pool` both append to `calls` so cleanup-sweep tests
+ * (which use `emit_pool` exclusively — see `auth/cleanup.ts`) can also
+ * read assertions off the same array.
+ *
+ * Pass `calls_ref` to write into a caller-owned array (callers that
+ * declared `const events: Array<AuditLogInput> = []` and want to keep
+ * the reference). Omit to let the helper allocate a fresh array and
+ * return it on the `calls` field of the result.
+ *
+ * The returned emitter is deliberately NOT frozen — slots stay mutable
+ * so a test can override one when it needs bespoke shape (e.g. an
+ * `emit_pool` that throws on the first call). The production
+ * `create_audit_emitter` freeze invariant exists to catch the
+ * `patch_audit_emit_capture` hot-patch footgun against the
+ * closure-captured `emit`; the recording emitter has no inner closure,
+ * so the freeze isn't load-bearing here.
+ */
+export declare const create_recording_audit_emitter: (calls_ref?: Array<AuditLogInput>) => RecordingAuditEmitter;
+/**
+ * Build an `audit_factory` that produces a real `create_audit_emitter`
+ * with its `emit` decorated to push a `{kind: 'emit', at: seq.value++}`
+ * marker into a shared sequence + events array. Used by the close-vs-emit
+ * ordering test to compose against a shared sequence counter (typically
+ * `create_recording_closer(seq_ref)` capturing eager-close calls).
+ *
+ * Pass the returned factory through `create_test_app({audit_factory: …})`
+ * — the test backend invokes it with its constructed `{db, log}` and
+ * lands the decorated emitter on `backend.deps.audit`. Production
+ * handlers dereference `deps.audit.emit` at call time, so the decorator
+ * sees every subsequent handler invocation. The underlying `emit` still
+ * runs — the decorator records the call, it does not suppress side
+ * effects.
+ *
+ * **Scope — both `emit` and `emit_role_grant_target`.** The decorator
+ * is captured by `emit_role_grant_target`'s closure inside
+ * `create_audit_emitter` (and re-exposed as the outer `emit` slot), so
+ * role-grant-shape emissions land in `events_ref` alongside bare `emit`
+ * calls. `emit_pool` and `notify` are not decorated — they take
+ * `AuditLogInput` / `AuditLogEvent` directly without going through
+ * `emit`, so handler-side `emit_pool` writes (today only
+ * `auth/cleanup.ts`) skip capture. Close-firing handlers all reach for
+ * `emit` or `emit_role_grant_target`, so the ordering test sees them
+ * regardless of which entry point a future refactor picks.
+ *
+ * Optionally accept `extra_options` to thread `on_audit_event` /
+ * `audit_log_config` into the inner emitter — useful when a test wants
+ * both ordering capture and a real SSE/WS guard wired into the same
+ * emitter chain.
+ */
+export declare const create_emit_ordering_audit_factory: <E extends {
+    kind: string;
+    at: number;
+}>(seq_ref: {
+    value: number;
+}, events_ref: Array<AuditEmitMarker | E>, extra_options?: Omit<CreateAuditEmitterOptions, "db" | "log" | "emit_decorator">) => AuditFactory;
+//# sourceMappingURL=audit_drift_guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit_drift_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/audit_drift_guard.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAU7B,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,QAAO,IAiB5C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACX;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,8BAA8B,GAC1C,YAAY,KAAK,CAAC,aAAa,CAAC,KAC9B,qBA0BF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,kCAAkC,GAAI,CAAC,SAAS;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAC,EACtF,SAAS;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,EACxB,YAAY,KAAK,CAAC,eAAe,GAAG,CAAC,CAAC,EACtC,gBAAgB,IAAI,CAAC,yBAAyB,EAAE,IAAI,GAAG,KAAK,GAAG,gBAAgB,CAAC,KAC9E,YAWF,CAAC"}

package/dist/testing/audit_drift_guard.js

@@ -0,0 +1,134 @@
+import './assert_dev_env.js';
+import { assert, beforeEach, afterEach } from 'vitest';
+import { get_audit_metadata_validation_failures, get_audit_unknown_event_type_failures, reset_audit_metadata_validation_failures, reset_audit_unknown_event_type_failures, } from '../auth/audit_log_queries.js';
+import { create_audit_emitter, } from '../auth/audit_emitter.js';
+/**
+ * Register per-test `beforeEach` + `afterEach` hooks that catch any audit
+ * emission with a metadata shape that fails its `audit_metadata_schemas`
+ * entry, or an `event_type` not present in the active `AuditLogConfig`.
+ *
+ * The production validation in `query_audit_log` is fail-open — it bumps
+ * process-wide counters and proceeds, so a regression that emits an
+ * undeclared metadata field or a typo'd event-type lands a row that
+ * passes downstream queries but breaks forensics. Tests that exercise
+ * audit emits should fail loudly when this happens.
+ *
+ * Call at the top of every `describe` / `describe_db` block that fires
+ * audit writes through `deps.audit.emit`. Resets counters before each
+ * test and asserts zero on completion.
+ *
+ * Pair with `await_pending_effects: true` (the default for
+ * `create_test_app`) so fire-and-forget audit writes have completed by
+ * the time the after-each check observes counter state.
+ */
+export const install_audit_drift_guard = () => {
+    beforeEach(() => {
+        reset_audit_metadata_validation_failures();
+        reset_audit_unknown_event_type_failures();
+    });
+    afterEach(() => {
+        assert.strictEqual(get_audit_metadata_validation_failures(), 0, 'audit metadata failed schema validation — see audit_log_schema.audit_metadata_schemas');
+        assert.strictEqual(get_audit_unknown_event_type_failures(), 0, 'audit emitted an unknown event_type — see AUDIT_EVENT_TYPES');
+    });
+};
+/**
+ * Build a no-op `AuditEmitter` that records every `emit`, `emit_pool`, and
+ * `emit_role_grant_target` call into `calls` as an `AuditLogInput`. Use to
+ * capture audit metadata shapes in unit tests (e.g. password change failure
+ * outcome, role-grant create denial) without standing up the full PGlite +
+ * `query_audit_log` pipeline.
+ *
+ * **Capture scope — all four production fan-out shapes.**
+ * `emit_role_grant_target` mirrors `create_audit_emitter`'s lift logic in
+ * place — `actor_id` / `account_id` / `ip` are populated from `auth` + `ctx`
+ * and the `event_type` / `outcome` / `target_*_id` / `metadata` fields
+ * forward from the input envelope. Tests asserting on role-grant-shape
+ * emissions read out of the same homogeneous `calls` array.
+ * `notify` is a no-op; `on_event_chain` is an empty array.
+ *
+ * `emit` AND `emit_pool` both append to `calls` so cleanup-sweep tests
+ * (which use `emit_pool` exclusively — see `auth/cleanup.ts`) can also
+ * read assertions off the same array.
+ *
+ * Pass `calls_ref` to write into a caller-owned array (callers that
+ * declared `const events: Array<AuditLogInput> = []` and want to keep
+ * the reference). Omit to let the helper allocate a fresh array and
+ * return it on the `calls` field of the result.
+ *
+ * The returned emitter is deliberately NOT frozen — slots stay mutable
+ * so a test can override one when it needs bespoke shape (e.g. an
+ * `emit_pool` that throws on the first call). The production
+ * `create_audit_emitter` freeze invariant exists to catch the
+ * `patch_audit_emit_capture` hot-patch footgun against the
+ * closure-captured `emit`; the recording emitter has no inner closure,
+ * so the freeze isn't load-bearing here.
+ */
+export const create_recording_audit_emitter = (calls_ref) => {
+    const calls = calls_ref ?? [];
+    const emitter = {
+        emit: (_ctx, input) => {
+            calls.push(input);
+        },
+        emit_role_grant_target: (ctx, auth, input) => {
+            calls.push({
+                event_type: input.event_type,
+                actor_id: auth.actor.id,
+                account_id: auth.account.id,
+                outcome: input.outcome,
+                target_account_id: input.target_account_id,
+                target_actor_id: input.target_actor_id,
+                ip: ctx.client_ip,
+                metadata: input.metadata,
+            });
+        },
+        emit_pool: (input) => {
+            calls.push(input);
+            return Promise.resolve();
+        },
+        notify: () => undefined,
+        on_event_chain: [],
+    };
+    return { emitter, calls };
+};
+/**
+ * Build an `audit_factory` that produces a real `create_audit_emitter`
+ * with its `emit` decorated to push a `{kind: 'emit', at: seq.value++}`
+ * marker into a shared sequence + events array. Used by the close-vs-emit
+ * ordering test to compose against a shared sequence counter (typically
+ * `create_recording_closer(seq_ref)` capturing eager-close calls).
+ *
+ * Pass the returned factory through `create_test_app({audit_factory: …})`
+ * — the test backend invokes it with its constructed `{db, log}` and
+ * lands the decorated emitter on `backend.deps.audit`. Production
+ * handlers dereference `deps.audit.emit` at call time, so the decorator
+ * sees every subsequent handler invocation. The underlying `emit` still
+ * runs — the decorator records the call, it does not suppress side
+ * effects.
+ *
+ * **Scope — both `emit` and `emit_role_grant_target`.** The decorator
+ * is captured by `emit_role_grant_target`'s closure inside
+ * `create_audit_emitter` (and re-exposed as the outer `emit` slot), so
+ * role-grant-shape emissions land in `events_ref` alongside bare `emit`
+ * calls. `emit_pool` and `notify` are not decorated — they take
+ * `AuditLogInput` / `AuditLogEvent` directly without going through
+ * `emit`, so handler-side `emit_pool` writes (today only
+ * `auth/cleanup.ts`) skip capture. Close-firing handlers all reach for
+ * `emit` or `emit_role_grant_target`, so the ordering test sees them
+ * regardless of which entry point a future refactor picks.
+ *
+ * Optionally accept `extra_options` to thread `on_audit_event` /
+ * `audit_log_config` into the inner emitter — useful when a test wants
+ * both ordering capture and a real SSE/WS guard wired into the same
+ * emitter chain.
+ */
+export const create_emit_ordering_audit_factory = (seq_ref, events_ref, extra_options) => {
+    return ({ db, log }) => create_audit_emitter({
+        ...extra_options,
+        db,
+        log,
+        emit_decorator: (inner) => (ctx, input) => {
+            events_ref.push({ kind: 'emit', at: seq_ref.value++ });
+            inner(ctx, input);
+        },
+    });
+};

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/connection_closer_helpers.d.ts

@@ -0,0 +1,44 @@
+import './assert_dev_env.js';
+import type { ConnectionCloser } from '../actions/connection_closer.js';
+/**
+ * Record of a single `ConnectionCloser` method invocation. `at` is the
+ * value of a monotonically-increasing sequence counter at the time of
+ * the call — pair with `create_emit_ordering_audit_factory` to record both
+ * close + audit emit calls into the same sequence for ordering tests.
+ */
+export interface RecordedClose {
+    method: 'session' | 'token' | 'account';
+    id: string;
+    at: number;
+}
+export interface RecordingCloser {
+    closer: ConnectionCloser;
+    calls: Array<RecordedClose>;
+}
+/**
+ * Build a `ConnectionCloser` that records every call into `calls` rather
+ * than touching real transports. Each method returns 1 ("one socket
+ * closed") regardless of whether a real socket exists — handlers
+ * typically ignore the return value.
+ *
+ * Pass `seq_ref` to share the sequence counter with a sibling
+ * `create_emit_ordering_audit_factory` so tests can pin close-vs-emit
+ * ordering at the handler call site. Without `seq_ref`, the closer
+ * uses a fresh internal counter — `at: N` values within a single test
+ * are meaningful, but cannot be compared against audit emit ordering.
+ */
+export declare const create_recording_closer: (seq_ref?: {
+    value: number;
+}) => RecordingCloser;
+/**
+ * Pin `{method, id}` on a single recorded close call without baking in
+ * the `at: N` sequence number. Use at every "did the closer fire?"
+ * assertion site; the sequence number is only meaningful for dedicated
+ * ordering tests (paired with `create_emit_ordering_audit_factory`).
+ *
+ * Throws via `assert.ok` if `call` is `undefined` — index a recorded
+ * `calls` array directly (`calls[0]`) and let this helper handle the
+ * missing-element case.
+ */
+export declare const assert_close_call: (call: RecordedClose | undefined, method: "session" | "token" | "account", id: string) => void;
+//# sourceMappingURL=connection_closer_helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection_closer_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/connection_closer_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,iCAAiC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,KAAG,eAkBnE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,aAAa,GAAG,SAAS,EAC/B,QAAQ,SAAS,GAAG,OAAO,GAAG,SAAS,EACvC,IAAI,MAAM,KACR,IAIF,CAAC"}

package/dist/testing/connection_closer_helpers.js

@@ -0,0 +1,48 @@
+import './assert_dev_env.js';
+import { assert } from 'vitest';
+/**
+ * Build a `ConnectionCloser` that records every call into `calls` rather
+ * than touching real transports. Each method returns 1 ("one socket
+ * closed") regardless of whether a real socket exists — handlers
+ * typically ignore the return value.
+ *
+ * Pass `seq_ref` to share the sequence counter with a sibling
+ * `create_emit_ordering_audit_factory` so tests can pin close-vs-emit
+ * ordering at the handler call site. Without `seq_ref`, the closer
+ * uses a fresh internal counter — `at: N` values within a single test
+ * are meaningful, but cannot be compared against audit emit ordering.
+ */
+export const create_recording_closer = (seq_ref) => {
+    const calls = [];
+    const seq = seq_ref ?? { value: 0 };
+    const closer = {
+        close_sockets_for_session: (id) => {
+            calls.push({ method: 'session', id, at: seq.value++ });
+            return 1;
+        },
+        close_sockets_for_token: (id) => {
+            calls.push({ method: 'token', id, at: seq.value++ });
+            return 1;
+        },
+        close_sockets_for_account: (id) => {
+            calls.push({ method: 'account', id, at: seq.value++ });
+            return 1;
+        },
+    };
+    return { closer, calls };
+};
+/**
+ * Pin `{method, id}` on a single recorded close call without baking in
+ * the `at: N` sequence number. Use at every "did the closer fire?"
+ * assertion site; the sequence number is only meaningful for dedicated
+ * ordering tests (paired with `create_emit_ordering_audit_factory`).
+ *
+ * Throws via `assert.ok` if `call` is `undefined` — index a recorded
+ * `calls` array directly (`calls[0]`) and let this helper handle the
+ * missing-element case.
+ */
+export const assert_close_call = (call, method, id) => {
+    assert.ok(call, 'expected a recorded close call');
+    assert.strictEqual(call.method, method);
+    assert.strictEqual(call.id, id);
+};

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);
+    }
+};