@fuzdev/fuz_app 0.144.0 → 0.146.0

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

@@ -31,13 +31,25 @@ export interface CrossProcessWsTestOptions {
      * the server cap.
      */
     readonly max_message_bytes?: number;
+    /** REST logout route path, for the logout close case. Default `/api/account/logout`. */
+    readonly logout_path?: string;
+    /** REST password-change route path, for its close case. Default `/api/account/password`. */
+    readonly password_path?: string;
+    /**
+     * The backend's per-account API token cap, which the token-cap close case
+     * mints past. Defaults to `DEFAULT_MAX_TOKENS`; `null` (a backend with the
+     * cap disabled) skips the case.
+     */
+    readonly max_tokens?: number | null;
 }
 /**
  * Register the cross-process WS round-trip suite over a real upgrade: authed
  * `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 and account deletion closing the live socket, plus a
+ * each listed revocation (session and token revokes, admin revoke-all, logout,
+ * password change, token-cap eviction, account delete and purge) closing the
+ * live socket, plus a
  * self-revoking socket reading its reply before its close, and a WS mutation's
  * audit row read back after `_testing_drain_effects`.
  */

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;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"}
+{"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;AAyH9B,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AAGtE,OAAO,KAAK,EAAE,SAAS,EAAmC,MAAM,YAAY,CAAC;AAK7E,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;IACpC,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,4FAA4F;IAC5F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,yBAAyB,KAAG,IA4epF,CAAC"}

package/dist/testing/cross_backend/ws_round_trip.js

@@ -43,21 +43,30 @@ import '../assert_dev_env.js';
  * 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
+ * its transaction commits, and every close here is asserted with
+ * `WS_CLOSE_SESSION_REVOKED` and `WS_CLOSE_SESSION_REVOKED_REASON`, so a
+ * dropped connection can't pass for one. 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).
+ * (`account_delete`, also gated on `capabilities.account_lifecycle`). The
+ * rest of the revocation table follows, each closing a second account's
+ * socket:
+ * `account_token_revoke` closes the revoked token's bearer socket and leaves
+ * a socket on the account's other token open; `admin_token_revoke_all`,
+ * `POST /logout`, `POST /password`, and `account_purge` (also gated on
+ * `capabilities.account_lifecycle`) close the account's bearer and session
+ * sockets — the rows `create_account_revocations` shares with the SSE suite;
+ * and a token the per-account cap evicts (`max_tokens` further mints) has its
+ * bearer socket closed. Omit `rpc_path` to skip them
+ * (consumers without the standard account and admin actions on their RPC
+ * endpoint).
  *
  * 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. Under the same gate (and
+ * `WS_CLOSE_SESSION_REVOKED` after reading the reply to its request — both
+ * spines answer the revoking request ahead of the close, so the caller is
+ * never left without an answer. 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.
@@ -73,16 +82,19 @@ 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, WS_CLOSE_SESSION_REVOKED } from '../../actions/transports.js';
-import { account_session_revoke_all_action_spec, account_token_create_action_spec } from '../../auth/account_action_specs.js';
+import { DEFAULT_WS_MAX_MESSAGE_BYTES, WS_CLOSE_MESSAGE_TOO_BIG, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON } from '../../actions/transports.js';
+import { account_session_revoke_all_action_spec, account_token_create_action_spec, account_token_revoke_action_spec, TokenCreateOutput, TokenRevokeOutput } from '../../auth/account_action_specs.js';
+import { DEFAULT_MAX_TOKENS } from '../../auth/account_route_schema.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 { create_admitted_ws_transport, 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 { DEFAULT_TEST_PASSWORD } from '../test_credentials.js';
 import { test_if } from './capabilities.js';
 import { cross_rpc_call, expect_output } from './cell_cross_helpers.js';
