@fuzdev/fuz_app 0.118.0 → 0.120.0

package/dist/realtime/sse_auth_guard.d.ts

@@ -1,58 +1,71 @@
 /**
- * SSE auth guard and convenience factory for audit log SSE.
+ * SSE auth guard, connection closer, and convenience factory for audit log SSE.
  *
- * `create_sse_auth_guard` bridges audit events to `SubscriberRegistry.close_by_identity()`,
- * closing SSE streams when a subscriber's access is revoked (role revocation or
- * session invalidation).
+ * An SSE stream is authorized once, at open, and then only emits — nothing
+ * re-reads its credential or its role. Two things close it when its access is
+ * revoked:
+ *
+ * - `create_sse_connection_closer` adapts a `SubscriberRegistry` to
+ *   `ConnectionCloser`, so the revocation handlers close streams directly
+ *   after their transaction commits (`queue_connection_close`), whatever
+ *   happens to the audit write.
+ * - `create_sse_auth_guard` is the audit-event listener: it repeats those
+ *   closes when the row is announced, and it is the only closer for a role
+ *   revocation.
  *
  * `create_audit_log_sse` is a convenience factory that combines the registry,
- * guard, and broadcaster — making the secure path the easy path for consumers.
+ * guard, closer, and broadcaster — making the secure path the easy path for
+ * consumers.
  *
  * @module
  */
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import { type AuditLogEvent } from '../auth/audit_log_schema.js';
-import { SubscriberRegistry, type SubscribeOptions } from './subscriber_registry.js';
-import type { SseStream, SseNotification, EventSpec } from './sse.js';
+import type { ConnectionCloser, RealtimeCloser } from '../actions/connection_closer.js';
+import { SubscriberRegistry } from './subscriber_registry.js';
+import type { SseNotification, EventSpec } from './sse.js';
 /** SSE channel the audit-log stream route publishes on. */
 export declare const AUDIT_LOG_CHANNEL = "audit_log";
 /**
- * Audit event types that trigger SSE stream disconnection — the union of
- * access-invalidation events. Over-closing a one-way admin feed is cheap (the
- * client reconnects if still authorized), so the SSE set is the full union.
- *
- * `role_grant_revoke` requires the revoked role to match the guard's `required_role`
- * (or is skipped entirely when `required_role` is `null` — useful for streams
- * not gated by any specific role_grant). The WS half deliberately omits this
- * event (per-message re-authorization picks role changes up there); a one-way
- * SSE stream has no per-message recheck, so it must close here.
- * `session_revoke_all` / `token_revoke_all` / `password_change` / `logout` close
- * every stream for the target account.
- * `session_revoke` closes only the stream tied to the specific revoked session
- * (matched by the blake3 session hash in `event.metadata.session_id`) — closing
- * all of a user's streams for a single-session revoke would be over-aggressive.
- * The single `token_revoke` the WS half handles is omitted, and what makes that
- * correct is a gate rather than an assumption: the audit route declares
- * `credential_types: ['session']` (`auth/audit_log_route_schema.ts`), so a
- * bearer is refused at the channel and no stream is ever keyed by a single
- * token id. **A consumer that widens that gate must key its subscribers by
- * api-token id and add `token_revoke` here** — otherwise a revoked token keeps
- * receiving audit rows for the life of the connection. The Rust twin enforces
- * the same pairing structurally, via the `RevocationScope` column on
- * `AUDIT_EVENT_SPECS`.
- */
-export declare const disconnect_event_types: ReadonlySet<string>;
-/**
- * Create an audit event handler that closes SSE streams on auth changes.
+ * Adapt a `SubscriberRegistry` to `ConnectionCloser`, so a revocation handler's
+ * close reaches its streams.
  *
- * Closes streams when:
- * - `role_grant_revoke` fires for the `required_role` targeting a connected subscriber
- * - `session_revoke` targets the specific revoked session (session-hash-scoped)
- * - `session_revoke_all` / `token_revoke_all` / `password_change` / `logout`
- *   target a connected subscriber (account-wide)
+ * Each method is `SubscriberRegistry.close_by_identity` on the id it is given,
+ * so it closes the streams registered under that id as their `scope` or in
+ * their `groups` — pending registrations included. The audit stream route
+ * registers `scope = session hash` and `groups = [account id]`; a route that
+ * admits bearer tokens registers the API token id too, and
+ * `close_sockets_for_token` then reaches it.
  *
- * The registry must use `account_id` as the identity key when subscribing
- * (passed as the third argument to `registry.subscribe()`).
+ * Twin of the Rust spine's `SocketRevoker` impl on `SseRegistry`.
+ */
+export declare const create_sse_connection_closer: <T>(registry: SubscriberRegistry<T>) => ConnectionCloser;
+/**
+ * Create an audit event handler that closes SSE streams on a successful
+ * revocation row, dispatching on the event's `RevocationScope`
+ * (`audit_event_revocation_scopes`, the table `create_ws_auth_guard` reads
+ * too):
+ *
+ * - `session` → the stream registered under the revoked session's hash
+ *   (`metadata.session_id`). Closing all of an account's streams for a
+ *   single-session revoke would be over-aggressive.
+ * - `token` → the stream registered under the revoked API token's id
+ *   (`metadata.token_id`). The audit stream route admits sessions only, so no
+ *   stream of its own is keyed that way; a consumer route that admits bearers
+ *   registers the token id and is closed here.
+ * - `account` → every stream of `target_account_id ?? account_id`.
+ * - `role` → every stream of the target account, when the revoked role
+ *   (`metadata.role`) is `required_role`. The WebSocket guard does not act on
+ *   this scope — per-message dispatch re-authorizes there — but a one-way
+ *   stream has no later check, so it must close here.
+ * - `none` → nothing.
+ *
+ * Over-closing a one-way feed is cheap: the client reconnects if it is still
+ * authorized.
+ *
+ * The registry's subscribers must carry `account_id` as an identity key (in
+ * `SubscribeOptions.groups`), and the session hash as `scope` for the
+ * session-scoped close.
  *
  * @param registry - the subscriber registry to guard
  * @param required_role - the role that grants access to the SSE endpoint,
@@ -69,14 +82,17 @@ export declare const create_sse_auth_guard: <T>(registry: SubscriberRegistry<T>,
  * `on_audit_event` callback (broadcast + guard).
  */
 export interface AuditLogSse {
-    /** Subscribe function — pass as part of `stream` option to `create_audit_log_route_specs`. */
-    subscribe: (stream: SseStream<SseNotification>, options?: SubscribeOptions) => () => void;
+    /**
+     * The subscriber registry the audit stream route registers each stream on
+     * (two-phase: `subscribe_pending` then `admit`) — pass as part of the
+     * `stream` option to `create_audit_log_route_specs`. Also exposed for
+     * subscriber count monitoring.
+     */
+    registry: SubscriberRegistry<SseNotification>;
     /** Logger — pass as part of `stream` option to `create_audit_log_route_specs`. */
     log: Logger;
     /** Combined broadcast + guard callback. Wired by `create_app_server`'s `audit_log_sse` option, or compose inside the consumer's `audit_factory` body. */
     on_audit_event: (event: AuditLogEvent) => void;
-    /** The underlying registry — exposed for subscriber count monitoring. */
-    registry: SubscriberRegistry<SseNotification>;
 }
 /**
  * SSE event specs for audit log events.
@@ -97,10 +113,12 @@ export declare const audit_log_event_specs: Array<EventSpec>;
  */
 export declare const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
 /**
- * Create a complete audit log SSE setup with broadcasting and auth guard.
+ * Create a complete audit log SSE setup with broadcasting, auth guard, and
+ * connection closer.
  *
  * Combines `SubscriberRegistry`, `create_sse_auth_guard`, and the broadcast
- * call into a single object. The result satisfies `AuditLogRouteOptions['stream']`
+ * call into a single object, and adds the registry to `connection_closer`.
+ * The result satisfies `AuditLogRouteOptions['stream']`
  * and provides the `on_audit_event` listener for the audit emitter.
  *
  * Most consumers pass `audit_log_sse: true` to `create_app_server` and never
@@ -116,9 +134,12 @@ export declare const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
  *
  * @example
  * ```ts
- * const audit_sse = create_audit_log_sse({log});
+ * const connection_closer = create_realtime_closer();
+ * const audit_sse = create_audit_log_sse({log, connection_closer});
  *
- * // Inside the audit_factory body on CreateAppBackendOptions:
+ * // On CreateAppBackendOptions — the same closer, and the listener inside
+ * // the audit_factory body:
+ * connection_closer,
  * audit_factory: ({db, log}) => create_audit_emitter({
  *   db,
  *   log,
@@ -136,6 +157,15 @@ export declare const create_audit_log_sse: (options: {
     /** Role required to access the SSE endpoint. Default `'admin'`. */
     role?: string;
     log: Logger;
