@fuzdev/fuz_app 0.127.0 → 0.129.0

package/dist/testing/cross_backend/ws_round_trip.js

@@ -19,14 +19,15 @@ import '../assert_dev_env.js';
  * every WS endpoint — so the suite needs no knowledge of a consumer's domain
  * WS methods. It validates the transport, not the domain.
  *
- * The first three cases mirror the upgrade stack `register_ws_endpoint` wires
- * (origin check → `require_auth` → dispatch): an authenticated upgrade
- * round-trips `heartbeat`; an anonymous upgrade is refused; a
- * disallowed-origin upgrade is refused. Per-connection auth is enforced at
- * upgrade time (not per message), so the negative cases assert the upgrade
- * itself rejects rather than a per-message error frame.
+ * Three cases mirror the upgrade stack `register_ws_endpoint` wires (origin
+ * check → `require_auth` → dispatch): an authenticated upgrade round-trips
+ * `heartbeat` (the first case), and an anonymous upgrade and a
+ * disallowed-origin upgrade are refused (after the spine-parity cases).
+ * Per-connection auth is enforced at upgrade time (not per message), so the
+ * negative cases assert the upgrade itself rejects rather than a per-message
+ * error frame.
  *
- * Spine-parity cases follow. Both spines admit a connection only after
+ * Spine-parity cases follow the first. Both spines admit a connection only after
  * re-reading its credential, and requests that arrive first wait for that
  * rather than being dropped: requests sent the moment the socket opens are all
  * answered, and — gated on `capabilities.ws_handshake_pipelining`, with the
@@ -38,7 +39,8 @@ import '../assert_dev_env.js';
  * `DEFAULT_WS_MAX_MESSAGE_BYTES`) closes the socket with
  * `WS_CLOSE_MESSAGE_TOO_BIG`.
  *
- * The final cases (gated on `rpc_path`) cover server-initiated close.
+ * The cases after the refused upgrades (gated on `rpc_path`) cover
+ * server-initiated close.
  * Per-message dispatch never re-checks credential validity, so an open socket
  * ends only when a revocation closes it — which every revocation does, once
  * its transaction commits. An authenticated socket is dropped when the
@@ -48,14 +50,18 @@ import '../assert_dev_env.js';
  * `rpc_path` to skip them (consumers without the standard account and admin
  * actions on their RPC endpoint).
  *
- * One more case is gated on `capabilities.ws_account_actions` — the backend's
+ * The last cases are gated on `capabilities.ws_account_actions` — the backend's
  * WS endpoint mounts the self-service account actions: a socket that revokes
  * its own sessions *over that socket* is closed with
  * `WS_CLOSE_SESSION_REVOKED`, and — on a backend declaring
  * `capabilities.ws_self_revocation_reply` — reads the reply to its request
  * first. The TS spine queues the close behind the commit and sends the reply
  * ahead of it, so the caller is never left without an answer; the Rust spine
- * does not answer yet, which that flag records.
+ * does not answer yet, which that flag records. Under the same gate (and
+ * `rpc_path`), a socket mints an API token over WS and the token's
+ * `token_create` audit row is read back after `_testing_drain_effects` — the
+ * barrier a WS mutation needs, since a WS reply can precede its audit write.
+ * The binary's `create_testing_actions` mount provides the drain.
  *
  * Gated on `capabilities.ws` — backends without an end-to-end WS transport
  * skip (the cases still surface as `.skip` in the report). Cross-process
@@ -68,14 +74,15 @@ import { assert, describe } from 'vitest';
 import { assert_rejects } from '@fuzdev/fuz_util/testing.ts';
 import { heartbeat_action_spec } from '../../actions/heartbeat.js';
 import { DEFAULT_WS_MAX_MESSAGE_BYTES, WS_CLOSE_MESSAGE_TOO_BIG, WS_CLOSE_SESSION_REVOKED } from '../../actions/transports.js';
-import { account_session_revoke_all_action_spec } from '../../auth/account_action_specs.js';
-import { account_delete_action_spec } from '../../auth/admin_action_specs.js';
+import { account_session_revoke_all_action_spec, account_token_create_action_spec } from '../../auth/account_action_specs.js';
+import { account_delete_action_spec, audit_log_list_action_spec, AuditLogListOutput } from '../../auth/admin_action_specs.js';
 import { JSONRPC_ERROR_CODES } from '../../http/jsonrpc_errors.js';
 import { is_response_for } from '../transports/ws_client.js';
 import { create_ws_transport } from '../transports/ws_transport.js';
 import { connect_raw_ws, is_raw_ws_close, RAW_WS_OPCODE_TEXT } from '../transports/ws_raw_client.js';
 import { create_rpc_post_init } from '../rpc_helpers.js';
 import { test_if } from './capabilities.js';
