@optimystic/db-core 0.13.5 → 0.14.0

package/dist/src/cohort-topic/antidos/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/antidos/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC"}

package/dist/src/cohort-topic/antidos/index.js

@@ -0,0 +1,6 @@
+export * from "./rate-limiter.js";
+export * from "./topic-budget.js";
+export * from "./replay-guard.js";
+export * from "./bootstrap-evidence.js";
+export * from "./bootstrap-evidence-envelope.js";
+//# sourceMappingURL=index.js.map

package/dist/src/cohort-topic/antidos/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cohort-topic/antidos/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC"}

package/dist/src/cohort-topic/antidos/rate-limiter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Cohort-topic substrate — per-peer registration rate limiter (anti-DoS).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 1. A cohort member tracks inbound
+ * `RegisterV1` rate per `(sourcePeerId, topicId)` and refuses a source that exceeds
+ * `register_rate_per_peer` (default 4 / min). An over-rate registration draws `UnwillingCohort` with
+ * an **exponential** `retryAfter`, so a peer hammering one topic at one cohort backs off geometrically
+ * — the same capped-doubling curve the willingness back-off uses ({@link backoffRetryMs}).
+ *
+ * The limiter is a sliding-window counter: it keeps the accept timestamps inside the trailing
+ * `windowMs` for each key, admits while the window holds `< ratePerWindow`, and on rejection advances
+ * a per-key strike counter that indexes the back-off curve. A run of strikes decays once the source
+ * has been quiet for a full window (its window empties and the strike counter resets), so a
+ * well-behaved peer is never permanently penalized. Each key's accept history is trimmed to the live
+ * window whenever that key is checked, so a key's footprint stays `O(ratePerWindow)`.
+ *
+ * The `states` map is bounded two complementary ways so a long-running host cannot leak memory and a
+ * flood of attacker-chosen keys cannot exhaust it:
+ *
+ * - **Hard LRU cap (`maxKeys`)** — enforced inline in {@link SlidingWindowRateLimiter.check}. Every
+ *   check moves its key to the most-recently-checked end (the {@link import("../../utility/lru-map.js").LruMap}
+ *   delete-then-set trick over `Map` insertion order); when a *new* key would exceed `maxKeys` the
+ *   least-recently-checked keys are evicted until within cap. Recency is refreshed on **every** check,
+ *   rejects included, so a source mid-attack (accumulated `strikes` driving back-off) stays at the hot
+ *   end and is never the eviction victim — only genuinely idle keys age to the cold end.
+ * - **Idle-TTL sweep (`idleTtlMs`)** — {@link SlidingWindowRateLimiter.sweep} drops keys not checked
+ *   within `idleTtlMs`. Driver-called on the host's gossip cadence, it reclaims steady-state footprint
+ *   proportional to *active* keys.
+ *
+ * Eviction is penalty-free when a key is dropped only after a full window of quiet: the window logic
+ * already forgives a source quiet for a full window (its accepts age out and `strikes` resets), so
+ * dropping such a key and re-allocating a fresh `{ accepts:[now], strikes:0 }` on its return is
+ * observationally identical to keeping it — just an earlier reclaim. This holds for the LRU cap (a
+ * mid-attack key is refreshed to the hot end on every check, so only genuinely idle keys are evicted)
+ * and for the default `idleTtlMs` (`== windowMs`). A configured `idleTtlMs < windowMs` reclaims more
+ * aggressively: `sweep` may then drop a key whose accepts have *not* fully aged out, forgiving its
+ * accumulated `strikes` sooner than the window alone would — an accepted footprint/strike-accounting
+ * tradeoff, not an identity. The substrate does not defend against unbounded Sybil key creation (that is FRET's /
+ * the reputation subsystem's concern; see §Anti-DoS closing note).
+ */
+import { type BackoffConfig } from "../willingness.js";
+/** Default per-peer-per-topic acceptance ceiling per window — `register_rate_per_peer` (4 / min). */
+export declare const DEFAULT_REGISTER_RATE_PER_PEER = 4;
+/** Default sliding window the ceiling applies over (ms). */
+export declare const DEFAULT_RATE_WINDOW_MS = 60000;
+/** Default hard cap on tracked `(peer, topic)` keys; the least-recently-checked are evicted beyond this. */
+export declare const DEFAULT_RATE_LIMITER_MAX_KEYS = 100000;
+/** Default idle threshold for {@link RegisterRateLimiter.sweep} — one quiet window makes a key evictable. */
+export declare const DEFAULT_RATE_LIMITER_IDLE_TTL_MS = 60000;
+export interface RegisterRateLimiterConfig {
+    /** Accepts permitted per window per `(peer, topic)`. Default {@link DEFAULT_REGISTER_RATE_PER_PEER}. */
+    ratePerWindow?: number;
+    /** Sliding-window length (ms). Default {@link DEFAULT_RATE_WINDOW_MS}. */
+    windowMs?: number;
+    /** Exponential `retryAfter` curve for over-rate sources. Default {@link DEFAULT_BACKOFF_CONFIG}. */
+    backoff?: BackoffConfig;
+    /** Hard cap on tracked `(peer, topic)` keys; least-recently-checked evicted beyond this. Default {@link DEFAULT_RATE_LIMITER_MAX_KEYS}. */
+    maxKeys?: number;
+    /**
+     * A key not checked within this many ms is evictable by {@link RegisterRateLimiter.sweep}. Default
+     * {@link DEFAULT_RATE_LIMITER_IDLE_TTL_MS} (`== windowMs`). Keep `>= windowMs` to preserve the
+     * penalty-free invariant; a smaller value reclaims sooner but may forgive an idle source's strikes
+     * before its window would (see the class doc comment).
+     */
+    idleTtlMs?: number;
+}
+/** Outcome of a rate check: admitted, or refused with the back-off the caller puts in `UnwillingCohort`. */
+export type RateCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    retryAfterMs: number;
+};
+/** Per-peer-per-topic inbound `RegisterV1` rate limiter. */
+export interface RegisterRateLimiter {
+    /**
+     * Classify a register from `peerId` for `topicId` at `now`. Records the accept on `{ ok: true }`;
+     * an over-rate source gets `{ ok: false, retryAfterMs }` with exponential back-off and the strike
+     * is *not* recorded as an accept (so back-off cannot itself fill the window). Every call — accept
+     * **or** reject — refreshes the key's recency, so an actively-hammering source is never evicted by
+     * the LRU cap (which would reset its back-off escalation).
+     */
+    check(peerId: Uint8Array, topicId: Uint8Array, now: number): RateCheckResult;
+    /**
+     * Evict keys idle (not checked) for `>= idleTtlMs`. Returns the number evicted. Driver-called on
+     * the host's gossip cadence to reclaim steady-state footprint; the hard `maxKeys` LRU cap bounds
+     * worst-case footprint even without it.
+     */
+    sweep(now: number): number;
+    /** Tracked `(peer, topic)` key count (test/diagnostic introspection). */
+    readonly size: number;
+}
+/** Build a {@link RegisterRateLimiter} over the configured ceiling, window, and back-off curve. */
+export declare function createRegisterRateLimiter(config?: RegisterRateLimiterConfig): RegisterRateLimiter;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/src/cohort-topic/antidos/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/antidos/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAAkB,KAAK,aAAa,EAA0B,MAAM,mBAAmB,CAAC;AAK/F,qGAAqG;AACrG,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAChD,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,4GAA4G;AAC5G,eAAO,MAAM,6BAA6B,SAAU,CAAC;AACrD,6GAA6G;AAC7G,eAAO,MAAM,gCAAgC,QAAyB,CAAC;AAEvE,MAAM,WAAW,yBAAyB;IACzC,wGAAwG;IACxG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,2IAA2I;IAC3I,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4GAA4G;AAC5G,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IACnC;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC;IAC7E;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AA+GD,mGAAmG;AACnG,wBAAgB,yBAAyB,CAAC,MAAM,GAAE,yBAA8B,GAAG,mBAAmB,CAErG"}

