@fuzdev/fuz_app 0.128.0 → 0.130.0

package/dist/testing/cross_backend/ws_inbound_dispatch.js

@@ -0,0 +1,177 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process suite for the two refusals a WebSocket request can meet ahead
+ * of dispatch — the same on both spines, pinned over a real upgrade:
+ *
+ * - a request whose id names a request still running on the socket is
+ *   answered `invalid_request` with `data.reason: 'duplicate_request_id'` and
+ *   not dispatched; the running request keeps the id and answers as usual, and
+ *   once it has answered the id is free again
+ * - past the per-socket in-flight ceiling (128 on both spines) a new request is
+ *   answered `queue_overflow` with its id and not dispatched; the socket stays
+ *   open, the running requests still answer, and the duplicate check comes
+ *   first
+ *
+ * A request has to stay in flight for either to be observable, so the suite
+ * holds requests with `peer/ping`: the server's handler pings the client back
+ * and waits for the echo, and the client's responder withholds it until the
+ * test releases it. Gated on `capabilities.peer_request` for that reason.
+ *
+ * The wire literals are deliberate independent copies of the producers'
+ * constants (`ERROR_DUPLICATE_REQUEST_ID`,
+ * `MAX_INBOUND_DISPATCHES_PER_CONNECTION`, `WS_INBOUND_DISPATCH_OVERFLOW_MESSAGE`
+ * on TS; their Rust twins in `fuz_realtime`) — parity by test, so a value
+ * renamed on one side fails here instead of moving both at once.
+ *
+ * Cross-process only: `create_ws_transport` needs a real bound socket, so wire
+ * it from a `*.cross.test.ts` file.
+ *
+ * @module
+ */
+import { assert, describe } from 'vitest';
+import { create_jsonrpc_request } from '../../http/jsonrpc_helpers.js';
+import { create_ws_transport } from '../transports/ws_transport.js';
+import { is_response_for } from '../transports/ws_client.js';
+import { test_if } from './capabilities.js';
+/** `data.reason` of the duplicate-id refusal. */
+const REASON_DUPLICATE_REQUEST_ID = 'duplicate_request_id';
+/** The per-socket in-flight ceiling on both spines. */
+const MAX_INBOUND_DISPATCHES = 128;
+/** The `queue_overflow` message past the ceiling. */
+const OVERFLOW_MESSAGE = 'too many concurrent requests on this connection';
+const INVALID_REQUEST = -32600;
+const QUEUE_OVERFLOW = -32009;
+const PEER_PING_METHOD = 'peer/ping';
+const HEARTBEAT_METHOD = 'heartbeat';
+/** How long the test waits on a frame — above the server's peer-request deadline. */
+const FRAME_TIMEOUT_MS = 12_000;
+/**
+ * A client responder that withholds every server-initiated `peer/ping` echo
+ * until `release` — so each client `peer/ping` stays in flight on the server —
+ * and answers at once after it.
+ */
+const create_holding_responder = () => {
+    let release;
+    const released = new Promise((resolve) => {
+        release = resolve;
+    });
+    let ping_count = 0;
+    const ping_waiters = [];
+    const responder = async (request) => {
+        ping_count++;
+        for (let i = ping_waiters.length - 1; i >= 0; i--) {
+            const waiter = ping_waiters[i];
+            if (ping_count >= waiter.count) {
+                waiter.resolve();
+                ping_waiters.splice(i, 1);
+            }
+        }
+        await released;
+        const nonce = request.params?.nonce ?? 0;
+        return { result: { nonce, protocol_version: 1 } };
+    };
+    const pinged = (count) => ping_count >= count
+        ? Promise.resolve()
+        : new Promise((resolve) => ping_waiters.push({ count, resolve }));
+    return { responder, release, pinged };
+};
+/** A response for `id` that carries a `peer/ping` result (`nonce` present). */
+const is_ping_result_for = (id) => (msg) => is_response_for(id)(msg) &&
+    typeof msg.result === 'object' &&
+    msg.result !== null &&
+    'nonce' in msg.result;
+/** A response for `id` that carries a `heartbeat` result (an object without `nonce`). */
+const is_heartbeat_result_for = (id) => (msg) => is_response_for(id)(msg) &&
+    typeof msg.result === 'object' &&
+    msg.result !== null &&
+    !('nonce' in msg.result);
+/** An error response for `id`. */
+const is_error_for = (id) => (msg) => is_response_for(id)(msg) && 'error' in msg;
+/**
+ * Register the duplicate-id and in-flight-ceiling cases. Gated on
+ * `capabilities.peer_request` (the cases hold requests with `peer/ping`).
+ */
+export const describe_ws_inbound_dispatch_cross_tests = (options) => {
+    const { setup_test, capabilities, base_url, ws_path } = options;
+    const open_ws = (cookie, on_request) => {
+        assert.ok(cookie, 'expected a session cookie for the WS upgrade');
+        return create_ws_transport({
+            base_url,
+            ws_path,
+            cookies: [cookie],
+            origin: base_url,
+            on_request,
+            default_timeout_ms: FRAME_TIMEOUT_MS
+        });
+    };
+    const send_ping = (ws, id, nonce) => ws.send(create_jsonrpc_request(PEER_PING_METHOD, { nonce }, id));
+    const send_heartbeat = (ws, id) => ws.send(create_jsonrpc_request(HEARTBEAT_METHOD, undefined, id));
+    const assert_duplicate_refusal = (frame, id) => {
+        assert.ok('error' in frame, `expected the duplicate to be refused: ${JSON.stringify(frame)}`);
+        assert.strictEqual(frame.id, id);
+        assert.strictEqual(frame.error.code, INVALID_REQUEST);
+        assert.strictEqual(frame.error.message, 'invalid request');
+        assert.deepStrictEqual(frame.error.data, { reason: REASON_DUPLICATE_REQUEST_ID });
+    };
+    describe('ws inbound dispatch refusals (cross-process)', () => {
+        test_if(capabilities.peer_request, 'a request reusing a live id is refused with that id; the first keeps it, then the id frees', async () => {
+            const fixture = await setup_test();
+            const { responder, release, pinged } = create_holding_responder();
+            const ws = await open_ws(fixture.create_session_headers().cookie, responder);
+            try {
+                const id = 'held';
+                await send_ping(ws, id, 41);
+                // the server pinged back: the first request is dispatched and waiting
+                await pinged(1);
+                await send_heartbeat(ws, id);
+                assert_duplicate_refusal(await ws.wait_for(is_error_for(id)), id);
+                // the string '7' and the number 7 are different ids on both spines
+                await send_ping(ws, 7, 7);
+                await pinged(2);
+                await send_heartbeat(ws, '7');
+                await ws.wait_for(is_heartbeat_result_for('7'));
+                release();
+                const first = await ws.wait_for(is_ping_result_for(id));
+                assert.strictEqual(first.result.nonce, 41, 'the first request answers under its id');
+                await ws.wait_for(is_ping_result_for(7));
+                // answered, the id is free again
+                await send_heartbeat(ws, id);
+                await ws.wait_for(is_heartbeat_result_for(id));
+                const refusals = ws.messages.filter(is_error_for(id));
+                assert.strictEqual(refusals.length, 1, 'only the duplicate was refused');
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'past the in-flight ceiling a request is shed with queue_overflow and the socket keeps serving', async () => {
+            const fixture = await setup_test();
+            const { responder, release } = create_holding_responder();
+            const ws = await open_ws(fixture.create_session_headers().cookie, responder);
+            try {
+                for (let n = 0; n < MAX_INBOUND_DISPATCHES; n++) {
+                    await send_ping(ws, n, n);
+                }
+                // a duplicate at the ceiling is refused as a duplicate — that check is first
+                await send_heartbeat(ws, 0);
+                await send_heartbeat(ws, 'over');
+                assert_duplicate_refusal(await ws.wait_for(is_error_for(0)), 0);
+                const over = await ws.wait_for(is_response_for('over'));
+                assert.ok('error' in over, `expected the request to be shed: ${JSON.stringify(over)}`);
+                assert.strictEqual(over.error.code, QUEUE_OVERFLOW);
+                assert.strictEqual(over.error.message, OVERFLOW_MESSAGE);
+                assert.strictEqual(ws.close_code, null, 'shedding never closes the socket');
+                release();
+                for (let n = 0; n < MAX_INBOUND_DISPATCHES; n++) {
+                    const frame = await ws.wait_for(is_ping_result_for(n));
+                    assert.strictEqual(frame.result.nonce, n);
+                }
+                await send_heartbeat(ws, 'after');
+                await ws.wait_for(is_heartbeat_result_for('after'));
+            }
+            finally {
+                await ws.close();
+            }
+        });
+    });
+};

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

@@ -1,7 +1,7 @@
 import '../assert_dev_env.js';
 import { type BackendCapabilities } from './capabilities.js';
 import type { SetupTest } from './setup.js';
-/** Configuration for {@link describe_cross_process_ws_tests}. */
+/** Configuration for `describe_cross_process_ws_tests`. */
 export interface CrossProcessWsTestOptions {
     /**
      * Per-test fixture producer (`default_cross_process_setup(handle)`).

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

@@ -1 +1 @@
-{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAwG9B,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACzC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,yBAAyB,KAAG,IAkVpF,CAAC"}
+{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA0G9B,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C,2DAA2D;AAC3D,MAAM,WAAW,yBAAyB;IACzC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,yBAAyB,KAAG,IAkVpF,CAAC"}

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,7 +50,7 @@ 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

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';
@@ -79,16 +80,33 @@ 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;
+/** 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. 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.
+ * 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. */
@@ -161,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.
@@ -172,13 +207,16 @@ 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`) 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. If
+ * 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).
  *

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,12 +8,13 @@ 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';
@@ -135,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.
  */
@@ -161,12 +151,30 @@ export const create_stub_app_deps = () => ({
     audit: create_test_audit_emitter(),
     connection_closer: create_realtime_closer()
 });
+/**
+ * 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. 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.
+ * 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 = [
@@ -182,7 +190,7 @@ export const create_stub_api_middleware = (options) => {
             name: 'bearer_auth',
             path: AUTH_MIDDLEWARE_PATH,
             handler: create_stub_mw(),
-            errors: { 401: ApiError, 403: ApiError, 429: RateLimitError }
+            errors: {}
         }
     ];
     if (options?.include_daemon_token) {
@@ -190,7 +198,7 @@ export const create_stub_api_middleware = (options) => {
             name: 'daemon_token',
             path: AUTH_MIDDLEWARE_PATH,
             handler: create_stub_mw(),
-            errors: { 401: ApiError, 500: ApiError, 503: ApiError }
+            errors: {}
         });
     }
     return specs;
@@ -204,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,
@@ -251,13 +253,16 @@ 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`) 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. If
+ * 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).
  *
@@ -308,11 +313,33 @@ 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];
+    // 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()
+        ...create_stub_api_middleware({ include_daemon_token: options.daemon_token })
     ];
     let middleware_specs = stack_specs;
     if (options.transform_middleware) {
@@ -321,7 +348,7 @@ export const create_test_app_surface_spec = (options) => {
         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,
@@ -329,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":"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"}

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