@fuzdev/fuz_app 0.117.1 → 0.119.0

package/dist/actions/transports_ws_auth_guard.js

@@ -1,148 +1,124 @@
 /**
- * WebSocket auth guard — bridges audit events to `BackendWebsocketTransport`.
+ * WebSocket auth guard — the audit-event listener that closes live
+ * connections when a row reports a revocation.
  *
  * **Why this exists.** `register_action_ws` captures `account_id` and
  * `credential_type` at upgrade time and reuses them for every message.
  * `perform_action`'s per-message authorization phase reloads role_grants
- * from the DB, but session and token VALIDITY are not re-queried — that
- * trade-off keeps chatty WS connections fast. The cost: nothing in the
- * dispatch path notices when a session is revoked or a token is rotated.
- * This guard is the enforcement mechanism — it listens on the audit
- * chain and closes affected sockets when revocation events fire, so
- * revocation actually takes effect on existing connections. Without it,
- * `session_revoke` / `token_revoke` are no-ops for open WS connections.
+ * from the DB, but session and token VALIDITY are not re-queried per message
+ * — they are re-read once, at admission (`revalidate_resolved_auth`) — a
+ * trade-off that keeps chatty WS connections fast. The cost: nothing in the
+ * dispatch path notices when a session is revoked or a token is rotated, so a
+ * revocation reaches an open connection only when something closes it.
  *
- * Mirror of `realtime/sse_auth_guard.ts` for the backend WebSocket
- * transport. Dispatches audit events to the right `close_sockets_for_*`
- * method so consumers do not re-implement the switch themselves.
+ * Two things do. The revocation handlers close directly, after their
+ * transaction commits (`queue_connection_close` in
+ * `actions/connection_closer.ts`) — that close does not depend on the audit
+ * write. This guard repeats it when the audit row is announced, which covers
+ * a revocation emitted by code that holds no closer. Closing is idempotent, so
+ * the overlap is a repeat, not a conflict. A success row is announced only
+ * after its request's transaction commits (`auth/audit_emitter.ts`), so the
+ * guard's close is post-commit too.
+ *
+ * ## Which rows close
+ *
+ * The guard dispatches on the `RevocationScope` each audit event declares in
+ * `audit_event_revocation_scopes` (`auth/audit_log_schema.ts`), the table the
+ * SSE guard (`realtime/sse_auth_guard.ts`) reads too — one declaration, so the
+ * 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.
  *
  * For standard WS endpoints mounted via `AppServerOptions.ws_endpoints`,
- * `create_app_server` composes the guard automatically per
+ * `create_app_server` registers the guard automatically per
  * `WsEndpointSpec.auth_guard`. For custom wiring, register the handler
  * inside the consumer's `audit_factory` body (or via
  * `audit.add_listener(...)` post-assembly).
  *
+ * Twin of the Rust spine's `register_socket_revocation_listeners`.
+ *
  * @module
  */
+import { UnreachableError } from '@fuzdev/fuz_util/error.ts';
+import { to_revocation_scope } from '../auth/audit_log_schema.js';
 /**
- * Audit event types that trigger WebSocket socket closure.
+ * Create an audit event handler that closes connections on a successful
+ * revocation row, dispatching on the event's `RevocationScope`:
  *
- * - `session_revoke` — close only the socket tied to the revoked session hash.
- * - `token_revoke` — close only the socket(s) authenticated with the revoked `api_token.id`.
- * - `session_revoke_all` / `token_revoke_all` / `password_change` — close every socket
- *   for the affected account (all credentials invalidated).
- *
- * `role_grant_revoke` is intentionally omitted: the WS transport does not track
- * per-connection role requirements, so role-scoped disconnection would
- * require either closing all sockets (too aggressive) or new tracking
- * (out of scope). Consumers that need it compose their own callback.
- */
-export const ws_disconnect_event_types = new Set([
-    'session_revoke',
-    'token_revoke',
-    'session_revoke_all',
-    'token_revoke_all',
-    'password_change'
-]);
-/**
- * Create an audit event handler that closes WebSocket connections on auth changes.
+ * - `session` → `close_sockets_for_session(metadata.session_id)`
+ * - `token` → `close_sockets_for_token(metadata.token_id)`
+ * - `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)
+ * - `none` → nothing — every other event, and any event type fuz_app does not
+ *   define
  *
  * Ignores `outcome === 'failure'` events — they carry attacker-controlled
  * identifiers (e.g. a `session_revoke` that the DB rejected still records
  * the submitted session_id), so reacting to them would let any authenticated
  * user close another user's socket by guessing a session hash or token id.
  *
+ * @param closer - what to close on — a `BackendWebsocketTransport`, or a
+ *   `RealtimeCloser` to reach every transport from one listener
  * @param log - logger for disconnect events (info level on non-zero closures)
  * @returns an `on_audit_event` callback suitable for `create_audit_emitter`'s
  *   `on_audit_event` slot, or for registering via
- *   `audit.add_listener` post-assembly. The returned callback mutates
- *   `transport` (closing matching sockets via
- *   `close_sockets_for_session` / `_token` / `_account`) on every relevant event.
+ *   `audit.add_listener` post-assembly. The returned callback closes matching
+ *   connections on `closer` on every relevant event.
  */
