@fuzdev/fuz_app 0.140.0 → 0.142.0

package/dist/rate_limiter.js

@@ -4,10 +4,28 @@
  * Tracks failed attempts per key (typically IP address) using a sliding
  * time window. No external dependencies — state resets on server restart.
  *
+ * **Reserve, then settle.** A handler that checks the limiter, awaits work,
+ * and records afterwards lets every request of a concurrent burst pass the
+ * check before any of them records — a burst of any size gets through.
+ * `RateLimiter.try_reserve` closes that: it admits a request and counts it in
+ * flight in one synchronous step, and the attempt counts against the cap
+ * until its `RateLimitReservation` is settled — `record` keeps it as an
+ * attempt, `release` gives it back. Every handler whose outcome decides
+ * whether the attempt counts reserves, and releases in a `finally` so an
+ * early return or a throw never leaks an in-flight slot; `check` + `record`
+ * stays for callers that record in the same synchronous step they check.
+ *
+ * **Attempts count while in flight, whatever their outcome** — so a burst of
+ * *correct* concurrent attempts from one key is capped too. The password
+ * surfaces therefore reserve with `RateLimiter.reserve`, which waits up to
+ * `RESERVATION_WAIT_MAX_MS` for a slot when the cap is reached only by
+ * attempts in flight, and refuses at once when it is reached by recorded ones.
+ *
  * @module
  */
 import { LruMap } from '@fuzdev/fuz_util/lru_map.ts';
 import { ERROR_RATE_LIMIT_EXCEEDED } from './http/error_schemas.js';
