@fuzdev/fuz_app 0.141.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/server/serve_fact_route.d.ts

@@ -5,8 +5,10 @@
  *
  * - `GET /api/cells/:cell_id/facts/:hash` — the **per-reference read**.
  *   The request names the referencing cell. Authz is scoped to that one
- *   reference: `can_view_cell(caller, cell) AND cell.refs includes hash`.
- *   This is the path non-admin callers use, and the only path for
+ *   reference: `(can_view_cell(caller, cell) OR the steward arm) AND
+ *   cell.refs includes hash`, the steward arm being the governing root's
+ *   manager reading a pending or rejected contribution
+ *   (`auth/cell_steward.ts`). This is the path non-admin callers use, and the only path for
  *   confidential content.
  * - `GET /api/facts/:hash` — the **bare-hash read**, restricted to admins.
  *
@@ -52,7 +54,8 @@
  * (populated by the `/api/*` session middleware) by resolving the caller's
  * single actor and loading their role_grants. Unauthed callers pass through
  * with `req_ctx: null` and are admitted only by a `cell.visibility ===
- * 'public'` cell. Multi-actor accounts fall through with `req_ctx: null`
+ * 'public'` cell whose `moderation` admits an audience (unmoderated or
+ * `'approved'`). Multi-actor accounts fall through with `req_ctx: null`
  * — there's no `acting?` slot on a pure-public route, so multi-actor
  * callers are treated as anonymous.
  *
@@ -121,7 +124,8 @@ export interface CreateServeFactRouteSpecOptions {
  * — the per-reference read.
  *
  * Resolves the named cell (404 if missing / soft-deleted), requires
- * `can_view_cell(caller, cell)` AND `cell.refs` to include the hash
+ * `can_view_cell(caller, cell)` — or the steward arm,
+ * `cell_steward_admits` — AND `cell.refs` to include the hash
  * (else 404, masked), then serves the bytes. Authz is scoped to this one
  * `(cell, hash)` edge — never unioned across the fact's other referrers.
  *

package/dist/server/serve_fact_route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAetD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAkEjD,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAkHD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAiDF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SA2CF,CAAC"}
+{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAetD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAO/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAkEjD,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAkHD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAuDF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SA2CF,CAAC"}

package/dist/server/serve_fact_route.js

@@ -5,8 +5,10 @@
  *
  * - `GET /api/cells/:cell_id/facts/:hash` — the **per-reference read**.
  *   The request names the referencing cell. Authz is scoped to that one
- *   reference: `can_view_cell(caller, cell) AND cell.refs includes hash`.
- *   This is the path non-admin callers use, and the only path for
+ *   reference: `(can_view_cell(caller, cell) OR the steward arm) AND
+ *   cell.refs includes hash`, the steward arm being the governing root's
+ *   manager reading a pending or rejected contribution
+ *   (`auth/cell_steward.ts`). This is the path non-admin callers use, and the only path for
  *   confidential content.
  * - `GET /api/facts/:hash` — the **bare-hash read**, restricted to admins.
  *
@@ -52,7 +54,8 @@
  * (populated by the `/api/*` session middleware) by resolving the caller's
  * single actor and loading their role_grants. Unauthed callers pass through
  * with `req_ctx: null` and are admitted only by a `cell.visibility ===
- * 'public'` cell. Multi-actor accounts fall through with `req_ctx: null`
+ * 'public'` cell whose `moderation` admits an audience (unmoderated or
+ * `'approved'`). Multi-actor accounts fall through with `req_ctx: null`
  * — there's no `acting?` slot on a pure-public route, so multi-actor
  * callers are treated as anonymous.
  *
@@ -106,6 +109,7 @@ import { query_get_fact, query_get_fact_meta } from '../db/fact_queries.js';
 import { query_cell_get } from '../db/cell_queries.js';
 import { query_cell_grant_list_for_cell } from '../db/cell_grant_queries.js';
 import { can_view_cell } from '../auth/cell_authorize.js';
+import { cell_steward_admits } from '../auth/cell_steward.js';
 import { parse_file_fact_url } from '../db/file_fact_url.js';
 /** `Cache-Control` for fact responses — 5 min revocation window. */
 const CACHE_CONTROL = 'private, max-age=300';