-export const create_ws_auth_guard = (transport, log) => {
+export const create_ws_auth_guard = (closer, log) => {
     return (event) => {
-        if (!ws_disconnect_event_types.has(event.event_type))
-            return;
         // Failed mutations carry attacker-controlled metadata — never act on them.
         if (event.outcome === 'failure')
             return;
-        if (event.event_type === 'session_revoke') {
-            const session_id = event.metadata?.session_id;
-            if (typeof session_id !== 'string' || session_id.length === 0)
+        const scope = to_revocation_scope(event.event_type);
+        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':
+                return;
+            case 'session': {
+                const session_id = event.metadata?.session_id;
+                if (typeof session_id !== 'string' || session_id.length === 0)
+                    return;
+                const closed = closer.close_sockets_for_session(session_id);
+                if (closed > 0) {
+                    log.info(`WS auth guard: closed ${closed} socket(s) for session ${session_id} (${event.event_type})`);
+                }
                 return;
-            const closed = transport.close_sockets_for_session(session_id);
-            if (closed > 0) {
-                log.info(`WS auth guard: closed ${closed} socket(s) for session ${session_id} (session_revoke)`);
             }
-            return;
-        }
-        if (event.event_type === 'token_revoke') {
-            const token_id = event.metadata?.token_id;
-            if (typeof token_id !== 'string' || token_id.length === 0)
+            case 'token': {
+                const token_id = event.metadata?.token_id;
+                if (typeof token_id !== 'string' || token_id.length === 0)
+                    return;
+                const closed = closer.close_sockets_for_token(token_id);
+                if (closed > 0) {
+                    log.info(`WS auth guard: closed ${closed} socket(s) for token ${token_id} (${event.event_type})`);
+                }
                 return;
-            const closed = transport.close_sockets_for_token(token_id);
-            if (closed > 0) {
-                log.info(`WS auth guard: closed ${closed} socket(s) for token ${token_id} (token_revoke)`);
             }
-            return;
-        }
-        // session_revoke_all / token_revoke_all / password_change — all of the
-        // account's credentials are invalidated; close every socket on the account.
-        // Admin actions set `target_account_id`; self-service actions only set `account_id`.
-        const target = event.target_account_id ?? event.account_id;
-        if (!target)
-            return;
-        // `target` is a DB account id (string); the transport's account map is
-        // keyed by the branded `Uuid` used elsewhere in fuz_app. Same value,
-        // differing type disciplines across the audit-log and transport layers.
-        const closed = transport.close_sockets_for_account(target);
-        if (closed > 0) {
-            log.info(`WS auth guard: closed ${closed} socket(s) for account ${target} (${event.event_type})`);
-        }
-    };
-};
-/**
- * Create an audit event handler that closes WebSocket connections on
- * user-initiated logout.
- *
- * Sibling helper to `create_ws_auth_guard` — kept separate because
- * `ws_disconnect_event_types` deliberately omits `logout` (admin-initiated
- * revocations use `session_revoke`, while `logout` is the user-initiated
- * case). Multiple consumers hand-rolled this same branch before extraction.
- *
- * Compose with `create_ws_auth_guard` to handle both kinds of disconnect:
- *
- * ```ts
- * const ws_guard = create_ws_auth_guard(transport, log);
- * const ws_logout_closer = create_ws_logout_closer(transport, log);
- * const on_audit_event = (event: AuditLogEvent): void => {
- *   ws_guard(event);
- *   ws_logout_closer(event);
- * };
- * ```
- *
- * Ignores `outcome === 'failure'` events — failed logouts carry
- * unauthenticated identifiers (no session to close anyway), and reacting
- * to them would let an unauthenticated probe close the targeted account's
- * sockets by submitting a logout for an arbitrary `account_id`.
- *
- * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`.
- *   The returned callback mutates `transport` via `close_sockets_for_account`
- *   on every successful `logout` event with a non-empty `account_id`.
- */
-export const create_ws_logout_closer = (transport, log) => {
-    return (event) => {
-        if (event.event_type !== 'logout')
-            return;
-        if (event.outcome === 'failure')
-            return;
-        const account_id = event.account_id;
-        if (!account_id)
-            return;
-        const closed = transport.close_sockets_for_account(account_id);
-        if (closed > 0) {
-            log.info(`WS logout closer: closed ${closed} socket(s) for account ${account_id} (logout)`);
+            case 'account': {
+                // Admin actions set `target_account_id`; self-service actions only
+                // set `account_id`.
+                const target = event.target_account_id ?? event.account_id;
+                if (!target)
+                    return;
+                const closed = closer.close_sockets_for_account(target);
+                if (closed > 0) {
+                    log.info(`WS auth guard: closed ${closed} socket(s) for account ${target} (${event.event_type})`);
+                }
+                return;
+            }
+            default:
+                throw new UnreachableError(scope);
         }
     };
 };

package/dist/actions/transports_ws_backend.d.ts

@@ -1,10 +1,53 @@
 /**
  * Backend WebSocket transport — manages server-side WebSocket connections
- * with session tracking and revocation support.
+ * with session tracking, revocation support, a per-account connection cap,
+ * and two-phase registration.
+ *
+ * ## Two-phase registration
+ *
+ * An upgrade resolves its credential before the socket exists, and every
+ * revocation closes the connections *registered* under the revoked
+ * credential. A one-step registration therefore has a window: a revocation
+ * landing between the credential check and the insert closes nothing, and the
+ * upgrade is admitted on a dead credential — for the socket's lifetime, since
+ * per-message dispatch never re-reads the session or token.
+ *
+ * Registration is split to close it:
+ *
+ * 1. `BackendWebsocketTransport.register_pending` inserts the entry
+ *    **un-admitted**. It is closeable from that instant — `close_sockets_for_*`
+ *    match pending entries deliberately — and is otherwise inert: it evicts
+ *    nothing, the cap does not count it, no broadcast / `send_to_account` /
+ *    `request_connection` reaches it, and the count accessors and
+ *    `is_registered` do not see it (`get_pending_connection_count` does).
+ * 2. The caller re-checks the credential against the database
+ *    (`revalidate_resolved_auth` in `auth/resolved_auth.ts`).
+ * 3. `BackendWebsocketTransport.admit` flips the entry to admitted — or
+ *    refuses when a revocation closed it in the meantime, evicting nothing.
+ *    The cap's eviction happens here, so a connection that is never admitted
+ *    never closes a live one, and any number of pending registrations on one
+ *    account leave its admitted connections alone.
+ *
+ * A revocation whose close ran **after** step 1 finds the entry, pending or
+ * admitted, and closes it; one that **committed before** step 2 is seen by the
+ * re-read, which refuses. Nothing is delivered to a pending entry rather than
+ * queued for it, so a refusal never has to promise that a queue a revoked
+ * credential would have read is dropped unread, and a broadcast's returned
+ * count names only connections that can receive it. The cost is a slightly
+ * wider blind spot at connect: a server-initiated message sent between the
+ * handshake and admission — one credential re-check later — is not delivered,
+ * just as one sent before the handshake is not.
+ *
+ * `add_connection` stays as the one-step form (register and admit together)
+ * for a connection with no revocable credential behind it — tests and
+ * harnesses that register a socket directly. An upgrade that authenticated a session or token
+ * uses the two-phase form. The twin of the Rust `fuz_realtime`
+ * `ConnectionRegistry`.
  *
  * @module
  */
 import type { WSContext } from 'hono/ws';
+import { Logger } from '@fuzdev/fuz_util/log.ts';
 import { type Uuid } from '@fuzdev/fuz_util/id.ts';
 import type { JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcRequestParams, JsonrpcResponse, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 import { type Transport, type TransportSendOptions } from './transports.js';
@@ -39,11 +82,103 @@ export interface FilterableBroadcastTransport extends Transport {
 }
 /** Type guard for `FilterableBroadcastTransport`. */
 export declare const is_filterable_broadcast_transport: (transport: Transport) => transport is FilterableBroadcastTransport;
+/**
+ * Default per-account WebSocket connection cap, applied by
+ * `BackendWebsocketTransport` unless overridden via
+ * `BackendWebsocketTransportOptions.max_connections_per_account`.
+ *
+ * Matches the account-wide ceiling the audit SSE cap implies (the default
+ * session cap, `DEFAULT_MAX_SESSIONS`, times `AUDIT_LOG_SSE_MAX_PER_SCOPE`
+ * streams per session) — generous enough that a user's tabs and tools never
+ * meet it; only an abusive or leaking client does. The twin of the Rust
+ * spine's `DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT`.
+ */
+export declare const DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT = 50;
+/** Options for `BackendWebsocketTransport`. */
+export interface BackendWebsocketTransportOptions {
+    /**
+     * Max concurrent connections per `account_id`, across every credential
+     * type (session, API token, daemon token — none exempt). The policy is
+     * **evict-oldest**: a connection past the cap is always admitted, and the
+     * account's oldest connections are closed with `WS_CLOSE_CONNECTION_LIMIT`
+     * to make room. Refusing the new one instead would let half-open sockets
+     * lock a user out with their own dead connections, and would let a stolen
+     * credential fill the slots ahead of the real user — revocation is the fix
+     * for a stolen credential, and evict-oldest never stands in its way.
+     *
+     * The cap is per transport: endpoints sharing one transport share one
+     * count per account. `null` disables it.
+     *
+     * @default DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT
+     */
+    max_connections_per_account?: number | null;
+    /**
+     * Logger for cap evictions and failed sends or closes. A cap eviction logs
+     * at info — the account, how many connections were closed, and the cap —
+     * so an operator can see a client that keeps meeting it. Unset falls back
+     * to a `[ws]` logger; `null` silences it. `register_action_ws` passes its
+     * own logger to the transport it creates.
+     */
+    log?: Logger | null;
+}
 export declare class BackendWebsocketTransport implements FilterableBroadcastTransport {
     #private;
     readonly transport_name: "backend_websocket_rpc";
     /**
-     * Add a new WebSocket connection with auth info.
+     * @throws Error when `max_connections_per_account` is neither `null` nor a
+     *   positive integer
+     */
+    constructor(options?: BackendWebsocketTransportOptions);
+    /**
+     * Register a connection **un-admitted** — phase one of the two-phase
+     * registration an upgrade runs (module doc).
+     *
+     * 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
+     * counted toward the per-account cap, and receives no message.
+     *
+     * The caller owns the entry until it is admitted: every refusal path calls
+     * `remove_connection` with the returned id.
+     *
+     * @param ws - the socket to close on revocation
+     * @param token_hash - blake3 session token hash, or `null` for non-session credentials
+     * @param account_id - the authenticated account
+     * @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)
+     * @returns the freshly assigned `connection_id` (branded `Uuid`)
+     * @mutates this - inserts an un-admitted entry into `#connections`
+     */
+    register_pending(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null): Uuid;
+    /**
+     * Admit a pending connection — phase two (module doc).
+     *
+     * If the entry is gone — a revocation closed it while it was pending, or it
+     * was removed — nothing is evicted and the connection is refused. Otherwise
+     * the per-account cap is enforced exactly as in `add_connection`, counting
+     * only **admitted** connections, and the entry becomes admitted: it now
+     * receives messages, is counted, and can itself be superseded. Admitting an
+     * already-admitted connection is a no-op that answers `true`.
+     *
+     * @param connection_id - the id `register_pending` returned
+     * @returns `false` when the connection is no longer registered — the caller
+     *   closes the socket as revoked
+     * @mutates this - marks the entry admitted; past the cap, first removes the
+     *   account's oldest admitted connections and closes their `WSContext`
+     */
+    admit(connection_id: Uuid): boolean;
+    /**
+     * Register a connection, admitted at once — the one-step form of
+     * `register_pending` + `admit`.
+     *
+     * **Not for an upgrade that authenticated a revocable credential**: a
+     * revocation landing between that upgrade's credential check and this call
+     * closes nothing, and the connection would be admitted on a dead credential
+     * (module doc, "Two-phase registration"). This is for a connection with
+     * nothing to revoke behind it.
+     *
      * Session connections pass a token hash for targeted revocation.
      * Bearer token connections (`api_token`) pass the `api_token.id` so the
      * socket can be closed when that specific token is revoked without
@@ -51,51 +186,77 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * pass `null` for both — they're only reachable via
      * `close_sockets_for_account`.
      *
+     * Enforces the per-account cap (`max_connections_per_account`): when
+     * `account_id` already holds the maximum, its oldest admitted connections are
+     * removed and sent a `WS_CLOSE_CONNECTION_LIMIT` close before the new one is
+     * inserted. A removed connection gets no further broadcast or peer request,
+     * stops counting toward the cap at once, and has its `abort_controller`
+     * aborted; its socket is closed when the close handshake completes. The new
+     * connection is always admitted.
+     *
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
-     * @mutates this - inserts into `#connections`, `#connection_ids`, and
-     *   `#connection_identities`
+     * @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): Uuid;
+    add_connection(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null, abort_controller?: AbortController | null): Uuid;
     /**
-     * Remove a WebSocket connection and its auth tracking data.
-     * Idempotent — safe to call after revocation has already cleaned up.
+     * Remove a connection and its auth tracking data, pending or admitted, by
+     * the id `register_pending` / `add_connection` returned. Idempotent — safe
+     * to call after revocation or a cap eviction has already cleaned up, and a
+     * no-op for an unknown id.
+     *
+     * Keyed by id rather than by `WSContext` because a runtime adapter may hand
+     * each socket event its own context object (`hono/bun` does), so the one a
+     * close event carries can't identify the connection.
      *
-     * @mutates this - deletes the connection's entries from `#connections`,
-     *   `#connection_ids`, and `#connection_identities`
+     * Removal only: the socket is not closed and the registered
+     * `abort_controller` is not aborted — the caller that ends a socket does
+     * both.
+     *
+     * @mutates this - deletes the connection's entry from `#connections` and
+     *   settles its pending peer requests as `connection_gone`
      */
-    remove_connection(ws: WSContext): void;
+    remove_connection(connection_id: Uuid): void;
     /**
-     * Close all sockets associated with a specific session token hash.
+     * Close all sockets associated with a specific session token hash,
+     * including a registration still pending admission.
      *
      * @returns the number of sockets closed
-     * @mutates this - removes matching connections from internal maps and
-     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_session(token_hash: string): number;
     /**
-     * Close all sockets associated with a specific account.
+     * Close all sockets associated with a specific account, including a
+     * registration still pending admission.
      *
      * @returns the number of sockets closed
-     * @mutates this - removes matching connections from internal maps and
-     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_account(account_id: Uuid): number;
     /**
-     * Close all sockets associated with a specific API token.
+     * Close all sockets associated with a specific API token, including a
+     * registration still pending admission.
      *
-     * Used on `token_revoke` audit events so revoking one token doesn't
-     * tear down the account's session-authenticated sockets or other
-     * tokens' sockets.
+     * Closes just this token's sockets, so revoking one token — or evicting
+     * one past the token cap — doesn't tear down the account's
+     * session-authenticated sockets or other tokens' sockets.
      *
      * @returns the number of sockets closed
-     * @mutates this - removes matching connections from internal maps and
-     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_token(api_token_id: string): number;
     send(message: JsonrpcRequest, options?: TransportSendOptions): Promise<JsonrpcResponseOrError>;
     send(message: JsonrpcNotification, options?: TransportSendOptions): Promise<JsonrpcErrorResponse | null>;
     /**
-     * Broadcast to connections whose identity satisfies a predicate.
+     * Broadcast to admitted connections whose identity satisfies a predicate. A
+     * registration pending admission is skipped before the predicate runs.
      *
      * Used by the broadcast API when a consumer supplies a subscription ACL hook
      * (e.g. zap's `zap_run_created` only reaches the account that owns the run).
@@ -106,7 +267,7 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      */
     broadcast_filtered(message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean): number;
     /**
-     * Send a message to every socket bound to a specific account.
+     * Send a message to every admitted socket bound to a specific account.
      *
      * Targeted per-account fan-out for any flow where the delivery target
      * is a single known account. Prefer this over `broadcast_filtered` when
@@ -129,7 +290,9 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * connection. Resolves when the client's matching reply arrives (routed in
      * via `resolve_peer_response`), the deadline elapses (`timeout`), the
      * per-connection cap is hit (`too_many_in_flight`), or the socket closes
-     * (`connection_gone`). Never throws — every failure is a `PeerRequestError`.
+     * (`connection_gone`). A connection still pending admission answers
+     * `connection_gone` like an unknown one. Never throws — every failure is a
+     * `PeerRequestError`.
      *
      * Delegates correlation to `#pending` (id allocation, deadline, cap, drain);
      * this method owns only the socket lookup + the send. Server-issued ids are
@@ -152,15 +315,34 @@ export declare class BackendWebsocketTransport implements FilterableBroadcastTra
      * @mutates this - clears the matched entry from `#pending`
      */
     resolve_peer_response(connection_id: Uuid, response: JsonrpcResponse | JsonrpcErrorResponse): boolean;
+    /**
+     * Whether a connection is still registered — and admitted: a registration
+     * pending admission answers `false`, like every other reader of the
+     * transport.
+     *
+     * `register_action_ws` checks it before dispatching each inbound message, so
+     * a socket the server has closed — revoked, superseded by the cap, or
+     * refused at admission — dispatches nothing more while its close handshake
+     * is still in flight. The twin of the Rust `ConnectionRegistry::is_registered`.
+     */
+    is_registered(connection_id: Uuid): boolean;
     is_ready(): boolean;
     /**
-     * Number of currently tracked WebSocket connections.
+     * Number of currently **admitted** WebSocket connections.
      *
-     * Read-only counter intended for telemetry, logging, and tests.
-     * Counts every entry in the connection map — including connections
-     * that have been closed by the peer but not yet removed by the WS
-     * adapter's `onClose` callback.
+     * Read-only counter intended for telemetry, logging, and tests. A
+     * registration still pending admission is not a connection yet and is
+     * counted by `get_pending_connection_count` instead. Includes connections
+     * that have been closed by the peer but not yet removed by the WS adapter's
+     * `onClose` callback.
      */
     get_connection_count(): number;
+    /**
+     * Number of registrations awaiting admission — between `register_pending`
+     * and `admit` (or their refusal). Each lives for one credential re-check, so
+     * a count that stays high means upgrades are stalling there. For telemetry
+     * and tests.
+     */
+    get_pending_connection_count(): number;
 }
 //# sourceMappingURL=transports_ws_backend.d.ts.map

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":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,KAAK,EAEX,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,EAEN,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA6B,SAAQ,SAAS;IAC9D,kBAAkB,EAAE,CACnB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,KAChD,MAAM,CAAC;CACZ;AAED,qDAAqD;AACrD,eAAO,MAAM,iCAAiC,GAC7C,WAAW,SAAS,KAClB,SAAS,IAAI,4BAEqE,CAAC;AAEtF,qBAAa,yBAA0B,YAAW,4BAA4B;;IAC7E,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IAiB3D;;;;;;;;;;;;OAYG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,GAChC,IAAI;IAQP;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IA0BtC;;;;;;OAMG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;;;OAMG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;;;OAUG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAuB/C,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAyCvC;;;;;;;;;OASG;IACH,kBAAkB,CACjB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,GAClD,MAAM;IAoBT;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,gCAAgC,GAAG,MAAM;IAIpF;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAAkB,CACjB,aAAa,EAAE,IAAI,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,oBAAoB,GAAG,SAAS,EACxC,OAAO,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,kBAAkB,CAAC;IAkB9B;;;;;;;;;;OAUG;IACH,qBAAqB,CACpB,aAAa,EAAE,IAAI,EACnB,QAAQ,EAAE,eAAe,GAAG,oBAAoB,GAC9C,OAAO;IAIV,QAAQ,IAAI,OAAO;IAInB;;;;;;;OAOG;IACH,oBAAoB,IAAI,MAAM;CAG9B"}
+{"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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"}