@fuzdev/fuz_app 0.139.0 → 0.141.0

package/dist/actions/transports_ws_auth_guard.js

@@ -28,11 +28,16 @@
  * two cannot drift into closing a revoked token's socket while leaving its
  * stream open.
  *
- * `role` is the one scope this guard deliberately does not act on:
- * `perform_action` re-authorizes every message, so a socket whose account just
- * lost the gating role is refused at its next message, and closing it would
- * only change when the caller learns. A stream has no later check, so the SSE
- * guard closes there.
+ * `role` closes the target account's sockets whose endpoint gated the upgrade
+ * on the revoked role (`close_sockets_for_role`), with
+ * `WS_CLOSE_PERMISSION_REVOKED`, when the revoked grant was global
+ * (`to_global_role_revocation` — a role gate admits on global grants only).
+ * `perform_action` re-authorizes every *request* against its own action, but
+ * the role gate is the only check on what the socket *receives*: broadcasts
+ * and notifications reach every admitted connection of the endpoint with no
+ * per-recipient filter, so a socket left open past the revocation would keep
+ * receiving what the gate exists to withhold. The role is the only revocation
+ * no handler closes for, so this guard is its one closer.
  *
  * For standard WS endpoints mounted via `AppServerOptions.ws_endpoints`,
  * `create_app_server` registers the guard automatically per
@@ -45,7 +50,7 @@
  * @module
  */
 import { UnreachableError } from '@fuzdev/fuz_util/error.ts';