@@ -254,7 +258,8 @@ const build_public_request_context = async (c, route) => {
  * — the per-reference read.
  *
  * Resolves the named cell (404 if missing / soft-deleted), requires
- * `can_view_cell(caller, cell)` AND `cell.refs` to include the hash
+ * `can_view_cell(caller, cell)` — or the steward arm,
+ * `cell_steward_admits` — AND `cell.refs` to include the hash
  * (else 404, masked), then serves the bytes. Authz is scoped to this one
  * `(cell, hash)` edge — never unioned across the fact's other referrers.
  *
@@ -269,7 +274,7 @@ export const create_serve_cell_fact_route_spec = (options) => {
         path: '/api/cells/:cell_id/facts/:hash',
         auth: { account: 'none', actor: 'none' },
         reads_credential: true,
-        description: 'Serve content-addressed fact bytes through a named referencing cell. 404 unless the cell admits the caller via can_view_cell AND references the hash (per-reference, never union-of-referrers).',
+        description: "Serve content-addressed fact bytes through a named referencing cell. 404 unless the cell admits the caller via can_view_cell (or the steward arm: the governing root's manager reading a pending or rejected contribution) AND references the hash (per-reference, never union-of-referrers).",
         params: cell_fact_params_schema,
         input: z.null(),
         // The body is a binary stream; no JSON output schema applies.
@@ -298,7 +303,11 @@ export const create_serve_cell_fact_route_spec = (options) => {
             const grants = req_ctx
                 ? await query_cell_grant_list_for_cell({ db: route.db }, cell.id)
                 : null;
-            if (!can_view_cell(req_ctx, cell, grants)) {
+            // The governing root's manager also reads a pending or rejected
+            // contribution's facts (the steward arm, `auth/cell_steward.ts`),
+            // checked only once the view check denies.
+            if (!can_view_cell(req_ctx, cell, grants) &&
+                !(await cell_steward_admits({ db: route.db }, req_ctx, cell))) {
                 // 404 (not 403) so an unviewable cell→fact edge doesn't leak.
                 return c.body(null, 404);
             }

package/dist/testing/CLAUDE.md

@@ -1421,7 +1421,14 @@ moderation_required}`, with `moderation` set per the verdict (`pending`+private
   **visible** one **403**s; plain parentless creates stay open. The moderate
   suite then proves the `pending → approved | rejected` transition: an admin
   (root manager) approves → public, the **author** self-approve → 403
-  (anti-self-approval), a non-viewer → 404, reject → stays private. The
+  (anti-self-approval), a non-viewer → 404, reject → stays private. It also
+  pins the moderation read gate (a pending or rejected post reaches no
+  non-steward reader past its author and admins on `cell_get`, `cell_list`,
+  `cell_item_list`, and fact serving, even flipped public or granted while
+  approved), `cell_grant_create`'s
+  403 `cell_grant_unapproved`, and the steward arm (a non-admin root owner — a
+  non-`space` root the policy leaves open — reads the queue, `cell_get`, and
+  the fact, and moderates, but still 404s on clone and create-under). The
   authorizer _behavior_ adds no method/wire shape, so schema + manifest parity
   are **blind** to a divergence — these are the only gates that catch one (the
   `cell_moderate` verb itself is manifest-covered). In-process hook coverage is
@@ -1846,9 +1853,9 @@ so one fixture is the cross-impl contract): the TS spine via
 `import.meta.url` constant off `spine_surface_constants.ts`; the Rust
 `testing_spine_stub` via the absolute path `rust_spine_stub_backend_config`
 passes through `FUZ_RUST_SPINE_STUB_EXPECTED_SCHEMA_PATH`. The fixture covers the full
-spine bootstrap (auth + cell + cell_history + fact) and is regenerated +
+spine bootstrap (auth + cell + fact) and is regenerated +
 drift-guarded by `src/test/cross_backend/spine_expected_schema.db.test.ts`
-(`UPDATE_SCHEMA_READY=1`, then `gro format`).
+(`UPDATE_SCHEMA_READY=1`).
 
 ### Testing-backdoor credential gate — `cross_backend/testing_backdoor.ts`
 

package/dist/testing/cross_backend/account_lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account_lifecycle.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/account_lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAmC9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAG1E;;;;;GAKG;AACH,MAAM,MAAM,gCAAgC,GAAG,uCAAuC,CAAC;AAEvF,eAAO,MAAM,sCAAsC,GAClD,SAAS,gCAAgC,KACvC,IAoUF,CAAC"}
+{"version":3,"file":"account_lifecycle.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/account_lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuC9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAG1E;;;;;GAKG;AACH,MAAM,MAAM,gCAAgC,GAAG,uCAAuC,CAAC;AAEvF,eAAO,MAAM,sCAAsC,GAClD,SAAS,gCAAgC,KACvC,IAqZF,CAAC"}