@fuzdev/fuz_app 0.118.0 → 0.120.0

package/dist/testing/cross_backend/ws_round_trip.js

@@ -12,10 +12,12 @@ import '../assert_dev_env.js';
  * cross-process bundle (`describe_standard_cross_process_tests`) omits WS
  * by design, so consumers call this alongside it.
  *
- * **Consumer-agnostic.** Every case drives the `heartbeat` protocol action,
- * which `assert_ws_endpoints_include_protocol_actions` guarantees is present
- * on every WS endpoint — so the suite needs no knowledge of a consumer's
- * domain WS methods. It validates the transport, not the domain.
+ * **Consumer-agnostic**, apart from the cases `rpc_path` and
+ * `capabilities.ws_account_actions` gate. Every other case drives the
+ * `heartbeat` protocol action, which
+ * `assert_ws_endpoints_include_protocol_actions` guarantees is present on
+ * 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
@@ -24,20 +26,36 @@ import '../assert_dev_env.js';
  * upgrade time (not per message), so the negative cases assert the upgrade
  * itself rejects rather than a per-message error frame.
  *
- * Two spine-parity cases follow: `heartbeat` answers the parameterless shapes
- * (absent, `{}`) and refuses a declared param with `invalid_params`, and a
+ * Spine-parity cases follow. 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
+ * ordering forced — so are frames written in the same TCP write as the upgrade
+ * request (driven through `connect_raw_ws`, since a client library sends
+ * nothing before its `open` event). `heartbeat` answers the parameterless
+ * shapes (absent, `{}`) and refuses a declared param with `invalid_params`, and a
  * message over the backend's cap (`max_message_bytes`, default
  * `DEFAULT_WS_MAX_MESSAGE_BYTES`) closes the socket with
  * `WS_CLOSE_MESSAGE_TOO_BIG`.
  *
- * A final case (gated on `rpc_path`) covers server-initiated close: an
- * authenticated socket is dropped when the account's sessions are revoked
- * mid-connection. Per-message dispatch never re-checks credential validity,
- * so the live socket survives on the audit-fed `create_ws_auth_guard` seam —
- * firing `account_session_revoke_all` over the keeper's session channel
- * emits `session_revoke_all`, which closes the socket. Omit `rpc_path` to
- * skip it (consumers without the standard account actions on their RPC
- * endpoint).
+ * The final cases (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
+ * account's sessions are revoked over the keeper's session channel
+ * (`account_session_revoke_all`), and when its account is deleted
+ * (`account_delete`, also gated on `capabilities.account_lifecycle`). Omit
+ * `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
+ * 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.
  *
  * Gated on `capabilities.ws` — backends without an end-to-end WS transport
  * skip (the cases still surface as `.skip` in the report). Cross-process
@@ -49,11 +67,13 @@ import '../assert_dev_env.js';
 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 } from '../../actions/transports.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 { 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';
 /** Origin guaranteed to fail the `http://localhost:*` allowlist the test backends run with. */
@@ -63,7 +83,8 @@ const DISALLOWED_ORIGIN = 'http://disallowed.example';
  * `heartbeat` round-trip, `heartbeat`'s parameterless-shape contract, an
  * oversized message closing with `WS_CLOSE_MESSAGE_TOO_BIG`, anonymous-upgrade
  * refusal, disallowed-origin refusal, and — when `rpc_path` is supplied —
- * session-revocation closing the live socket.
+ * session revocation and account deletion closing the live socket, plus a
+ * self-revoking socket reading its reply before its close.
  */
 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;
@@ -82,6 +103,61 @@ export const describe_cross_process_ws_tests = (options) => {
                 await client.close();
             }
         });