+import { cross_rpc_call, expect_output } from './cell_cross_helpers.js';
 /** Origin guaranteed to fail the `http://localhost:*` allowlist the test backends run with. */
 const DISALLOWED_ORIGIN = 'http://disallowed.example';
 /**
@@ -84,7 +91,8 @@ const DISALLOWED_ORIGIN = 'http://disallowed.example';
  * oversized message closing with `WS_CLOSE_MESSAGE_TOO_BIG`, anonymous-upgrade
  * refusal, disallowed-origin refusal, and — when `rpc_path` is supplied —
  * session revocation and account deletion closing the live socket, plus a
- * self-revoking socket reading its reply before its close.
+ * self-revoking socket reading its reply before its close, and a WS mutation's
+ * audit row read back after `_testing_drain_effects`.
  */
 export const describe_cross_process_ws_tests = (options) => {
     const { setup_test, capabilities, base_url, ws_path, origin, rpc_path, max_message_bytes = DEFAULT_WS_MAX_MESSAGE_BYTES } = options;
@@ -308,5 +316,35 @@ export const describe_cross_process_ws_tests = (options) => {
                 await client.close();
             }
         });
+        // A WS mutation is answered before its effects flush, so its audit row
+        // can land after the reply. `_testing_drain_effects` is the barrier: once
+        // it returns, the row is visible on either spine.
+        test_if(capabilities.ws && capabilities.ws_account_actions && rpc_path !== undefined, "a WS mutation's audit row is visible after _testing_drain_effects", async () => {
+            const fixture = await setup_test();
+            const client = await create_ws_transport({
+                base_url,
+                ws_path,
+                cookies: fixture.transport.cookies(),
+                origin
+            });
+            try {
+                await client.request(1, account_token_create_action_spec.method, {
+                    name: 'ws drain probe',
+                    scope: { kind: 'full' },
+                    lifetime: { kind: 'eternal' }
+                });
+            }
+            finally {
+                await client.close();
+            }
+            const drained = await cross_rpc_call(fixture.fresh_transport({ origin: null }), rpc_path, '_testing_drain_effects', undefined, fixture.create_daemon_token_headers());
+            assert.ok(drained.ok, `_testing_drain_effects failed: ${JSON.stringify(drained.error)}`);
+            // `_testing_reset` wiped audit_log at setup, so the mint is the only
+            // token_create event
+            const listed = expect_output(await cross_rpc_call(fixture.transport, rpc_path, audit_log_list_action_spec.method, { event_type: 'token_create' }, fixture.create_session_headers()), AuditLogListOutput);
+            assert.strictEqual(listed.events.length, 1, JSON.stringify(listed.events));
+            assert.strictEqual(listed.events[0].outcome, 'success');
+            assert.strictEqual(listed.events[0].account_id, fixture.account.id);
+        });
     });
 };

package/dist/testing/stubs.d.ts

@@ -6,6 +6,7 @@ import type { AppDeps } from '../auth/deps.js';
 import type { AuditEmitter } from '../auth/audit_emitter.js';
 import type { BootstrapServerOptions } from '../server/app_server.js';
 import type { AppServerContext } from '../server/app_server_context.js';
+import type { AppBackend } from '../server/app_backend.js';
 import { Db } from '../db/db.js';
 import { type RouteSpec } from '../http/route_spec.js';
 import { type AppSurfaceSpec, type RpcEndpointSpec } from '../http/surface.js';
@@ -62,7 +63,8 @@ export declare const stub_mw: (_c: any, next: any) => Promise<void>;
  * immediately; `notify` is a no-op; `add_listener` throws, so a test that
  * wires a listener fails loudly instead of silently never firing
  * (`create_recording_audit_emitter` accepts listeners); `listener_count`