+import { create_account_revocations } from './revocation_drivers.js';
 /** Origin guaranteed to fail the `http://localhost:*` allowlist the test backends run with. */
 const DISALLOWED_ORIGIN = 'http://disallowed.example';
 /**
@@ -90,12 +102,15 @@ 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 and account deletion closing the live socket, plus a
+ * each listed revocation (session and token revokes, admin revoke-all, logout,
+ * password change, token-cap eviction, account delete and purge) closing the
+ * live socket, plus a
  * 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;
+    const { setup_test, capabilities, base_url, ws_path, origin, rpc_path, max_message_bytes = DEFAULT_WS_MAX_MESSAGE_BYTES, logout_path = '/api/account/logout', password_path = '/api/account/password' } = options;
+    const max_tokens = options.max_tokens === undefined ? DEFAULT_MAX_TOKENS : options.max_tokens;
     const open_authed = async () => {
         const fixture = await setup_test();
         return create_ws_transport({ base_url, ws_path, cookies: fixture.transport.cookies(), origin });
@@ -229,6 +244,54 @@ export const describe_cross_process_ws_tests = (options) => {
         test_if(capabilities.ws, 'disallowed-origin upgrade is refused', async () => {
             await assert_rejects(() => create_ws_transport({ base_url, ws_path, cookies: [], origin: DISALLOWED_ORIGIN }));
         });
+        // Every revocation closes with 4001 "Session revoked" — the code and its
+        // reason, so a dropped connection (1006) or a crash can't pass for one.
+        const assert_revoked_close = async (client, label) => {
+            assert.ok(await client.wait_for_close(2000), `socket did not close within 2s after ${label}`);
+            assert.strictEqual(client.close_code, WS_CLOSE_SESSION_REVOKED, label);
+            assert.strictEqual(client.close_reason, WS_CLOSE_SESSION_REVOKED_REASON, label);
+        };
+        // A bearer socket opens outside a browser context (no Origin, no cookie),
+        // as a CLI client's would.
+        const open_bearer = (token) => create_admitted_ws_transport({
+            base_url,
+            ws_path,
+            cookies: [],
+            origin: null,
+            headers: { Authorization: `Bearer ${token}` }
+        });
+        const open_session = (account) => {
+            const { cookie } = account.create_session_headers();
+            assert.ok(cookie, 'expected a session cookie');
+            return create_admitted_ws_transport({ base_url, ws_path, cookies: [cookie], origin });
+        };
+        /**
+         * Open each socket in turn, run `fn` over them, and close every socket
+         * that opened — also when a later open fails, so a refused upgrade leaves
+         * no socket registered on the shared backend for the rest of the run.
+         *
+         * Every close is awaited whatever the others do. When the open or `fn`
+         * failed, that error propagates and a close error is dropped, so it never
+         * hides the case's own failure; when they succeeded, the first close error
+         * is thrown, so a transport error surfacing at close still fails the case.
+         */
+        const with_sockets = async (opens, fn) => {
+            const clients = [];
+            try {
+                for (const open of opens)
+                    clients.push(await open());
+                await fn(...clients);
+            }
+            catch (error) {
+                await Promise.allSettled(clients.map((c) => c.close()));
+                throw error;
+            }
+            const closes = await Promise.allSettled(clients.map((c) => c.close()));
+            for (const close of closes) {
+                if (close.status === 'rejected')
+                    throw close.reason;
+            }
+        };
         // Per-message dispatch never re-checks credential validity, so a live
         // socket drops only when a revocation closes it. Revoke the keeper's
         // sessions over its own session channel → the handler's post-commit
@@ -248,8 +311,7 @@ export const describe_cross_process_ws_tests = (options) => {
                 await client.request(1, heartbeat_action_spec.method, {});
                 const res = await fixture.transport(rpc_path, create_rpc_post_init(account_session_revoke_all_action_spec.method));
                 assert.strictEqual(res.status, 200, `account_session_revoke_all RPC failed (status=${res.status})`);
-                const closed = await client.wait_for_close(2000);
-                assert.ok(closed, 'socket did not close within 2s after session_revoke_all');
+                await assert_revoked_close(client, 'account_session_revoke_all');
             }
             finally {
                 await client.close();
@@ -273,22 +335,80 @@ export const describe_cross_process_ws_tests = (options) => {
                     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);
+                await assert_revoked_close(client, 'account_delete');
             }
             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