+        // Both spines answer the handshake before the connection is admitted
+        // (the credential is re-read in between) and dispatch nothing until it
+        // is. Requests that reach the backend first must wait for that
+        // admission — not be dropped by it, and not run ahead of it.
+        test_if(capabilities.ws, 'requests sent the moment the socket opens are all answered', async () => {
+            const client = await open_authed();
+            try {
+                const ids = [1, 2, 3];
+                // back to back, with no round trip first — these may reach the
+                // backend while the connection is still pending admission
+                await Promise.all(ids.map((id) => client.send({ jsonrpc: '2.0', id, method: heartbeat_action_spec.method })));
+                const frames = await Promise.all(ids.map((id) => client.wait_for(is_response_for(id))));
+                for (const frame of frames) {
+                    assert.ok('result' in frame, JSON.stringify(frame));
+                    assert.deepStrictEqual(frame.result, {});
+                }
+                assert.strictEqual(client.close_code, null);
+            }
+            finally {
+                await client.close();
+            }
+        });
+        // The same contract with the ordering forced: frames written in the same
+        // TCP write as the upgrade request are in the backend's hands before it
+        // can have admitted anything.
+        test_if(capabilities.ws && capabilities.ws_handshake_pipelining, 'frames sent with the handshake are answered once the connection is admitted', async () => {
+            const fixture = await setup_test();
+            const url = new URL(base_url);
+            const ids = [1, 2, 3];
+            const client = await connect_raw_ws({
+                hostname: url.hostname,
+                port: url.port ? Number(url.port) : 80,
+                path: ws_path,
+                headers: {
+                    Cookie: fixture.transport.cookies().join('; '),
+                    Origin: origin ?? base_url
+                },
+                pipelined: ids.map((id) => JSON.stringify({ jsonrpc: '2.0', id, method: heartbeat_action_spec.method }))
+            });
+            try {
+                for (const id of ids) {
+                    const frame = await client.wait_for((f) => f.opcode === RAW_WS_OPCODE_TEXT &&
+                        JSON.parse(f.payload.toString('utf-8')).id === id);
+                    assert.deepStrictEqual(JSON.parse(frame.payload.toString('utf-8')), {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {}
+                    });
+                }
+                assert.ok(!client.frames.some(is_raw_ws_close), 'the socket stays open');
+            }
+            finally {
+                client.destroy();
+            }
+        });
         // `heartbeat` is parameterless on both spines (`z.void()` /
         // `require_void_params`): the empty shapes are the no-arg call, and a
         // declared param is `invalid_params`, not ignored.
@@ -146,9 +222,9 @@ export const describe_cross_process_ws_tests = (options) => {
             await assert_rejects(() => create_ws_transport({ base_url, ws_path, cookies: [], origin: DISALLOWED_ORIGIN }));
         });
         // Per-message dispatch never re-checks credential validity, so a live
-        // socket only drops via the audit-fed `create_ws_auth_guard`. Revoke the
-        // keeper's sessions over its own session channel → `session_revoke_all`
-        // closes the socket. Gated on `rpc_path` (depends on the standard
+        // socket drops only when a revocation closes it. Revoke the keeper's
+        // sessions over its own session channel → the handler's post-commit
+        // close ends the socket. Gated on `rpc_path` (depends on the standard
         // account actions on the RPC endpoint).
         test_if(capabilities.ws && rpc_path !== undefined, 'session revocation closes the live socket', async () => {
             const fixture = await setup_test();
@@ -171,5 +247,66 @@ export const describe_cross_process_ws_tests = (options) => {
                 await client.close();
             }
         });
