@optimystic/db-core 0.13.4 → 0.14.0

package/src/cohort-topic/addressing.ts

@@ -0,0 +1,112 @@
+/**
+ * Cohort-topic substrate — tier addressing (`coord_d`).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Tier addressing:
+ *
+ * ```
+ * coord_0(_, topicId) = H(0x00 ‖ topicId)
+ * coord_d(P, topicId) = H(d ‖ prefix(P, d·log₂F) ‖ topicId)   for d ≥ 1
+ * ```
+ *
+ * `H` is the injected {@link IRingHash} (db-core's own SHA-256 truncated to the ring width — **not**
+ * a FRET import). `prefix(P, n)` is the `n` most-significant bits of peer id `P`, left-padded if
+ * shorter. `F` is the fan-out (default 16, `log₂F = 4`); tier `d` has exactly `F^d` coordinates.
+ *
+ * The db-p2p binding is responsible for ensuring the coord byte layout (ring width) matches FRET's
+ * `RING_BITS` so the routing keys produced here line up with FRET's ring on the wire.
+ */
+
+import type { IRingHash, RingCoord } from "./ports.js";
+
+/** Tier-addressing surface — derives the ring coordinate for tier `d` of a topic. */
+export interface TierAddressing {
+	/** Fan-out per tier (default 16). */
+	readonly F: number;
+	/** Tier-0 root coordinate: `H(0x00 ‖ topicId)`. Peer-independent. */
+	coord0(topicId: Uint8Array): RingCoord;
+	/** Tier-`d` coordinate for `d ≥ 1`: `H(d ‖ prefix(peerId, d·log₂F) ‖ topicId)`. */
+	coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
+	/** Dispatches `d === 0` to {@link coord0}, otherwise to {@link coordD}. */
+	coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
+}
+
+/** Default fan-out per tier (`log₂16 = 4`). */
+export const DEFAULT_FANOUT = 16;
+
+/**
+ * `prefix(P, n)` — the `n` most-significant bits of `P`, packed MSB-first into `⌈n/8⌉` bytes with
+ * the trailing partial byte's unused low bits zeroed. If `P` carries fewer than `n` bits it is
+ * **left-padded**: the high `(n − bits(P))` positions are zero and `P`'s bits occupy the low end, so
+ * the result is always exactly `n` bits wide. `n === 0` yields an empty array (the tier-0 case).
+ *
+ * Exported for tests; not part of the public substrate surface.
+ */
+export function prefixBits(peerId: Uint8Array, n: number): Uint8Array {
+	if (!Number.isInteger(n) || n < 0) {
+		throw new RangeError(`prefix bit count must be a non-negative integer, got ${n}`);
+	}
+	const outBytes = Math.ceil(n / 8);
+	const out = new Uint8Array(outBytes);
+	const available = peerId.length * 8;
+	const pad = Math.max(0, n - available);
+	for (let j = 0; j < n; j++) {
+		// Result bit j (MSB-first). High `pad` positions are zero (left-pad); the rest map to P.
+		if (j < pad) continue;
+		const srcBit = j - pad;
+		const srcByte = peerId[srcBit >>> 3]!;
+		const bit = (srcByte >>> (7 - (srcBit & 7))) & 1;
+		if (bit) out[j >>> 3]! |= 1 << (7 - (j & 7));
+	}
+	return out;
+}
+
+/** Implements {@link TierAddressing} over an injected {@link IRingHash}. */
+export class HashTierAddressing implements TierAddressing {
+	public readonly F: number;
+	private readonly log2F: number;
+
+	constructor(private readonly hash: IRingHash, F: number = DEFAULT_FANOUT) {
+		if (!Number.isInteger(F) || F < 2) {
+			throw new RangeError(`fan-out F must be an integer ≥ 2, got ${F}`);
+		}
+		const log2F = Math.log2(F);
+		if (!Number.isInteger(log2F)) {
+			throw new RangeError(`fan-out F must be a power of two, got ${F}`);
+		}
+		this.F = F;
+		this.log2F = log2F;
+	}
+
+	coord0(topicId: Uint8Array): RingCoord {
+		// H(0x00 ‖ topicId)
+		const input = new Uint8Array(1 + topicId.length);
+		input[0] = 0x00;
+		input.set(topicId, 1);
+		return this.hash.H(input);
+	}
+
+	coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
+		if (!Number.isInteger(d) || d < 1) {
+			throw new RangeError(`coordD requires an integer tier d ≥ 1, got ${d}`);
+		}
+		if (d > 255) {
+			throw new RangeError(`tier d must fit in one byte (≤ 255), got ${d}`);
+		}
+		// H(d ‖ prefix(peerId, d·log₂F) ‖ topicId)
+		const prefix = prefixBits(peerId, d * this.log2F);
+		const input = new Uint8Array(1 + prefix.length + topicId.length);
+		input[0] = d;
+		input.set(prefix, 1);
+		input.set(topicId, 1 + prefix.length);
+		return this.hash.H(input);
+	}
+
+	coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
+		return d === 0 ? this.coord0(topicId) : this.coordD(d, peerId, topicId);
+	}
+}
+
+/** Convenience factory mirroring the db-p2p adapter construction style. */
+export function createTierAddressing(hash: IRingHash, F: number = DEFAULT_FANOUT): TierAddressing {
+	return new HashTierAddressing(hash, F);
+}