+        // The rest of the revocation table (docs/security.md §Closing on
+        // Revocation), one case per revocation, each closing a socket of a second
+        // account with 4001 "Session revoked".
+        /** Mint a token for `account` over its own session. */
+        const mint_token = async (fixture, account, name) => expect_output(await cross_rpc_call(fixture.fresh_transport(), rpc_path, account_token_create_action_spec.method, { name, scope: { kind: 'full' }, lifetime: { kind: 'eternal' } }, account.create_session_headers()), TokenCreateOutput);
+        // `account_token_revoke` closes the revoked token's connections and no
+        // others: a socket on the account's other token stays open.
+        test_if(capabilities.ws && rpc_path !== undefined, "account_token_revoke closes the revoked token's bearer socket only", async () => {
+            const fixture = await setup_test();
+            const target = await fixture.create_account({ username: 'ws_token_revoke' });
+            const minted = await mint_token(fixture, target, 'ws revoke probe');
+            await with_sockets([() => open_bearer(minted.token), () => open_bearer(target.api_token)], async (revoked, other) => {
+                const res = expect_output(await cross_rpc_call(fixture.fresh_transport(), rpc_path, account_token_revoke_action_spec.method, { token_id: minted.id }, target.create_session_headers()), TokenRevokeOutput);
+                assert.strictEqual(res.revoked, true);
+                await assert_revoked_close(revoked, 'account_token_revoke');
+                // the account's other token keeps its socket
+                assert.deepStrictEqual(await other.request(2, heartbeat_action_spec.method, {}), {});
+                assert.strictEqual(other.close_code, null);
+            });
+        });
+        // The account-wide revocations (`revocation_drivers.ts`, shared with the
+        // SSE suite) close the account's connections — its bearer socket, and its
+        // session socket too.
+        // Without `rpc_path` the rows still register, as skipped cases, and never
+        // run — so the empty path is never sent.
+        const revocations = create_account_revocations({
+            capabilities,
+            rpc_path: rpc_path ?? '',
+            logout_path,
+            password_path
+        });
+        for (const { label, slug, gate, revoke } of revocations) {
+            test_if(capabilities.ws && gate && rpc_path !== undefined, `${label} closes the account's bearer and session sockets`, async () => {
+                const fixture = await setup_test();
+                const target = await fixture.create_account({
+                    username: `ws_revoke_${slug}`,
+                    password_value: DEFAULT_TEST_PASSWORD
+                });
+                await with_sockets([() => open_bearer(target.api_token), () => open_session(target)], async (bearer, session) => {
+                    await revoke(fixture, target);
+                    await assert_revoked_close(bearer, `${label} (bearer socket)`);
+                    await assert_revoked_close(session, `${label} (session socket)`);
+                });
+            });
+        }
+        // `max_tokens` further mints leave the watched token outside the newest
+        // `max_tokens`, so the cap evicts it whatever tokens the account held
+        // before it, and its socket closes once the evicting mint commits.
+        test_if(capabilities.ws && rpc_path !== undefined && max_tokens !== null, 'a token the cap evicts has its bearer socket closed', async () => {
+            const fixture = await setup_test();
+            const target = await fixture.create_account({ username: 'ws_token_cap' });
+            const watched = await mint_token(fixture, target, 'ws cap victim');
+            const client = await open_bearer(watched.token);
+            try {
+                for (let i = 0; i < max_tokens; i++) {
+                    await mint_token(fixture, target, `ws cap filler ${i}`);
+                }
+                await assert_revoked_close(client, `${max_tokens} further token mints`);
+            }
+            finally {
+                await client.close();
+            }
+        });
+        // A socket that revokes the session it is running on. Its 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 () => {
+        test_if(capabilities.ws && capabilities.ws_account_actions, 'a socket that revokes its own sessions reads the reply, then the revocation close', async () => {
             const client = await open_authed();
             try {
                 await client.request(1, heartbeat_action_spec.method, {});
@@ -298,19 +418,15 @@ export const describe_cross_process_ws_tests = (options) => {
                     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");
-                }
+                await assert_revoked_close(client, 'revoking its own sessions');
+                // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.144.0",
+  "version": "0.146.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",
@@ -36,7 +36,7 @@
     "@fuzdev/fuz_css": ">=0.70.0",
     "@fuzdev/fuz_schema": "^0.5.0",
     "@fuzdev/fuz_util": ">=0.77.0",
-    "@fuzdev/pglet-wasm": ">=0.1.1",
+    "@fuzdev/pglet-wasm": ">=0.1.2",
     "@hono/bun": ">=1",
     "@hono/deno": ">=1",
     "@hono/node-server": ">=1",
@@ -98,7 +98,7 @@
     "@fuzdev/fuz_util": "^0.77.0",
     "@fuzdev/gro": "^0.220.0",
     "@fuzdev/mdz": "^0.6.0",
-    "@fuzdev/pglet-wasm": "^0.1.1",
+    "@fuzdev/pglet-wasm": "^0.1.2",
     "@hono/bun": "^1.0.1",
     "@hono/deno": "^1.0.3",
     "@hono/node-server": "^1.19.14",