+        // A soft-deleted account's credentials stop authenticating, and its open
+        // socket must end with them: the tombstone revokes every session and
+        // token, and the handler closes the account's connections once that has
+        // committed. The keeper deletes a second account whose socket is open.
+        test_if(capabilities.ws && capabilities.account_lifecycle && rpc_path !== undefined, 'an account delete closes the live socket of the deleted account', async () => {
+            const fixture = await setup_test();
+            const target = await fixture.create_account({ username: 'ws_delete_target', roles: [] });
+            const cookie = target.create_session_headers().cookie;
+            assert.ok(cookie, 'expected a session cookie for the target account');
+            const client = await create_ws_transport({ base_url, ws_path, cookies: [cookie], origin });
+            try {
+                // admitted and dispatching before the delete, so a failed close
+                // assertion can't be confused with a dead connection
+                await client.request(1, heartbeat_action_spec.method, {});
+                const res = await fixture.transport(rpc_path, create_rpc_post_init(account_delete_action_spec.method, {
+                    account_id: target.account.id
+                }));
+                assert.strictEqual(res.status, 200, `account_delete RPC failed (status=${res.status})`);
+                const closed = await client.wait_for_close(2000);
+                assert.ok(closed, 'socket did not close within 2s after account_delete');
+                assert.strictEqual(client.close_code, WS_CLOSE_SESSION_REVOKED);
+            }
+            finally {
+                await client.close();
+            }
+        });
+        // A socket that revokes the session it is running on. It must be closed;
+        // and where the backend declares `ws_self_revocation_reply`, the request
+        // is answered first, the close following from behind the revocation's
+        // commit. A caller left with only the close cannot tell a completed
+        // revocation from a dropped connection.
+        test_if(capabilities.ws && capabilities.ws_account_actions, capabilities.ws_self_revocation_reply
+            ? 'a socket that revokes its own sessions reads the reply, then the revocation close'
+            : 'a socket that revokes its own sessions is closed with the revocation code', async () => {
+            const client = await open_authed();
+            try {
+                await client.request(1, heartbeat_action_spec.method, {});
+                const revoke_id = 2;
+                await client.send({
+                    jsonrpc: '2.0',
+                    id: revoke_id,
+                    method: account_session_revoke_all_action_spec.method
+                });
+                const closed = await client.wait_for_close(2000);
+                assert.ok(closed, 'socket did not close within 2s of revoking its own sessions');
+                assert.strictEqual(client.close_code, WS_CLOSE_SESSION_REVOKED);
+                if (capabilities.ws_self_revocation_reply) {
+                    // frames arrive in wire order and nothing arrives after the
+                    // close, so a reply in hand was written ahead of it
+                    const reply = client.messages.find(is_response_for(revoke_id));
+                    assert.ok(reply, 'the reply must reach the caller before the close');
+                    assert.ok('result' in reply, JSON.stringify(reply));
+                    const result = reply.result;
+                    assert.strictEqual(result.ok, true);
+                    assert.ok((result.count ?? 0) >= 1, "at least the socket's own session was revoked");
+                }
+            }
+            finally {
+                await client.close();
+            }
+        });
     });
 };

package/dist/testing/sse_round_trip.d.ts

@@ -27,8 +27,9 @@ export interface SseRouteTestSpec {
     event_specs?: Array<EventSpec>;
     /**
      * Whether to assert the stream closes after `session_revoke_all`.
-     * Default `true`. Set `false` for endpoints that don't wire a close-on-revoke
-     * guard (leaves a TODO to fix, rather than silently passing).
+     * Default `true`. Set `false` for endpoints whose registry no revocation
+     * reaches — neither joined to the backend's closer nor guarded (leaves a
+     * TODO to fix, rather than silently passing).
      */
     assert_closes_on_revoke?: boolean;
 }
@@ -45,8 +46,9 @@ export interface SseRouteTestOptions {
     /**
      * Backend audit event callback — threaded to `create_test_app_server`.
      * Use to wire a close-on-revoke guard for consumer SSE registries
-     * (e.g., via `create_sse_auth_guard`) so `session_revoke_all` actually
-     * closes the tested streams.
+     * (e.g., via `create_sse_auth_guard`) so `session_revoke_all` closes the
+     * tested streams — not needed for a registry the route joined to
+     * `ctx.deps.connection_closer`, which the revoking handler closes itself.
      */
     on_audit_event?: (event: AuditLogEvent) => void;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"sse_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/sse_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAmB7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AAGrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,OAAO,EAEN,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAEhE,OAAO,EAIN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAO1B,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/B;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,qDAAqD;IACrD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChD;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC,8BAA8B;IAC9B,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CAChC;AAmDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,mBAAmB,KAAG,IAkIvE,CAAC"}
+{"version":3,"file":"sse_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/sse_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAmB7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AAGrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,OAAO,EAEN,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAEhE,OAAO,EAIN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAO1B,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,qDAAqD;IACrD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChD;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC,8BAA8B;IAC9B,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CAChC;AAmDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,mBAAmB,KAAG,IAkIvE,CAAC"}

package/dist/testing/stubs.d.ts

@@ -71,7 +71,7 @@ export declare const create_test_audit_emitter: () => AuditEmitter;
  * Build a no-op `AuditLogSse` for tests that wire `audit_sse` into the
  * surface helper but don't assert on SSE fan-out or subscriber state.
  *