package/src/cohort-topic/antidos/bootstrap-evidence-envelope.ts

@@ -0,0 +1,253 @@
+/**
+ * Cohort-topic substrate — bootstrap-evidence envelope (anti-DoS, crypto-free).
+ *
+ * The on-the-wire structure a participant attaches to a cold-start `bootstrap: true` register, and the
+ * byte-level canonicalization both sides agree on. This module owns only the **format** — the versioned
+ * envelope, the canonical anti-replay bound image, and the proof-of-work puzzle's preimage/difficulty.
+ * It embeds **no cryptography**: the actual PoW hashing, reputation-signature checks, and parent-topic
+ * verification live in db-p2p (which binds the node's `RingHash` and peer-key crypto). The sibling
+ * discipline of `wire/payloads.ts` / `sig/payloads.ts` — explicitly-ordered arrays, deterministic UTF-8
+ * JSON, base64url without padding — so a participant who *mints* evidence and a cohort that *verifies*
+ * it never re-canonicalize bytes independently.
+ *
+ * The envelope rides in the dedicated, signature-covered {@link RegisterV1.bootstrapEvidence} field
+ * (not `appPayload`). A verifier reads only the kind its tier accepts; an absent kind, a malformed
+ * envelope, or a wrong/future version all surface as "this kind not offered" (the parse is **total** —
+ * like `verifyPeerSig`, any decode error yields `undefined`, never a throw), so a verifier fails its
+ * check (→ `unwilling_cohort`) rather than crashing on attacker-supplied input.
+ */
+
+import { b64urlToBytes, bytesToB64url } from "../wire/codec.js";
+import type { RegisterV1 } from "../wire/types.js";
+
+const utf8 = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** Proof-of-work evidence (T2/T3 path). `nonce` is base64url, bound via {@link powPreimage}. */
+export interface PowEvidenceV1 {
+	/** Base64url nonce; `hash(powPreimage(reg, nonce))` must satisfy {@link meetsDifficulty}. */
+	nonce: string;
+}
+
+/** Signed parent-topic reference (all tiers). Both base64url; `sig` is over {@link parentRefSigningImage}. */
+export interface ParentRefEvidenceV1 {
+	/** The committed parent topic id, base64url. */
+	parentTopicId: string;
+	/** Participant peer-key signature over {@link parentRefSigningImage} (the bound tuple extended with `parentTopicId`), base64url. */
+	sig: string;
+}
+
+/**
+ * Reputation endorsement (T2/T3 path). `referee` is the endorsing peer-id-string bytes (base64url) and
+ * `sig` is that referee's peer-key signature over the bound image. The referee MAY equal the
+ * participant (a reputable participant self-vouches).
+ */
+export interface ReputationEvidenceV1 {
+	/** Endorsing peer-id-string bytes, base64url. */
+	referee: string;
+	/** Referee's peer-key signature over the bound image, base64url. */
+	sig: string;
+}
+
+/** V1 bootstrap-evidence envelope, base64url-encoded into {@link RegisterV1.bootstrapEvidence}. */
+export interface BootstrapEvidenceEnvelopeV1 {
+	v: 1;
+	/** Proof-of-work (T2/T3 path). Absent → no PoW offered. */
+	pow?: PowEvidenceV1;
+	/** Signed parent-topic reference (all tiers). Absent → none offered. */
+	parentRef?: ParentRefEvidenceV1;
+	/** Reputation endorsement (T2/T3 path). Absent → none offered. */
+	reputation?: ReputationEvidenceV1;
+}
+
+/**
+ * The four register fields every bootstrap-evidence kind is bound to (the anti-replay tuple). The full
+ * {@link RegisterV1} satisfies this, so a verifier passes its decoded register directly; the
+ * participant-side builder passes just these fields (it has no full register yet).
+ */
+export type BootstrapBoundFields = Pick<RegisterV1, "topicId" | "tier" | "participantCoord" | "timestamp">;
+
+/** Default PoW difficulty: leading zero bits required. ~2^bits hashes to mint, one hash to verify. */
+export const DEFAULT_POW_DIFFICULTY_BITS = 20;
+
+/**
+ * The canonical bytes every bootstrap-evidence kind is bound to: `(topicId, tier, participantCoord,
+ * timestamp)`. `topicId`/`participantCoord` are bound as their base64url wire strings verbatim (matching
+ * `sig/payloads.ts`) so signer and verifier never re-canonicalize bytes independently. Binding all four
+ * means evidence minted for one (topic, tier, peer, time) cannot be replayed for another; binding
+ * `timestamp` additionally bounds a captured proof's reuse window, since the register replay guard drops
+ * a `timestamp` older than its acceptance window.
+ */
+export function bootstrapBoundImage(reg: BootstrapBoundFields): Uint8Array {
+	return utf8.encode(JSON.stringify([
+		"BootstrapEvidenceV1",
+		reg.topicId,
+		reg.tier,
+		reg.participantCoord,
+		reg.timestamp,
+	]));
+}
+
+/**
+ * The canonical bytes a **signed parent-topic reference** binds: the {@link bootstrapBoundImage} tuple
+ * `(topicId, tier, participantCoord, timestamp)` **extended with the referenced `parentTopicId`**, under a
+ * distinct discriminator tag (`"BootstrapParentRefV1"`). Extending the image with `parentTopicId` means a
+ * reference minted for one `(topic, tier, peer, time, parent)` cannot be lifted onto another register —
+ * including onto a register naming a *different* parent; the distinct tag keeps it from colliding with a
+ * {@link bootstrapBoundImage} reputation/PoW signature (domain separation). `topicId`/`participantCoord`/
+ * `parentTopicId` are bound as their base64url wire strings verbatim, like {@link bootstrapBoundImage}, so
+ * the participant who *signs* the reference and the cohort that *verifies* it never re-canonicalize bytes.
+ */
+export function parentRefSigningImage(reg: BootstrapBoundFields, parentTopicId: string): Uint8Array {
+	return utf8.encode(JSON.stringify([
+		"BootstrapParentRefV1",
+		reg.topicId,
+		reg.tier,
+		reg.participantCoord,
+		reg.timestamp,
+		parentTopicId,
+	]));
+}
+
+/**
+ * The proof-of-work hash preimage: {@link bootstrapBoundImage} concatenated with `nonce`. db-p2p hashes
+ * this (via the node's `RingHash`) and checks the digest against {@link meetsDifficulty}. Bound to the
+ * register tuple ⇒ no cross-topic / cross-peer replay; cheap to verify (one hash + bit check), tunably
+ * costly to produce.
+ */
+export function powPreimage(reg: BootstrapBoundFields, nonce: Uint8Array): Uint8Array {
+	const image = bootstrapBoundImage(reg);
+	const out = new Uint8Array(image.length + nonce.length);
+	out.set(image, 0);
+	out.set(nonce, image.length);
+	return out;
+}
+
+/**
+ * True iff the first `bits` most-significant bits of `hash` are zero (the PoW difficulty target). Bits
+ * are read MSB-first per byte (mirroring `addressing.ts`'s `prefixBits`). `bits = 0` is trivially met
+ * (lets a config disable PoW cost for tests); a non-finite `bits` is a guard-failure (never met); a
+ * negative `bits` clamps to 0; `bits` larger than `hash.length * 8` requires every bit of `hash` to be
+ * zero and so is effectively unsatisfiable for a random hash.
+ */
+export function meetsDifficulty(hash: Uint8Array, bits: number): boolean {
+	if (!Number.isFinite(bits)) {
+		return false; // NaN / ±Infinity → defensive guard, never satisfiable
+	}
+	let remaining = Math.floor(bits);
+	if (remaining <= 0) {
+		return true; // 0 (or clamped-negative) leading zero bits is trivially met
+	}
+	for (let i = 0; i < hash.length && remaining > 0; i++) {
+		const byte = hash[i]!;
+		if (remaining >= 8) {
+			if (byte !== 0) {
+				return false;
+			}
+			remaining -= 8;
+		} else {
+			// Check only the top `remaining` MSBs of this partial final byte (MSB-first).
+			const mask = (0xff << (8 - remaining)) & 0xff;
+			if ((byte & mask) !== 0) {
+				return false;
+			}
+			remaining = 0;
+		}
+	}
+	// Exhausted the hash before satisfying `bits` (oversize target) → unsatisfiable.
+	return remaining === 0;
+}
+
+/** Serialize an envelope to the base64url JSON string carried in {@link RegisterV1.bootstrapEvidence}. */
+export function serializeBootstrapEvidenceEnvelope(env: BootstrapEvidenceEnvelopeV1): string {
+	// Rebuild in a fixed field order so serialization is a pure function of the logical content
+	// (serialize∘parse is stable regardless of how a caller ordered the source object's keys).
+	const out: BootstrapEvidenceEnvelopeV1 = { v: 1 };
+	if (env.pow !== undefined) {
+		out.pow = { nonce: env.pow.nonce };
+	}
+	if (env.parentRef !== undefined) {
+		out.parentRef = { parentTopicId: env.parentRef.parentTopicId, sig: env.parentRef.sig };
+	}
+	if (env.reputation !== undefined) {
+		out.reputation = { referee: env.reputation.referee, sig: env.reputation.sig };
+	}
+	return bytesToB64url(utf8.encode(JSON.stringify(out)));
+}
+
+/**
+ * Decode {@link RegisterV1.bootstrapEvidence} (base64url → JSON), structurally validate it, and return
+ * the {@link BootstrapEvidenceEnvelopeV1}. **Total**: returns `undefined` on an absent/empty field, a
+ * non-base64url or non-JSON body, a wrong/future `v`, or a structurally-invalid kind — never throws. A
+ * verifier treats `undefined` as "this kind not offered" and fails its check (fails closed).
+ */
+export function parseBootstrapEvidenceEnvelope(reg: Pick<RegisterV1, "bootstrapEvidence">): BootstrapEvidenceEnvelopeV1 | undefined {
+	const raw = reg.bootstrapEvidence;
+	if (raw === undefined || raw === "") {
+		return undefined; // not offered
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(utf8Decoder.decode(b64urlToBytes(raw)));
+	} catch {
+		return undefined; // not base64url / not UTF-8 / not JSON → fail closed
+	}
+	return narrowEnvelope(parsed);
+}
+
+/** Structurally narrow an already-parsed value to a v1 envelope, or `undefined`. */
+function narrowEnvelope(value: unknown): BootstrapEvidenceEnvelopeV1 | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return undefined;
+	}
+	const obj = value as Record<string, unknown>;
+	if (obj["v"] !== 1) {
+		return undefined; // wrong / future version → fail closed under the v1 reader
+	}
+	const out: BootstrapEvidenceEnvelopeV1 = { v: 1 };
+
+	if (obj["pow"] !== undefined) {
+		const nonce = b64urlSubfield(obj["pow"], "nonce");
+		if (nonce === undefined) {
+			return undefined;
+		}
+		out.pow = { nonce };
+	}
+
+	if (obj["parentRef"] !== undefined) {
+		const parentTopicId = b64urlSubfield(obj["parentRef"], "parentTopicId");
+		const sig = b64urlSubfield(obj["parentRef"], "sig");
+		if (parentTopicId === undefined || sig === undefined) {
+			return undefined;
+		}
+		out.parentRef = { parentTopicId, sig };
+	}
+
+	if (obj["reputation"] !== undefined) {
+		const referee = b64urlSubfield(obj["reputation"], "referee");
+		const sig = b64urlSubfield(obj["reputation"], "sig");
+		if (referee === undefined || sig === undefined) {
+			return undefined;
+		}
+		out.reputation = { referee, sig };
+	}
+
+	return out;
+}
+
+/** A required base64url sub-field: a non-empty string that decodes cleanly, else `undefined`. */
+function b64urlSubfield(container: unknown, key: string): string | undefined {
+	if (typeof container !== "object" || container === null || Array.isArray(container)) {
+		return undefined;
+	}
+	const value = (container as Record<string, unknown>)[key];
+	if (typeof value !== "string" || value === "") {
+		return undefined; // missing, non-string, or empty → treat as absent
+	}
+	try {
+		b64urlToBytes(value); // structural: must decode as base64url
+	} catch {
+		return undefined;
+	}
+	return value;
+}

