@fuzdev/fuz_app 0.62.0 → 0.64.0

package/dist/server/app_server.d.ts

@@ -8,6 +8,7 @@
  * @module
  */
 import { Hono, type Context } from 'hono';
+import type { UpgradeWebSocket } from 'hono/ws';
 import { z } from 'zod';
 import { type SessionOptions } from '../auth/session_cookie.js';
 import type { BootstrapAccountSuccess } from '../auth/bootstrap_account.js';
@@ -25,6 +26,8 @@ import { type AppSurfaceSpec, type RpcEndpointSpec } from '../http/surface.js';
 import { type RouteSpec } from '../http/route_spec.js';
 import type { MiddlewareSpec } from '../http/middleware_spec.js';
 import { type BootstrapStatus } from '../auth/bootstrap_routes.js';
+import type { WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
+import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 /**
  * Context passed to `on_effect_error` when a pending effect rejects.
  */
@@ -163,6 +166,50 @@ export interface AppServerOptions {
      * `create_standard_rpc_actions(ctx.deps, {app_settings: ctx.app_settings})`.
      */
     rpc_endpoints?: Array<RpcEndpointSpec> | ((context: AppServerContext) => Array<RpcEndpointSpec>);
+    /**
+     * Hono adapter's `upgradeWebSocket` helper. Required whenever
+     * `ws_endpoints` resolves to a non-empty array — `create_app_server`
+     * throws at assembly otherwise. Omit (along with `ws_endpoints`)
+     * when the consumer doesn't mount any WS endpoints. The same
+     * adapter helper services every `WsEndpointSpec` mounted from
+     * `ws_endpoints` — one adapter per app.
+     *
+     * For Node, `import {upgradeWebSocket} from '@hono/node-ws'`. For
+     * Deno, `import {upgradeWebSocket} from 'hono/deno'`. Test harnesses
+     * use `create_stub_upgrade` from `$lib/testing/ws_round_trip.ts`.
+     */
+    upgradeWebSocket?: UpgradeWebSocket;
+    /**
+     * WebSocket endpoint specs — single source of truth for both surface
+     * generation *and* live dispatch. Each entry is auto-mounted via
+     * `register_ws_endpoint` against the assembled Hono app, so
+     * consumers no longer call `register_ws_endpoint` themselves.
+     *
+     * Accepts either an array (evaluated eagerly) or a factory
+     * `(ctx: AppServerContext) => ReadonlyArray<WsEndpointSpec>`
+     * (evaluated after the server context is assembled). Use the factory
+     * form when action lists depend on `ctx.deps` /
+     * `ctx.action_*_rate_limiter` — e.g. when spreading
+     * `create_standard_rpc_actions(ctx.deps, ...)` over WS.
+     *
+     * When non-empty, `upgradeWebSocket` must be supplied (throws
+     * otherwise). A factory returning `[]` does NOT trip the check —
+     * feature-flag gated WS surfaces stay safe.
+     *
+     * Duplicate `path` values across two `WsEndpointSpec`s throw at
+     * mount time (Hono would silently shadow them otherwise).
+     *
+     * Each spec's `auth_guard?` defaults to `true` — the factory
+     * composes `create_ws_auth_guard` + `create_ws_logout_closer`
+     * against the mounted transport and appends them to
+     * `deps.audit.on_event_chain`. Wiring is deduped by transport
+     * **reference identity** so two specs sharing one
+     * `BackendWebsocketTransport` instance get a single pair of
+     * listeners; wrapped / proxied transports dedupe as separate
+     * entries (set `auth_guard: false` on duplicates and compose
+     * against the underlying transport once).
+     */
+    ws_endpoints?: ReadonlyArray<WsEndpointSpec> | ((context: AppServerContext) => ReadonlyArray<WsEndpointSpec>);
     /**
      * Env schema for surface generation. Defaults to `BaseServerEnv` —
      * pass an extended schema (typically `BaseServerEnv.extend({...})`)
@@ -241,6 +288,19 @@ export interface AppServer {
      * Use `require_audit_sse(server)` to assert the invariant.
      */
     audit_sse: AuditLogSse | null;
+    /**
+     * Path-keyed map of mounted WS endpoints. Each value is the
+     * `BackendWebsocketTransport` `create_app_server` registered
+     * connections against — supplied via `WsEndpointSpec.transport` or
+     * auto-created when omitted. Retain for broadcast / fan-out:
+     *
+     * ```ts
+     * app_server.ws_endpoints['/api/ws'].send_to_account(account_id, msg);
+     * ```
+     *
+     * Empty when no `ws_endpoints` were mounted.
+     */
+    ws_endpoints: Readonly<Record<string, BackendWebsocketTransport>>;
     /** Close the database connection. Propagated from `AppBackend`. */
     close: () => Promise<void>;
 }

package/dist/server/app_server.d.ts.map

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

package/dist/server/app_server.js

@@ -32,6 +32,9 @@ import { fuz_auth_guard_resolver } from '../auth/auth_guard_resolver.js';
 import { create_fuz_authorization_handler } from '../auth/request_context.js';
 import { ERROR_PAYLOAD_TOO_LARGE } from '../http/error_schemas.js';
 import { create_rpc_endpoint } from '../actions/action_rpc.js';
+import { register_ws_endpoint } from '../actions/register_ws_endpoint.js';
+import { create_ws_auth_guard, create_ws_logout_closer, } from '../actions/transports_ws_auth_guard.js';
+import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 /**
  * Assert that `audit_sse` was wired by `create_app_server` and return it
  * as a non-null `AuditLogSse`. Throws a labelled error when the
@@ -127,7 +130,15 @@ export const create_app_server = async (options) => {
     const app_settings = await query_app_settings_load({ db: deps.db });
     // Surface route ref — factory manages the circular ref
     const surface_ref = {
-        surface: { middleware: [], routes: [], rpc_endpoints: [], env: [], events: [], diagnostics: [] },
+        surface: {
+            middleware: [],
+            routes: [],
+            rpc_endpoints: [],
+            ws_endpoints: [],
+            env: [],
+            events: [],
+            diagnostics: [],
+        },
     };
     // Route specs (consumer routes + factory-managed routes)
     const context = {
@@ -173,6 +184,15 @@ export const create_app_server = async (options) => {
             }));
         }
     }
+    // WS endpoint resolution — done here (alongside RPC) so the captured
+    // array threads into surface generation below. Actual mount happens
+    // after `apply_route_specs` because `register_ws_endpoint` mutates the
+    // live Hono `app` (origin / auth / role / authorization middleware +
+    // the `app.get(path, ...)` upgrade route), and `app` does not exist
+    // until the assembly phase below.
+    const resolved_ws_endpoints = typeof options.ws_endpoints === 'function'
+        ? options.ws_endpoints(context)
+        : options.ws_endpoints;
     // Surface route (default: enabled)
     if (options.surface_route !== false) {
         factory_routes.push(create_surface_route_spec(surface_ref));
@@ -192,6 +212,7 @@ export const create_app_server = async (options) => {
         env_schema: options.env_schema ?? BaseServerEnv,
         event_specs: all_event_specs,
         rpc_endpoints: resolved_rpc_endpoints,
+        ws_endpoints: resolved_ws_endpoints,
     });
     // Config-level diagnostics (concatenated after spec-level from generate_app_surface)
     const config_diagnostics = [];
@@ -215,7 +236,7 @@ export const create_app_server = async (options) => {
             config_diagnostics.push({
                 level: 'warning',
                 category: 'security',
-                message: 'Session cookie httpOnly=false — cookie accessible to JavaScript',
+                message: 'Session cookie httpOnly=false — cookie accessible to JS',
             });
         }
     }
@@ -291,6 +312,77 @@ export const create_app_server = async (options) => {
     apply_middleware_specs(app, middleware_specs);
     const authorize = create_fuz_authorization_handler({ db: deps.db });
     apply_route_specs(app, route_specs, fuz_auth_guard_resolver, log, deps.db, authorize);
+    // WS endpoint auto-mount — must run after `app` exists and
+    // `apply_route_specs` has registered the request routes. Each spec
+    // becomes a `register_ws_endpoint` call, plus optional `auth_guard`
+    // wiring onto the audit chain. `post_route_middleware` and static
+    // serving register after this loop, so WS upgrade routes sit
+    // adjacent to the consumer routes and ahead of the static fallback —
+    // matches the "WS mount is route registration" mental model.
+    const mounted_ws_endpoints = {};
+    if (resolved_ws_endpoints?.length) {
+        if (options.upgradeWebSocket === undefined) {
+            throw new Error('create_app_server: ws_endpoints resolved non-empty but upgradeWebSocket is missing. ' +
+                "Pass the Hono adapter's upgradeWebSocket helper as a top-level option.");
+        }
+        // Cross-surface collision: `register_ws_endpoint` mounts a `GET path`
+        // upgrade route. If a `RouteSpec` already registered `GET path`,
+        // Hono's last-wins semantics would silently shadow the consumer's
+        // GET route — fail fast instead.
+        const route_spec_get_paths = new Set();
+        for (const r of route_specs) {
+            if (r.method === 'GET')
+                route_spec_get_paths.add(r.path);
+        }
+        const seen_paths = new Set();
+        // Dedupe `auth_guard` wiring by transport reference — two specs
+        // sharing one transport instance get a single pair of listeners,
+        // otherwise revocation events would fire `close_sockets_for_*`
+        // twice per event (idempotent on the transport but log-spammy).
+        // Cross-spec OR-semantics: any spec with `auth_guard !== false`
+        // wires the guard for that transport; once wired, sibling specs
+        // (even with explicit `auth_guard: false`) cannot opt out. To
+        // disable, every spec sharing the transport must pass `auth_guard: false`.
+        const guarded_transports = new WeakSet();
+        for (const endpoint of resolved_ws_endpoints) {
+            if (seen_paths.has(endpoint.path)) {
+                throw new Error(`create_app_server: duplicate ws_endpoints path: ${endpoint.path}`);
+            }
+            if (route_spec_get_paths.has(endpoint.path)) {
+                throw new Error(`create_app_server: ws_endpoints path collides with a GET RouteSpec: ${endpoint.path}`);
+            }
+            seen_paths.add(endpoint.path);
+            const endpoint_transport = endpoint.transport ?? new BackendWebsocketTransport();
+            register_ws_endpoint({
+                app,
+                path: endpoint.path,
+                upgradeWebSocket: options.upgradeWebSocket,
+                allowed_origins: endpoint.allowed_origins,
+                db: deps.db,
+                actions: endpoint.actions,
+                transport: endpoint_transport,
+                heartbeat: endpoint.heartbeat,
+                artificial_delay: endpoint.artificial_delay,
+                on_socket_open: endpoint.on_socket_open,
+                on_socket_close: endpoint.on_socket_close,
+                log,
+                required_roles: endpoint.required_roles,
+                action_ip_rate_limiter,
+                action_account_rate_limiter,
+            });
+            mounted_ws_endpoints[endpoint.path] = endpoint_transport;
+            if (endpoint.auth_guard !== false && !guarded_transports.has(endpoint_transport)) {
+                guarded_transports.add(endpoint_transport);
+                deps.audit.on_event_chain.push(create_ws_auth_guard(endpoint_transport, log));
+                deps.audit.on_event_chain.push(create_ws_logout_closer(endpoint_transport, log));
+            }
+            if (endpoint.extra_audit_handlers?.length) {
+                for (const handler of endpoint.extra_audit_handlers) {
+                    deps.audit.on_event_chain.push(handler);
+                }
+            }
+        }
+    }
     // Post-route middleware (before static serving)
     if (options.post_route_middleware) {
         apply_middleware_specs(app, options.post_route_middleware);
@@ -309,6 +401,7 @@ export const create_app_server = async (options) => {
         app_settings,
         migration_results: backend.migration_results,
         audit_sse,
+        ws_endpoints: mounted_ws_endpoints,
         close: backend.close,
     };
 };

package/dist/server/startup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"startup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/startup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC/B,SAAS,UAAU,EACnB,KAAK,MAAM,EACX,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAClC,IAqCF,CAAC"}
+{"version":3,"file":"startup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/startup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC/B,SAAS,UAAU,EACnB,KAAK,MAAM,EACX,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAClC,IAkDF,CAAC"}

package/dist/server/startup.js

@@ -17,6 +17,18 @@ import { format_env_display_value } from '../env/mask.js';
  */
 export const log_startup_summary = (surface, log, env_values) => {
     log.info(`Surface: ${surface.routes.length} routes, ${surface.middleware.length} middleware layers`);
+    // Endpoint surfaces — logged when non-empty so operators can confirm
+    // auto-mount picked up the expected actions (and so a factory that
+    // silently returns `[]` is loud at boot instead of a method_not_found
+    // at first call).
+    if (surface.rpc_endpoints.length) {
+        const rpc_method_count = surface.rpc_endpoints.reduce((sum, ep) => sum + ep.methods.length, 0);
+        log.info(`RPC: ${surface.rpc_endpoints.length} endpoint(s), ${rpc_method_count} method(s)`);
+    }
+    if (surface.ws_endpoints.length) {
+        const ws_method_count = surface.ws_endpoints.reduce((sum, ep) => sum + ep.methods.length, 0);
+        log.info(`WS: ${surface.ws_endpoints.length} endpoint(s), ${ws_method_count} method(s)`);
+    }
     if (surface.env.length) {
         const required = surface.env.filter((e) => !e.optional);
         const secret = surface.env.filter((e) => e.sensitivity === 'secret');

package/dist/testing/CLAUDE.md

@@ -6,43 +6,37 @@ round-trip harnesses. Consumers import these to assemble their own test suites
 against a fuz_app-derived server.
 
 For narrative wiring examples (how to call these from a consumer's vitest
-setup), see `../../../docs/testing.md`. For fuz_app's own test suite
-conventions (`.db.test.ts` suffix, the `db` vitest project, `assert_rejects`),
-see `../../test/CLAUDE.md`. This file is a reference index for the helpers
-themselves.
+setup), see ../../../docs/testing.md. For fuz_app's own test suite
+conventions, see ../../test/CLAUDE.md. For shared testing conventions
+(`.db.test.ts`, `assert` from vitest, `assert_rejects`, `vi.mock` caveats),
+see Skill(fuz-stack) testing-patterns. This file is a reference index for
+the helpers themselves.
 
 ## Production guard — always the first import
 
-Every module in this directory starts with `import './assert_dev_env.js';`
-as its first line. The side-effect import reads `DEV` from `esm-env` and
-throws if it is false — preventing accidental inclusion in production
-bundles. SvelteKit and Vite set `DEV` correctly for dev + tests; the
-production code path explodes at the first testing-module import.
-
-When adding a new module to this directory, make this import the first
-line. The convention is enforced by grep, not by a linter — break it and
-the production bundle still builds, then crashes at runtime on first
-module load.
+Every module here starts with `import './assert_dev_env.js';` — reads `DEV`
+from `esm-env` and throws if false, preventing production-bundle inclusion.
+Enforced by grep, not a linter; make this the first line in new modules.
 
 ## Stubs, factories, mocks
 
 ### `stubs.ts` — `AppDeps` + `AppServerContext` stubs
 
-| Helper                                                | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `create_throwing_stub<T>(label)`                      | Proxy whose every property access throws `Throwing stub 'label' — unexpected access to 'prop'`; JS-internal probes return `undefined`; `toJSON` returns `"[throwing_stub:label]"` so accidental serialization is visible rather than `{}`.                                                                                                                                                                                                                                                                                          |
-| `create_noop_stub<T>(label, overrides?)`              | Proxy whose every method returns `async () => undefined`; `overrides` lets callers pin specific props.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `stub`                                                | Pre-built throwing stub labelled `'stub'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `create_stub_db()`                                    | Returns a real `Db` whose `client.query` yields `{rows: []}` and whose `transaction(fn)` synchronously calls `fn(inner_stub_db)`. Safe for `apply_route_specs`'s declarative transaction wrapper.                                                                                                                                                                                                                                                                                                                                   |
-| `stub_handler()`                                      | Returns a fresh `Response('stub')`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `stub_mw`                                             | Pass-through middleware handler (`async (_c, next) => next()`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `stub_app_deps`                                       | Frozen `AppDeps` — every capability is a throwing stub, `audit` is a no-op `AuditEmitter` from `create_test_audit_emitter`.                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `create_stub_app_deps()`                              | Factory returning fresh `AppDeps` with no-op FS/keyring/password, a `create_noop_stub` DB, silent `Logger`, no-op `audit`.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `create_test_audit_emitter()`                         | No-op `AuditEmitter` for tests that don't assert on audit fan-out. `emit` / `emit_role_grant_target` are no-ops; `emit_pool` resolves immediately; `notify` is a no-op; `on_event_chain` is empty.                                                                                                                                                                                                                                                                                                                                  |
-| `create_stub_audit_sse()`                             | No-op `AuditLogSse` for surface-test wiring without booting real SSE. `subscribe` returns a no-op cleanup; `on_audit_event` is a no-op; the `registry` is a fresh `SubscriberRegistry` (live `.size` / `.close_*` for tests touching registry state, isolated per call). For real SSE plumbing, build via `create_audit_log_sse` against `create_test_app`.                                                                                                                                                                         |
-| `create_stub_api_middleware({include_daemon_token?})` | Stub `MiddlewareSpec[]` matching `create_auth_middleware_specs`'s output (origin/session/request_context/bearer_auth, optional daemon_token) for surface generation without booting real auth. See `../auth/CLAUDE.md` §Middleware for the real stack.                                                                                                                                                                                                                                                                              |
-| `create_stub_app_server_context(session_options)`     | Stub `AppServerContext` — rate limiters null, `bootstrap_status.available: false`, `app_settings.open_signup: false`.                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `create_test_app_surface_spec(options)`               | Builds an `AppSurfaceSpec` that mirrors `create_app_server`'s route assembly: consumer routes + factory-managed bootstrap routes (prefixed via `bootstrap_route_prefix`, default `'/api/account'`) + stub middleware + surface generation. `CreateTestAppSurfaceSpecOptions` accepts `session_options`, `create_route_specs`, `env_schema?`, `event_specs?`, `rpc_endpoints?`, `transform_middleware?`, `bootstrap_route_prefix?`. Single source of truth for attack-surface tests — track `create_app_server` wiring changes here. |
+| Helper                                                | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create_throwing_stub<T>(label)`                      | Proxy whose every property access throws `Throwing stub 'label' — unexpected access to 'prop'`; JS-internal probes return `undefined`; `toJSON` returns `"[throwing_stub:label]"` so accidental serialization is visible rather than `{}`.                                                                                                                                                                                                                                                                                                           |
+| `create_noop_stub<T>(label, overrides?)`              | Proxy whose every method returns `async () => undefined`; `overrides` lets callers pin specific props.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `stub`                                                | Pre-built throwing stub labelled `'stub'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `create_stub_db()`                                    | Returns a real `Db` whose `client.query` yields `{rows: []}` and whose `transaction(fn)` synchronously calls `fn(inner_stub_db)`. Safe for `apply_route_specs`'s declarative transaction wrapper.                                                                                                                                                                                                                                                                                                                                                    |
+| `stub_handler()`                                      | Returns a fresh `Response('stub')`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `stub_mw`                                             | Pass-through middleware handler (`async (_c, next) => next()`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `stub_app_deps`                                       | Frozen `AppDeps` — every capability is a throwing stub, `audit` is a no-op `AuditEmitter` from `create_test_audit_emitter`.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `create_stub_app_deps()`                              | Factory returning fresh `AppDeps` with no-op FS/keyring/password, a `create_noop_stub` DB, silent `Logger`, no-op `audit`.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `create_test_audit_emitter()`                         | No-op `AuditEmitter` for tests that don't assert on audit fan-out. `emit` / `emit_role_grant_target` are no-ops; `emit_pool` resolves immediately; `notify` is a no-op; `on_event_chain` is empty.                                                                                                                                                                                                                                                                                                                                                   |
+| `create_stub_audit_sse()`                             | No-op `AuditLogSse` for surface-test wiring without booting real SSE. `subscribe` returns a no-op cleanup; `on_audit_event` is a no-op; the `registry` is a fresh `SubscriberRegistry` (live `.size` / `.close_*` for tests touching registry state, isolated per call). For real SSE plumbing, build via `create_audit_log_sse` against `create_test_app`.                                                                                                                                                                                          |
+| `create_stub_api_middleware({include_daemon_token?})` | Stub `MiddlewareSpec[]` matching `create_auth_middleware_specs`'s output (origin/session/request_context/bearer_auth, optional daemon_token) for surface generation without booting real auth. See `auth/CLAUDE.md` §Middleware for the real stack.                                                                                                                                                                                                                                                                                                  |
+| `create_stub_app_server_context(session_options)`     | Stub `AppServerContext` — rate limiters null, `bootstrap_status.available: false`, `app_settings.open_signup: false`.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `create_test_app_surface_spec(options)`               | Builds an `AppSurfaceSpec` that mirrors `create_app_server`'s route assembly: consumer routes + factory-managed bootstrap routes (prefixed via `bootstrap_route_prefix`, default `'/api/account'`) + stub middleware + surface generation. `CreateTestAppSurfaceSpecOptions` accepts `session_options`, `create_route_specs`, `env_schema?`, `event_specs?`, `rpc_endpoints?`, `ws_endpoints?`, `transform_middleware?`, `bootstrap_route_prefix?`. Single source of truth for attack-surface tests — track `create_app_server` wiring changes here. |
 
 Throwing stubs surface mock escape: a test that accidentally reaches into
 stub territory breaks immediately with a label-scoped error rather than
@@ -88,6 +82,25 @@ DB rows but not a full session/token bundle. For tests that also need
 an API token + session cookie + role_grants, use `bootstrap_test_account`
 from `app_server.ts` instead.
 
+### `audit_drift_guard.ts` — audit-emission validation
+
+| Helper                                                                    | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `install_audit_drift_guard()`                                             | `beforeEach` resets + `afterEach` zero-checks the `audit_metadata_validation_failures` + `audit_unknown_event_type_failures` counters from `auth/audit_log_queries.ts`. Call once at the top of any `describe_db` block that fires audit emits — production validation is fail-open, so without this any regression that ships a typo'd `event_type` or an undeclared metadata field is silent. Pair with `await_pending_effects: true` (the `create_test_app` default) so fire-and-forget audit writes have completed by response time.                                                                                                                                                                                                                                           |
+| `create_emit_ordering_audit_factory<E>(seq_ref, events_ref, build_inner)` | Returns an `AuditFactory` that wraps the result of `build_inner({db, log})` so every `emit` call pushes `{kind: 'emit', at: seq.value++}` into a shared sequence + events array. Pass through `create_test_app({audit_factory: …})` — the test backend invokes it with its constructed `{db, log}` and lands the wrapped emitter on `deps.audit`. Generic `E extends {kind: string; at: number}` so the events array typechecks against the caller's own `close` / custom marker shape. Pair with `create_recording_closer(seq_ref)` (in `connection_closer_helpers.ts`) for close-vs-emit ordering tests. Scope is `emit` only — `emit_role_grant_target`, `emit_pool`, `notify` forward to the inner emitter unwrapped (same caveat as the previous `patch_audit_emit_capture`). |
+| `AuditEmitMarker`                                                         | `{kind: 'emit'; at: number}` — the type of marker `create_emit_ordering_audit_factory` pushes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `create_recording_audit_emitter(calls_ref?)`                              | Build a no-op `AuditEmitter` that pushes every `emit` and `emit_pool` call into `calls`. Pass `calls_ref` to write into a caller-owned array; omit to let the helper allocate one. Returns `{emitter, calls}` — destructure `emitter` as the `audit` dep and read `calls` to assert on captured metadata. Replaces per-file capturing emitters previously duplicated across `password_change.test.ts`, `audit_log.test.ts`, etc.                                                                                                                                                                                                                                                                                                                                                   |
+| `RecordingAuditEmitter`                                                   | `{emitter: AuditEmitter; calls: Array<AuditLogInput>}` — return shape of `create_recording_audit_emitter`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
+### `connection_closer_helpers.ts` — `ConnectionCloser` test doubles
+
+| Helper                                | Role                                                                                                                                                                                                                                              |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create_recording_closer(seq_ref?)`   | Returns `{closer, calls}` where every method on `closer` records `{method, id, at}` into `calls`. Pass `seq_ref` to share the sequence counter with `create_emit_ordering_audit_factory` so close + emit markers compose for ordering tests.      |
+| `assert_close_call(call, method, id)` | Pins `{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; reserve `at: N` assertions for the dedicated ordering test paired with the capture helper. |
+| `RecordedClose`                       | `{method: 'session' \| 'token' \| 'account', id, at}` — recorded shape pushed by the closer.                                                                                                                                                      |
+| `RecordingCloser`                     | `{closer, calls}` — return shape of `create_recording_closer`.                                                                                                                                                                                    |
+
 ## Database — `db.ts`
 
 Factory builders for parameterized DB tests. Consumer projects pass their
@@ -146,13 +159,13 @@ Key module-scope values:
 "insert account + actor + roles + API token + session + cookie" flow.
 Takes `{db, keyring, session_options, password, username?, password_value?, roles?}`.
 
-| Type                                                | Shape                                                                                                                                                      |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TestAppServer extends AppBackend`                  | Adds `account`, `actor`, `api_token`, `session_cookie`, `keyring`, `cleanup()`.                                                                            |
-| `TestAppServerOptions`                              | `session_options` (required), optional `db`, `db_type`, `password`, `username`, `password_value`, `roles`, `on_audit_event`, `audit_log_config`.           |
-| `CreateTestAppOptions extends TestAppServerOptions` | Adds `create_route_specs` (required) + `app_options` (narrow `Partial<AppServerOptions>` excluding the three the helper manages).                          |
-| `TestAccount`                                       | `{account, actor, session_cookie, api_token, create_session_headers, create_bearer_headers}`.                                                              |
-| `TestApp`                                           | `{app, backend, surface_spec, surface, route_specs, create_session_headers, create_bearer_headers, create_daemon_token_headers, create_account, cleanup}`. |
+| Type                                                | Shape                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `TestAppServer extends AppBackend`                  | Adds `account`, `actor`, `api_token`, `session_cookie`, `keyring`, `cleanup()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `TestAppServerOptions`                              | `session_options` (required), optional `db`, `db_type`, `password`, `username`, `password_value`, `roles`, `audit_factory`. The optional `audit_factory` defaults to `default_audit_factory` (no-listener `create_audit_emitter` over the test backend's `{db, log}`); pass a custom factory to compose `on_audit_event` / `audit_log_config`, wrap with `emit_decorator` (via `create_emit_ordering_audit_factory`), or otherwise replace the emitter. Mirrors `CreateAppBackendOptions` end-to-end — the previous `on_audit_event` / `audit_log_config` sugar was removed alongside the production rename. |
+| `CreateTestAppOptions extends TestAppServerOptions` | Adds `create_route_specs` (required), `rpc_endpoints?: RpcEndpointsSuiteOption` (top-level only — single source of truth, symmetric with the suite-level option), and `app_options?: SuiteAppOptions` (`Partial<AppServerOptions>` excluding the four fields the helper manages: `backend`, `session_options`, `create_route_specs`, `rpc_endpoints`).                                                                                                                                                                                                                                                       |
+| `TestAccount`                                       | `{account, actor, session_cookie, api_token, create_session_headers, create_bearer_headers}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `TestApp`                                           | `{app, backend, surface_spec, surface, route_specs, create_session_headers, create_bearer_headers, create_daemon_token_headers, create_account, cleanup}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 `create_test_app` hard-codes the test-friendly `AppServerOptions`:
 `allowed_origins: [/^http:\/\/localhost/]`, stub proxy pinned to
@@ -219,6 +232,21 @@ Structural invariants (options-free, apply universally):
 | `assert_error_code_status_consistency`    | The same `z.literal()` error code never appears at two different HTTP statuses.                  |
 | `assert_404_schemas_use_specific_errors`  | Routes with params declaring 404 must use `z.literal()` or `z.enum()`, not generic `z.string()`. |
 
+RPC / WS structural invariants (options-free, apply universally over
+`surface.rpc_endpoints` + `surface.ws_endpoints`):
+
+| Assertion                                      | Checks                                                                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `assert_rpc_method_descriptions_present`       | Every RPC method on every endpoint has a non-empty `description`.                                                         |
+| `assert_ws_method_descriptions_present`        | Every WS method on every endpoint has a non-empty `description`.                                                          |
+| `assert_ws_endpoints_include_protocol_actions` | Every WS endpoint includes `heartbeat` + `cancel` (the `protocol_actions` spread from `actions/protocol.js`).             |
+| `assert_ws_notifications_have_null_auth`       | WS method `kind === 'remote_notification' ⟺ auth === null` — guards against drift between spec union and surface emitter. |
+
+Per-endpoint duplicate method names and the auth-shape biconditional are
+already enforced at startup by `compile_action_registry` (see
+`actions/CLAUDE.md` §Registry compile) — these assertions only cover
+contract-surface concerns a runtime registration check cannot reach.
+
 Policy invariants (configurable, sensible defaults):
 
 | Assertion                               | Checks                                                                                                                                             |
@@ -254,7 +282,8 @@ Tightness audit:
 
 Aggregate runners (called by the standard attack-surface suite):
 
-- `assert_surface_invariants(surface)` — runs all structural assertions.
+- `assert_surface_invariants(surface)` — runs all route-level structural assertions.
+- `assert_rpc_ws_surface_invariants(surface)` — runs all RPC/WS structural assertions.
 - `assert_surface_security_policy(surface, options?)` — runs all policy assertions.
 
 ### `error_coverage.ts` — reachability tracking
@@ -337,7 +366,7 @@ Single-call bundle of 5 top-level groups (10 named tests + every
 adversarial case per route):
 
 1. **attack surface snapshot** — `matches committed snapshot`, `is deterministic`.
-2. **attack surface structure** — `only expected public routes`, `full middleware stack on API routes`, `surface invariants`, `security policy`, `error schema tightness` (logs counts and asserts against `default_error_schema_tightness` by default; pass an override config or `null` via `error_schema_tightness`).
+2. **attack surface structure** — `only expected public routes`, `full middleware stack on API routes`, `surface invariants`, `rpc/ws surface invariants`, `security policy`, `error schema tightness` (logs counts and asserts against `default_error_schema_tightness` by default; pass an override config or `null` via `error_schema_tightness`).
 3. **adversarial HTTP auth enforcement** — `unauthenticated → 401`, `wrong role → 403` × roles, `authenticated without role → 403`, `keeper routes reject session credential → 403`, `correct auth passes guard`.
 4. **adversarial input validation** — delegated to `describe_adversarial_input`.
 5. **adversarial 404 response validation** — delegated to `describe_adversarial_404`.
@@ -390,8 +419,8 @@ body matches the declared 404 Zod schema. No DB needed.
 3. no auth headers → passes through
 4. bearer + empty Origin → 403 `ERROR_FORBIDDEN_ORIGIN` (defense-in-depth)
 5. lowercase `bearer` scheme → RFC 7235 §2.1 soft-fail
-6. bearer + rogue Referer → 403 `ERROR_FORBIDDEN_REFERER`
-7. bearer + allowed Referer → bearer silently discarded
+6. bearer + rogue Referer (no Origin) → passes origin check (Origin-only posture), bearer silently discarded (Referer is still a browser-context indicator for bearer auth)
+7. bearer + allowed Referer (no Origin) → bearer silently discarded (browser context)
 
 Each case declares `validate_expectation: 'called' | 'not_called'` so the
 suite asserts that short-circuit middleware actually fires before token
@@ -572,7 +601,7 @@ Options: `{session_options, create_route_specs, app_options?, db_factories?}`.
 
 7 test groups covering admin surface: account listing, role_grant grant
 lifecycle (via `role_grant_offer_create` + `role_grant_revoke` RPC flows —
-**not** REST; see `../auth/CLAUDE.md` for `role_grant_offer_action_specs.ts` + `role_grant_offer_actions.ts`), session / token management, audit log reads (RPC),
+**not** REST; see `auth/CLAUDE.md` for `role_grant_offer_action_specs.ts` + `role_grant_offer_actions.ts`), session / token management, audit log reads (RPC),
 admin-to-admin isolation, error coverage, response schema validation.
 
 Required options: `{session_options, create_route_specs, roles: RoleSchemaResult, rpc_endpoints: RpcEndpointsSuiteOption, admin_prefix?, app_options?, db_factories?}`.
@@ -581,8 +610,9 @@ Required options: `{session_options, create_route_specs, roles: RoleSchemaResult
 the same `RpcEndpointsSuiteOption` union every DB-backed suite accepts
 (`integration`, `admin_integration`, `audit_completeness`, `rate_limiting`,
 `rpc_round_trip`, `sse_round_trip`). Prefer the factory form: it forwards
-raw to `app_options.rpc_endpoints` so `create_app_server` resolves it per-test
-with the real ctx — the only way action handlers can close over
+raw to the top-level `rpc_endpoints` slot on `CreateTestAppOptions` so
+`create_app_server` resolves it per-test with the real ctx — the only way
+action handlers can close over
 `ctx.deps` / `ctx.app_settings` (e.g. `create_standard_rpc_actions(ctx.deps,
 {app_settings: ctx.app_settings})`). Factory must return the same endpoint
 `path` regardless of ctx — `resolve_rpc_endpoints_for_setup` invokes it
@@ -688,7 +718,7 @@ Registry lookups:
    - unauthenticated → `unauthenticated` (code -32001)
    - wrong role → `forbidden` (-32002)
    - authenticated without role → `forbidden`
-   - **keeper rejects non-daemon credentials** — session and api_token credentials are rejected even when the account has the keeper role (only `daemon_token` passes). The credential-type gate fires before the role gate (see `../auth/CLAUDE.md` §`request_context.ts` for `require_credential_types`).
+   - **keeper rejects non-daemon credentials** — session and api_token credentials are rejected even when the account has the keeper role (only `daemon_token` passes). The credential-type gate fires before the role gate (see `auth/CLAUDE.md` §`request_context.ts` for `require_credential_types`).
    - correct auth passes (not 401/403)
    - GET unauthenticated for `side_effects: false` reads
 2. **RPC adversarial envelopes** — fixed set exercising dispatcher steps 1–2: non-JSON body, wrong `jsonrpc` version, missing `jsonrpc` / `method` / `id`, batch array, unknown method, GET missing `method`/`id`, GET invalid JSON params, GET non-object params, GET mutation method → `invalid_request`.
@@ -705,42 +735,32 @@ not folded into `create_standard_rpc_actions` (today `self_service_role_actions`
 / round-trip coverage from `describe_rpc_attack_surface_tests` +
 `describe_rpc_round_trip_tests` unless the consumer ships a
 `<module>.rpc_suites.db.test.ts` mounting the opt-in factory on the RPC
-endpoint and calling both suites. See `../../test/CLAUDE.md` §Composable
+endpoint and calling both suites. See ../../test/CLAUDE.md §Composable
 Test Suites for the obligation note; existing
-`../../test/auth/*.rpc_suites.db.test.ts` files are templates.
+../../test/auth/\*.rpc_suites.db.test.ts files are templates.
 
 ## Cross-cutting conventions
 
-- **`assert` from vitest, not `expect`.** Project-wide convention
-  (mirrored in `src/test/CLAUDE.md`). Use `assert_rejects` from
-  `@fuzdev/fuz_util/testing.js` for async rejection assertions.
-- **`.db.test.ts` suffix** for any test file that instantiates a `Db`
-  (directly or via `create_test_app`, `create_describe_db`,
-  `create_pglite_factory`). The suffix opts the file into the `db`
-  vitest project (`isolate: false`, `fileParallelism: false`) so the
-  PGlite WASM cache is shared across every DB test file.
+Shared conventions (`.db.test.ts` suffix, `isolate: false` semantics,
+`assert` from vitest, `assert_rejects`, `vi.mock` avoidance under
+`isolate: false`) live in Skill(fuz-stack) testing-patterns.
+fuz_app-specific points:
+
 - **`await_pending_effects: true`** is set by `create_test_app`.
   Fire-and-forget effects (audit logs, session touches, WS fan-out via
   `emit_after_commit`) resolve before the response returns, so tests
   can assert on side effects inline without manual flushing.
-- **Avoid `vi.mock()` inside `.db.test.ts`.** With `isolate: false`,
-  module-level mocks leak across files. When a mock is unavoidable
-  (e.g. `middleware.ts` uses them module-level for bearer auth tests),
-  always pair with `vi.restoreAllMocks()` in `afterEach` to contain
-  the blast radius.
-- **Deep-path imports only.** `testing/` follows the package
-  convention — import from the canonical module (`./db.js`,
-  `./rpc_helpers.js`, etc.), never a barrel. fuz_app's `dist/` doesn't
-  ship one.
-- **DI via small `*Deps` interfaces.** Stub factories here accept the
-  same narrow `*Deps` contracts production code uses — never
-  `Pick<GodType, ...>`. New helpers that need env/fs/logger access
-  should take `EnvDeps` / `FsReadDeps` / `Logger` from
-  `runtime/deps.ts` or `@fuzdev/fuz_util/log.js`.
+- **Deep-path imports only.** Import from the canonical module
+  (`testing/db.js`, `testing/rpc_helpers.js`, etc.); fuz_app's `dist/` ships no
+  barrel.
+- **DI via small `*Deps` interfaces.** Stub factories accept the same
+  narrow `*Deps` contracts production code uses — never
+  `Pick<GodType, ...>`. New helpers needing env/fs/logger take
+  `EnvDeps` / `FsReadDeps` / `Logger` from `runtime/deps.ts` or
+  `@fuzdev/fuz_util/log.js`.
 - **Keep the shared echo routes in sync with public surface.** When
   middleware or public API gains a new context variable, header, or
   field, update the echo in `middleware.ts`
   (`create_bearer_auth_test_app`, `create_test_middleware_stack_app`)
-  alongside the assertions in `src/test/auth/*.test.ts`. The two move
-  together — drift between them shows up as a missed assertion, not a
-  test failure.
+  alongside the assertions in `src/test/auth/*.test.ts`. Drift surfaces
+  as a missed assertion, not a test failure.

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

@@ -1 +1 @@
-{"version":3,"file":"admin_integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/admin_integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAgC7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAA0B,KAAK,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAGtF,OAAO,EAA6C,KAAK,eAAe,EAAC,MAAM,iBAAiB,CAAC;AACjG,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AASjB,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAoB1B;;GAEG;AACH,MAAM,WAAW,mCAAmC;IACnD,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,4GAA4G;IAC5G,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAmCD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,mCAAmC,KAC1C,IA+1BF,CAAC"}
+{"version":3,"file":"admin_integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/admin_integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAgC7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAA0B,KAAK,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAGtF,OAAO,EAA6C,KAAK,eAAe,EAAC,MAAM,iBAAiB,CAAC;AACjG,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AASjB,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAoB1B;;GAEG;AACH,MAAM,WAAW,mCAAmC;IACnD,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,4GAA4G;IAC5G,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAiCD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,mCAAmC,KAC1C,IAg2BF,CAAC"}

package/dist/testing/admin_integration.js

@@ -61,10 +61,8 @@ const build_admin_test_app_options = (options, db, roles) => ({
     create_route_specs: options.create_route_specs,
     db,
     roles: roles ?? [ROLE_KEEPER, ROLE_ADMIN],
-    app_options: {
-        ...options.app_options,
-        rpc_endpoints: options.rpc_endpoints,
-    },
+    rpc_endpoints: options.rpc_endpoints,
+    app_options: options.app_options,
 });
 /**
  * Standard admin integration test suite for fuz_app admin routes.
@@ -84,7 +82,8 @@ export const describe_standard_admin_integration_tests = (options) => {
     // Hard-fail early so consumers see a clear setup error instead of a
     // confusing test failure when `rpc_endpoints` is missing. Factory-form
     // callers are resolved with a stub ctx purely to extract the endpoint
-    // path; real handlers run per-test via `app_options.rpc_endpoints`.
+    // path; real handlers run per-test via the top-level `rpc_endpoints`
+    // slot on `CreateTestAppOptions`.
     const rpc_endpoints_for_setup = resolve_rpc_endpoints_for_setup(options.rpc_endpoints, options.session_options);
     const rpc_path = require_rpc_endpoint_path(rpc_endpoints_for_setup);
     const init_schema = async (db) => {