+import { PERIODIC_INTERVAL_MS_MAX } from './periodic.js';
 /**
  * Default tracked-key cap: bounds worst-case memory under key-enumeration
  * attacks (an attacker rotating source IPs cannot grow the backing map
@@ -90,10 +108,36 @@ export const announce_rate_limiters_disabled = () => {
     rate_limiters_disabled_announced = true;
     console.error(RATE_LIMITERS_DISABLED_BANNER);
 };
+/**
+ * `retry_after` reported while a key is at its cap only because of attempts
+ * still in flight. Those settle within a request's lifetime, so the earliest
+ * moment worth retrying is the next second, not the oldest recorded attempt's
+ * expiry. Mirrors the Rust spine's `IN_FLIGHT_RETRY_AFTER_SECONDS`.
+ */
+export const IN_FLIGHT_RETRY_AFTER_SECONDS = 1;
+/**
+ * How long a password-surface reservation (`RateLimiter.reserve`) waits for a
+ * slot when the key is at its cap only because of attempts still in flight,
+ * before answering `429`. Mirrors the Rust spine's `RESERVATION_WAIT_MAX`.
+ *
+ * Counting attempts while they are in flight caps *successful* concurrent
+ * attempts from one key too — a class behind one NAT logging in together.
+ * Those attempts settle within a request's lifetime, so a short wait turns
+ * most of those refusals into a late success, while a key at its cap on
+ * *recorded* attempts is still refused at once.
+ */
+export const RESERVATION_WAIT_MAX_MS = 5_000;
+/** The reservation a disabled limiter hands out: settling it does nothing. */
+const INERT_RESERVATION = Object.freeze({
+    record: () => { },
+    release: () => { }
+});
+const entry_is_idle = (entry) => entry.timestamps.length === 0 && entry.in_flight === 0;
 /**
  * In-memory sliding window rate limiter.
  *
- * Stores an array of timestamps per key. On `check`/`record`, timestamps
+ * Stores an array of timestamps per key, plus a count of attempts reserved
+ * (`try_reserve`) and not yet settled. On `check`/`record`, timestamps
  * outside the window are pruned. `retry_after` reports seconds until the
  * oldest active timestamp expires.
  *
@@ -110,10 +154,37 @@ export const announce_rate_limiters_disabled = () => {
  */
 export class RateLimiter {
     options;
-    /** Key → array of attempt timestamps. */
+    /** Key → recorded attempt timestamps + attempts in flight. */
     #attempts;
     #cleanup_timer = null;
+    /**
+     * `reserve` calls parked on a key at its in-flight cap, per key, with the
+     * wakers that key's settles, records, and resets run so each re-decides.
+     * Held apart from the attempts map, so evicting a key's entry strands none
+     * of its waiters; a key's slot is removed when its last waiter leaves. Per
+     * key, so a settle wakes only the waiters it can admit or refuse — never
+     * every waiter on the limiter.
+     */
+    #waiters = new Map();
+    /**
+     * @param options - the limiter's bounds
+     * @throws {RangeError} when `max_attempts`, `window_ms`, or `cleanup_interval_ms` is not a safe integer ≥ 0, `cleanup_interval_ms` exceeds `PERIODIC_INTERVAL_MS_MAX`, or `max_keys` is neither `null` nor a positive safe integer
+     */
     constructor(options) {
+        for (const field of ['max_attempts', 'window_ms', 'cleanup_interval_ms']) {
+            const value = options[field];
+            if (!Number.isSafeInteger(value) || value < 0) {
+                throw new RangeError(`RateLimiterOptions.${field} must be a safe integer ≥ 0: ${value}`);
+            }
+        }
+        if (options.cleanup_interval_ms > PERIODIC_INTERVAL_MS_MAX) {
+            throw new RangeError(`RateLimiterOptions.cleanup_interval_ms must be at most ${PERIODIC_INTERVAL_MS_MAX}: ${options.cleanup_interval_ms}`);
+        }
+        if (options.max_keys !== undefined &&
+            options.max_keys !== null &&
+            !(Number.isSafeInteger(options.max_keys) && options.max_keys > 0)) {
+            throw new RangeError(`RateLimiterOptions.max_keys must be null or a positive safe integer: ${options.max_keys}`);
+        }
         this.options = options;
         const max_keys = options.max_keys === undefined ? DEFAULT_RATE_LIMITER_MAX_KEYS : options.max_keys;
         this.#attempts = max_keys === null ? new Map() : new LruMap(max_keys);
@@ -129,6 +200,17 @@ export class RateLimiter {
     get size() {
         return this.#attempts.size;
     }
+    /**
+     * Keys holding a parked-waiter slot right now (see `reserve`): each slot is
+     * removed with its key's last waiter. For tests pinning that a waiter
+     * leaves nothing behind; the twin of the Rust spine's test-only
+     * `waiter_keys`.
+     *
+     * @internal
+     */
+    get waiter_keys() {
+        return this.#waiters.size;
+    }
     /**
      * Custom inspect output that exposes only `options` and `size`, never the
      * tracked keys. The key set is sensitive (usernames / IP addresses) and
@@ -141,38 +223,59 @@ export class RateLimiter {
         return { options: this.options, size: this.size };
     }
     /**
-     * Check whether `key` is allowed without recording an attempt.
+     * Check whether `key` is allowed without recording an attempt, counting
+     * recorded attempts and reserved ones still in flight.
      *
      * Prunes timestamps that fell outside the window as a side effect (and
-     * removes the key entirely when none remain), so the backing map stays
-     * bounded even under read-only traffic.
+     * removes the key entirely when none remain and none are in flight), so
+     * the backing map stays bounded even under read-only traffic.
+     *
+     * A check followed by an awaited operation and then a `record` lets a
+     * concurrent burst past the cap; reserve with `try_reserve` instead.
      *
      * @param key - rate limit key (e.g. IP address)
      * @param now - current timestamp in ms (defaults to `Date.now()`)
      * @mutates internal map - prunes expired timestamps for `key`
      */
     check(key, now = Date.now()) {
+        const load = this.#load(key, now);
+        switch (load.kind) {
+            case 'free':
+                return { allowed: true, remaining: this.options.max_attempts - load.used, retry_after: 0 };
+            case 'recorded':
+                return { allowed: false, remaining: 0, retry_after: load.retry_after };
+            case 'in_flight':
+                return { allowed: false, remaining: 0, retry_after: IN_FLIGHT_RETRY_AFTER_SECONDS };
+        }
+    }
+    /** Where `key` stands against the cap, pruning expired timestamps first. */
+    #load(key, now) {
         const { max_attempts, window_ms } = this.options;
-        const cutoff = now - window_ms;
-        const timestamps = this.#attempts.get(key);
-        if (!timestamps) {
-            return { allowed: true, remaining: max_attempts, retry_after: 0 };
+        // A cap of zero refuses before reading the key: no entry is created or
+        // promoted, and no reservation parks. The wait it names is the whole
+        // window, at least a second.
+        if (max_attempts === 0) {
+            return { kind: 'recorded', retry_after: Math.max(1, Math.ceil(window_ms / 1000)) };
         }
-        const active = timestamps.filter((t) => t > cutoff);
-        if (active.length !== timestamps.length) {
-            if (active.length === 0) {
-                this.#attempts.delete(key);
-            }
-            else {
-                this.#attempts.set(key, active);
-            }
+        const entry = this.#attempts.get(key);
+        if (!entry)
+            return { kind: 'free', used: 0 };
+        const cutoff = now - window_ms;
+        const active = entry.timestamps.filter((t) => t > cutoff);
+        entry.timestamps = active;
+        // A key with attempts in flight stays even with no live timestamp:
+        // deleting it would drop the count it carries.
+        if (entry_is_idle(entry)) {
+            this.#attempts.delete(key);
+            return { kind: 'free', used: 0 };
         }
-        if (active.length < max_attempts) {
-            return { allowed: true, remaining: max_attempts - active.length, retry_after: 0 };
+        // At the cap on recorded attempts alone, wait for the oldest; at the
+        // cap only with the in-flight attempts counted, a settle frees a slot.
+        if (active.length >= max_attempts) {
+            return { kind: 'recorded', retry_after: Math.ceil((active[0] + window_ms - now) / 1000) };
         }
-        const oldest = active[0];
-        const retry_after = Math.ceil((oldest + window_ms - now) / 1000);
-        return { allowed: false, remaining: 0, retry_after };
+        const used = active.length + entry.in_flight;
+        return used < max_attempts ? { kind: 'free', used } : { kind: 'in_flight' };
     }
     /**
      * Record a failed attempt for `key` and return the updated result.
@@ -184,19 +287,21 @@ export class RateLimiter {
     record(key, now = Date.now()) {
         const { max_attempts, window_ms } = this.options;
         const cutoff = now - window_ms;
-        let timestamps = this.#attempts.get(key);
-        if (timestamps) {
+        let entry = this.#attempts.get(key);
+        if (entry) {
             // Prune expired entries in place.
-            const active = timestamps.filter((t) => t > cutoff);
-            active.push(now);
-            this.#attempts.set(key, active);
-            timestamps = active;
+            entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+            entry.timestamps.push(now);
         }
         else {
-            timestamps = [now];
-            this.#attempts.set(key, timestamps);
+            entry = { timestamps: [now], in_flight: 0 };
+            this.#attempts.set(key, entry);
         }
-        const count = timestamps.length;
+        // A parked reservation re-decides: the key may now be at its cap on
+        // recorded attempts, which refuses it at once.
+        this.#wake(key);
+        const timestamps = entry.timestamps;
+        const count = timestamps.length + entry.in_flight;
         if (count <= max_attempts) {
             return { allowed: true, remaining: max_attempts - count, retry_after: 0 };
         }
@@ -204,6 +309,171 @@ export class RateLimiter {
         const retry_after = Math.ceil((oldest + window_ms - now) / 1000);
         return { allowed: false, remaining: 0, retry_after };
     }
+    /**
+     * Admit an attempt for `key` and count it in flight, in one synchronous
+     * step.
+     *
+     * The attempt counts against the cap — for this request and every
+     * concurrent one — until the returned reservation is settled: recorded as
+     * an attempt, or released. So no burst of concurrent requests gets more
+     * than `max_attempts` past the limiter between them. Release in a
+     * `finally`: nothing settles a reservation for you, so one left unsettled
+     * holds its slot for the life of the process.
+     *
+     * @param key - rate limit key (e.g. IP address)
+     * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @returns the reservation, or `{ok: false, retry_after}` when recorded plus in-flight attempts already reach the cap (nothing is reserved then)
+     * @mutates internal map - increments `key`'s in-flight count, creating its entry when absent
+     */
+    try_reserve(key, now = Date.now()) {
+        const checked = this.check(key, now);
+        if (!checked.allowed)
+            return { ok: false, retry_after: checked.retry_after };
+        return { ok: true, reservation: this.#admit(key) };
+    }
+    /**
+     * `try_reserve`, waiting up to `max_wait_ms` for a slot when the key is at
+     * its cap only because of attempts still in flight.
+     *
+     * Each settle (and record and reset) on the key wakes its waiters to
+     * re-decide — that key's only, so a settle costs nothing for waiters parked
+     * elsewhere: a freed slot is reserved; recorded attempts reaching the cap
+     * refuse at once with their real `retry_after`; reaching `max_wait_ms` (or
+     * `signal` aborting) refuses with `IN_FLIGHT_RETRY_AFTER_SECONDS`. At most
+     * `max_attempts` reservations wait on one key — one more is refused at
+     * once — so a flood can't park requests without bound. A waiter that
+     * leaves, by any path, leaves the key's waiter count as it found it. A
+     * waiter holds no place in a queue: each wake, every waiter re-decides, so
+     * one can lose every race for a freed slot until `max_wait_ms` refuses it.
+     *
+     * @param key - rate limit key (e.g. IP address)
+     * @param options - the wait bound and an abort signal
+     * @returns the reservation, or `{ok: false, retry_after}` as described (nothing is reserved then)
+     * @mutates internal map - increments `key`'s in-flight count on admission; counts the call in `key`'s waiters while it waits
+     */
+    async reserve(key, options = {}) {
+        const { max_wait_ms = RESERVATION_WAIT_MAX_MS, signal } = options;
+        const deadline = Date.now() + max_wait_ms;
+        let parked = false;
+        try {
+            for (;;) {
+                const load = this.#load(key, Date.now());
+                if (load.kind === 'free') {
+                    this.#leave(key, parked);
+                    parked = false;
+                    return { ok: true, reservation: this.#admit(key) };
+                }
+                if (load.kind === 'recorded')
+                    return { ok: false, retry_after: load.retry_after };
+                if (!parked) {
+                    let waiters = this.#waiters.get(key);
+                    if (waiters && waiters.count >= this.options.max_attempts) {
+                        return { ok: false, retry_after: IN_FLIGHT_RETRY_AFTER_SECONDS };
+                    }
+                    if (!waiters) {
+                        waiters = { count: 0, wakers: new Set() };
+                        this.#waiters.set(key, waiters);
+                    }
+                    waiters.count++;
+                    parked = true;
+                }
+                const remaining_ms = deadline - Date.now();
+                if (remaining_ms <= 0 || !(await this.#wait_for_wake(key, remaining_ms, signal))) {
+                    return { ok: false, retry_after: IN_FLIGHT_RETRY_AFTER_SECONDS };
+                }
+            }
+        }
+        finally {
+            this.#leave(key, parked);
+        }
+    }
+    /** Leave `key`'s waiters, if parked there; the last one out removes the key's slot. */
+    #leave(key, parked) {
+        if (!parked)
+            return;
+        const waiters = this.#waiters.get(key);
+        if (!waiters)
+            return;
+        waiters.count--;
+        if (waiters.count <= 0)
+            this.#waiters.delete(key);
+    }
+    /** Resolves `true` on `key`'s next wake, `false` on timeout or abort; cleans up either way. */
+    #wait_for_wake(key, timeout_ms, signal) {
+        return new Promise((resolve) => {
+            const wakers = this.#waiters.get(key)?.wakers;
+            if (signal?.aborted || !wakers) {
+                resolve(false);
+                return;
+            }
+            const done = (woke) => {
+                wakers.delete(waker);
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', on_abort);
+                resolve(woke);
+            };
+            const waker = () => done(true);
+            const on_abort = () => done(false);
+            const timer = setTimeout(() => done(false), timeout_ms);
+            wakers.add(waker);
+            signal?.addEventListener('abort', on_abort, { once: true });
+        });
+    }
+    /** Run the wakers of the reservations parked on `key`. */
+    #wake(key) {
+        const wakers = this.#waiters.get(key)?.wakers;
+        if (!wakers)
+            return;
+        for (const waker of [...wakers])
+            waker();
+    }
+    /** Count one more attempt in flight on `key`, already found free. */
+    #admit(key) {
+        let entry = this.#attempts.get(key);
+        if (!entry) {
+            // A fresh key past `max_keys` evicts the least-recently-used entry,
+            // in-flight attempts and all; their reservations settle as no-ops
+            // (release) or into a fresh entry (record).
+            entry = { timestamps: [], in_flight: 0 };
+            this.#attempts.set(key, entry);
+        }
+        entry.in_flight++;
+        const reserved = entry;
+        let settled = false;
+        const settle = (record, settle_now) => {
+            if (settled)
+                return;
+            settled = true;
+            this.#settle(key, reserved, record, settle_now);
+        };
+        return {
+            record: (record_now = Date.now()) => settle(true, record_now),
+            release: () => settle(false, Date.now())
+        };
+    }
+    #settle(key, reserved, record, now) {
+        const current = this.#attempts.get(key);
+        if (current !== reserved) {
+            // The reserved entry is gone — evicted, or reset with nothing in
+            // flight but this — so there is no in-flight count to give back. A
+            // record still counts, against whatever the key holds now.
+            if (record)
+                this.record(key, now);
+            else
+                this.#wake(key);
+            return;
+        }
+        reserved.in_flight = Math.max(0, reserved.in_flight - 1);
+        if (record) {
+            const cutoff = now - this.options.window_ms;
+            reserved.timestamps = reserved.timestamps.filter((t) => t > cutoff);
+            reserved.timestamps.push(now);
+        }
+        else if (entry_is_idle(reserved)) {
+            this.#attempts.delete(key);
+        }
+        this.#wake(key);
+    }
     /**
      * Clear all attempts for `key`.
      *
@@ -218,8 +488,9 @@ export class RateLimiter {
      * otherwise an attacker interleaves their own logins (or, under open signup,
      * throwaway account creations needing no credential at all) with guesses
      * against arbitrary victims and sprays indefinitely from one address.
-     * Nothing records on the IP bucket on success on any path, so with no reset
-     * it is a pure monotone-within-window failure counter that only time clears.
+     * The only success that records on an IP bucket is an open signup (charged
+     * like a failure); no success clears one, so with no reset each is a
+     * monotone-within-window counter that only time clears.
      *
      * Because they are monotone, the IP buckets are **one instance per auth
      * surface** (`login_ip_rate_limiter`, `signup_ip_rate_limiter`,
@@ -229,13 +500,24 @@ export class RateLimiter {
      * four routes at once — a cost that used to be masked by the reset this
      * doc forbids.
      *
-     * @mutates internal map - removes the entry for `key`
+     * Attempts still in flight on `key` (reserved by concurrent requests) are
+     * kept: a reset forgives what was recorded, not what is still running.
+     *
+     * @mutates internal map - removes the entry for `key`, or clears its timestamps while attempts are in flight
      */
     reset(key) {
-        this.#attempts.delete(key);
+        const entry = this.#attempts.get(key);
+        if (entry && entry.in_flight > 0) {
+            entry.timestamps = [];
+        }
+        else {
+            this.#attempts.delete(key);
+        }
+        this.#wake(key);
     }
     /**
-     * Remove entries whose timestamps are all outside the window.
+     * Remove entries whose timestamps are all outside the window and that
+     * have no attempt in flight.
      *
      * @param now - current timestamp in ms (defaults to `Date.now()`)
      * @mutates internal map - prunes expired timestamps and deletes empty keys
@@ -246,14 +528,11 @@ export class RateLimiter {
         // to the MRU end during iteration and causes re-visit in the same pass.
         // The `Map` path is unaffected but the snapshot is cheap on both.
         const entries = [...this.#attempts];
-        for (const [key, timestamps] of entries) {
-            const active = timestamps.filter((t) => t > cutoff);
-            if (active.length === 0) {
+        for (const [key, entry] of entries) {
+            entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+            if (entry_is_idle(entry)) {
                 this.#attempts.delete(key);
             }
-            else {
-                this.#attempts.set(key, active);
-            }
         }
     }
     /**
@@ -268,6 +547,37 @@ export class RateLimiter {
         }
     }
 }
+/**
+ * `RateLimiter.try_reserve` against a limiter that may be absent.
+ *
+ * An inert reservation when `limiter` is `null` (disabled) or `key` is `null`
+ * (no resolvable key — e.g. no client IP), so a handler reserves and settles
+ * the same way whether or not the surface is limited. Twin of the Rust
+ * spine's `try_reserve_optional`.
+ *
+ * @param limiter - the limiter, or `null` when disabled
+ * @param key - rate limit key, or `null` to skip
+ * @param now - current timestamp in ms (defaults to `Date.now()`)
+ */
+export const try_reserve_optional = (limiter, key, now = Date.now()) => {
+    if (!limiter || key === null)
+        return { ok: true, reservation: INERT_RESERVATION };
+    return limiter.try_reserve(key, now);
+};
+/**
+ * `RateLimiter.reserve` against a limiter that may be absent — an inert
+ * reservation when `limiter` or `key` is `null`. Twin of the Rust spine's
+ * `reserve_optional`.
+ *
+ * @param limiter - the limiter, or `null` when disabled
+ * @param key - rate limit key, or `null` to skip
+ * @param options - the wait bound and an abort signal
+ */
+export const reserve_optional = async (limiter, key, options) => {
+    if (!limiter || key === null)
+        return { ok: true, reservation: INERT_RESERVATION };
+    return limiter.reserve(key, options);
+};
 /**
  * Create a `RateLimiter` with sensible defaults for per-IP login protection.
  *

package/dist/realtime/sse_auth_guard.d.ts

@@ -35,12 +35,20 @@ export declare const AUDIT_LOG_CHANNEL = "audit_log";
  * 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. `close_all_sockets` is
- * `SubscriberRegistry.close_all` — every stream, for shutdown.
+ * `close_sockets_for_token` then reaches it. `close_sockets_for_role` closes
+ * the account's streams when `role` is the one the registry's streams are
+ * gated on — the registry keeps one gating role for all its streams, not one
+ * per stream. `close_all_sockets` is `SubscriberRegistry.close_all` — every
+ * stream, for shutdown.
  *
  * Twin of the Rust spine's `SocketRevoker` impl on `SseRegistry`.
+ *
+ * @param registry - the registry to close streams on
+ * @param required_role - the role every stream of `registry` was gated on,
+ *   or `null` when they are not role-gated (`close_sockets_for_role` then
+ *   closes nothing)
  */
-export declare const create_sse_connection_closer: <T>(registry: SubscriberRegistry<T>) => ConnectionCloser;
+export declare const create_sse_connection_closer: <T>(registry: SubscriberRegistry<T>, required_role: string | null) => ConnectionCloser;
 /**
  * Create an audit event handler that closes SSE streams on a successful
  * revocation row, dispatching on the event's `RevocationScope`
@@ -56,9 +64,12 @@ export declare const create_sse_connection_closer: <T>(registry: SubscriberRegis
  *   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.
+ *   (`metadata.role`) is `required_role` and the revoked grant was global
+ *   (`to_global_role_revocation`): the stream's role gate admits on global
+ *   grants only, so revoking a scoped grant of the same role takes away
+ *   nothing it admitted on. A stream is authorized once at open and has no
+ *   later check; the WebSocket guard closes its role-gated sockets on the
+ *   same rows.
  * - `none` → nothing.
  *
  * Over-closing a one-way feed is cheap: the client reconnects if it is still
@@ -94,6 +105,11 @@ export interface AuditLogSse {
     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 role the stream requires — what a caller adapting `registry` passes
+     * `create_sse_connection_closer`, so its role close matches the guard's.
+     */
+    required_role: string;
 }
 /**
  * SSE event specs for audit log events.

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;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,EAC7C,UAAU,kBAAkB,CAAC,CAAC,CAAC,KAC7B,gBAKD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;OASG;IACH,iBAAiB,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC;;;;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,EAKN,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;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,EAC7C,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,GAAG,IAAI,KAC1B,gBAOD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;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,CAoEjC,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;IAC/C;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;OASG;IACH,iBAAiB,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,KAAG,WAiBH,CAAC"}

package/dist/realtime/sse_auth_guard.js

@@ -20,7 +20,7 @@
  * @module
  */
 import { UnreachableError } from '@fuzdev/fuz_util/error.ts';
-import { AUDIT_EVENT_TYPES, AuditLogEventJson, to_revocation_scope } from '../auth/audit_log_schema.js';
+import { AUDIT_EVENT_TYPES, AuditLogEventJson, to_global_role_revocation, 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';
@@ -33,15 +33,24 @@ export const AUDIT_LOG_CHANNEL = 'audit_log';
  * 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. `close_all_sockets` is
- * `SubscriberRegistry.close_all` — every stream, for shutdown.
+ * `close_sockets_for_token` then reaches it. `close_sockets_for_role` closes
+ * the account's streams when `role` is the one the registry's streams are
+ * gated on — the registry keeps one gating role for all its streams, not one
+ * per stream. `close_all_sockets` is `SubscriberRegistry.close_all` — every
+ * stream, for shutdown.
  *
  * Twin of the Rust spine's `SocketRevoker` impl on `SseRegistry`.
+ *
+ * @param registry - the registry to close streams on
+ * @param required_role - the role every stream of `registry` was gated on,
+ *   or `null` when they are not role-gated (`close_sockets_for_role` then
+ *   closes nothing)
  */
-export const create_sse_connection_closer = (registry) => ({
+export const create_sse_connection_closer = (registry, required_role) => ({
     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),
+    close_sockets_for_role: (account_id, role) => required_role !== null && role === required_role ? registry.close_by_identity(account_id) : 0,
     close_all_sockets: () => registry.close_all()
 });
 /**
@@ -59,9 +68,12 @@ export const create_sse_connection_closer = (registry) => ({
  *   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.
+ *   (`metadata.role`) is `required_role` and the revoked grant was global
+ *   (`to_global_role_revocation`): the stream's role gate admits on global
+ *   grants only, so revoking a scoped grant of the same role takes away
+ *   nothing it admitted on. A stream is authorized once at open and has no
+ *   later check; the WebSocket guard closes its role-gated sockets on the
+ *   same rows.
  * - `none` → nothing.
  *
  * Over-closing a one-way feed is cheap: the client reconnects if it is still
@@ -111,20 +123,26 @@ export const create_sse_auth_guard = (registry, required_role, log) => {
                 }
                 return;
             }
-            case 'role':
+            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)
+                // global grants only — the gate never admitted on a scoped one
+                const revoked = to_global_role_revocation(event);
+                if (!revoked || revoked.role !== required_role)
                     return;
-                break;
+                const closed = registry.close_by_identity(revoked.account_id);
+                if (closed > 0) {
+                    log.info(`SSE auth guard: closed ${closed} stream(s) for account ${revoked.account_id} (${event.event_type})`);
+                }
+                return;
+            }
             case 'account':
                 break;
             default:
                 throw new UnreachableError(scope);
         }
-        // `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;
@@ -207,9 +225,10 @@ 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, log: options.log });
     const guard = create_sse_auth_guard(registry, role, options.log);
-    options.connection_closer?.add(create_sse_connection_closer(registry));
+    options.connection_closer?.add(create_sse_connection_closer(registry, role));
     return {
         log: options.log,
+        required_role: role,
         on_audit_event: (event) => {
             registry.broadcast(AUDIT_LOG_CHANNEL, { method: event.event_type, params: event });
             guard(event);