- * returns 0. Tests asserting on real audit-row persistence (or on listener
+ * returns 0; `drain_inflight` resolves immediately, since nothing is ever
+ * written. Tests asserting on real audit-row persistence (or on listener
  * fan-out) build a real emitter via `create_audit_emitter` against a stub or
  * real DB — `create_test_app` already does this on the test backend.
  */
@@ -78,13 +80,34 @@ export declare const create_test_audit_emitter: () => AuditEmitter;
  * `create_audit_log_sse` against `create_test_app`.
  */
 export declare const create_stub_audit_sse: () => AuditLogSse;
-/** Stub `AppDeps` for auth surface tests — throws on any method access. */
-export declare const stub_app_deps: AppDeps;
 /**
  * Create no-op `AppDeps` for auth surface testing.
  */
 export declare const create_stub_app_deps: () => AppDeps;
-/** Create the API middleware stub array matching `create_auth_middleware_specs` output. */
+/** Options for `create_stub_app_backend`. */
+export interface CreateStubAppBackendOptions {
+    /** The backend's deps. Default a fresh `create_stub_app_deps()`. */
+    deps?: AppDeps;
+    /** The backend's `close`. Default one that does nothing. */
+    close?: () => Promise<void>;
+}
+/**
+ * Create a stub `AppBackend` with no database behind it — no migration
+ * results, and a `close` that does nothing unless one is passed. For
+ * assembling a server (`create_app_server`) in tests that never reach the
+ * database; one whose `close` does nothing can host server after server.
+ *
+ * @param options - the deps and `close` to use in place of the defaults
+ */
+export declare const create_stub_app_backend: (options?: CreateStubAppBackendOptions) => AppBackend;
+/**
+ * Create the API middleware stub array matching `create_auth_middleware_specs`
+ * output — the same names, paths, order, and declared `errors` (the surface
+ * merges middleware errors into every route under the path, so a stub that
+ * declared more than the real stack would widen the test surface). Like the
+ * real factory's, each spec gets its own pass-through handler, so
+ * `assert_middleware_stack_mounted` can tell the layers apart by identity.
+ */
 export declare const create_stub_api_middleware: (options?: {
     /** Include the daemon_token middleware layer. */
     include_daemon_token?: boolean;
@@ -136,7 +159,15 @@ export interface CreateTestAppSurfaceSpecOptions {
      * the exact patterns the upgrade gate matches.
      */
     allowed_origins?: ReadonlyArray<RegExp>;
-    /** Transform middleware array (e.g., zap's `extend_middleware_for_zap_binary`). */
+    /**
+     * Transform middleware array — `AppServerOptions.transform_middleware`.
+     * Receives shallow copies of a stub `trusted_proxy` spec (at `'*'`)
+     * followed by the stub auth stack, in a fresh array, as
+     * `create_app_server` passes the real ones. Throws, like
+     * `create_app_server`, if the result doesn't keep each of those specs
+     * mounted once at its original path in its original order
+     * (`assert_middleware_stack_mounted`).
+     */
     transform_middleware?: (specs: Array<MiddlewareSpec>) => Array<MiddlewareSpec>;
     /**
      * Bootstrap config — symmetric with `AppServerOptions.bootstrap`. Discriminated
@@ -148,6 +179,23 @@ export interface CreateTestAppSurfaceSpecOptions {
      * Surface assembly only reads `route_prefix` (default `'/api/account'`).
      */
     bootstrap?: BootstrapServerOptions;
+    /**
+     * Symmetric with `AppServerOptions.surface_route` — `true` lists the
+     * admin-only `GET /api/surface`, which `create_app_server` mounts only when
+     * opted in. Pass the same value to both entry points so the surface tests
+     * probe the route exactly when the live server serves it.
+     *
+     * @default false
+     */
+    surface_route?: boolean;
+    /**
+     * List the `daemon_token` middleware layer, as `create_app_server` mounts
+     * it when given a `daemon_token_state`. Pass `true` exactly when the live
+     * server gets one — `create_test_app` always passes one.
+     *
+     * @default false
+     */
+    daemon_token?: boolean;
 }
 /**
  * Create an `AppSurfaceSpec` for the standard testing suites.
@@ -159,18 +207,25 @@ export interface CreateTestAppSurfaceSpecOptions {
  * suites consume the spec object this function returns, not the JSON
  * file.
  *
- * Mirrors `create_app_server`'s route assembly: consumer routes +
- * factory-managed bootstrap routes + surface generation — including its
+ * Mirrors `create_app_server`'s route assembly, in its order: consumer
+ * routes, then the factory-managed bootstrap routes, RPC endpoint routes, and
+ * `GET /api/surface` (with `surface_route: true`), then surface
+ * generation — including its
  * refusal of an `rpc_endpoints` or `ws_endpoints` path outside the auth
- * middleware's scope (`assert_endpoint_in_auth_scope`). If
+ * middleware's scope (`assert_endpoint_in_auth_scope`) and of a
+ * `transform_middleware` that doesn't keep the proxy and auth stack mounted
+ * (`assert_middleware_stack_mounted`). The middleware list mirrors the real
+ * one: a stub `trusted_proxy` spec at `'*'`, then the stub auth stack (with
+ * `daemon_token` when `options.daemon_token` is set). If
  * `create_app_server` changes how it wires routes, update this helper
  * to stay in sync (single source of truth for all consumers).
  *
  * @param options - surface spec options
  * @returns the surface spec for the standard suites
- * @throws Error when an endpoint path is outside `AUTH_MIDDLEWARE_PATH`, or a
+ * @throws Error when an endpoint path is outside `AUTH_MIDDLEWARE_PATH`, a
  *   `ws_endpoints` spec declares no `allowed_origins` and no `allowed_origins`
- *   option is given
+ *   option is given, or `transform_middleware` moves, drops, duplicates,
+ *   reorders, wraps, or replaces the stub proxy spec or a stub auth spec
  */
 export declare const create_test_app_surface_spec: (options: CreateTestAppSurfaceSpecOptions) => AppSurfaceSpec;
 //# sourceMappingURL=stubs.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"stubs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/stubs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stubs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/stubs.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAa7B,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACjC,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAI3E,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAS9F;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,GAAG,GAAG,EAAE,OAAO,MAAM,KAAG,CAqBtD,CAAC;AAET;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,GAAG,GAAG,EAAE,QAAQ,MAAM,EAAE,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,CAOxF,CAAC;AAET,iEAAiE;AACjE,eAAO,MAAM,IAAI,EAAE,GAAkC,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,QAAO,EAI/B,CAAC;AAEJ,gDAAgD;AAChD,eAAO,MAAM,YAAY,QAAO,QAAgC,CAAC;AAEjE,2CAA2C;AAC3C,eAAO,MAAM,OAAO,GAAU,IAAI,GAAG,EAAE,MAAM,GAAG,KAAG,OAAO,CAAC,IAAI,CAAW,CAAC;AAI3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,QAAO,YAY3C,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,QAAO,WASxC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAO,OAWtC,CAAC;AAEH,6CAA6C;AAC7C,MAAM,WAAW,2BAA2B;IAC3C,oEAAoE;IACpE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU,2BAA2B,KAAG,UAM9E,CAAC;AAKH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU;IACpD,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAC/B,KAAG,KAAK,CAAC,cAAc,CA0BvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GAC1C,iBAAiB,cAAc,CAAC,MAAM,CAAC,KACrC,gBAgBF,CAAC;AAEF,kDAAkD;AAClD,MAAM,WAAW,+BAA+B;IAC/C,6DAA6D;IAC7D,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,qFAAqF;IACrF,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,oEAAoE;IACpE,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACzB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;IAC7F;;;;;;;;OAQG;IACH,YAAY,CAAC,EACZ,aAAa,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,gBAAgB,KAAK,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;IAC5F;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,KAAK,CAAC,cAAc,CAAC,CAAC;IAC/E;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,cA4FF,CAAC"}

package/dist/testing/stubs.js

@@ -8,18 +8,19 @@ import './assert_dev_env.js';
  * @module
  */
 import { Logger } from '@fuzdev/fuz_util/log.ts';
-import { ApiError, RateLimitError } from '../http/error_schemas.js';
+import { ApiError } from '../http/error_schemas.js';
 import { create_realtime_closer } from '../actions/connection_closer.js';
 import { Db } from '../db/db.js';
 import { prefix_route_specs } from '../http/route_spec.js';
 import { bootstrap_route_shape } from '../auth/bootstrap_route_schema.js';
 import { create_rpc_endpoint } from '../actions/action_rpc.js';
+import { create_surface_route_spec } from '../server/surface_route.js';
 import { create_app_surface_spec } from '../http/surface.js';
 import { resolve_ws_endpoints } from '../actions/ws_endpoint_spec.js';
 import { AUDIT_LOG_SSE_MAX_PER_SCOPE } from '../realtime/sse_auth_guard.js';
 import { SubscriberRegistry } from '../realtime/subscriber_registry.js';
 import { BaseServerEnv } from '../server/env.js';
-import { AUTH_MIDDLEWARE_PATH, assert_endpoint_in_auth_scope } from '../auth/middleware.js';
+import { AUTH_MIDDLEWARE_PATH, assert_endpoint_in_auth_scope, assert_middleware_stack_mounted } from '../auth/middleware.js';
 /**
  * Create a Proxy that throws descriptive errors on any property access or method call.
  *
@@ -99,7 +100,8 @@ const stub_db = create_noop_stub('stub_db');
  * immediately; `notify` is a no-op; `add_listener` throws, so a test that
  * wires a listener fails loudly instead of silently never firing
  * (`create_recording_audit_emitter` accepts listeners); `listener_count`
- * returns 0. Tests asserting on real audit-row persistence (or on listener
+ * returns 0; `drain_inflight` resolves immediately, since nothing is ever
+ * written. Tests asserting on real audit-row persistence (or on listener
  * fan-out) build a real emitter via `create_audit_emitter` against a stub or
  * real DB — `create_test_app` already does this on the test backend.
  */
@@ -111,7 +113,8 @@ export const create_test_audit_emitter = () => ({
     add_listener: () => {
         throw new Error('create_test_audit_emitter accepts no listeners — use create_recording_audit_emitter');
     },
-    listener_count: () => 0
+    listener_count: () => 0,
+    drain_inflight: async () => { }
 });
 /**
  * Build a no-op `AuditLogSse` for tests that wire `audit_sse` into the
@@ -133,17 +136,6 @@ export const create_stub_audit_sse = () => {
         registry
     };
 };
-/** Stub `AppDeps` for auth surface tests — throws on any method access. */
-export const stub_app_deps = {
-    read_secure_file: create_throwing_stub('read_secure_file'),
-    delete_file: create_throwing_stub('delete_file'),
-    keyring: create_throwing_stub('keyring'),
-    password: create_throwing_stub('password'),
-    db: create_throwing_stub('db'),
-    log: create_throwing_stub('log'),
-    audit: create_test_audit_emitter(),
-    connection_closer: create_realtime_closer()
-};
 /**
  * Create no-op `AppDeps` for auth surface testing.
  */
@@ -159,25 +151,54 @@ export const create_stub_app_deps = () => ({
     audit: create_test_audit_emitter(),
     connection_closer: create_realtime_closer()
 });
-/** Create the API middleware stub array matching `create_auth_middleware_specs` output. */
+/**
+ * Create a stub `AppBackend` with no database behind it — no migration
+ * results, and a `close` that does nothing unless one is passed. For
+ * assembling a server (`create_app_server`) in tests that never reach the
+ * database; one whose `close` does nothing can host server after server.
+ *
+ * @param options - the deps and `close` to use in place of the defaults
+ */
+export const create_stub_app_backend = (options) => ({
+    db_type: 'pglite-memory',
+    db_name: 'test',
+    migration_results: [],
+    close: options?.close ?? (async () => { }),
+    deps: options?.deps ?? create_stub_app_deps()
+});
+/** A fresh pass-through middleware — a distinct handler per call, unlike the shared `stub_mw`. */
+const create_stub_mw = () => async (_c, next) => next();
+/**
+ * Create the API middleware stub array matching `create_auth_middleware_specs`
+ * output — the same names, paths, order, and declared `errors` (the surface
+ * merges middleware errors into every route under the path, so a stub that
+ * declared more than the real stack would widen the test surface). Like the
+ * real factory's, each spec gets its own pass-through handler, so
+ * `assert_middleware_stack_mounted` can tell the layers apart by identity.
+ */
 export const create_stub_api_middleware = (options) => {
     const specs = [
-        { name: 'origin', path: AUTH_MIDDLEWARE_PATH, handler: stub_mw, errors: { 403: ApiError } },
-        { name: 'session', path: AUTH_MIDDLEWARE_PATH, handler: stub_mw },
-        { name: 'request_context', path: AUTH_MIDDLEWARE_PATH, handler: stub_mw },
+        {
+            name: 'origin',
+            path: AUTH_MIDDLEWARE_PATH,
+            handler: create_stub_mw(),
+            errors: { 403: ApiError }
+        },
+        { name: 'session', path: AUTH_MIDDLEWARE_PATH, handler: create_stub_mw() },
+        { name: 'request_context', path: AUTH_MIDDLEWARE_PATH, handler: create_stub_mw() },
         {
             name: 'bearer_auth',
             path: AUTH_MIDDLEWARE_PATH,
-            handler: stub_mw,
-            errors: { 401: ApiError, 403: ApiError, 429: RateLimitError }
+            handler: create_stub_mw(),
+            errors: {}
         }
     ];
     if (options?.include_daemon_token) {
         specs.push({
             name: 'daemon_token',
             path: AUTH_MIDDLEWARE_PATH,
-            handler: stub_mw,
-            errors: { 401: ApiError, 500: ApiError, 503: ApiError }
+            handler: create_stub_mw(),
+            errors: {}
         });
     }
     return specs;
@@ -191,16 +212,10 @@ export const create_stub_api_middleware = (options) => {
  * @param session_options - consumer's session config (required — varies per app)
  */
 export const create_stub_app_server_context = (session_options) => {
-    const deps = create_stub_app_deps();
+    const backend = create_stub_app_backend();
     return {
-        deps,
-        backend: {
-            deps,
-            db_type: 'pglite-memory',
-            db_name: 'test',
-            migration_results: [],
-            close: async () => { }
-        },
+        deps: backend.deps,
+        backend,
         bootstrap_status: { available: false, token_path: null },
         session_options,
         login_ip_rate_limiter: null,
@@ -238,18 +253,25 @@ const to_self_resolved_ws_endpoint = (endpoint) => {
  * suites consume the spec object this function returns, not the JSON
  * file.
  *
- * Mirrors `create_app_server`'s route assembly: consumer routes +
- * factory-managed bootstrap routes + surface generation — including its
+ * Mirrors `create_app_server`'s route assembly, in its order: consumer
+ * routes, then the factory-managed bootstrap routes, RPC endpoint routes, and
+ * `GET /api/surface` (with `surface_route: true`), then surface
+ * generation — including its
  * refusal of an `rpc_endpoints` or `ws_endpoints` path outside the auth
- * middleware's scope (`assert_endpoint_in_auth_scope`). If
+ * middleware's scope (`assert_endpoint_in_auth_scope`) and of a
+ * `transform_middleware` that doesn't keep the proxy and auth stack mounted
+ * (`assert_middleware_stack_mounted`). The middleware list mirrors the real
+ * one: a stub `trusted_proxy` spec at `'*'`, then the stub auth stack (with
+ * `daemon_token` when `options.daemon_token` is set). If
  * `create_app_server` changes how it wires routes, update this helper
  * to stay in sync (single source of truth for all consumers).
  *
  * @param options - surface spec options
  * @returns the surface spec for the standard suites
- * @throws Error when an endpoint path is outside `AUTH_MIDDLEWARE_PATH`, or a
+ * @throws Error when an endpoint path is outside `AUTH_MIDDLEWARE_PATH`, a
  *   `ws_endpoints` spec declares no `allowed_origins` and no `allowed_origins`
- *   option is given
+ *   option is given, or `transform_middleware` moves, drops, duplicates,
+ *   reorders, wraps, or replaces the stub proxy spec or a stub auth spec
  */
 export const create_test_app_surface_spec = (options) => {
     const ctx = create_stub_app_server_context(options.session_options);
@@ -291,12 +313,42 @@ export const create_test_app_surface_spec = (options) => {
             { ...bootstrap_route_shape, handler: stub_handler }
         ])
         : [];
-    const route_specs = [...consumer_routes, ...rpc_route_specs, ...bootstrap_route_specs];
-    let middleware_specs = create_stub_api_middleware();
+    // the surface route mirrors `create_app_server`'s opt-in mount — its handler
+    // serves the surface generated below, backfilled into the same ref
+    const surface_ref = {
+        surface: {
+            middleware: [],
+            routes: [],
+            rpc_endpoints: [],
+            ws_endpoints: [],
+            env: [],
+            events: [],
+            diagnostics: []
+        }
+    };
+    const surface_route_specs = options.surface_route
+        ? [create_surface_route_spec(surface_ref)]
+        : [];
+    // `create_app_server`'s order: consumer routes, then the factory routes
+    const route_specs = [
+        ...consumer_routes,
+        ...bootstrap_route_specs,
+        ...rpc_route_specs,
+        ...surface_route_specs
+    ];
+    // mirrors `create_app_server`'s `[proxy_spec, ...auth_middleware]`
+    const stack_specs = [
+        { name: 'trusted_proxy', path: '*', handler: create_stub_mw() },
+        ...create_stub_api_middleware({ include_daemon_token: options.daemon_token })
+    ];
+    let middleware_specs = stack_specs;
     if (options.transform_middleware) {
-        middleware_specs = options.transform_middleware(middleware_specs);
+        // the transform gets copies in a fresh array, so mutating what it was
+        // handed can't rewrite the originals the check matches against
+        middleware_specs = options.transform_middleware(stack_specs.map((spec) => ({ ...spec })));
+        assert_middleware_stack_mounted(stack_specs, middleware_specs);
     }
-    return create_app_surface_spec({
+    const surface_spec = create_app_surface_spec({
         middleware_specs,
         route_specs,
         env_schema: options.env_schema ?? BaseServerEnv,
@@ -304,4 +356,6 @@ export const create_test_app_surface_spec = (options) => {
         rpc_endpoints: resolved_rpc_endpoints,
         ws_endpoints: resolved_ws_endpoints
     });
+    surface_ref.surface = surface_spec.surface;
+    return surface_spec;
 };

package/dist/testing/ws_round_trip.d.ts

@@ -202,9 +202,7 @@ export interface WsTestHarness {
     /**
      * Open a mock connection. Resolves after `on_socket_open` (and the
      * transport's `register_ws`) completes, so broadcasts issued
-     * immediately after the `await` reach the connection. Earlier
-     * revisions returned synchronously and required a `settle_open()`
-     * microtask drain — no longer necessary.
+     * immediately after the `await` reach the connection.
      *
      * Returns the shared `WsClient` interface — same surface the
      * cross-process driver in `transports/ws_transport.ts` implements,

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

@@ -1 +1 @@
-{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/ws_round_trip.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/ws_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,MAAM,CAAC;AAC1C,OAAO,EACN,SAAS,EAET,KAAK,gBAAgB,EAErB,KAAK,QAAQ,EACb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,EAAsB,KAAK,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAEpG,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAChF,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAKN,KAAK,cAAc,EACnB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAMN,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAEvB,MAAM,2BAA2B,CAAC;AAMnC;;;GAGG;AACH,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,SAAS,CAAC;IACd,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAO,MAajC,CAAC;AAEF,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACtC,eAAe,EAAE,cAAc,CAAC;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,sBAAsB,KAAG,OAmBvE,CAAC;AAEF,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,CAAC,EAAE,OAAO,CAAC;IACX,8DAA8D;IAC9D,aAAa,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5D;AAED,mGAAmG;AACnG,MAAM,WAAW,WAAW;IAC3B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC,CAAC,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtE;;;;;OAKG;IACH,QAAQ,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,QAAO,WAsBtC,CAAC;AAEF;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,sBAAsB;;IACtE,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAa;gBAEjC,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC;IAGjD,qBAAqB,IAAI,SAAS;IAGlC,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;CAG/D;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC/B,YAAY,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,EAC9C,OAAO,YAAY,EACnB,IAAI,SAAS,KACX,OAAO,CAAC,IAAI,CAId,CAAC;AAMF,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IACjC,wEAAwE;IACxE,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,yFAAyF;IACzF,eAAe,CAAC,EAAE,cAAc,CAAC;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sFAAsF;IACtF,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,4CAA4C;AAC5C,MAAM,WAAW,0BAA0B;IAC1C;;;;;OAKG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B,kEAAkE;IAClE,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;OAIG;IACH,SAAS,CAAC,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAC;IACjD,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,cAAc,CAAC,EAAE,uBAAuB,CAAC,gBAAgB,CAAC,CAAC;IAC3D,yDAAyD;IACzD,eAAe,CAAC,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;IAC7D;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,yBAAyB,CAAC;IACrC;;;;;;;;OAQG;IACH,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,iBAAiB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC7D;AAiED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,0BAA0B,KAAG,aA+N5E,CAAC"}

package/dist/ui/AdminSurface.svelte

@@ -3,7 +3,9 @@
 	 * Attack-surface viewer. Fetches `GET /api/surface` (REST — not RPC, since
 	 * the surface dump exists outside the action surface) and delegates
 	 * rendering to `SurfaceExplorer`. Surfaces a retry button on fetch
-	 * failures.
+	 * failures. The server must opt in to the route
+	 * (`create_app_server({surface_route: true})`), which is admin-only and
+	 * refused to a narrowed API token.
 	 *
 	 * @module
 	 */

package/dist/ui/AdminSurface.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AdminSurface.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/AdminSurface.svelte"],"names":[],"mappings":"AAkEA,QAAA,MAAM,YAAY,2DAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"AdminSurface.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/AdminSurface.svelte"],"names":[],"mappings":"AAoEA,QAAA,MAAM,YAAY,2DAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/ui/CLAUDE.md

@@ -326,7 +326,9 @@ destructive actions.
 - `AdminSettings.svelte` — shell for `OpenSignupToggle` + the logged-in
   account line + logout `ConfirmButton`. No direct RPC calls.
 - `AdminSurface.svelte` — attack-surface viewer. Fetches
-  `/api/surface` (REST) and delegates to `SurfaceExplorer`.
+  `/api/surface` (REST) and delegates to `SurfaceExplorer`. The server must
+  opt in with `create_app_server({surface_route: true})`; the route is
+  admin-only and refused to a narrowed API token.
 - `OpenSignupToggle.svelte` — single checkbox bound to
   `AppSettingsState.settings.open_signup`. Consumes
   `app_settings_rpc_context`.

package/dist/ui/async_slot.svelte.d.ts

@@ -28,7 +28,7 @@
  *   would otherwise need to compensate for.
  * - **`AbortSignal` threaded to the callback** — RPC clients that accept
  *   a signal (or `fetch`) get cancellation for free; callers can also
- *   pass an external `signal` via {@link RunOptions} to bind the slot's
+ *   pass an external `signal` via `RunOptions` to bind the slot's
  *   lifetime to a component / page.
  * - **`preserve_error_on_retry`** — opt-in to keeping the previous error
  *   visible while a retry is pending (default clears at the start of
@@ -68,7 +68,7 @@ export interface AsyncSlotOptions<T, E = string> {
     initial?: T;
     /**
      * Convert a caught throw into the error value stored in
-     * {@link AsyncSlot.error}. Default extracts `Error.message` (falling
+     * `AsyncSlot.error`. Default extracts `Error.message` (falling
      * back to `'Request failed'` for non-Error throws). Pass
      * `to_rpc_error_message` to unwrap JSON-RPC `data.reason` codes.
      */
@@ -87,7 +87,7 @@ export interface RunOptions {
     /**
      * External signal chained into the slot's internal controller. Aborts
      * the in-flight run when fired (alongside automatic supersession by
-     * the next `run()` and manual {@link AsyncSlot.abort} calls).
+     * the next `run()` and manual `AsyncSlot.abort` calls).
      */
     signal?: AbortSignal;
 }
@@ -96,7 +96,7 @@ export interface RunOptions {
  *
  * @typeParam T - The success payload type. Use `void` for write-only
  *   actions whose response isn't worth retaining.
- * @typeParam E - The shape of {@link AsyncSlot.error}. Defaults to
+ * @typeParam E - The shape of `AsyncSlot.error`. Defaults to
  *   `string` (set by the default `map_error`). Narrow to a structured
  *   type by providing a `map_error` that returns it.
  */

package/dist/ui/async_slot.svelte.js

@@ -28,7 +28,7 @@
  *   would otherwise need to compensate for.
  * - **`AbortSignal` threaded to the callback** — RPC clients that accept
  *   a signal (or `fetch`) get cancellation for free; callers can also
- *   pass an external `signal` via {@link RunOptions} to bind the slot's
+ *   pass an external `signal` via `RunOptions` to bind the slot's
  *   lifetime to a component / page.
  * - **`preserve_error_on_retry`** — opt-in to keeping the previous error
  *   visible while a retry is pending (default clears at the start of
@@ -64,7 +64,7 @@ import { to_error_message } from '@fuzdev/fuz_util/error.ts';
  *
  * @typeParam T - The success payload type. Use `void` for write-only
  *   actions whose response isn't worth retaining.
- * @typeParam E - The shape of {@link AsyncSlot.error}. Defaults to
+ * @typeParam E - The shape of `AsyncSlot.error`. Defaults to
  *   `string` (set by the default `map_error`). Narrow to a structured
  *   type by providing a `map_error` that returns it.
  */
@@ -85,7 +85,7 @@ export class AsyncSlot {
     #controller = null;
     /**
      * Tracks whether any `run()` or `set()` has ever produced a success
-     * result. Used by {@link abort} to revert to `'success'` (vs `'initial'`)
+     * result. Used by `abort` to revert to `'success'` (vs `'initial'`)
      * — explicit flag instead of inspecting `data` so the discriminator
      * stays correct for `T = void` (where success-`data` is `undefined`)
      * and for nullable `T`s where `null` is a legitimate success value.
@@ -183,7 +183,7 @@ export class AsyncSlot {
     }
     /**
      * Abort the in-flight run (if any) and null out the controller field.
-     * Shared by {@link abort}, {@link set}, and {@link reset}.
+     * Shared by `abort`, `set`, and `reset`.
      */
     #clear_controller(reason) {
         this.#controller?.abort(reason);