-import { to_revocation_scope } from '../auth/audit_log_schema.js';
+import { to_global_role_revocation, to_revocation_scope } from '../auth/audit_log_schema.js';
 /**
  * Create an audit event handler that closes connections on a successful
  * revocation row, dispatching on the event's `RevocationScope`:
@@ -55,7 +60,9 @@ import { to_revocation_scope } from '../auth/audit_log_schema.js';
  * - `account` → `close_sockets_for_account(target_account_id ?? account_id)`
  *   — `logout`, `password_change`, `session_revoke_all`, `token_revoke_all`,
  *   `account_delete`, `account_purge`
- * - `role` → nothing, deliberately (module doc)
+ * - `role` → `close_sockets_for_role(target_account_id ?? account_id,
+ *   metadata.role)` when the revoked grant was global; a scoped revoke closes
+ *   nothing (module doc)
  * - `none` → nothing — every other event, and any event type fuz_app does not
  *   define
  *
@@ -81,10 +88,17 @@ export const create_ws_auth_guard = (closer, log) => {
         switch (scope) {
             case 'none':
                 return;
-            // A decision, not a fallthrough: per-message dispatch re-authorizes,
-            // so the next message is refused. The SSE guard closes on this scope.
-            case 'role':
+            case 'role': {
+                // global grants only — a role gate never admitted on a scoped one
+                const revoked = to_global_role_revocation(event);
+                if (!revoked)
+                    return;
+                const closed = closer.close_sockets_for_role(revoked.account_id, revoked.role);
+                if (closed > 0) {
+                    log.info(`WS auth guard: closed ${closed} socket(s) gated on ${revoked.role} for account ${revoked.account_id} (${event.event_type})`);
+                }
                 return;
+            }
             case 'session': {
                 const session_id = event.metadata?.session_id;
                 if (typeof session_id !== 'string' || session_id.length === 0)

package/dist/actions/transports_ws_backend.d.ts

@@ -124,7 +124,10 @@ import { type PeerRequestOptions, type PeerRequestOutcome } from './peer_request
  * One record per connection. `token_hash` is set for cookie-session
  * connections, `api_token_id` for bearer (`api_token`) connections, and
  * both are null for daemon-token connections (reachable only via
- * `BackendWebsocketTransport.close_sockets_for_account`).
+ * `BackendWebsocketTransport.close_sockets_for_account`). `required_roles`
+ * is what the connection's endpoint gated the upgrade on, kept per
+ * registration because endpoints with different gates can share one
+ * transport.
  */
 export interface ConnectionIdentity {
     /** Blake3 session token hash, or null for non-session credentials. */
@@ -133,6 +136,11 @@ export interface ConnectionIdentity {
     account_id: Uuid;
     /** `api_token.id` for bearer-authenticated connections, else null. */
     api_token_id: string | null;
+    /**
+     * The roles the endpoint required at upgrade (any-of), or empty for an
+     * ungated endpoint — what `close_sockets_for_role` matches on.
+     */
+    required_roles: ReadonlyArray<string>;
 }
 /**
  * Structural capability for transports that can broadcast with a
@@ -227,8 +235,9 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      *
      * The entry is closeable at once: a `close_sockets_for_*` matching
      * `token_hash` / `account_id` / `api_token_id` removes it, aborts
-     * `abort_controller`, and closes `ws` with `WS_CLOSE_SESSION_REVOKED`; the
-     * later `admit` then refuses. Until admitted it evicts nothing, is not
+     * `abort_controller`, and closes `ws` with `WS_CLOSE_SESSION_REVOKED`
+     * (`close_sockets_for_role`, matching `required_roles`, with
+     * `WS_CLOSE_PERMISSION_REVOKED`); the later `admit` then refuses. Until admitted it evicts nothing, is not
      * counted toward the per-account cap, and receives no message.
      *
      * The caller owns the entry until it is admitted: a refusal closes it with
@@ -246,11 +255,27 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * @param api_token_id - `api_token.id` for bearer connections, else `null`
      * @param abort_controller - the socket-scoped controller to abort when the
      *   transport closes this connection (revocation or cap eviction)
+     * @param required_roles - the roles the endpoint gated the upgrade on, for
+     *   `close_sockets_for_role`; empty for an ungated endpoint
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
      * @mutates this - inserts an un-admitted entry into `#connections`, unless
      *   the transport is closing
      */
-    register_pending(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null): Uuid;
+    register_pending(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null, required_roles?: ReadonlyArray<string>): Uuid;
+    /**
+     * The close code the transport closed a still-pending registration with —
+     * `WS_CLOSE_SESSION_REVOKED` for a credential revocation,
+     * `WS_CLOSE_PERMISSION_REVOKED` for a role close, `WS_CLOSE_GOING_AWAY`
+     * for the shutdown — read once: the record is dropped by this call (and by
+     * `remove_connection`). `null` when the transport did not close it while
+     * pending. For a caller whose `admit` was refused, to say why; the twin of
+     * the reason the Rust `ConnectionRegistry::admit` refuses with.
+     *
+     * @param connection_id - the id `register_pending` returned
+     * @returns the close code, or `null`
+     * @mutates this - drops the recorded code
+     */
+    take_pending_close_code(connection_id: Uuid): number | null;
     /**
      * Admit a pending connection — phase two (module doc).
      *
@@ -294,12 +319,14 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * connection is always admitted — unless the transport is closing: then it
      * is born closed, as in `register_pending`, and evicts nothing.
      *
+     * @param required_roles - the roles the endpoint gated the connection on,
+     *   for `close_sockets_for_role`; empty for an ungated one
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
      * @mutates this - inserts an admitted entry into `#connections`; past the
      *   cap, first removes the account's oldest admitted connections and closes
      *   their `WSContext`
      */
-    add_connection(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null): Uuid;
+    add_connection(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null, required_roles?: ReadonlyArray<string>): Uuid;
     /**
      * Remove a connection and its auth tracking data, pending or admitted, by
      * the id `register_pending` / `add_connection` returned. Idempotent — safe
@@ -376,6 +403,25 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      *   `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_token(api_token_id: string): number;
+    /**
+     * Close the sockets of `account_id` whose endpoint required `role`,
+     * including a registration still pending admission — the close for a
+     * revoked global grant of a role the upgrade gate admitted on. Each closes
+     * with `WS_CLOSE_PERMISSION_REVOKED`, not a revocation's code: the
+     * credential is still good.
+     *
+     * **Over-closes an any-of gate.** An endpoint gated on several roles admits
+     * an account holding any one of them, but this closes on the loss of any
+     * listed role, without checking whether the account still holds another.
+     * The client can reconnect when it still qualifies. The account's sockets
+     * on endpoints that did not list `role`, and on ungated ones, stay open.
+     *
+     * @returns the number of sockets closed
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_PERMISSION_REVOKED`
+     */
+    close_sockets_for_role(account_id: Uuid, role: string): number;
     /**
      * Close every connection, pending or admitted, with `WS_CLOSE_GOING_AWAY` —
      * the shutdown close `AppServer.close` runs. Not a revocation: the client

package/dist/actions/transports_ws_backend.d.ts.map

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

package/dist/actions/transports_ws_backend.js

@@ -117,7 +117,7 @@ import { Logger } from '@fuzdev/fuz_util/log.ts';
 import { create_uuid } from '../primitive_schemas.js';
 import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, create_jsonrpc_request, to_jsonrpc_message_id, is_jsonrpc_request } from '../http/jsonrpc_helpers.js';
-import { WS_CLOSE_CONNECTION_LIMIT, WS_CLOSE_GOING_AWAY, WS_CLOSE_GOING_AWAY_REASON, WS_CLOSE_OUTBOUND_OVERFLOW, WS_CLOSE_OUTBOUND_OVERFLOW_REASON, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON, utf8_length } from './transports.js';
+import { WS_CLOSE_CONNECTION_LIMIT, WS_CLOSE_GOING_AWAY, WS_CLOSE_GOING_AWAY_REASON, WS_CLOSE_OUTBOUND_OVERFLOW, WS_CLOSE_OUTBOUND_OVERFLOW_REASON, WS_CLOSE_PERMISSION_REVOKED, WS_CLOSE_PERMISSION_REVOKED_REASON, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON, utf8_length } from './transports.js';
 import { PendingPeerRequests } from './peer_request.js';
 import { WsOutboundWriter } from './ws_outbound_writer.js';
 /** Type guard for `FilterableBroadcastTransport`. */
@@ -163,6 +163,10 @@ export class BackendWebsocketTransport {
     // close arrives (`remove_connection`) or the close deadline passes — so the
     // deadline timer is cleared when the socket goes.
     #closing_writers = new Map();
+    // The close code each registration the transport closed while it was still
+    // pending got, until `take_pending_close_code` or `remove_connection` drops
+    // it — so a refused admission can say why it was refused.
+    #pending_close_codes = new Map();
     // set once by `close_all_sockets`, never cleared — every later
     // registration is born closed (module doc, "Shutdown")
     #closing = false;
@@ -197,8 +201,9 @@ export class BackendWebsocketTransport {
      *
      * The entry is closeable at once: a `close_sockets_for_*` matching
      * `token_hash` / `account_id` / `api_token_id` removes it, aborts
-     * `abort_controller`, and closes `ws` with `WS_CLOSE_SESSION_REVOKED`; the
-     * later `admit` then refuses. Until admitted it evicts nothing, is not
+     * `abort_controller`, and closes `ws` with `WS_CLOSE_SESSION_REVOKED`
+     * (`close_sockets_for_role`, matching `required_roles`, with
+     * `WS_CLOSE_PERMISSION_REVOKED`); the later `admit` then refuses. Until admitted it evicts nothing, is not
      * counted toward the per-account cap, and receives no message.
      *
      * The caller owns the entry until it is admitted: a refusal closes it with
@@ -216,14 +221,36 @@ export class BackendWebsocketTransport {
      * @param api_token_id - `api_token.id` for bearer connections, else `null`
      * @param abort_controller - the socket-scoped controller to abort when the
      *   transport closes this connection (revocation or cap eviction)
+     * @param required_roles - the roles the endpoint gated the upgrade on, for
+     *   `close_sockets_for_role`; empty for an ungated endpoint
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
      * @mutates this - inserts an un-admitted entry into `#connections`, unless
      *   the transport is closing
      */
-    register_pending(ws, token_hash, account_id, api_token_id = null, abort_controller = null) {
+    register_pending(ws, token_hash, account_id, api_token_id = null, abort_controller = null, required_roles = []) {
         if (this.#closing)
             return this.#close_born_closed(ws, abort_controller);
-        return this.#insert(ws, token_hash, account_id, api_token_id, abort_controller, false);
+        return this.#insert(ws, { token_hash, account_id, api_token_id, required_roles }, abort_controller, false);
+    }
+    /**
+     * The close code the transport closed a still-pending registration with —
+     * `WS_CLOSE_SESSION_REVOKED` for a credential revocation,
+     * `WS_CLOSE_PERMISSION_REVOKED` for a role close, `WS_CLOSE_GOING_AWAY`
+     * for the shutdown — read once: the record is dropped by this call (and by
+     * `remove_connection`). `null` when the transport did not close it while
+     * pending. For a caller whose `admit` was refused, to say why; the twin of
+     * the reason the Rust `ConnectionRegistry::admit` refuses with.
+     *
+     * @param connection_id - the id `register_pending` returned
+     * @returns the close code, or `null`
+     * @mutates this - drops the recorded code
+     */
+    take_pending_close_code(connection_id) {
+        const code = this.#pending_close_codes.get(connection_id);
+        if (code === undefined)
+            return null;
+        this.#pending_close_codes.delete(connection_id);
+        return code;
     }
     /**
      * Admit a pending connection — phase two (module doc).
@@ -281,24 +308,26 @@ export class BackendWebsocketTransport {
      * connection is always admitted — unless the transport is closing: then it
      * is born closed, as in `register_pending`, and evicts nothing.
      *
+     * @param required_roles - the roles the endpoint gated the connection on,
+     *   for `close_sockets_for_role`; empty for an ungated one
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
      * @mutates this - inserts an admitted entry into `#connections`; past the
      *   cap, first removes the account's oldest admitted connections and closes
      *   their `WSContext`
      */
-    add_connection(ws, token_hash, account_id, api_token_id = null, abort_controller = null) {
+    add_connection(ws, token_hash, account_id, api_token_id = null, abort_controller = null, required_roles = []) {
         if (this.#closing)
             return this.#close_born_closed(ws, abort_controller);
         if (this.#max_connections_per_account !== null) {
             this.#evict_oldest_for_account(account_id, this.#max_connections_per_account);
         }
-        return this.#insert(ws, token_hash, account_id, api_token_id, abort_controller, true);
+        return this.#insert(ws, { token_hash, account_id, api_token_id, required_roles }, abort_controller, true);
     }
-    #insert(ws, token_hash, account_id, api_token_id, abort_controller, admitted) {
+    #insert(ws, identity, abort_controller, admitted) {
         const connection_id = create_uuid();
         this.#connections.set(connection_id, {
             ws,
-            identity: { token_hash, account_id, api_token_id },
+            identity,
             admitted,
             abort_controller,
             writer: new WsOutboundWriter({
@@ -333,6 +362,7 @@ export class BackendWebsocketTransport {
      *   requests as `connection_gone`
      */
     remove_connection(connection_id) {
+        this.#pending_close_codes.delete(connection_id);
         this.#connections.get(connection_id)?.writer.dispose();
         // a connection the transport closed: its socket is gone now
         const closing = this.#closing_writers.get(connection_id);
@@ -451,6 +481,27 @@ export class BackendWebsocketTransport {
     close_sockets_for_token(api_token_id) {
         return this.#close_where((id) => id.api_token_id === api_token_id);
     }
+    /**
+     * Close the sockets of `account_id` whose endpoint required `role`,
+     * including a registration still pending admission — the close for a
+     * revoked global grant of a role the upgrade gate admitted on. Each closes
+     * with `WS_CLOSE_PERMISSION_REVOKED`, not a revocation's code: the
+     * credential is still good.
+     *
+     * **Over-closes an any-of gate.** An endpoint gated on several roles admits
+     * an account holding any one of them, but this closes on the loss of any
+     * listed role, without checking whether the account still holds another.
+     * The client can reconnect when it still qualifies. The account's sockets
+     * on endpoints that did not list `role`, and on ungated ones, stay open.
+     *
+     * @returns the number of sockets closed
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_PERMISSION_REVOKED`
+     */
+    close_sockets_for_role(account_id, role) {
+        return this.#close_where((id) => id.account_id === account_id && id.required_roles.includes(role), WS_CLOSE_PERMISSION_REVOKED, WS_CLOSE_PERMISSION_REVOKED_REASON);
+    }
     /**
      * Close every connection, pending or admitted, with `WS_CLOSE_GOING_AWAY` —
      * the shutdown close `AppServer.close` runs. Not a revocation: the client
@@ -511,6 +562,8 @@ export class BackendWebsocketTransport {
     }
     #end_connection(connection_id, entry, code, reason, backlog = 'flush') {
         this.#cleanup_connection(connection_id);
+        if (!entry.admitted)
+            this.#pending_close_codes.set(connection_id, code);
         // abort before the close so a handler observing `ctx.signal` bails out
         // without waiting for the close handshake
         entry.abort_controller?.abort();

package/dist/actions/ws_endpoint_spec.d.ts

@@ -46,10 +46,12 @@ export interface WsEndpointSpec {
      */
     actions: ReadonlyArray<Action>;
     /**
-     * Roles permitted to upgrade — any-of disjunction. Omit (or pass `[]`)
-     * to skip the upgrade-time role gate; per-action `auth` on each spec
-     * still applies at dispatch time via `perform_action`. Pass
-     * `[ROLE_ADMIN]` for an admin-only WS endpoint.
+     * Roles permitted to upgrade — any-of disjunction, global grants only.
+     * Omit (or pass `[]`) to skip the upgrade-time role gate; per-action
+     * `auth` on each spec still applies at dispatch time via
+     * `perform_action`. Pass `[ROLE_ADMIN]` for an admin-only WS endpoint.
+     * Held for the socket's life — see `register_ws_endpoint`'s
+     * `required_roles`.
      */
     required_roles?: ReadonlyArray<RoleName>;
     /**
@@ -133,18 +135,17 @@ export interface WsEndpointSpec {
      * Set `false` when a consumer needs to compose their own callback
      * from scratch — or to opt out of the auto-wiring entirely.
      *
-     * NOTE: does NOT close sockets on `role_grant_revoke` — that omission
-     * is deliberate (per-connection role tracking is out of scope). A user
-     * whose admin role is revoked keeps their socket open; the next message
-     * gets `forbidden` from the per-message authorization phase. Consumers
-     * wanting role-revoke disconnection use `extra_audit_handlers`.
+     * The guard is also the one closer of a role revocation: a revoked
+     * global grant of a role in `required_roles` closes the account's
+     * sockets on this endpoint with `WS_CLOSE_PERMISSION_REVOKED`. With the
+     * guard off for a transport, nothing closes them.
      */
     auth_guard?: boolean;
     /**
      * Extra audit-event handlers registered via `deps.audit.add_listener`
      * AFTER the standard `auth_guard` wiring (when enabled). By the time
      * these run, the standard guard may have already closed sockets. Use
-     * for role-revoke disconnection, custom analytics, etc.
+     * for custom analytics, a consumer's own revocation events, etc.
      *
      * Never deduped — consumer-owned; pass the same handler twice and it
      * fires twice.

package/dist/actions/ws_endpoint_spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws_endpoint_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/ws_endpoint_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EACX,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACxD;AAED,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG;IAAE,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAEjG;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAChC,cAAc,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,EACvD,iBAAiB,aAAa,CAAC,MAAM,CAAC,KACpC,KAAK,CAAC,sBAAsB,CAAC,GAAG,SAI/B,CAAC"}
+{"version":3,"file":"ws_endpoint_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/ws_endpoint_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EACX,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACxD;AAED,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG;IAAE,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAEjG;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAChC,cAAc,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,EACvD,iBAAiB,aAAa,CAAC,MAAM,CAAC,KACpC,KAAK,CAAC,sBAAsB,CAAC,GAAG,SAI/B,CAAC"}

package/dist/auth/CLAUDE.md

@@ -35,7 +35,7 @@ over the pool so rows persist when request transactions roll back. See root
 - `auth/session_cookie.ts` — `SessionOptions<T>`, `parse_session`, `process_session_cookie` (`'none' | 'clear'` — no refresh action; the 30-day lifetime is an absolute cap signed once at mint), `create_session_config`, `fuz_session_config`, `SESSION_AGE_MAX`.
 - `auth/password.ts` — `Password`, `PasswordProvided`, `PasswordHashDeps`, `PASSWORD_LENGTH_MIN` (12, OWASP), `PASSWORD_LENGTH_MAX` (300).
 - `auth/password_argon2.ts` — `hash_password`, `verify_password`, `verify_dummy`, `argon2_password_deps`.
-- `auth/api_token.ts` — `API_TOKEN_PREFIX` (`secret_fuz_token_`), `hash_api_token`, `generate_api_token`.
+- `auth/api_token.ts` — `API_TOKEN_PREFIX` (`secret_fuz_token_`), `hash_api_token`, `generate_api_token`, and the shape precheck `is_api_token_shaped` (`API_TOKEN_REGEX`: the prefix plus exactly `API_TOKEN_BODY_LENGTH` = 43 base64url chars).
 - `auth/daemon_token.ts` — `DaemonToken`, `DAEMON_TOKEN_HEADER` (`X-Daemon-Token`), `generate_daemon_token`, `validate_daemon_token`, `DaemonTokenState`.
 - `auth/bootstrap_account.ts` — `bootstrap_account` (one-shot, `bootstrap_lock`-protected).
 
@@ -74,7 +74,7 @@ Convention — `*_schema.ts` is Zod-only; `*_ddl.ts` holds DDL strings.
 
 ### Queries
 
-All take `deps: QueryDeps = {db}` first; `query_validate_api_token` adds `log`.
+All take `deps: QueryDeps = {db}` first; `query_validate_api_token` adds `log` and returns a `ValidatedApiToken` — the row with `scope` parsed, refusing (returning `undefined` for) a row whose stored scope is unreadable.
 
 - `auth/account_queries.ts` — account CRUD, actor resolution, password update with verify-write race guard, paged `query_admin_account_list`.
 - `auth/actor_lookup_queries.ts` — batched `actor` ⨝ `account` for the labels arc.
@@ -219,11 +219,12 @@ Everything else listed under §RPC action surfaces.
 
 ### Middleware
 
-- `auth/middleware.ts` — `create_auth_middleware_specs(deps, options)` assembles `[origin, session, request_context, bearer_auth]` + optional `daemon_token` (the content-type refusal isn't a middleware: `apply_route_specs` checks every `POST` route, see `http/simple_request.ts`). `AUTH_MIDDLEWARE_PATH` (`'/api/*'`) is where `create_app_server` mounts the stack; two assembly asserts lean on it: `assert_endpoint_in_auth_scope` (an `rpc_endpoints` / `ws_endpoints` path, or the bootstrap route under `bootstrap.route_prefix`, must sit inside it) and `assert_middleware_stack_mounted(stack_specs, middleware_specs)`, run on a `transform_middleware` result against the pre-transform stack (`[proxy, ...auth]`) — each stack spec, matched by its `handler` closure (not its spoofable `name`), mounted exactly once at its original path (`'*'` for the trusted proxy, `AUTH_MIDDLEWARE_PATH` for auth), in its original order; other specs may sit anywhere, including before the proxy and between the auth layers. The proxy is in the stack because dropping it turns every `get_client_ip` into `'unknown'`, one shared bucket for every IP-keyed limiter. The transform receives shallow copies in a fresh array, so an in-place mutation can't rewrite the originals the check reads. The check pins where those layers sit, not what added layers do — a layer you add runs with full context access. Both run in `create_test_app_surface_spec` too.
+- `auth/middleware.ts` — `create_auth_middleware_specs(deps, options)` assembles `[origin, session, request_context, bearer_auth]` + optional `daemon_token` (the content-type refusal isn't a middleware: `apply_route_specs` checks every `POST` route, see `http/simple_request.ts`). The origin check mounts on every path (`ORIGIN_MIDDLEWARE_PATH`, `'*'`), less its `origin_carve_outs` — each a `MiddlewareCarveOut` (`{path, reason}`, copied and frozen at assembly by `freeze_origin_carve_outs`, refused by `assert_origin_carve_outs_valid` without a reason or when it overlaps the auth scope — `middleware_paths_overlap` against `AUTH_MIDDLEWARE_PATH`, which holds every credential-reading and credential-minting route — and recorded on the origin spec so the surface leaves its `403` off the carved routes); `AUTH_MIDDLEWARE_PATH` (`'/api/*'`) is where `create_app_server` mounts the rest of the stack; assembly asserts lean on it: `assert_endpoint_in_auth_scope` (an `rpc_endpoints` / `ws_endpoints` path, or the bootstrap route under `bootstrap.route_prefix`, must sit inside it — so no carve-out can reach one), `assert_credential_routes_in_auth_scope(route_specs)` (every registered route that reads a credential — `auth.account` not `'none'`, or marked `reads_credential`, as account status is — or is marked `mints_credential` — login, signup, bootstrap — must sit inside it too, so a consumer prefixing the relative account or signup specs outside `/api/` is refused), and `assert_middleware_stack_mounted(stack_specs, middleware_specs)`, run on a `transform_middleware` result against the pre-transform stack (`[proxy, ...auth]`) — each stack spec, matched by its `handler` closure (not its spoofable `name`), mounted exactly once at its original path (`'*'` for the trusted proxy and the origin check, `AUTH_MIDDLEWARE_PATH` for the rest of auth), in its original order; other specs may sit anywhere, including before the proxy and between the auth layers. The proxy is in the stack because dropping it turns every `get_client_ip` into `'unknown'`, one shared bucket for every IP-keyed limiter. The transform receives shallow copies in a fresh array, so an in-place mutation can't rewrite the originals the check reads. The check pins where those layers sit, not what added layers do — a layer you add runs with full context access. Both run in `create_test_app_surface_spec` too.
 - `auth/request_context.ts` — `RequestContext`, `resolve_acting_actor`, `build_request_context`, predicates (`has_role`, `has_scoped_role`, `has_any_scoped_role` — the dispatcher's role gate and every builtin-role check read the **global** grant via `has_scoped_role(_, role, null)` / `has_any_scoped_role(_, roles, null)`; scope-blind `has_role` is never the gate for a builtin role), guards (`require_auth`, `require_role`, `require_credential_types`, `require_token_scope`), `token_scope_surface_denial` (the direct-call form, for surfaces that aren't route specs), `refresh_role_grants`.
 - `auth/session_middleware.ts` — `process_session_cookie` integration, `create_session_and_set_cookie` (shared by login / signup / bootstrap; returns the token hashes of the sessions the cap evicted, which the caller closes after its commit — only login passes a cap).
-- `auth/resolved_auth.ts` — `ResolvedAuth` (the resolved credential as one value: `account_id`, `credential_type`, `token_hash`, `api_token_id`), `get_resolved_auth(c)` (gathers it from the context keys the auth middleware set), and `revalidate_resolved_auth(deps, resolved)`, the no-touch re-read a long-lived connection runs once it is registered: session row / token row (by id) still live and still on the account, account not soft-deleted; a daemon token re-reads its account only. Reuses the middleware's own queries and predicates. Called by the WS upgrade (`actions/register_action_ws.ts`) and the audit SSE route between registering a connection pending and admitting it. Twin of the Rust `revalidate_resolved_auth`.
-- `auth/bearer_auth.ts` — soft-fail bearer middleware; rejects when `Origin` or `Referer` present (browser context).
+- `auth/resolved_auth.ts` — `ResolvedAuth` (the resolved credential as one value: `account_id`, `credential_type`, `token_hash`, `api_token_id`, `credential_deadline`), `get_resolved_auth(c)` (gathers it from the context keys the auth middleware set), and `revalidate_resolved_auth(deps, resolved)`, the no-touch re-read a long-lived connection runs once it is registered: session row / token row (by id) still live and still on the account, account not soft-deleted; a daemon token re-reads its account only. Reuses the middleware's own queries and predicates. Called by the WS upgrade (`actions/register_action_ws.ts`) and the audit SSE route between registering a connection pending and admitting it. Twin of the Rust `revalidate_resolved_auth`.
+- `auth/credential_deadline.ts` — when a resolved credential stops authenticating, which a WebSocket or audit stream opened on it closes at (expiry writes nothing a revocation listener hears): `credential_deadline_after` (the earliest remaining lifetime, anchored to `performance.now()`), `EXPIRES_IN_MS_SQL` (a row's `expires_at - NOW()`, read on the database clock in the statement that checks it, so the session and token validation queries return `expires_in_ms`), and `schedule_credential_deadline` (a chain of timers of at most `CREDENTIAL_DEADLINE_TIMER_CAP_MS`, an hour — a 30-day session is past `setTimeout`'s ceiling — each wake-up also checking a wall-clock copy of the deadline, so a host suspend, which stops the monotonic clock, delays the close by at most one timer after the resume). The middleware sets `CREDENTIAL_DEADLINE_KEY`: session — the earlier of the cookie's signed expiry (`SESSION_COOKIE_EXPIRES_AT_KEY`, set by the session middleware) and the row's; bearer — the row's, none for an eternal token; daemon token — none. Twin of the Rust `ResolvedAuth::credential_deadline`.
+- `auth/bearer_auth.ts` — soft-fail bearer middleware; rejects when `Origin` or `Referer` present (browser context), and soft-fails a value that is not `is_api_token_shaped` before any query. The scope it sets is the one the query parsed — there is no fallback.
 - `auth/daemon_token_middleware.ts` — `create_daemon_token_middleware(state, deps, log)` — the credential **consumer** only (soft-fail validation, keeper account resolution). The producer (`write_daemon_token` / `start_daemon_token_rotation`) lives in `testing/daemon_token_rotation.ts` behind the dev-env guard — no production assembly mints daemon tokens, mirroring the Rust spine's `fuz_testing`-confined producer. Soft-fails — discards the credential (pass-through, no own 401/503) on **every** non-success path: browser context (`Origin`/`Referer` present), malformed/invalid token, and valid-token-but-no-keeper all `next()` through to the dispatcher's `credential_type_required` (403) gate, mirroring the bearer guard and the Rust spine's `resolve.rs`. Daemon tokens are loopback-only, so browser context never arises in practice — the discard is defense-in-depth.
 
 See root ../../../CLAUDE.md §Middleware Ordering for canonical assembly
@@ -913,10 +914,11 @@ session, and once the sweep deletes an expired row `account_session_revoke`
 has nothing left to close for — so `cleanup_expired_sessions` closes each
 swept session's connections itself, by session id
 (`connection_closer.close_sockets_for_session`), which is why
-`query_session_cleanup_expired` returns the deleted ids. With the cleanup
-scheduled, a connection outlives its **session's** expiry by at most one
-interval. An expired API token's row is not swept and its connection is not
-closed (`account_token_revoke` still finds the row).
+`query_session_cleanup_expired` returns the deleted ids. The close repeats
+one already made: every connection closes at its credential's deadline
+(`auth/credential_deadline.ts`) in the process holding it, sweep or no sweep.
+An expired API token's row is not swept; its connections close at their
+deadline (`account_token_revoke` still finds the row).
 
 - The delete runs in its own transaction and the closes follow the commit —
   the rule every revocation close keeps (`actions/CLAUDE.md` §Connection

package/dist/auth/account_route_schema.d.ts

@@ -111,6 +111,7 @@ export declare const account_status_route_shape: {
         account: "none";
         actor: "none";
     };
+    reads_credential: true;
     description: string;
     input: z.ZodNull;
     output: z.ZodObject<{

package/dist/auth/account_route_schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account_route_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_route_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAQvD,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAC3C,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;kBAI9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,4EAA4E;AAC5E,eAAO,MAAM,iCAAiC;;;iBAG5C,CAAC;AACH,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAElG,oFAAoF;AACpF,eAAO,MAAM,UAAU;;;kBAGrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,6EAA6E;AAC7E,eAAO,MAAM,WAAW;;kBAEtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,2EAA2E;AAC3E,eAAO,MAAM,WAAW,WAAW,CAAC;AACpC,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wFAAwF;AACxF,eAAO,MAAM,YAAY;;;kBAGvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,sHAAsH;AACtH,eAAO,MAAM,mBAAmB;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,uGAAuG;AACvG,eAAO,MAAM,oBAAoB;;;;kBAI/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAUD,CAAC;AAEvC,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACxC,8FAA8F;IAC9F,0BAA0B,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,GACvC,SAAS,wBAAwB,KAC/B,CACF,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAC1B,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAC1B,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAC1B,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAoD1B,CAAC"}
+{"version":3,"file":"account_route_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_route_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAQvD,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAC3C,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;kBAI9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,4EAA4E;AAC5E,eAAO,MAAM,iCAAiC;;;iBAG5C,CAAC;AACH,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAElG,oFAAoF;AACpF,eAAO,MAAM,UAAU;;;kBAGrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,6EAA6E;AAC7E,eAAO,MAAM,WAAW;;kBAEtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,2EAA2E;AAC3E,eAAO,MAAM,WAAW,WAAW,CAAC;AACpC,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wFAAwF;AACxF,eAAO,MAAM,YAAY;;;kBAGvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,sHAAsH;AACtH,eAAO,MAAM,mBAAmB;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,uGAAuG;AACvG,eAAO,MAAM,oBAAoB;;;;kBAI/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAaD,CAAC;AAEvC,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACxC,8FAA8F;IAC9F,0BAA0B,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,GACvC,SAAS,wBAAwB,KAC/B,CACF,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAC1B,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAC1B,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAC1B,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAqD1B,CAAC"}

package/dist/auth/account_route_schema.js

@@ -85,6 +85,9 @@ export const account_status_route_shape = {
     method: 'GET',
     path: '/status',
     auth: { account: 'none', actor: 'none' },
+    // no gate — the handler answers an anonymous caller with its own 401 — but
+    // it reads the account the auth middleware resolved
+    reads_credential: true,
     description: 'Current account info (unauthenticated: 401 with bootstrap status)',
     input: AccountStatusInput,
     output: AccountStatusOutput,
@@ -115,6 +118,7 @@ export const create_account_route_shapes = (options) => [
         method: 'POST',
         path: '/login',
         auth: { account: 'none', actor: 'none' },
+        mints_credential: true,
         description: 'Exchange credentials for session',
         input: LoginInput,
         output: LoginOutput,

package/dist/auth/api_token.d.ts

@@ -11,6 +11,26 @@
 import { z } from 'zod';
 /** Prefix for all fuz API tokens (enables secret scanning). */
 export declare const API_TOKEN_PREFIX = "secret_fuz_token_";
+/** Random bytes encoded into the raw token body (256 bits). */
+export declare const API_TOKEN_ENTROPY_BYTES = 32;
+/** Length of the unpadded base64url body that encodes `API_TOKEN_ENTROPY_BYTES`. */
+export declare const API_TOKEN_BODY_LENGTH: number;
+/**
+ * Regex for a raw API token: `API_TOKEN_PREFIX` plus exactly
+ * `API_TOKEN_BODY_LENGTH` base64url characters. Matches the format produced
+ * by `generate_api_token`.
+ */
+export declare const API_TOKEN_REGEX: RegExp;
+/**
+ * Whether `raw` has the shape of a raw API token — the bearer path's precheck,
+ * so a value that cannot be a token costs no database work. A `true` says
+ * nothing about whether the token exists. Twin of the Rust spine's
+ * `is_api_token_shaped`.
+ *
+ * @param raw - the value from the `Authorization: Bearer` header
+ * @returns `true` when `raw` matches `API_TOKEN_REGEX`
+ */
+export declare const is_api_token_shaped: (raw: string) => boolean;
 /**
  * Regex for the public API token id (e.g. `tok_abC0_d-3xyzA`). Twelve
  * base64url characters after the `tok_` prefix. Matches the format produced

package/dist/auth/api_token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api_token.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/api_token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAA4B,CAAC;AAE5D,8CAA8C;AAC9C,eAAO,MAAM,UAAU,aAAuC,CAAC;AAC/D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAA4B,CAAC;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAO;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAMpF,CAAC"}
+{"version":3,"file":"api_token.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/api_token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD,+DAA+D;AAC/D,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,QAA+C,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAE3B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,KAAG,OAAoC,CAAC;AAEvF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAA4B,CAAC;AAE5D,8CAA8C;AAC9C,eAAO,MAAM,UAAU,aAAuC,CAAC;AAC/D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAA4B,CAAC;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAO;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAMpF,CAAC"}

package/dist/auth/api_token.js

@@ -13,6 +13,26 @@ import { hash_blake3 } from '@fuzdev/fuz_util/hash_blake3.ts';
 import { generate_random_base64url } from '../crypto.js';
 /** Prefix for all fuz API tokens (enables secret scanning). */
 export const API_TOKEN_PREFIX = 'secret_fuz_token_';
+/** Random bytes encoded into the raw token body (256 bits). */
+export const API_TOKEN_ENTROPY_BYTES = 32;
+/** Length of the unpadded base64url body that encodes `API_TOKEN_ENTROPY_BYTES`. */
+export const API_TOKEN_BODY_LENGTH = Math.ceil((API_TOKEN_ENTROPY_BYTES * 4) / 3);
+/**
+ * Regex for a raw API token: `API_TOKEN_PREFIX` plus exactly
+ * `API_TOKEN_BODY_LENGTH` base64url characters. Matches the format produced
+ * by `generate_api_token`.
+ */
+export const API_TOKEN_REGEX = new RegExp(`^${API_TOKEN_PREFIX}[A-Za-z0-9_-]{${API_TOKEN_BODY_LENGTH}}$`);
+/**
+ * Whether `raw` has the shape of a raw API token — the bearer path's precheck,
+ * so a value that cannot be a token costs no database work. A `true` says
+ * nothing about whether the token exists. Twin of the Rust spine's
+ * `is_api_token_shaped`.
+ *
+ * @param raw - the value from the `Authorization: Bearer` header
+ * @returns `true` when `raw` matches `API_TOKEN_REGEX`
+ */
+export const is_api_token_shaped = (raw) => API_TOKEN_REGEX.test(raw);
 /**
  * Regex for the public API token id (e.g. `tok_abC0_d-3xyzA`). Twelve
  * base64url characters after the `tok_` prefix. Matches the format produced
@@ -37,7 +57,7 @@ export const hash_api_token = (token) => hash_blake3(token);
  * @returns the raw token, a public id, and the blake3 hash for storage
  */
 export const generate_api_token = () => {
-    const raw = generate_random_base64url();
+    const raw = generate_random_base64url(API_TOKEN_ENTROPY_BYTES);
     const token = `${API_TOKEN_PREFIX}${raw}`;
     const token_hash = hash_api_token(token);
     const id = `tok_${raw.slice(0, 12)}`;

package/dist/auth/api_token_queries.d.ts

@@ -7,6 +7,22 @@ import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import type { QueryDeps } from '../db/query_deps.js';
 import type { ApiToken } from './account_schema.js';
 import { type TokenScope } from './token_scope.js';
+/**
+ * A live `api_token` row as `query_validate_api_token` returns it: the stored
+ * `scope` document already parsed, so a caller holds the narrowing the
+ * credential was minted with and never decides what an unreadable one means.
+ * The Rust twin's `ApiTokenRow` carries the parsed scope the same way.
+ */
+export type ValidatedApiToken = Omit<ApiToken, 'scope'> & {
+    scope: TokenScope;
+    /**
+     * Milliseconds until the token expires — `expires_at - NOW()`, measured on
+     * the database clock in the statement that found it live
+     * (`EXPIRES_IN_MS_SQL`); `null` for an eternal token. The Rust twin's
+     * `ApiTokenRow.expires_in`.
+     */
+    expires_in_ms: number | null;
+};
 /** Extended deps for `query_validate_api_token` which needs a logger. */
 export interface ApiTokenQueryDeps extends QueryDeps {
     log: Logger;
@@ -32,21 +48,23 @@ export declare const API_TOKEN_COLUMNS: readonly ["id", "account_id", "name", "t
  */
 export declare const query_create_api_token: (deps: QueryDeps, id: string, account_id: string, name: string, token_hash: string, scope: TokenScope, expires_at?: Date | null) => Promise<ApiToken>;
 /**
- * Validate a raw API token and return the token record.
+ * Validate a raw API token and return the token record with its scope parsed.
  *
  * Hashes the token with blake3, looks up the hash, and checks
- * expiration. Updates `last_used_at` and `last_used_ip` on success
+ * expiration, reading how long the token has left on the database clock in
+ * the same statement. A row whose stored scope is unreadable is refused like an
+ * unknown hash. Updates `last_used_at` and `last_used_ip` on success
  * (fire-and-forget — errors logged, never thrown).
  *
  * @param deps - query dependencies with logger
  * @param raw_token - the raw API token from the Authorization header
  * @param ip - the client IP address (for audit)
  * @param pending_effects - optional array to register the usage-tracking effect for later awaiting
- * @returns the token record if valid, or `undefined`
+ * @returns the token record with its parsed scope if valid, or `undefined`
  * @mutates `api_token` row - fire-and-forget UPDATE of `last_used_at` / `last_used_ip` on a valid token
  * @mutates `pending_effects` - pushes the in-flight tracking promise when provided
  */
-export declare const query_validate_api_token: (deps: ApiTokenQueryDeps, raw_token: string, ip: string | undefined, pending_effects: Array<Promise<void>> | undefined) => Promise<ApiToken | undefined>;
+export declare const query_validate_api_token: (deps: ApiTokenQueryDeps, raw_token: string, ip: string | undefined, pending_effects: Array<Promise<void>> | undefined) => Promise<ValidatedApiToken | undefined>;
 /**
  * Look up the owning account of a live API token — one that still exists and
  * has not expired — by its public id.