package/dist/src/cohort-topic/antidos/rate-limiter.js

@@ -0,0 +1,146 @@
+/**
+ * Cohort-topic substrate — per-peer registration rate limiter (anti-DoS).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 1. A cohort member tracks inbound
+ * `RegisterV1` rate per `(sourcePeerId, topicId)` and refuses a source that exceeds
+ * `register_rate_per_peer` (default 4 / min). An over-rate registration draws `UnwillingCohort` with
+ * an **exponential** `retryAfter`, so a peer hammering one topic at one cohort backs off geometrically
+ * — the same capped-doubling curve the willingness back-off uses ({@link backoffRetryMs}).
+ *
+ * The limiter is a sliding-window counter: it keeps the accept timestamps inside the trailing
+ * `windowMs` for each key, admits while the window holds `< ratePerWindow`, and on rejection advances
+ * a per-key strike counter that indexes the back-off curve. A run of strikes decays once the source
+ * has been quiet for a full window (its window empties and the strike counter resets), so a
+ * well-behaved peer is never permanently penalized. Each key's accept history is trimmed to the live
+ * window whenever that key is checked, so a key's footprint stays `O(ratePerWindow)`.
+ *
+ * The `states` map is bounded two complementary ways so a long-running host cannot leak memory and a
+ * flood of attacker-chosen keys cannot exhaust it:
+ *
+ * - **Hard LRU cap (`maxKeys`)** — enforced inline in {@link SlidingWindowRateLimiter.check}. Every
+ *   check moves its key to the most-recently-checked end (the {@link import("../../utility/lru-map.js").LruMap}
+ *   delete-then-set trick over `Map` insertion order); when a *new* key would exceed `maxKeys` the
+ *   least-recently-checked keys are evicted until within cap. Recency is refreshed on **every** check,
+ *   rejects included, so a source mid-attack (accumulated `strikes` driving back-off) stays at the hot
+ *   end and is never the eviction victim — only genuinely idle keys age to the cold end.
+ * - **Idle-TTL sweep (`idleTtlMs`)** — {@link SlidingWindowRateLimiter.sweep} drops keys not checked
+ *   within `idleTtlMs`. Driver-called on the host's gossip cadence, it reclaims steady-state footprint
+ *   proportional to *active* keys.
+ *
+ * Eviction is penalty-free when a key is dropped only after a full window of quiet: the window logic
+ * already forgives a source quiet for a full window (its accepts age out and `strikes` resets), so
+ * dropping such a key and re-allocating a fresh `{ accepts:[now], strikes:0 }` on its return is
+ * observationally identical to keeping it — just an earlier reclaim. This holds for the LRU cap (a
+ * mid-attack key is refreshed to the hot end on every check, so only genuinely idle keys are evicted)
+ * and for the default `idleTtlMs` (`== windowMs`). A configured `idleTtlMs < windowMs` reclaims more
+ * aggressively: `sweep` may then drop a key whose accepts have *not* fully aged out, forgiving its
+ * accumulated `strikes` sooner than the window alone would — an accepted footprint/strike-accounting
+ * tradeoff, not an identity. The substrate does not defend against unbounded Sybil key creation (that is FRET's /
+ * the reputation subsystem's concern; see §Anti-DoS closing note).
+ */
+import { recordKey } from "../registration/bytes.js";
+import { backoffRetryMs, DEFAULT_BACKOFF_CONFIG } from "../willingness.js";
+import { createLogger } from "../../logger.js";
+const log = createLogger("cohort-topic:antidos");
+/** Default per-peer-per-topic acceptance ceiling per window — `register_rate_per_peer` (4 / min). */
+export const DEFAULT_REGISTER_RATE_PER_PEER = 4;
+/** Default sliding window the ceiling applies over (ms). */
+export const DEFAULT_RATE_WINDOW_MS = 60_000;
+/** Default hard cap on tracked `(peer, topic)` keys; the least-recently-checked are evicted beyond this. */
+export const DEFAULT_RATE_LIMITER_MAX_KEYS = 100_000;
+/** Default idle threshold for {@link RegisterRateLimiter.sweep} — one quiet window makes a key evictable. */
+export const DEFAULT_RATE_LIMITER_IDLE_TTL_MS = DEFAULT_RATE_WINDOW_MS;
+class SlidingWindowRateLimiter {
+    states = new Map();
+    ratePerWindow;
+    windowMs;
+    backoff;
+    maxKeys;
+    idleTtlMs;
+    constructor(config = {}) {
+        this.ratePerWindow = config.ratePerWindow ?? DEFAULT_REGISTER_RATE_PER_PEER;
+        if (!Number.isInteger(this.ratePerWindow) || this.ratePerWindow <= 0) {
+            throw new RangeError(`ratePerWindow must be a positive integer, got ${this.ratePerWindow}`);
+        }
+        this.windowMs = config.windowMs ?? DEFAULT_RATE_WINDOW_MS;
+        if (!(this.windowMs > 0)) {
+            throw new RangeError(`windowMs must be > 0, got ${this.windowMs}`);
+        }
+        this.backoff = config.backoff ?? DEFAULT_BACKOFF_CONFIG;
+        this.maxKeys = config.maxKeys ?? DEFAULT_RATE_LIMITER_MAX_KEYS;
+        if (!Number.isInteger(this.maxKeys) || this.maxKeys <= 0) {
+            throw new RangeError(`maxKeys must be a positive integer, got ${this.maxKeys}`);
+        }
+        this.idleTtlMs = config.idleTtlMs ?? DEFAULT_RATE_LIMITER_IDLE_TTL_MS;
+        if (!(this.idleTtlMs > 0)) {
+            throw new RangeError(`idleTtlMs must be > 0, got ${this.idleTtlMs}`);
+        }
+    }
+    check(peerId, topicId, now) {
+        const key = recordKey(topicId, peerId);
+        const state = this.states.get(key);
+        const cutoff = now - this.windowMs;
+        if (state === undefined) {
+            // New key: enforce the hard cap by evicting the least-recently-checked keys (oldest by
+            // `Map` insertion order) until this insertion stays within `maxKeys`. The evicted keys
+            // are by construction the coldest — an actively-checked key is refreshed to the hot end
+            // below and so is never the victim.
+            while (this.states.size >= this.maxKeys) {
+                const oldest = this.states.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                this.states.delete(oldest);
+            }
+            this.states.set(key, { accepts: [now], strikes: 0, lastSeen: now });
+            return { ok: true };
+        }
+        // Refresh LRU recency on every check (accept OR reject): delete-then-set moves this key to the
+        // most-recently-checked end of the `Map`, and `lastSeen = now` is the idle-TTL key sweep() reads.
+        // A source mid-attack stays at the hot end here even on a reject, so the cap never evicts (and
+        // thus never resets the back-off of) an active attacker.
+        this.states.delete(key);
+        this.states.set(key, state);
+        state.lastSeen = now;
+        // Drop accepts that have aged out of the trailing window.
+        let live = 0;
+        for (const t of state.accepts) {
+            if (t > cutoff) {
+                state.accepts[live++] = t;
+            }
+        }
+        state.accepts.length = live;
+        if (live === 0) {
+            // The source has been quiet for a full window — forgive accumulated strikes.
+            state.strikes = 0;
+        }
+        if (live < this.ratePerWindow) {
+            state.accepts.push(now);
+            state.strikes = 0;
+            return { ok: true };
+        }
+        // Over rate: exponential back-off indexed by the strike count, then advance the strike.
+        const retryAfterMs = backoffRetryMs(state.strikes, this.backoff);
+        state.strikes++;
+        log("rate-limit reject window=%d/%d strikes=%d retryAfter=%d", live, this.ratePerWindow, state.strikes, retryAfterMs);
+        return { ok: false, retryAfterMs };
+    }
+    sweep(now) {
+        let evicted = 0;
+        // Deleting the current key during `Map` iteration is well-defined and does not skip entries.
+        for (const [key, state] of this.states) {
+            if (now - state.lastSeen >= this.idleTtlMs) {
+                this.states.delete(key);
+                evicted++;
+            }
+        }
+        return evicted;
+    }
+    get size() {
+        return this.states.size;
+    }
+}
+/** Build a {@link RegisterRateLimiter} over the configured ceiling, window, and back-off curve. */
+export function createRegisterRateLimiter(config = {}) {
+    return new SlidingWindowRateLimiter(config);
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/src/cohort-topic/antidos/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../../../src/cohort-topic/antidos/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/src/cohort-topic/antidos/replay-guard.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cohort-topic substrate — correlation-id replay guard (anti-DoS).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 3. Every `RegisterV1` carries a
+ * `correlationId` (16 random bytes) and a signature over `(topicId, tier, correlationId, timestamp)`.
+ * The signature (verified elsewhere — the participant-key check) proves authorship; this guard adds
+ * **freshness**: it drops a registration whose `timestamp` is outside the accepted skew window
+ * (stale, or implausibly far in the future) and drops a `correlationId` it has already seen inside the
+ * window (a captured-and-replayed registration).
+ *
+ * Because a stale registration is rejected outright, the guard only needs to remember correlation ids
+ * for one `maxAgeMs` window: an id older than that would be rejected on timestamp alone, so its record
+ * can be pruned. Pruning runs on access, bounding memory to the live window's worth of registrations.
+ */
+/** Default acceptance window: a registration timestamped older than this (relative to `now`) is stale. */
+export declare const DEFAULT_REPLAY_MAX_AGE_MS = 60000;
+/** Default tolerated forward clock skew: a timestamp this far past `now` is rejected as implausible. */
+export declare const DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS = 5000;
+export interface CorrelationReplayGuardConfig {
+    /** A timestamp older than `now − maxAgeMs` is stale. Default {@link DEFAULT_REPLAY_MAX_AGE_MS}. */
+    maxAgeMs?: number;
+    /** A timestamp newer than `now + maxFutureSkewMs` is rejected. Default {@link DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS}. */
+    maxFutureSkewMs?: number;
+}
+/** Freshness + anti-replay gate over registration `correlationId`s and timestamps. */
+export interface CorrelationReplayGuard {
+    /**
+     * Accept `correlationId` (from `peerId`, stamped `timestamp`) evaluated at `now`. Returns `false`
+     * — and records nothing — when the timestamp is stale or implausibly future, or when this
+     * `correlationId` was already accepted inside the window (replay). Returns `true` and remembers the
+     * id on first sight of a fresh registration.
+     */
+    accept(correlationId: Uint8Array, peerId: Uint8Array, timestamp: number, now: number): boolean;
+}
+/** Build a {@link CorrelationReplayGuard} over the configured staleness window and forward skew. */
+export declare function createCorrelationReplayGuard(config?: CorrelationReplayGuardConfig): CorrelationReplayGuard;
+//# sourceMappingURL=replay-guard.d.ts.map

package/dist/src/cohort-topic/antidos/replay-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-guard.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/antidos/replay-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,0GAA0G;AAC1G,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAChD,wGAAwG;AACxG,eAAO,MAAM,iCAAiC,OAAQ,CAAC;AAEvD,MAAM,WAAW,4BAA4B;IAC5C,mGAAmG;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qHAAqH;IACrH,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,sFAAsF;AACtF,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,MAAM,CAAC,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/F;AAgED,oGAAoG;AACpG,wBAAgB,4BAA4B,CAAC,MAAM,GAAE,4BAAiC,GAAG,sBAAsB,CAE9G"}

package/dist/src/cohort-topic/antidos/replay-guard.js

@@ -0,0 +1,78 @@
+/**
+ * Cohort-topic substrate — correlation-id replay guard (anti-DoS).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 3. Every `RegisterV1` carries a
+ * `correlationId` (16 random bytes) and a signature over `(topicId, tier, correlationId, timestamp)`.
+ * The signature (verified elsewhere — the participant-key check) proves authorship; this guard adds
+ * **freshness**: it drops a registration whose `timestamp` is outside the accepted skew window
+ * (stale, or implausibly far in the future) and drops a `correlationId` it has already seen inside the
+ * window (a captured-and-replayed registration).
+ *
+ * Because a stale registration is rejected outright, the guard only needs to remember correlation ids
+ * for one `maxAgeMs` window: an id older than that would be rejected on timestamp alone, so its record
+ * can be pruned. Pruning runs on access, bounding memory to the live window's worth of registrations.
+ */
+import { bytesKey } from "../registration/bytes.js";
+import { createLogger } from "../../logger.js";
+const log = createLogger("cohort-topic:antidos");
+/** Default acceptance window: a registration timestamped older than this (relative to `now`) is stale. */
+export const DEFAULT_REPLAY_MAX_AGE_MS = 60_000;
+/** Default tolerated forward clock skew: a timestamp this far past `now` is rejected as implausible. */
+export const DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS = 5_000;
+class WindowedReplayGuard {
+    seen = new Map();
+    maxAgeMs;
+    maxFutureSkewMs;
+    /** `now` of the last prune, so pruning amortizes rather than scanning on every call. */
+    lastPruneAt = -Infinity;
+    constructor(config = {}) {
+        this.maxAgeMs = config.maxAgeMs ?? DEFAULT_REPLAY_MAX_AGE_MS;
+        if (!(this.maxAgeMs > 0)) {
+            throw new RangeError(`maxAgeMs must be > 0, got ${this.maxAgeMs}`);
+        }
+        this.maxFutureSkewMs = config.maxFutureSkewMs ?? DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS;
+        if (!(this.maxFutureSkewMs >= 0)) {
+            throw new RangeError(`maxFutureSkewMs must be >= 0, got ${this.maxFutureSkewMs}`);
+        }
+    }
+    accept(correlationId, peerId, timestamp, now) {
+        if (timestamp < now - this.maxAgeMs) {
+            log("replay-guard reject: stale timestamp age=%d > maxAge=%d", now - timestamp, this.maxAgeMs);
+            return false; // stale
+        }
+        if (timestamp > now + this.maxFutureSkewMs) {
+            log("replay-guard reject: future timestamp skew=%d > maxSkew=%d", timestamp - now, this.maxFutureSkewMs);
+            return false; // implausibly future
+        }
+        this.maybePrune(now);
+        const key = bytesKey(correlationId);
+        const prior = this.seen.get(key);
+        if (prior !== undefined) {
+            // Attribute the replay to the *original* accepter: the correlationId (not the peer id) is the
+            // anti-replay key, so a replayer that spoofs a different source id is still caught here.
+            log("replay-guard reject: replayed correlationId (first seen from peer=%s)", prior.peer);
+            return false; // replay
+        }
+        this.seen.set(key, { timestamp, peer: bytesKey(peerId) });
+        return true;
+    }
+    /** Forget ids whose timestamp has aged past the window — they would be rejected as stale anyway. */
+    maybePrune(now) {
+        // Amortize: prune at most once per window rather than scanning on every accept.
+        if (now - this.lastPruneAt < this.maxAgeMs) {
+            return;
+        }
+        this.lastPruneAt = now;
+        const cutoff = now - this.maxAgeMs;
+        for (const [key, entry] of this.seen) {
+            if (entry.timestamp < cutoff) {
+                this.seen.delete(key);
+            }
+        }
+    }
+}
+/** Build a {@link CorrelationReplayGuard} over the configured staleness window and forward skew. */
+export function createCorrelationReplayGuard(config = {}) {
+    return new WindowedReplayGuard(config);
+}
+//# sourceMappingURL=replay-guard.js.map

package/dist/src/cohort-topic/antidos/replay-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-guard.js","sourceRoot":"","sources":["../../../../src/cohort-topic/antidos/replay-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,GAAG,GAAG,YAAY,CAAC,sBAAsB,CAAC,CAAC;AAEjD,0GAA0G;AAC1G,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAChD,wGAAwG;AACxG,MAAM,CAAC,MAAM,iCAAiC,GAAG,KAAK,CAAC;AA0BvD,MAAM,mBAAmB;IACP,IAAI,GAAG,IAAI,GAAG,EAAqB,CAAC;IACpC,QAAQ,CAAS;IACjB,eAAe,CAAS;IACzC,wFAAwF;IAChF,WAAW,GAAG,CAAC,QAAQ,CAAC;IAEhC,YAAY,SAAuC,EAAE;QACpD,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,yBAAyB,CAAC;QAC7D,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,UAAU,CAAC,6BAA6B,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,iCAAiC,CAAC;QACnF,IAAI,CAAC,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,UAAU,CAAC,qCAAqC,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;QACnF,CAAC;IACF,CAAC;IAED,MAAM,CAAC,aAAyB,EAAE,MAAkB,EAAE,SAAiB,EAAE,GAAW;QACnF,IAAI,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrC,GAAG,CAAC,yDAAyD,EAAE,GAAG,GAAG,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC/F,OAAO,KAAK,CAAC,CAAC,QAAQ;QACvB,CAAC;QACD,IAAI,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YAC5C,GAAG,CAAC,4DAA4D,EAAE,SAAS,GAAG,GAAG,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;YACzG,OAAO,KAAK,CAAC,CAAC,qBAAqB;QACpC,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACrB,MAAM,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,8FAA8F;YAC9F,yFAAyF;YACzF,GAAG,CAAC,uEAAuE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACzF,OAAO,KAAK,CAAC,CAAC,SAAS;QACxB,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACb,CAAC;IAED,oGAAoG;IAC5F,UAAU,CAAC,GAAW;QAC7B,gFAAgF;QAChF,IAAI,GAAG,GAAG,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5C,OAAO;QACR,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC;QACvB,MAAM,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;QACnC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACtC,IAAI,KAAK,CAAC,SAAS,GAAG,MAAM,EAAE,CAAC;gBAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;QACF,CAAC;IACF,CAAC;CACD;AAED,oGAAoG;AACpG,MAAM,UAAU,4BAA4B,CAAC,SAAuC,EAAE;IACrF,OAAO,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC"}

package/dist/src/cohort-topic/antidos/topic-budget.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Cohort-topic substrate — per-cohort topic budget (anti-DoS).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 2. A cohort holds forwarder state for at
+ * most `topics_max` (default 2048) topics. Once the budget is full a request to instantiate a **new**
+ * topic is refused (the caller answers `UnwillingCohort`); topics already in the budget continue to
+ * serve. To keep room for genuinely active topics, the budget evicts cold ones: eviction order is
+ * **LRU by participant count**, with **zero-recent-registration topics dropped first** — a topic that
+ * carries no direct participants is the cheapest to shed and is shed before any populated topic.
+ *
+ * `admit` only ever evicts a *zero-participant* topic. If every resident topic still carries
+ * participants the budget is genuinely saturated and the new instantiation is refused — an attacker
+ * cannot, by flooding new topic ids, evict a topic that real participants are using. LRU ordering
+ * uses a monotonic access counter bumped on every `admit`/`touch`, so it is deterministic and needs
+ * no wall clock.
+ */
+/** Default per-cohort forwarder-topic ceiling — `topics_max`. */
+export declare const DEFAULT_TOPICS_MAX = 2048;
+export interface TopicBudgetConfig {
+    /** Max topics with forwarder state. Default {@link DEFAULT_TOPICS_MAX}. */
+    topicsMax?: number;
+}
+/** Per-cohort cap on the number of topics with forwarder state, with LRU eviction of cold topics. */
+export interface TopicBudget {
+    /**
+     * Admit `topicId` to the forwarder-state budget. Returns `true` if it is already resident or there
+     * is (or can be freed) room; `false` when the budget is full of populated topics, in which case the
+     * caller answers `UnwillingCohort` for the new instantiation. Admitting a *new* topic when full
+     * evicts the coldest zero-participant resident first.
+     */
+    admit(topicId: Uint8Array): boolean;
+    /**
+     * Record the current direct-participant count for a resident topic (LRU bookkeeping). Updates the
+     * eviction key and bumps the topic's recency; a no-op for a topic that is not resident.
+     */
+    touch(topicId: Uint8Array, participantCount: number): void;
+    /** Whether `topicId` currently holds forwarder state. */
+    has(topicId: Uint8Array): boolean;
+    /**
+     * The direct-participant count last reported for a resident `topicId` (the eviction key), or
+     * `undefined` when the topic is not resident. A resident reporting `0` is cold/evictable. Read-only
+     * introspection for tests/diagnostics — eviction policy reads the same field internally.
+     */
+    participantCount(topicId: Uint8Array): number | undefined;
+    /** Number of resident topics. */
+    readonly size: number;
+}
+/** Build a {@link TopicBudget} over the configured `topics_max`. */
+export declare function createTopicBudget(config?: TopicBudgetConfig): TopicBudget;
+//# sourceMappingURL=topic-budget.d.ts.map

package/dist/src/cohort-topic/antidos/topic-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-budget.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/antidos/topic-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qGAAqG;AACrG,MAAM,WAAW,WAAW;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3D,yDAAyD;IACzD,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;IAClC;;;;OAIG;IACH,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1D,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAuFD,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,iBAAsB,GAAG,WAAW,CAE7E"}

package/dist/src/cohort-topic/antidos/topic-budget.js

@@ -0,0 +1,95 @@
+/**
+ * Cohort-topic substrate — per-cohort topic budget (anti-DoS).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 2. A cohort holds forwarder state for at
+ * most `topics_max` (default 2048) topics. Once the budget is full a request to instantiate a **new**
+ * topic is refused (the caller answers `UnwillingCohort`); topics already in the budget continue to
+ * serve. To keep room for genuinely active topics, the budget evicts cold ones: eviction order is
+ * **LRU by participant count**, with **zero-recent-registration topics dropped first** — a topic that
+ * carries no direct participants is the cheapest to shed and is shed before any populated topic.
+ *
+ * `admit` only ever evicts a *zero-participant* topic. If every resident topic still carries
+ * participants the budget is genuinely saturated and the new instantiation is refused — an attacker
+ * cannot, by flooding new topic ids, evict a topic that real participants are using. LRU ordering
+ * uses a monotonic access counter bumped on every `admit`/`touch`, so it is deterministic and needs
+ * no wall clock.
+ */
+import { bytesKey } from "../registration/bytes.js";
+import { createLogger } from "../../logger.js";
+const log = createLogger("cohort-topic:antidos");
+/** Default per-cohort forwarder-topic ceiling — `topics_max`. */
+export const DEFAULT_TOPICS_MAX = 2048;
+class LruTopicBudget {
+    residents = new Map();
+    topicsMax;
+    seqCounter = 0;
+    constructor(config = {}) {
+        this.topicsMax = config.topicsMax ?? DEFAULT_TOPICS_MAX;
+        if (!Number.isInteger(this.topicsMax) || this.topicsMax <= 0) {
+            throw new RangeError(`topicsMax must be a positive integer, got ${this.topicsMax}`);
+        }
+    }
+    get size() {
+        return this.residents.size;
+    }
+    has(topicId) {
+        return this.residents.has(bytesKey(topicId));
+    }
+    participantCount(topicId) {
+        return this.residents.get(bytesKey(topicId))?.participantCount;
+    }
+    admit(topicId) {
+        const key = bytesKey(topicId);
+        const existing = this.residents.get(key);
+        if (existing !== undefined) {
+            existing.seq = ++this.seqCounter; // already resident — refresh recency, always allowed
+            return true;
+        }
+        if (this.residents.size < this.topicsMax) {
+            this.residents.set(key, { participantCount: 0, seq: ++this.seqCounter });
+            return true;
+        }
+        // Full: only a zero-participant resident may be evicted to make room for a new topic.
+        const victim = this.coldestEvictable();
+        if (victim === undefined) {
+            log("topic-budget full size=%d max=%d — refuse new topic", this.residents.size, this.topicsMax);
+            return false;
+        }
+        this.residents.delete(victim);
+        this.residents.set(key, { participantCount: 0, seq: ++this.seqCounter });
+        log("topic-budget evicted cold topic to admit new (size=%d max=%d)", this.residents.size, this.topicsMax);
+        return true;
+    }
+    touch(topicId, participantCount) {
+        const key = bytesKey(topicId);
+        const state = this.residents.get(key);
+        if (state === undefined) {
+            return;
+        }
+        state.participantCount = participantCount;
+        state.seq = ++this.seqCounter;
+    }
+    /**
+     * The coldest evictable resident key: among zero-participant topics, the least-recently used.
+     * `undefined` when every resident still carries participants (nothing may be evicted for a new topic).
+     */
+    coldestEvictable() {
+        let victim;
+        let victimSeq = Infinity;
+        for (const [key, state] of this.residents) {
+            if (state.participantCount > 0) {
+                continue; // populated topics continue — never evicted for a new instantiation
+            }
+            if (state.seq < victimSeq) {
+                victim = key;
+                victimSeq = state.seq;
+            }
+        }
+        return victim;
+    }
+}
+/** Build a {@link TopicBudget} over the configured `topics_max`. */
+export function createTopicBudget(config = {}) {
+    return new LruTopicBudget(config);
+}
+//# sourceMappingURL=topic-budget.js.map

package/dist/src/cohort-topic/antidos/topic-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-budget.js","sourceRoot":"","sources":["../../../../src/cohort-topic/antidos/topic-budget.ts"],"names":[],"mappings":"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"}

package/dist/src/cohort-topic/antiflood/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./jitter.js";
+export * from "./invariants.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/cohort-topic/antiflood/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/antiflood/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/dist/src/cohort-topic/antiflood/index.js

@@ -0,0 +1,3 @@
+export * from "./jitter.js";
+export * from "./invariants.js";
+//# sourceMappingURL=index.js.map

package/dist/src/cohort-topic/antiflood/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cohort-topic/antiflood/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}