+    /**
+     * The backend's closer — `deps.connection_closer`. The new registry is
+     * added to it, so every revocation handler's close reaches these streams.
+     * Required so it can't be forgotten: without it a revoked credential's
+     * streams close only through the audit listener, which a failed audit write
+     * or a cap eviction never reaches. Pass `null` only for a registry no
+     * revocation has to reach (tests of the registry itself).
+     */
+    connection_closer: RealtimeCloser | null;
     /**
      * Max concurrent SSE subscribers per session scope. On overflow, the oldest
      * matching subscriber is closed. Default `AUDIT_LOG_SSE_MAX_PER_SCOPE`.

package/dist/realtime/sse_auth_guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAEtE,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAOrD,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACtC,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,GAAG,IAAI,EAC5B,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA6CjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,8FAA8F;IAC9F,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IAC1F,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,yJAAyJ;IACzJ,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,KAAG,WAgBH,CAAC"}
+{"version":3,"file":"sse_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,EAIN,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACxF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE3D,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,EAC7C,UAAU,kBAAkB,CAAC,CAAC,CAAC,KAC7B,gBAID,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACtC,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,GAAG,IAAI,EAC5B,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA4DjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;;OAKG;IACH,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAC9C,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,yJAAyJ;IACzJ,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,iBAAiB,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,KAAG,WAgBH,CAAC"}

package/dist/realtime/sse_auth_guard.js

@@ -1,63 +1,73 @@
 /**
- * SSE auth guard and convenience factory for audit log SSE.
+ * SSE auth guard, connection closer, and convenience factory for audit log SSE.
  *
- * `create_sse_auth_guard` bridges audit events to `SubscriberRegistry.close_by_identity()`,
- * closing SSE streams when a subscriber's access is revoked (role revocation or
- * session invalidation).
+ * An SSE stream is authorized once, at open, and then only emits — nothing
+ * re-reads its credential or its role. Two things close it when its access is
+ * revoked:
+ *
+ * - `create_sse_connection_closer` adapts a `SubscriberRegistry` to
+ *   `ConnectionCloser`, so the revocation handlers close streams directly
+ *   after their transaction commits (`queue_connection_close`), whatever
+ *   happens to the audit write.
+ * - `create_sse_auth_guard` is the audit-event listener: it repeats those
+ *   closes when the row is announced, and it is the only closer for a role
+ *   revocation.
  *
  * `create_audit_log_sse` is a convenience factory that combines the registry,
- * guard, and broadcaster — making the secure path the easy path for consumers.
+ * guard, closer, and broadcaster — making the secure path the easy path for
+ * consumers.
  *
  * @module
  */
