@optimystic/db-core 0.13.4 → 0.14.0

package/src/cohort-topic/membership/publisher.ts

@@ -0,0 +1,171 @@
+/**
+ * Cohort-topic substrate — cohort-side `MembershipCertV1` publication.
+ *
+ * Per `docs/cohort-topic.md` §Membership snapshots: the cohort publishes a threshold-signed
+ * `MembershipCertV1`
+ *
+ * - at stabilization, and on any change to the first `k − x` members ({@link MembershipCertPublisher.onStabilized});
+ * - refreshed every `T_membership_refresh` (default 5 min) ({@link MembershipCertPublisher.tick}).
+ *
+ * The publisher is db-core logic over the {@link CohortSigner} (threshold sign) and the
+ * {@link IMembershipPublishSink} (serve/advertise). It never imports FRET. Members are sorted
+ * ascending for the cert (matching the sharding order) and the first `minSigs` (= `k − x`) of that
+ * order are the "first `k − x`" whose change forces a fresh publish.
+ */
+
+import type { IMembershipPublishSink } from "../ports.js";
+import { bytesToB64url, encodeCohortMessage } from "../wire/codec.js";
+import type { MembershipCertV1 } from "../wire/types.js";
+import { compareBytes } from "../registration/bytes.js";
+import { DEFAULT_MIN_SIGS, type CohortSigner } from "../sig/threshold.js";
+import { membershipCertSigningPayload, type MembershipCertSignable } from "../sig/payloads.js";
+
+/** Default membership-cert refresh interval (`T_membership_refresh`). */
+export const DEFAULT_T_MEMBERSHIP_REFRESH_MS = 5 * 60_000;
+
+/**
+ * The canonical {@link MembershipCertSignable} for a stabilized snapshot: members sorted ascending (the
+ * cert / sharding order), byte fields base64url-encoded, over exactly the threshold-signed fields. The
+ * publisher signs `membershipCertSigningPayload` of this; a rotation-attestation **producer** (db-p2p,
+ * `cohort-topic-trust-anchor-rotation-production`) signs the *successor* cert's image through the SAME
+ * helper, so signer and verifier never canonicalize the cert independently (signature-image agreement —
+ * a mismatch makes the db-core chain check fail).
+ */
+export function membershipCertSignable(snapshot: CohortSnapshot): MembershipCertSignable {
+	const sorted = [...snapshot.members].sort(compareBytes);
+	return {
+		cohortCoord: bytesToB64url(snapshot.coord),
+		cohortEpoch: bytesToB64url(snapshot.cohortEpoch),
+		members: sorted.map(bytesToB64url),
+		stabilizedAt: snapshot.stabilizedAt,
+	};
+}
+
+/** A stabilized cohort snapshot the publisher attests. */
+export interface CohortSnapshot {
+	/** Cohort coord (32 bytes). */
+	coord: Uint8Array;
+	/** Cohort epoch for this snapshot. */
+	cohortEpoch: Uint8Array;
+	/** Cohort members (any order; the cert sorts them ascending). */
+	members: readonly Uint8Array[];
+	/** Unix ms this membership stabilized. */
+	stabilizedAt: number;
+	/** Optional FRET stabilization proof. */
+	fretAttestation?: Uint8Array;
+}
+
+/**
+ * A predecessor-cohort rotation attestation to attach to a fresh cert (an epoch rotation). The
+ * predecessor cohort threshold-signs the **successor** cert's `membershipCertSigningPayload`; that
+ * `(prevEpoch, rotationSig, rotationSigners)` triple lets a participant holding a trusted predecessor
+ * verify the rotation is legitimate. Producing this triple is the db-p2p ticket
+ * `cohort-topic-trust-anchor-rotation-production`; the publisher only attaches a provided one.
+ */
+export interface RotationAttestation {
+	/** Predecessor cohort epoch this cert rotates from (32 bytes). */
+	prevEpoch: Uint8Array;
+	/** Predecessor cohort's threshold signature over the successor cert's signing payload. */
+	rotationSig: Uint8Array;
+	/** Predecessor cohort signers that produced {@link rotationSig}; `>= minSigs`. */
+	rotationSigners: readonly Uint8Array[];
+}
+
+/** Cohort-side membership-cert publisher. */
+export interface MembershipCertPublisher {
+	/**
+	 * Drive publication on a stabilization event. Publishes (and returns the cert) when the first
+	 * `k − x` members changed since the last publish, or on the first call; otherwise returns `undefined`.
+	 * Pass `rotation` to attach a predecessor-cohort rotation attestation (an epoch rotation); omit it for
+	 * the default non-rotation publish (no rotation fields are emitted).
+	 */
+	onStabilized(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined>;
+	/**
+	 * Periodic tick. Re-publishes (and returns the cert) when `T_membership_refresh` has elapsed since
+	 * the last publish; otherwise returns `undefined`. Pass `rotation` to attach a rotation attestation.
+	 */
+	tick(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined>;
+}
+
+export interface MembershipCertPublisherDeps {
+	signer: CohortSigner;
+	sink: IMembershipPublishSink;
+	refreshMs?: number;
+	minSigs?: number;
+	maxMessageBytes?: number;
+}
+
+class SigningMembershipCertPublisher implements MembershipCertPublisher {
+	private readonly refreshMs: number;
+	private readonly minSigs: number;
+	/** base64url of the first `minSigs` members of the last published snapshot. */
+	private lastFirstKx: string[] | undefined;
+	private lastPublishedAt: number | undefined;
+
+	constructor(private readonly deps: MembershipCertPublisherDeps) {
+		this.refreshMs = deps.refreshMs ?? DEFAULT_T_MEMBERSHIP_REFRESH_MS;
+		this.minSigs = deps.minSigs ?? DEFAULT_MIN_SIGS;
+	}
+
+	async onStabilized(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined> {
+		const firstKx = this.firstKx(snapshot.members);
+		if (this.lastFirstKx !== undefined && sameOrder(this.lastFirstKx, firstKx)) {
+			return undefined; // first k − x unchanged — no republish needed
+		}
+		return this.publish(snapshot, now, rotation);
+	}
+
+	async tick(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined> {
+		if (this.lastPublishedAt !== undefined && now - this.lastPublishedAt < this.refreshMs) {
+			return undefined;
+		}
+		return this.publish(snapshot, now, rotation);
+	}
+
+	/** The first `minSigs` members of the cert's ascending order, base64url — the republish-change key. */
+	private firstKx(members: readonly Uint8Array[]): string[] {
+		return [...members].sort(compareBytes).slice(0, this.minSigs).map(bytesToB64url);
+	}
+
+	private async publish(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1> {
+		const signable = membershipCertSignable(snapshot);
+		const { thresholdSig, signers } = await this.deps.signer.thresholdSign(membershipCertSigningPayload(signable));
+		const cert: MembershipCertV1 = {
+			v: 1,
+			...signable,
+			thresholdSig: bytesToB64url(thresholdSig),
+			signers: signers.map(bytesToB64url),
+		};
+		if (snapshot.fretAttestation !== undefined) {
+			cert.fretAttestation = bytesToB64url(snapshot.fretAttestation);
+		}
+		// A rotation attestation (when given) signs *over* the cert's signing payload, so it is attached to the
+		// envelope after signing and is not part of `membershipCertSigningPayload`. Omitted → no rotation fields.
+		if (rotation !== undefined) {
+			cert.prevEpoch = bytesToB64url(rotation.prevEpoch);
+			cert.rotationSig = bytesToB64url(rotation.rotationSig);
+			cert.rotationSigners = rotation.rotationSigners.map(bytesToB64url);
+		}
+		this.deps.sink.publish(encodeCohortMessage(cert, this.deps.maxMessageBytes));
+		this.lastFirstKx = signable.members.slice(0, this.minSigs);
+		this.lastPublishedAt = now;
+		return cert;
+	}
+}
+
+function sameOrder(a: readonly string[], b: readonly string[]): boolean {
+	if (a.length !== b.length) {
+		return false;
+	}
+	for (let i = 0; i < a.length; i++) {
+		if (a[i] !== b[i]) {
+			return false;
+		}
+	}
+	return true;
+}
+
+/** Build a cohort-side {@link MembershipCertPublisher}. */
+export function createMembershipCertPublisher(deps: MembershipCertPublisherDeps): MembershipCertPublisher {
+	return new SigningMembershipCertPublisher(deps);
+}

package/src/cohort-topic/membership/source.ts

@@ -0,0 +1,41 @@
+/**
+ * Cohort-topic substrate — membership-source dispatch.
+ *
+ * Resolved open question (per `docs/cohort-topic.md` §Membership source): how *committed*
+ * membership is obtained differs by tier.
+ *
+ * - **T0/T1** cohorts serve committed work (transaction commits, chain serving); their membership is
+ *   anchored in the transaction log's commit certificate. The verifier reads it from there (it never
+ *   writes the log).
+ * - **T2/T3** cohorts (matchmaking, push forwarding) derive membership from current FRET state and
+ *   verify against FRET's signed `MembershipCertV1` advertisements.
+ *
+ * Both back-ends present the same {@link IMembershipSource} surface; this router picks between them by
+ * tier. db-p2p supplies the two concrete sources (tx-log reader and FRET cert source).
+ */
+
+import type { IMembershipSource } from "../ports.js";
+
+/** Picks the authoritative membership source for a cohort by its tier. */
+export interface IMembershipSourceRouter {
+	/** Source for a cohort at `tier`: T0/T1 → committed tx-log, T2/T3 → FRET certs. */
+	for(tier: number): IMembershipSource;
+}
+
+/** Tiers whose committed membership is anchored in the transaction log. */
+function isCommittedTier(tier: number): boolean {
+	return tier === 0 || tier === 1;
+}
+
+/**
+ * Build a router over the two membership back-ends.
+ * @param deps.committed source backed by the transaction-log commit certificate (T0/T1).
+ * @param deps.fret source backed by FRET's signed `MembershipCertV1` advertisements (T2/T3).
+ */
+export function createMembershipSourceRouter(deps: { committed: IMembershipSource; fret: IMembershipSource }): IMembershipSourceRouter {
+	return {
+		for(tier: number): IMembershipSource {
+			return isCommittedTier(tier) ? deps.committed : deps.fret;
+		},
+	};
+}

package/src/cohort-topic/membership/verifier.ts

@@ -0,0 +1,345 @@
+/**
+ * Cohort-topic substrate — participant-side membership verification with a trust-anchor gate.
+ *
+ * Per `docs/cohort-topic.md` §Membership snapshots and §Bootstrapping trust. A participant verifying
+ * a threshold-signed message:
+ *
+ * 1. takes the message's `signers`, the cohort `coord` the signers should belong to, and the tier;
+ * 2. looks up the cached `MembershipCertV1` for that coord (or pulls the source's `current`);
+ * 3. checks the signers are a `≥ minSigs` subset of the cert's members and the signature verifies;
+ * 4. **on failure against a cached/stale cert, re-fetches the cert from any cohort member exactly
+ *    once and retries**; still failing → the message is untrusted.
+ *
+ * **Trust anchoring (the gate this module adds).** Self-consistency (a cert's own threshold signature
+ * is a `≥ minSigs` quorum over its own `members`) proves only internal well-formedness — *not* that the
+ * attesting key set is the legitimate cohort for the coord. An adversary controlling `k − x` keys could
+ * mint a self-consistent cert over a coord it does not own. So before a (re)fetched cert is believed,
+ * {@link CachingMembershipVerifier.certIsTrusted} requires it to be self-consistent **AND** anchored by
+ * at least one of:
+ *
+ * - **Trust root** — `(coord, epoch, member-set)` is in the out-of-band-seeded {@link TrustRoot} set
+ *   (the genesis-block cohorts). Base case of every chain; checked before the direct anchor, so a
+ *   configured root is authoritative.
+ * - **Direct anchor** — the injected {@link IMembershipTrustAnchor} vouches for the binding from a
+ *   source the node directly trusts (FRET ring agreement / tx-log commit cert, bound in db-p2p). A
+ *   `"rejected"` verdict is **fatal** (a forgery, even if self-consistent) and overrides the fallback.
+ * - **Attestation chain** — a cert carrying a rotation attestation (`prevEpoch`/`rotationSig`/
+ *   `rotationSigners`) inherits trust when the node already holds a **trusted** predecessor for the same
+ *   coord at `prevEpoch` whose members form a `≥ minSigs` quorum over this cert's signing payload.
+ *
+ * **Interim TOFU fallback (documented limit).** For a coord the node cannot anchor (the direct anchor
+ * returns `"unknown"` and there is no trust root / chain) and that has **no trusted cert yet**, the
+ * verifier falls back to trust-on-first-use of any self-consistent cert — identical to the pre-anchor
+ * behavior, so there is strictly no regression on coords no node can verify today (distant T2/T3, and
+ * T0/T1 until the committed-index binding lands). Once a coord *does* hold a trusted cert, the chain
+ * governs successors: an un-anchored cert for an already-trusted coord is rejected (no TOFU downgrade),
+ * which is what gives the rotation chain its teeth. The FRET / tx-log direct-anchor bindings that close
+ * the remaining TOFU gap are tracked in `cohort-topic-trust-anchor-fret-binding` and the backlog
+ * `...-fret-stabilization-proof` / `...-txlog-committed-binding` tickets.
+ *
+ * **Deviation from the ticket sketch (documented):** `verifyMessage` takes the cohort `tier`. A coord
+ * is an opaque hash, so the T0/T1-vs-T2/T3 source dispatch the same ticket mandates cannot be derived
+ * from the coord alone; the caller already knows the tier (it computed the coord from the message's
+ * claimed tier/topic). The `tier` is threaded into the gate so the direct anchor is consulted with the
+ * same tier the router used (the binding is tier-scoped).
+ */
+
+import type { IMembershipTrustAnchor, RingCoord, TrustRoot } from "../ports.js";
+import { noAuthorityTrustAnchor } from "../ports.js";
+import { b64urlToBytes, bytesToB64url, decodeMembershipCertV1 } from "../wire/codec.js";
+import { CohortWireError } from "../wire/validate.js";
+import type { MembershipCertV1 } from "../wire/types.js";
+import { DEFAULT_MIN_SIGS, type CohortSigner } from "../sig/threshold.js";
+import { membershipCertSigningPayload } from "../sig/payloads.js";
+import type { IMembershipSourceRouter } from "./source.js";
+
+/** Outcome of verifying a threshold-signed message against cohort membership. */
+export type VerifyResult = "verified" | "untrusted";
+
+/** Caches certs per coord and verifies threshold-signed messages with one stale-cert refetch. */
+export interface MembershipVerifier {
+	/** Cache `cert` as the latest known membership for its coord. */
+	cache(cert: MembershipCertV1): void;
+	/**
+	 * Verify a threshold-signed message. `expectedCoord` is the cohort the `signers` should belong to;
+	 * `tier` selects the membership source. Performs the single refetch+retry internally.
+	 *
+	 * `opts` bounds the network amplification a flood-exposed caller (the `promote` handler) can suffer:
+	 * when **both** `minRefetchIntervalMs` and `now` are given, the stale-cert `source.fetch()` retry is
+	 * **rate-limited per coord** — at most one refetch per coord per interval — so a stream of verify-misses
+	 * (e.g. forged notices) drives a bounded membership-fetch rate rather than one dial per message.
+	 * Eventual refetch is *preserved*: a cold cache or a membership rotation still re-fetches once the
+	 * interval elapses (unlike outright suppression). Omit `opts` (the default, and every existing caller)
+	 * for the unbounded exactly-one-refetch behavior.
+	 */
+	verifyMessage(signers: readonly Uint8Array[], expectedCoord: RingCoord, tier: number, payload: Uint8Array, sig: Uint8Array, opts?: RefetchBound): Promise<VerifyResult>;
+}
+
+/**
+ * Caller-supplied bound on the membership-cert refetch rate (anti-amplification on a flood-exposed verify
+ * path). Both fields are required to take effect; omit either for unbounded refetch.
+ */
+export interface RefetchBound {
+	/** Minimum wall-clock gap (ms) between `source.fetch()` refetches for the same coord. */
+	readonly minRefetchIntervalMs?: number;
+	/** Current wall clock (ms) for the interval comparison. */
+	readonly now?: number;
+}
+
+export interface MembershipVerifierDeps {
+	signer: CohortSigner;
+	router: IMembershipSourceRouter;
+	minSigs?: number;
+	maxMessageBytes?: number;
+	/**
+	 * Direct (base-case) trust anchor for a cert's `coord → keyset` binding. Defaults to
+	 * {@link noAuthorityTrustAnchor} (every coord `"unknown"`), which preserves the interim TOFU behavior.
+	 * db-p2p injects the FRET-ring-backed anchor.
+	 */
+	anchor?: IMembershipTrustAnchor;
+	/** Out-of-band-seeded genesis trust roots (the base case of every attestation chain). Defaults to `[]`. */
+	trustRoots?: readonly TrustRoot[];
+}
+
+/** Result of the trust gate: accept as a trusted anchor, accept as interim TOFU, or reject outright. */
+type CertTrust = "trusted" | "tofu" | "reject";
+
+/** A cached cert and whether it is *trusted* (may serve as an attestation-chain predecessor). */
+interface CachedCert {
+	cert: MembershipCertV1;
+	/** True only when the cert passed via trust-root / direct-anchor / chain, or was self-published (`cache`). */
+	trusted: boolean;
+}
+
+/** A {@link TrustRoot} pre-normalized to the cert's base64url form for cheap matching. */
+interface NormalizedTrustRoot {
+	coord: string;
+	epoch: string;
+	members: ReadonlySet<string>;
+}
+
+class CachingMembershipVerifier implements MembershipVerifier {
+	private readonly byCoord = new Map<string, CachedCert>();
+	/** Per-coord timestamp of the last `source.fetch()` attempt (the rate-limit clock for {@link RefetchBound}). */
+	private readonly lastFetchAt = new Map<string, number>();
+	private readonly minSigs: number;
+	private readonly anchor: IMembershipTrustAnchor;
+	private readonly trustRoots: readonly NormalizedTrustRoot[];
+
+	constructor(private readonly deps: MembershipVerifierDeps) {
+		this.minSigs = deps.minSigs ?? DEFAULT_MIN_SIGS;
+		this.anchor = deps.anchor ?? noAuthorityTrustAnchor;
+		this.trustRoots = (deps.trustRoots ?? []).map(normalizeTrustRoot);
+	}
+
+	cache(cert: MembershipCertV1): void {
+		// The public cache feeds this node its OWN freshly-published cert — a node trusts a cert it itself
+		// published, so it is marked trusted and may anchor the next rotation in the attestation chain.
+		this.byCoord.set(cert.cohortCoord, { cert, trusted: true });
+	}
+
+	async verifyMessage(signers: readonly Uint8Array[], expectedCoord: RingCoord, tier: number, payload: Uint8Array, sig: Uint8Array, opts?: RefetchBound): Promise<VerifyResult> {
+		const coordKey = bytesToB64url(expectedCoord);
+		const source = this.deps.router.for(tier);
+
+		// Seed from the cheap cached view if we hold nothing yet. A cached cert already passed the gate when
+		// it was loaded (or was self-published via `cache`), so it is used directly for message verification.
+		let cert = this.byCoord.get(coordKey)?.cert;
+		if (cert === undefined) {
+			cert = await this.loadFrom(source.current(expectedCoord), tier);
+		}
+		if (cert !== undefined && this.messageVerifies(cert, signers, payload, sig)) {
+			return "verified";
+		}
+
+		// Single fetch-and-retry: a stale or missing cert forces a network refresh. A flood-exposed caller
+		// (the ungated `promote` handler) bounds the amplification via {@link RefetchBound}: the refetch is
+		// then rate-limited to at most one per coord per interval, so a stream of verify-misses (forged
+		// notices) cannot turn into a storm of membership dials. Eventual refetch survives — a cold cache or a
+		// membership rotation still refreshes once the interval elapses.
+		if (!this.refetchAllowed(coordKey, opts)) {
+			return "untrusted";
+		}
+		const refreshed = await this.loadFrom(source.fetch(expectedCoord), tier);
+		if (refreshed !== undefined && this.messageVerifies(refreshed, signers, payload, sig)) {
+			return "verified";
+		}
+		return "untrusted";
+	}
+
+	/**
+	 * Whether a `source.fetch()` refetch is permitted for `coordKey` now. Unbounded (always `true`) unless
+	 * the caller supplies both `minRefetchIntervalMs` and `now`, in which case at most one refetch per coord
+	 * per interval is allowed — the per-coord fetch-rate bound that caps flood amplification. Records the
+	 * attempt time when it returns `true` (the dial is about to happen).
+	 */
+	private refetchAllowed(coordKey: string, opts?: RefetchBound): boolean {
+		const minInterval = opts?.minRefetchIntervalMs;
+		const now = opts?.now;
+		if (minInterval === undefined || now === undefined) {
+			return true;
+		}
+		const last = this.lastFetchAt.get(coordKey);
+		if (last !== undefined && now - last < minInterval) {
+			return false;
+		}
+		this.lastFetchAt.set(coordKey, now);
+		return true;
+	}
+
+	/**
+	 * Decode an encoded cert, run it through the trust gate, cache it (with its trusted status), and return
+	 * it for message verification; `undefined` if absent, malformed, or rejected by the gate. A rejected
+	 * cert (failed self-consistency, a `"rejected"` direct anchor, or an un-anchored cert for an
+	 * already-trusted coord) is treated exactly like an absent cert, so the single refetch still fires.
+	 */
+	private async loadFrom(pending: Promise<Uint8Array | undefined>, tier: number): Promise<MembershipCertV1 | undefined> {
+		const encoded = await pending;
+		if (encoded === undefined) {
+			return undefined;
+		}
+		let cert: MembershipCertV1;
+		let trust: CertTrust;
+		try {
+			cert = decodeMembershipCertV1(encoded, this.deps.maxMessageBytes);
+			trust = this.certIsTrusted(cert, tier);
+		} catch (err) {
+			if (err instanceof CohortWireError) {
+				return undefined; // a malformed cert (or non-base64url signer) is treated as no cert
+			}
+			throw err;
+		}
+		if (trust === "reject") {
+			return undefined;
+		}
+		// Only a `"trusted"` cert may anchor a successor in the attestation chain; a `"tofu"` cert is cached
+		// for message verification but must never launder trust into a rotation.
+		this.byCoord.set(cert.cohortCoord, { cert, trusted: trust === "trusted" });
+		return cert;
+	}
+
+	/**
+	 * The trust gate (see the module header). A cert is accepted iff it is self-consistent **and** anchored
+	 * by a trust root, the direct anchor, or the attestation chain; otherwise it falls to the interim TOFU
+	 * fallback (first-use only). Returns whether the cert is a trusted anchor (`"trusted"`), an interim
+	 * TOFU acceptance (`"tofu"`), or rejected (`"reject"`).
+	 */
+	private certIsTrusted(cert: MembershipCertV1, tier: number): CertTrust {
+		if (!this.certIsSelfConsistent(cert)) {
+			return "reject"; // internal well-formedness is the precondition for any trust path
+		}
+		if (this.matchesTrustRoot(cert)) {
+			return "trusted"; // a configured genesis root is authoritative, checked before the direct anchor
+		}
+		const verdict = this.anchor.directAnchor(cert, tier);
+		if (verdict === "anchored") {
+			return "trusted";
+		}
+		if (verdict === "rejected") {
+			return "reject"; // a contradicted binding is a forgery — fatal, overrides the TOFU fallback
+		}
+		// verdict === "unknown": no local authority for this coord. Try the attestation chain, else fall back.
+		if (this.hasRotationAttestation(cert) && this.chainGrantsTrust(cert)) {
+			return "trusted";
+		}
+		return this.fallbackTrust(cert);
+	}
+
+	/**
+	 * The interim fallback for a coord with no trust-root / anchor / chain coverage. Trust-on-first-use:
+	 * accept a self-consistent cert when the coord holds **no trusted cert yet**, preserving the pre-anchor
+	 * behavior on coords no node can verify today. But once a coord *is* trust-established, an un-anchored
+	 * cert (a failed/absent rotation, including a forged rotation off a trusted predecessor) is **rejected**
+	 * — no silent TOFU downgrade — which is what gives the attestation chain its teeth.
+	 */
+	private fallbackTrust(cert: MembershipCertV1): CertTrust {
+		return this.byCoord.get(cert.cohortCoord)?.trusted ? "reject" : "tofu";
+	}
+
+	/** Whether a cert carries a full rotation attestation (all three fields; validated all-or-nothing on the wire). */
+	private hasRotationAttestation(cert: MembershipCertV1): boolean {
+		return cert.prevEpoch !== undefined && cert.rotationSig !== undefined && cert.rotationSigners !== undefined;
+	}
+
+	/**
+	 * Whether `cert`'s rotation attestation is valid: a **trusted** predecessor for the same coord is cached
+	 * at `prevEpoch`, the rotation is not self-referential, and the predecessor's members form a `≥ minSigs`
+	 * quorum over this cert's signing payload via `rotationSig`. A predecessor that only reached the cache via
+	 * TOFU (not trusted) must not anchor the successor — the trusted-cache invariant.
+	 */
+	private chainGrantsTrust(cert: MembershipCertV1): boolean {
+		const prevEpoch = cert.prevEpoch!;
+		if (prevEpoch === cert.cohortEpoch) {
+			return false; // a cert cannot rotate from itself
+		}
+		const predecessor = this.byCoord.get(cert.cohortCoord);
+		if (predecessor === undefined || !predecessor.trusted || predecessor.cert.cohortEpoch !== prevEpoch) {
+			return false;
+		}
+		// `rotationSigners` is validated only as a string array, so `b64urlToBytes` may throw `CohortWireError`
+		// on a malformed signer — `loadFrom`'s try/catch turns that into "no cert", as for `certIsSelfConsistent`.
+		return this.deps.signer.verifyThreshold(
+			membershipCertSigningPayload(cert),
+			b64urlToBytes(cert.rotationSig!),
+			cert.rotationSigners!.map((s) => b64urlToBytes(s)),
+			predecessor.cert,
+			this.minSigs,
+		);
+	}
+
+	/** Whether `cert` matches a configured trust root by `(coord, epoch)` and an order-independent member set. */
+	private matchesTrustRoot(cert: MembershipCertV1): boolean {
+		for (const root of this.trustRoots) {
+			if (root.coord === cert.cohortCoord && root.epoch === cert.cohortEpoch && setEqualsArray(root.members, cert.members)) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	/** A cert is self-consistent only if its own threshold signature is a valid quorum of its members. */
+	private certIsSelfConsistent(cert: MembershipCertV1): boolean {
+		// `signers` is validated only as a string array (not per-element base64url), so `b64urlToBytes`
+		// below may throw `CohortWireError` on a malformed signer — `loadFrom`'s try/catch turns that
+		// into "no cert" rather than letting it escape.
+		return this.deps.signer.verifyThreshold(
+			membershipCertSigningPayload(cert),
+			b64urlToBytes(cert.thresholdSig),
+			cert.signers.map((s) => b64urlToBytes(s)),
+			cert,
+			this.minSigs,
+		);
+	}
+
+	private messageVerifies(cert: MembershipCertV1, signers: readonly Uint8Array[], payload: Uint8Array, sig: Uint8Array): boolean {
+		return this.deps.signer.verifyThreshold(payload, sig, signers, cert, this.minSigs);
+	}
+}
+
+/** Pre-normalize a {@link TrustRoot} (raw bytes) to the cert's base64url form for cheap matching. */
+function normalizeTrustRoot(root: TrustRoot): NormalizedTrustRoot {
+	return {
+		coord: bytesToB64url(root.coord),
+		epoch: bytesToB64url(root.epoch),
+		members: new Set(root.members.map(bytesToB64url)),
+	};
+}
+
+/** Order-independent set equality between a trust-root member set and a cert's member array (duplicate-safe). */
+function setEqualsArray(set: ReadonlySet<string>, members: readonly string[]): boolean {
+	const seen = new Set<string>();
+	for (const m of members) {
+		if (!set.has(m)) {
+			return false; // a member not in the root → not a root match
+		}
+		seen.add(m);
+	}
+	// Cover both directions: every distinct cert member is in the root AND every root member is covered,
+	// so a duplicate-inflated member list cannot masquerade as a full-set match.
+	return seen.size === set.size;
+}
+
+/** Build a participant-side {@link MembershipVerifier}. */
+export function createMembershipVerifier(deps: MembershipVerifierDeps): MembershipVerifier {
+	return new CachingMembershipVerifier(deps);
+}