- * `subscribe` returns a no-op cleanup; `on_audit_event` is a no-op; the
+ * `on_audit_event` is a no-op, so nothing is broadcast; the
  * `registry` is a fresh `SubscriberRegistry` instance (call sites that
  * inspect `.size` or call `.close_*` see a real registry, so writes are
  * isolated per test). Tests that need real SSE plumbing build it via

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":"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;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACjC,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAG3E,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAI9F;;;;;;;;;;;;;;;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;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,QAAO,YAW3C,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,QAAO,WAUxC,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,aAAa,EAAE,OAQ3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAO,OAUtC,CAAC;AAEH,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,GAAI,UAAU;IACpD,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAC/B,KAAG,KAAK,CAAC,cAAc,CAqBvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GAC1C,iBAAiB,cAAc,CAAC,MAAM,CAAC,KACrC,gBAsBF,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,mFAAmF;IACnF,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;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,cAmDF,CAAC"}
+{"version":3,"file":"stubs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/stubs.ts"],"names":[],"mappings":"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"}

package/dist/testing/stubs.js

@@ -9,6 +9,7 @@ import './assert_dev_env.js';
  */
 import { Logger } from '@fuzdev/fuz_util/log.ts';
 import { ApiError, RateLimitError } 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';
@@ -114,7 +115,7 @@ export const create_test_audit_emitter = () => ({
  * Build a no-op `AuditLogSse` for tests that wire `audit_sse` into the
  * surface helper but don't assert on SSE fan-out or subscriber state.
  *
- * `subscribe` returns a no-op cleanup; `on_audit_event` is a no-op; the
+ * `on_audit_event` is a no-op, so nothing is broadcast; the
  * `registry` is a fresh `SubscriberRegistry` instance (call sites that
  * inspect `.size` or call `.close_*` see a real registry, so writes are
  * isolated per test). Tests that need real SSE plumbing build it via
@@ -125,7 +126,6 @@ export const create_stub_audit_sse = () => {
         max_per_scope: AUDIT_LOG_SSE_MAX_PER_SCOPE
     });
     return {
-        subscribe: () => () => { },
         log: new Logger('test:audit_sse', { level: 'off' }),
         on_audit_event: () => { },
         registry
@@ -139,7 +139,8 @@ export const stub_app_deps = {
     password: create_throwing_stub('password'),
     db: create_throwing_stub('db'),
     log: create_throwing_stub('log'),
-    audit: create_test_audit_emitter()
+    audit: create_test_audit_emitter(),
+    connection_closer: create_realtime_closer()
 };
 /**
  * Create no-op `AppDeps` for auth surface testing.
@@ -153,7 +154,8 @@ export const create_stub_app_deps = () => ({
     password: create_noop_stub('password'),
     db: stub_db,
     log: new Logger('test', { level: 'off' }),
-    audit: create_test_audit_emitter()
+    audit: create_test_audit_emitter(),
+    connection_closer: create_realtime_closer()
 });
 /** Create the API middleware stub array matching `create_auth_middleware_specs` output. */
 export const create_stub_api_middleware = (options) => {

package/dist/testing/transports/sse_transport.d.ts

@@ -33,7 +33,7 @@ export interface SseTransport {
     /**
      * Drain until the server closes the stream. Resolves `true` if the
      * stream closes within `timeout_ms`, `false` on timeout. The signal for
-     * an auth-guard revocation dropping a live stream — mirrors
+     * a revocation dropping a live stream — mirrors
      * `WsClient.wait_for_close`.
      */
     wait_for_close: (timeout_ms?: number) => Promise<boolean>;

package/dist/testing/transports/ws_client.d.ts

@@ -130,6 +130,13 @@ export interface WsClient {
      * connection dropped without a close frame. `null` while open.
      */
     readonly close_code: number | null;
+    /**
+     * The close reason of the connection once it has closed — the text sent
+     * with `close_code` (e.g. `'connection limit'` with
+     * `WS_CLOSE_CONNECTION_LIMIT`), empty when the close carried none. `null`
+     * while open.
+     */
+    readonly close_reason: string | null;
     /** Every message the server has sent, in arrival order. */
     readonly messages: ReadonlyArray<unknown>;
     /**

package/dist/testing/transports/ws_client.d.ts.map

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

package/dist/testing/transports/ws_raw_client.d.ts

@@ -0,0 +1,51 @@
+import '../assert_dev_env.js';
+/** RFC 6455 opcode of a text frame. */
+export declare const RAW_WS_OPCODE_TEXT = 1;
+/** RFC 6455 opcode of a close frame. */
+export declare const RAW_WS_OPCODE_CLOSE = 8;
+/** One frame the server sent. */
+export interface RawWsFrame {
+    opcode: number;
+    payload: Buffer;
+}
+/** A WebSocket client that sends frames and never answers a close. */
+export interface RawWsClient {
+    /** Every frame the server sent, in order. */
+    frames: Array<RawWsFrame>;
+    /** Send one masked text frame. */
+    send_text: (text: string) => void;
+    /** Resolves with the first frame, already received or not, matching `predicate`. */
+    wait_for: (predicate: (frame: RawWsFrame) => boolean, timeout_ms?: number) => Promise<RawWsFrame>;
+    /** Drop the TCP connection, with no close handshake. */
+    destroy: () => void;
+}
+/** Options for `connect_raw_ws`. */
+export interface RawWsConnectOptions {
+    port: number;
+    /** @default '127.0.0.1' */
+    hostname?: string;
+    /** The WebSocket endpoint path (e.g. `/api/ws`). */
+    path: string;
+    /** Extra upgrade request headers — `Cookie`, `Origin`. */
+    headers?: Record<string, string>;
+    /**
+     * Text frames to write in the **same TCP write** as the upgrade request, so
+     * they are in the server's hands before the handshake is answered — and so
+     * before the connection can have been admitted.
+     */
+    pipelined?: ReadonlyArray<string>;
+}
+/** Whether a frame is a close frame. */
+export declare const is_raw_ws_close: (frame: RawWsFrame) => boolean;
+/** The close code a close frame carries, or `null` when it carries none. */
+export declare const raw_ws_close_code: (frame: RawWsFrame) => number | null;
+/**
+ * Upgrade a raw TCP socket to a WebSocket.
+ *
+ * Resolves once the server answers `101`; rejects on any other status or a
+ * connection error.
+ *
+ * @throws Error when the upgrade is refused or the connection fails
+ */
+export declare const connect_raw_ws: (options: RawWsConnectOptions) => Promise<RawWsClient>;
+//# sourceMappingURL=ws_raw_client.d.ts.map

package/dist/testing/transports/ws_raw_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws_raw_client.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/ws_raw_client.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,IAAM,CAAC;AACtC,wCAAwC;AACxC,eAAO,MAAM,mBAAmB,IAAM,CAAC;AAEvC,iCAAiC;AACjC,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC3B,6CAA6C;IAC7C,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1B,kCAAkC;IAClC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,oFAAoF;IACpF,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAClG,wDAAwD;IACxD,OAAO,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,wCAAwC;AACxC,eAAO,MAAM,eAAe,GAAI,OAAO,UAAU,KAAG,OAA+C,CAAC;AAEpG,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,GAAI,OAAO,UAAU,KAAG,MAAM,GAAG,IACE,CAAC;AAwClE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,mBAAmB,KAAG,OAAO,CAAC,WAAW,CAoF9E,CAAC"}

package/dist/testing/transports/ws_raw_client.js

@@ -0,0 +1,156 @@
+import '../assert_dev_env.js';
+/**
+ * A raw-socket WebSocket client for tests that need to misbehave, or to
+ * control exactly which bytes reach the server when.
+ *
+ * A client library answers a close frame itself and sends nothing until its
+ * `open` event, so two server behaviors can't be reached through one: what
+ * the server does with a client that **withholds its close frame**, and what
+ * it does with frames that arrive **with the handshake**, before the
+ * connection can have been admitted. This speaks just enough RFC 6455 over
+ * `node:net` to do both — the upgrade request, masked client text frames, and
+ * unmasked server frames — and deliberately never replies to a close.
+ *
+ * Small frames only (payloads under 64 KiB, unfragmented), which is all the
+ * JSON-RPC traffic the suites send.
+ *
+ * @module
+ */
+import { randomBytes } from 'node:crypto';
+import { connect } from 'node:net';
+/** RFC 6455 opcode of a text frame. */
+export const RAW_WS_OPCODE_TEXT = 0x1;
+/** RFC 6455 opcode of a close frame. */
+export const RAW_WS_OPCODE_CLOSE = 0x8;
+/** Whether a frame is a close frame. */
+export const is_raw_ws_close = (frame) => frame.opcode === RAW_WS_OPCODE_CLOSE;
+/** The close code a close frame carries, or `null` when it carries none. */
+export const raw_ws_close_code = (frame) => frame.payload.length >= 2 ? frame.payload.readUInt16BE(0) : null;
+/** Encode one masked client text frame. */
+const encode_client_text = (text) => {
+    const payload = Buffer.from(text, 'utf-8');
+    if (payload.length >= 65_536)
+        throw new Error('raw ws: payload too large for this test client');
+    const first = 0x80 | RAW_WS_OPCODE_TEXT;
+    const header = payload.length < 126
+        ? Buffer.from([first, 0x80 | payload.length])
+        : Buffer.from([first, 0x80 | 126, payload.length >> 8, payload.length & 0xff]);
+    const mask = randomBytes(4);
+    const masked = Buffer.from(payload);
+    for (let i = 0; i < masked.length; i++)
+        masked[i] ^= mask[i % 4];
+    return Buffer.concat([header, mask, masked]);
+};
+/** Split complete server frames off the front of `buffer` (server frames are unmasked). */
+const take_frames = (buffer) => {
+    const frames = [];
+    let offset = 0;
+    for (;;) {
+        if (buffer.length - offset < 2)
+            break;
+        const opcode = buffer[offset] & 0x0f;
+        let length = buffer[offset + 1] & 0x7f;
+        let header = 2;
+        if (length === 126) {
+            if (buffer.length - offset < 4)
+                break;
+            length = buffer.readUInt16BE(offset + 2);
+            header = 4;
+        }
+        else if (length === 127) {
+            throw new Error('raw ws: 64-bit frame lengths are not supported by this test client');
+        }
+        if (buffer.length - offset < header + length)
+            break;
+        frames.push({ opcode, payload: buffer.subarray(offset + header, offset + header + length) });
+        offset += header + length;
+    }
+    return { frames, rest: buffer.subarray(offset) };
+};
+/**
+ * Upgrade a raw TCP socket to a WebSocket.
+ *
+ * Resolves once the server answers `101`; rejects on any other status or a
+ * connection error.
+ *
+ * @throws Error when the upgrade is refused or the connection fails
+ */
+export const connect_raw_ws = (options) => new Promise((resolve, reject) => {
+    const { port, hostname = '127.0.0.1', path, headers = {}, pipelined = [] } = options;
+    const socket = connect(port, hostname);
+    const frames = [];
+    const waiters = [];
+    let buffer = Buffer.alloc(0);
+    let upgraded = false;
+    const client = {
+        frames,
+        send_text: (text) => {
+            socket.write(encode_client_text(text));
+        },
+        wait_for: (predicate, timeout_ms = 2000) => {
+            const found = frames.find(predicate);
+            if (found)
+                return Promise.resolve(found);
+            return new Promise((resolve_frame, reject_frame) => {
+                const waiter = {
+                    predicate,
+                    resolve: (frame) => {
+                        clearTimeout(timer);
+                        resolve_frame(frame);
+                    }
+                };
+                const timer = setTimeout(() => {
+                    waiters.splice(waiters.indexOf(waiter), 1);
+                    reject_frame(new Error(`raw ws: no matching frame within ${timeout_ms}ms`));
+                }, timeout_ms);
+                waiters.push(waiter);
+            });
+        },
+        destroy: () => socket.destroy()
+    };
+    socket.on('error', reject);
+    socket.on('connect', () => {
+        const request = [
+            `GET ${path} HTTP/1.1`,
+            `Host: ${hostname}:${port}`,
+            'Upgrade: websocket',
+            'Connection: Upgrade',
+            `Sec-WebSocket-Key: ${randomBytes(16).toString('base64')}`,
+            'Sec-WebSocket-Version: 13',
+            ...Object.entries(headers).map(([name, value]) => `${name}: ${value}`),
+            '',
+            ''
+        ].join('\r\n');
+        // one write, so the pipelined frames can't trail the handshake
+        socket.write(Buffer.concat([Buffer.from(request, 'utf-8'), ...pipelined.map(encode_client_text)]));
+    });
+    socket.on('data', (chunk) => {
+        buffer = Buffer.concat([buffer, chunk]);
+        if (!upgraded) {
+            const end = buffer.indexOf('\r\n\r\n');
+            if (end === -1)
+                return;
+            const status_line = buffer.subarray(0, end).toString('utf-8').split('\r\n')[0];
+            if (!/^HTTP\/1\.1 101\b/u.test(status_line)) {
+                reject(new Error(`raw ws: upgrade refused: ${status_line}`));
+                socket.destroy();
+                return;
+            }
+            upgraded = true;
+            buffer = buffer.subarray(end + 4);
+            resolve(client);
+        }
+        const taken = take_frames(buffer);
+        buffer = taken.rest;
+        for (const frame of taken.frames) {
+            frames.push(frame);
+            // Deliberately no reply to a close frame — this client withholds it.
+            for (const waiter of waiters.slice()) {
+                if (waiter.predicate(frame)) {
+                    waiters.splice(waiters.indexOf(waiter), 1);
+                    waiter.resolve(frame);
+                }
+            }
+        }
+    });
+});

package/dist/testing/transports/ws_transport.d.ts

@@ -44,9 +44,37 @@ export interface WsTransportOptions {
  * `messages` array; `wait_for` checks already-received messages first
  * before waiting for new arrivals.
  *
+ * An open socket is not yet an **admitted** connection: both spines answer
+ * the handshake first and admit the connection a credential re-check later,
+ * and deliver no server-initiated message to it until then. Requests sent
+ * meanwhile are queued and answered, so a suite that only round-trips can
+ * use this directly; one that waits for a push (a broadcast, a targeted
+ * notification) opens with `create_admitted_ws_transport` instead.
+ *
  * @throws Error if the upgrade fails (status, network) — the rejection
  *   message carries the underlying error so the test surfaces the real
  *   cause rather than hanging.
  */
 export declare const create_ws_transport: (options: WsTransportOptions) => Promise<WsClient>;
+/** The request id `create_admitted_ws_transport` round-trips `heartbeat` under. */
+export declare const WS_ADMISSION_PROBE_ID = "admitted";
+/**
+ * Open a real-upgrade WS client and round-trip `heartbeat` on it, so the
+ * backend has **admitted** the connection by the time this resolves.
+ *
+ * Both spines answer the upgrade handshake before the connection is
+ * registered and admitted (the credential is re-read in between), and deliver
+ * no broadcast or targeted notification to a connection still pending
+ * admission. A request is answered only once the connection is admitted, so
+ * the round trip is the one signal a client has. Suites that open a socket and
+ * then wait for a server-initiated message, or that need connections
+ * registered in a known order, open through this.
+ *
+ * `heartbeat` is a protocol action, present on every WS endpoint. Its response
+ * frame (id `WS_ADMISSION_PROBE_ID`) stays in the client's `messages`.
+ *
+ * @throws Error if the upgrade fails, or the heartbeat is refused or times out
+ *   — the socket is closed first
+ */
+export declare const create_admitted_ws_transport: (options: WsTransportOptions) => Promise<WsClient>;
 //# sourceMappingURL=ws_transport.d.ts.map

package/dist/testing/transports/ws_transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws_transport.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/ws_transport.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,OAAO,EAMN,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAEvB,MAAM,gBAAgB,CAAC;AAGxB,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IAClC,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAAU,SAAS,kBAAkB,KAAG,OAAO,CAAC,QAAQ,CAmJvF,CAAC"}
+{"version":3,"file":"ws_transport.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/ws_transport.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,OAAO,EAMN,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAEvB,MAAM,gBAAgB,CAAC;AAIxB,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IAClC,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,mBAAmB,GAAU,SAAS,kBAAkB,KAAG,OAAO,CAAC,QAAQ,CAwJvF,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,kBAAkB,KACzB,OAAO,CAAC,QAAQ,CASlB,CAAC"}