-import { AUDIT_EVENT_TYPES, AuditLogEventJson } from '../auth/audit_log_schema.js';
+import { UnreachableError } from '@fuzdev/fuz_util/error.ts';
+import { AUDIT_EVENT_TYPES, AuditLogEventJson, to_revocation_scope } from '../auth/audit_log_schema.js';
 import { SubscriberRegistry } from './subscriber_registry.js';
 /** SSE channel the audit-log stream route publishes on. */
 export const AUDIT_LOG_CHANNEL = 'audit_log';
 /**
- * Audit event types that trigger SSE stream disconnection — the union of
- * access-invalidation events. Over-closing a one-way admin feed is cheap (the
- * client reconnects if still authorized), so the SSE set is the full union.
- *
- * `role_grant_revoke` requires the revoked role to match the guard's `required_role`
- * (or is skipped entirely when `required_role` is `null` — useful for streams
- * not gated by any specific role_grant). The WS half deliberately omits this
- * event (per-message re-authorization picks role changes up there); a one-way
- * SSE stream has no per-message recheck, so it must close here.
- * `session_revoke_all` / `token_revoke_all` / `password_change` / `logout` close
- * every stream for the target account.
- * `session_revoke` closes only the stream tied to the specific revoked session
- * (matched by the blake3 session hash in `event.metadata.session_id`) — closing
- * all of a user's streams for a single-session revoke would be over-aggressive.
- * The single `token_revoke` the WS half handles is omitted, and what makes that
- * correct is a gate rather than an assumption: the audit route declares
- * `credential_types: ['session']` (`auth/audit_log_route_schema.ts`), so a
- * bearer is refused at the channel and no stream is ever keyed by a single
- * token id. **A consumer that widens that gate must key its subscribers by
- * api-token id and add `token_revoke` here** — otherwise a revoked token keeps
- * receiving audit rows for the life of the connection. The Rust twin enforces
- * the same pairing structurally, via the `RevocationScope` column on
- * `AUDIT_EVENT_SPECS`.
- */
-export const disconnect_event_types = new Set([
-    'role_grant_revoke', // role revoked — user lost access
-    'session_revoke', // single session revoked — close only that stream
-    'session_revoke_all', // all sessions invalidated — user should be kicked
-    'token_revoke_all', // all API tokens invalidated — close the account's streams
-    'password_change', // password changed — all sessions revoked implicitly
-    'logout' // explicit logout — close the account's streams
-]);
-/**
- * Create an audit event handler that closes SSE streams on auth changes.
+ * Adapt a `SubscriberRegistry` to `ConnectionCloser`, so a revocation handler's
+ * close reaches its streams.
  *
- * Closes streams when:
- * - `role_grant_revoke` fires for the `required_role` targeting a connected subscriber
- * - `session_revoke` targets the specific revoked session (session-hash-scoped)
- * - `session_revoke_all` / `token_revoke_all` / `password_change` / `logout`
- *   target a connected subscriber (account-wide)
+ * Each method is `SubscriberRegistry.close_by_identity` on the id it is given,
+ * so it closes the streams registered under that id as their `scope` or in
+ * their `groups` — pending registrations included. The audit stream route
+ * registers `scope = session hash` and `groups = [account id]`; a route that
+ * admits bearer tokens registers the API token id too, and
+ * `close_sockets_for_token` then reaches it.
  *
- * The registry must use `account_id` as the identity key when subscribing
- * (passed as the third argument to `registry.subscribe()`).
+ * Twin of the Rust spine's `SocketRevoker` impl on `SseRegistry`.
+ */
+export const create_sse_connection_closer = (registry) => ({
+    close_sockets_for_session: (session_token_hash) => registry.close_by_identity(session_token_hash),
+    close_sockets_for_token: (api_token_id) => registry.close_by_identity(api_token_id),
+    close_sockets_for_account: (account_id) => registry.close_by_identity(account_id)
+});
+/**
+ * Create an audit event handler that closes SSE streams on a successful
+ * revocation row, dispatching on the event's `RevocationScope`
+ * (`audit_event_revocation_scopes`, the table `create_ws_auth_guard` reads
+ * too):
+ *
+ * - `session` → the stream registered under the revoked session's hash
+ *   (`metadata.session_id`). Closing all of an account's streams for a
+ *   single-session revoke would be over-aggressive.
+ * - `token` → the stream registered under the revoked API token's id
+ *   (`metadata.token_id`). The audit stream route admits sessions only, so no
+ *   stream of its own is keyed that way; a consumer route that admits bearers
+ *   registers the token id and is closed here.
+ * - `account` → every stream of `target_account_id ?? account_id`.
+ * - `role` → every stream of the target account, when the revoked role
+ *   (`metadata.role`) is `required_role`. The WebSocket guard does not act on
+ *   this scope — per-message dispatch re-authorizes there — but a one-way
+ *   stream has no later check, so it must close here.
+ * - `none` → nothing.
+ *
+ * Over-closing a one-way feed is cheap: the client reconnects if it is still
+ * authorized.
+ *
+ * The registry's subscribers must carry `account_id` as an identity key (in
+ * `SubscribeOptions.groups`), and the session hash as `scope` for the
+ * session-scoped close.
  *
  * @param registry - the subscriber registry to guard
  * @param required_role - the role that grants access to the SSE endpoint,
@@ -68,8 +78,6 @@ export const disconnect_event_types = new Set([
  */
 export const create_sse_auth_guard = (registry, required_role, log) => {
     return (event) => {
-        if (!disconnect_event_types.has(event.event_type))
-            return;
         // Only act on successful revocations. Failed attempts carry
         // attacker-controlled identifiers (e.g., session_revoke with outcome=failure
         // carries the submitted session_id even when the DB rejected the cross-account
@@ -77,29 +85,46 @@ export const create_sse_auth_guard = (registry, required_role, log) => {
         // user's SSE stream by guessing or leaking a session hash.
         if (event.outcome === 'failure')
             return;
-        // session_revoke is session-scoped, not account-scoped — close only the
-        // stream subscribed under the revoked session's hash. The hash is already
-        // in the event metadata (set by the `account_session_revoke` RPC handler).
-        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;
-            const closed = registry.close_by_identity(session_id);
-            if (closed > 0) {
-                log.info(`SSE auth guard: closed ${closed} stream(s) for session ${session_id} (session_revoke)`);
-            }
-            return;
-        }
-        // role_grant_revoke requires matching the specific role. `null` means the
-        // stream isn't gated by a specific role_grant, so role_grant_revoke is a no-op.
-        if (event.event_type === 'role_grant_revoke') {
-            if (required_role === null)
+            case 'session': {
+                const session_id = event.metadata?.session_id;
+                if (typeof session_id !== 'string' || session_id.length === 0)
+                    return;
+                const closed = registry.close_by_identity(session_id);
+                if (closed > 0) {
+                    log.info(`SSE auth guard: closed ${closed} stream(s) for session ${session_id} (${event.event_type})`);
+                }
                 return;
-            if (event.metadata?.role !== required_role)
+            }
+            case 'token': {
+                const token_id = event.metadata?.token_id;
+                if (typeof token_id !== 'string' || token_id.length === 0)
+                    return;
+                const closed = registry.close_by_identity(token_id);
+                if (closed > 0) {
+                    log.info(`SSE auth guard: closed ${closed} stream(s) for token ${token_id} (${event.event_type})`);
+                }
                 return;
+            }
+            case 'role':
+                // `null` means the stream isn't gated by a specific role_grant, so
+                // a role revocation closes nothing.
+                if (required_role === null)
+                    return;
+                if (event.metadata?.role !== required_role)
+                    return;
+                break;
+            case 'account':
+                break;
+            default:
+                throw new UnreachableError(scope);
         }
-        // resolve the affected account — admin actions set target_account_id,
-        // self-service actions (password_change, own session_revoke_all) only set account_id
+        // `role` and `account` both close the affected account's streams —
+        // 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;
@@ -133,10 +158,12 @@ export const audit_log_event_specs = AUDIT_EVENT_TYPES.map((event_type) => ({
  */
 export const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
 /**
- * Create a complete audit log SSE setup with broadcasting and auth guard.
+ * Create a complete audit log SSE setup with broadcasting, auth guard, and
+ * connection closer.
  *
  * Combines `SubscriberRegistry`, `create_sse_auth_guard`, and the broadcast
- * call into a single object. The result satisfies `AuditLogRouteOptions['stream']`
+ * call into a single object, and adds the registry to `connection_closer`.
+ * The result satisfies `AuditLogRouteOptions['stream']`
  * and provides the `on_audit_event` listener for the audit emitter.
  *
  * Most consumers pass `audit_log_sse: true` to `create_app_server` and never
@@ -152,9 +179,12 @@ export const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
  *
  * @example
  * ```ts
- * const audit_sse = create_audit_log_sse({log});
+ * const connection_closer = create_realtime_closer();
+ * const audit_sse = create_audit_log_sse({log, connection_closer});
  *
- * // Inside the audit_factory body on CreateAppBackendOptions:
+ * // On CreateAppBackendOptions — the same closer, and the listener inside
+ * // the audit_factory body:
+ * connection_closer,
  * audit_factory: ({db, log}) => create_audit_emitter({
  *   db,
  *   log,
@@ -173,8 +203,8 @@ export const create_audit_log_sse = (options) => {
     const max_per_scope = options.max_per_scope === undefined ? AUDIT_LOG_SSE_MAX_PER_SCOPE : options.max_per_scope;
     const registry = new SubscriberRegistry({ max_per_scope });
     const guard = create_sse_auth_guard(registry, role, options.log);
+    options.connection_closer?.add(create_sse_connection_closer(registry));
     return {
-        subscribe: registry.subscribe.bind(registry),
         log: options.log,
         on_audit_event: (event) => {
             registry.broadcast(AUDIT_LOG_CHANNEL, { method: event.event_type, params: event });

package/dist/realtime/subscriber_registry.d.ts

@@ -17,9 +17,13 @@
  * carries a broader identity for coarse close — the broader identity
  * doesn't cap across sessions.
  *
+ * Registration can run in two phases (`subscribe_pending` then `admit`) so a
+ * revocation reaches a stream that is still opening — see the class doc.
+ *
  * @module
  */
 import type { SseStream } from './sse.js';
+/** One admitted subscriber, as `SubscriberRegistry.broadcast` sees it. */
 export interface Subscriber<T> {
     stream: SseStream<T>;
     /** Channels this subscriber listens to. `null` means all channels. */
@@ -32,14 +36,14 @@ export interface Subscriber<T> {
 /** Options for `SubscriberRegistry`. */
 export interface SubscriberRegistryOptions {
     /**
-     * Max subscribers sharing a single `scope`. On subscribe, when the count
-     * of subscribers with the same `scope` reaches this limit, the oldest
-     * matching subscriber(s) are closed before the new one is added.
+     * Max admitted subscribers sharing a single `scope`. When a subscriber is
+     * admitted and the count of admitted subscribers with the same `scope` has
+     * reached this limit, the oldest matching subscriber(s) are closed first.
      * `null` (default) disables the cap. `groups` identities are never capped.
      */
     max_per_scope?: number | null;
 }
-/** Options for `SubscriberRegistry.subscribe`. */
+/** Options for `SubscriberRegistry.subscribe` and `subscribe_pending`. */
 export interface SubscribeOptions {
     /** Channels to subscribe to. Empty/absent = all channels. */
     channels?: ReadonlyArray<string>;
@@ -54,6 +58,23 @@ export interface SubscribeOptions {
      */
     groups?: ReadonlyArray<string>;
 }
+/**
+ * A registered subscription awaiting admission — what
+ * `SubscriberRegistry.subscribe_pending` returns and
+ * `SubscriberRegistry.admit` takes.
+ *
+ * Its entry is already in the registry, so every `close_by_identity` can reach
+ * it, but nothing is delivered to it and it does not count toward the
+ * per-scope cap until it is admitted.
+ */
+export interface PendingSubscription {
+    /**
+     * Remove the registration, pending or admitted. Idempotent. Every path that
+     * refuses a pending subscription calls it, and an admitted stream's
+     * `on_close` listener does.
+     */
+    unsubscribe: () => void;
+}
 /**
  * Generic subscriber registry with channel-based filtering and identity-keyed disconnection.
  *
@@ -62,6 +83,28 @@ export interface SubscribeOptions {
  * matching subscribers. `close_by_identity` force-closes all subscribers
  * whose `scope` or `groups` contain the given key — use for auth revocation.
  *
+ * ## Two-phase registration
+ *
+ * A stream is authorized once, at open, so a revocation has to be able to
+ * reach it from the moment its credential is read. A route's gates run before
+ * the stream exists, and each revocation closes only the streams *registered*
+ * under what it revoked — registering after the gates leaves a window in which
+ * a revocation closes nothing and the stream then opens on a dead session, or
+ * under a role its actor no longer holds.
+ *
+ * So a route that authenticated a revocable credential registers in two
+ * phases: `subscribe_pending` registers the subscription **un-admitted** —
+ * closeable by every `close_by_identity`, and otherwise inert: it has no
+ * stream, so no broadcast reaches it, the cap neither counts nor evicts for
+ * it, and `count` does not see it (`pending_count` does). The route then
+ * re-reads the credential and the role, and `admit` attaches the stream and
+ * opens the feed — or refuses when a revocation closed the registration in
+ * between, evicting nothing. The cap's eviction happens at admission.
+ *
+ * `subscribe` stays as the one-step form for a stream with nothing to revoke
+ * behind it. The twin of the Rust `fuz_realtime` `SseRegistry`
+ * (`subscribe_pending` / `admit` / `subscribe`).
+ *
  * @example
  * ```ts
  * const registry = new SubscriberRegistry<SseNotification>();
@@ -91,14 +134,42 @@ export interface SubscribeOptions {
  * // fine — close just the stream(s) tied to a specific session
  * registry.close_by_identity(session_hash);
  * ```
+ *
+ * @example
+ * ```ts
+ * // two-phase, for a route behind a revocable credential
+ * const pending = registry.subscribe_pending({scope: session_hash, groups: [account_id]});
+ * if (!(await credential_is_still_live())) {
+ *   pending.unsubscribe();
+ *   return unauthorized();
+ * }
+ * const {response, stream} = create_sse_response(c, log);
+ * if (registry.admit(pending, stream)) stream.on_close(pending.unsubscribe);
+ * else stream.close(); // closed while pending — the body is the connect comment alone
+ * return response;
+ * ```
  */
 export declare class SubscriberRegistry<T> {
     #private;
     constructor(options?: SubscriberRegistryOptions);
-    /** Number of active subscribers. */
+    /**
+     * Number of open — **admitted** — subscribers. A registration still pending
+     * admission is counted by `pending_count` instead.
+     */
     get count(): number;
     /**
-     * Add a subscriber.
+     * Number of registrations awaiting admission — between `subscribe_pending`
+     * and `admit` (or their refusal). For telemetry and tests.
+     */
+    get pending_count(): number;
+    /**
+     * Add a subscriber, admitted at once — the one-step form of
+     * `subscribe_pending` + `admit`.
+     *
+     * **Not for a route that authenticated a revocable credential**: a
+     * revocation landing between that route's gates and this call closes
+     * nothing, and the stream would open on a dead credential (class doc,
+     * "Two-phase registration").
      *
      * @param stream - SSE stream to send data to
      * @param options - channel filter and identity slots (`scope` + `groups`)
@@ -107,10 +178,42 @@ export declare class SubscriberRegistry<T> {
      */
     subscribe(stream: SseStream<T>, options?: SubscribeOptions): () => void;
     /**
-     * Broadcast data to all subscribers on a channel.
+     * Register a subscription **un-admitted** — phase one of the two-phase
+     * registration (class doc).
+     *
+     * The registration is closeable at once by every `close_by_identity`
+     * matching its `scope` or `groups`, and until `admit` it receives no
+     * broadcast, is not counted, and evicts nothing. A caller that then refuses
+     * the request calls the returned handle's `unsubscribe`.
+     *
+     * @param options - channel filter and identity slots (`scope` + `groups`)
+     * @returns the pending handle `admit` takes
+     * @mutates registry - adds the un-admitted registration
+     */
+    subscribe_pending(options?: SubscribeOptions): PendingSubscription;
+    /**
+     * Admit a pending subscription, attaching the stream it delivers to — phase
+     * two (class doc).
+     *
+     * If the registration is gone — a revocation closed it while it was
+     * pending, or it was unsubscribed — nothing is evicted and the subscription
+     * is refused. Otherwise the per-scope cap is enforced as in `subscribe`,
+     * counting only admitted subscribers, and the stream starts receiving
+     * `broadcast` data. Admitting twice is refused the second time.
+     *
+     * @param pending - the handle `subscribe_pending` returned
+     * @param stream - SSE stream to send data to
+     * @returns `false` when the subscription was not admitted — the caller ends the stream
+     * @mutates registry - attaches `stream`; closes oldest matching subscribers when `max_per_scope` is exceeded
+     */
+    admit(pending: PendingSubscription, stream: SseStream<T>): boolean;
+    /**
+     * Broadcast data to all admitted subscribers on a channel.
      *
      * Subscribers with no channel filter receive all broadcasts.
-     * Subscribers with a channel filter only receive matching broadcasts.
+     * Subscribers with a channel filter only receive matching broadcasts. A
+     * registration pending admission is not an open stream and is skipped —
+     * nothing is queued toward a subscriber not yet authorized.
      */
     broadcast(channel: string, data: T): void;
     /**
@@ -120,9 +223,17 @@ export declare class SubscriberRegistry<T> {
      * Use for auth revocation — when a user's permissions change, close their
      * SSE connections so they must reconnect and re-authenticate.
      *
+     * Matches every registration, pending or admitted — never filter on
+     * admission here: reaching a registration in flight is the point of the
+     * pending phase, and `admit` then refuses it.
+     *
+     * A stream whose `close` throws does not stop the loop: every match is
+     * removed and closed, and the first error is thrown afterward.
+     *
      * @param identity - the identity key to match (checked against `scope` and `groups`)
      * @returns the number of subscribers closed
      * @mutates registry - removes matching subscribers and closes their streams
+     * @throws the first error a stream's `close` threw, after every match was attempted
      */
     close_by_identity(identity: string): number;
 }

package/dist/realtime/subscriber_registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscriber_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/subscriber_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,MAAM,WAAW,UAAU,CAAC,CAAC;IAC5B,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACrB,sEAAsE;IACtE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7B,mDAAmD;IACnD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qEAAqE;IACrE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CAC3B;AAED,wCAAwC;AACxC,MAAM,WAAW,yBAAyB;IACzC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,kBAAkB,CAAC,CAAC;;gBAIpB,OAAO,CAAC,EAAE,yBAAyB;IAI/C,oCAAoC;IACpC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAmBvE;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI;IAQzC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAiC3C"}
+{"version":3,"file":"subscriber_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/subscriber_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,0EAA0E;AAC1E,MAAM,WAAW,UAAU,CAAC,CAAC;IAC5B,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACrB,sEAAsE;IACtE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7B,mDAAmD;IACnD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qEAAqE;IACrE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CAC3B;AASD,wCAAwC;AACxC,MAAM,WAAW,yBAAyB;IACzC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,qBAAa,kBAAkB,CAAC,CAAC;;gBAQpB,OAAO,CAAC,EAAE,yBAAyB;IAI/C;;;OAGG;IACH,IAAI,KAAK,IAAI,MAAM,CAMlB;IAED;;;OAGG;IACH,IAAI,aAAa,IAAI,MAAM,CAM1B;IAED;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,IAAI;IASvE;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,mBAAmB;IAYlE;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO;IASlE;;;;;;;OAOG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI;IASzC;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAwE3C"}