package/src/cohort-topic/antidos/bootstrap-evidence.ts

@@ -0,0 +1,94 @@
+/**
+ * Cohort-topic substrate — bootstrap evidence policy (anti-DoS).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 4. A cold root that accepts a
+ * `bootstrap: true` registration must demand evidence, so a cold topic cannot be instantiated for
+ * free by an attacker. The accepted evidence is **tier-dependent**:
+ *
+ * - **T0 / T1** — generally no proof-of-work, because these tiers correspond to committed work; a
+ *   *signed reference to a committed parent topic that does exist* is sufficient.
+ * - **T2 / T3** — a **proof-of-work** OR a **reputation-score signature** (a signature from a peer
+ *   with sufficient reputation, see `architecture.md` §Reputation) OR a **signed parent-topic
+ *   reference**.
+ *
+ * This module is the *policy* — which evidence kinds satisfy which tier. The cryptographic checks
+ * themselves (verifying a PoW, a reputation signature, a parent-topic reference) are injected, keeping
+ * db-core free of any specific PoW/reputation scheme (the same injection discipline as the threshold
+ * crypto port). The evidence travels in the registration's dedicated, signature-covered
+ * `bootstrapEvidence` field — a versioned `BootstrapEvidenceEnvelopeV1`
+ * (`./bootstrap-evidence-envelope.js`), parsed crypto-free here and checked by the injected verifiers;
+ * NOT the opaque `appPayload` slot (which the cohort copies verbatim into the registration's appState).
+ * A registration that is not a bootstrap needs no evidence and is admitted.
+ */
+
+import type { RegisterV1 } from "../wire/types.js";
+import { createLogger } from "../../logger.js";
+
+const log = createLogger("cohort-topic:antidos");
+
+/** Tiers at/below this need no proof-of-work — a signed parent reference suffices (T0/T1). */
+export const DEFAULT_MAX_NO_POW_TIER = 1;
+
+export interface BootstrapEvidenceDeps {
+	/** Verify a proof-of-work attached to `reg` (T2/T3 path). Absent → PoW is never satisfiable. */
+	verifyPoW?: (reg: RegisterV1) => boolean;
+	/** Verify a sufficient-reputation signature on `reg` (T2/T3 path). Absent → never satisfiable. */
+	verifyReputation?: (reg: RegisterV1) => boolean;
+	/** Verify a signed reference to an existing committed parent topic (all tiers). Absent → never satisfiable. */
+	verifyParentReference?: (reg: RegisterV1) => boolean;
+	config?: BootstrapEvidenceConfig;
+}
+
+export interface BootstrapEvidenceConfig {
+	/** Highest tier exempt from proof-of-work (T0/T1 → 1). Default {@link DEFAULT_MAX_NO_POW_TIER}. */
+	maxNoPowTier?: number;
+}
+
+/** Tier-dependent bootstrap-evidence gate for cold-root registrations. */
+export interface BootstrapEvidence {
+	/**
+	 * Whether `reg` carries acceptable bootstrap evidence for `tier`. A non-bootstrap registration is
+	 * always acceptable (nothing to prove). For a bootstrap: T0/T1 require a signed parent reference;
+	 * T2/T3 accept proof-of-work OR a reputation signature OR a signed parent reference.
+	 */
+	verify(reg: RegisterV1, tier: number): boolean;
+}
+
+class TieredBootstrapEvidence implements BootstrapEvidence {
+	private readonly maxNoPowTier: number;
+	private readonly verifyPoW: (reg: RegisterV1) => boolean;
+	private readonly verifyReputation: (reg: RegisterV1) => boolean;
+	private readonly verifyParentReference: (reg: RegisterV1) => boolean;
+
+	constructor(deps: BootstrapEvidenceDeps = {}) {
+		this.maxNoPowTier = deps.config?.maxNoPowTier ?? DEFAULT_MAX_NO_POW_TIER;
+		this.verifyPoW = deps.verifyPoW ?? ((): boolean => false);
+		this.verifyReputation = deps.verifyReputation ?? ((): boolean => false);
+		this.verifyParentReference = deps.verifyParentReference ?? ((): boolean => false);
+	}
+
+	verify(reg: RegisterV1, tier: number): boolean {
+		if (reg.bootstrap !== true) {
+			return true; // only a cold-root bootstrap must carry evidence
+		}
+		if (tier <= this.maxNoPowTier) {
+			// T0/T1: a signed reference to a committed parent topic is sufficient (no PoW expected).
+			const ok = this.verifyParentReference(reg);
+			if (!ok) {
+				log("bootstrap-evidence reject: tier=%d needs a signed parent reference", tier);
+			}
+			return ok;
+		}
+		// T2/T3: any one of PoW, a reputation signature, or a signed parent reference.
+		const ok = this.verifyPoW(reg) || this.verifyReputation(reg) || this.verifyParentReference(reg);
+		if (!ok) {
+			log("bootstrap-evidence reject: tier=%d needs PoW / reputation / parent reference", tier);
+		}
+		return ok;
+	}
+}
+
+/** Build a {@link BootstrapEvidence} policy over the injected (db-p2p-supplied) evidence verifiers. */
+export function createBootstrapEvidence(deps: BootstrapEvidenceDeps = {}): BootstrapEvidence {
+	return new TieredBootstrapEvidence(deps);
+}

package/src/cohort-topic/antidos/index.ts

@@ -0,0 +1,5 @@
+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";

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

@@ -0,0 +1,210 @@
+/**
+ * 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, type BackoffConfig, 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;
+
+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;
+}
+
+/** Sliding-window state for one `(peer, topic)` key. */
+interface WindowState {
+	/** Accept timestamps inside the trailing window, ascending. */
+	accepts: number[];
+	/** Consecutive over-rate strikes since the last accept — indexes the back-off curve. */
+	strikes: number;
+	/** `now` of the most recent check (accept OR reject) — LRU recency + idle-TTL key for {@link RegisterRateLimiter.sweep}. */
+	lastSeen: number;
+}
+
+class SlidingWindowRateLimiter implements RegisterRateLimiter {
+	private readonly states = new Map<string, WindowState>();
+	private readonly ratePerWindow: number;
+	private readonly windowMs: number;
+	private readonly backoff: BackoffConfig;
+	private readonly maxKeys: number;
+	private readonly idleTtlMs: number;
+
+	constructor(config: RegisterRateLimiterConfig = {}) {
+		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: Uint8Array, topicId: Uint8Array, now: number): RateCheckResult {
+		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: number): number {
+		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(): number {
+		return this.states.size;
+	}
+}
+
+/** Build a {@link RegisterRateLimiter} over the configured ceiling, window, and back-off curve. */
+export function createRegisterRateLimiter(config: RegisterRateLimiterConfig = {}): RegisterRateLimiter {
+	return new SlidingWindowRateLimiter(config);
+}