@optimystic/db-p2p 0.22.0 → 0.24.1

package/src/cohort-topic/stream-util.ts

@@ -1,20 +1,77 @@
 /**
- * Cohort-topic libp2p stream helpers.
+ * Single-frame libp2p stream helpers, shared by cohort-topic, matchmaking, and reactivity.
  *
- * The cohort-topic protocols exchange a single self-delimiting cohort frame each way (the db-core wire
- * codec already length-prefixes the body), so request/response is one `send` + one bounded read. This
- * mirrors FRET's `rpc/maybe-act.ts` exactly and reuses FRET's exported `readAllBounded`, keeping the
- * stream lifecycle (open → send → close-write → read → close) consistent across both protocol families.
+ * These protocols exchange a single varint-length-prefixed frame each way, via FRET's exported
+ * `sendFramed` / `readFramed` pair — the varint prefix is what delimits the frame on the wire
+ * (the db-core codec's own internal length prefix travels *inside* the framed body and plays no
+ * part in stream delimiting). Request/response is one framed send + one framed read, matching
+ * FRET's own four RPC protocols and the `it-length-prefixed` framing the rest of `db-p2p`
+ * (`protocol-client.ts`, the cluster/repo/sync/dispute services) already uses, keeping the stream
+ * lifecycle (open → send → close-write → read → close) consistent across all protocol families.
+ *
+ * NOTE: every `sendFramed` here discards its boolean result (`false` = "write accepted, transport
+ * buffer now full"), so these helpers apply no backpressure. Harmless while each protocol writes
+ * exactly one bounded frame per stream and then closes; if a caller ever writes repeatedly on one
+ * stream, honor the flag by awaiting the stream's `'drain'` event the way FRET's `rpcRequest` does.
+ *
+ * {@link openStream} deliberately duplicates FRET's `rpc/protocols.ts#openRpcStream` connection
+ * selection. FRET now exports `openRpcStream`, but the accepted tradeoff on
+ * {@link STREAM_OPTIONS} is why the local copy stays: FRET's helper pins `negotiateFully: false`,
+ * which this module deliberately does not set — swapping would silently reverse that decision.
+ * Same applies to `libp2p-key-network.ts#connect`, which is a third copy.
  */
 
 import type { Libp2p } from "libp2p";
 import type { Connection, PeerId, Stream } from "@libp2p/interface";
-import { readAllBounded } from "p2p-fret";
+import { readFramed, sendFramed } from "p2p-fret";
 
 /** Default per-frame ceiling — matches FRET's 512 KiB maybe-act bound. */
 export const DEFAULT_STREAM_MAX_BYTES = 512 * 1024;
 
-/** Open `protocol` to `peer`, send `frame`, and read the bounded reply frame. */
+/**
+ * libp2p refuses to open a protocol stream over a *limited* (circuit-relay) connection unless the
+ * caller opts in, so every peer reachable only through a relay — the steady state for browsers and
+ * NATed peers — depends on this flag. It is a harmless no-op on a direct connection.
+ *
+ * NOTE: accepted tradeoff — FRET's `openRpcStream` and `libp2p-key-network.ts#connect` also set
+ * `negotiateFully: false`; deliberately not set here. It saves a round trip but defers an
+ * unsupported-protocol failure from stream-open to the first read, which would turn
+ * {@link sendOneWay} against a peer lacking the protocol into a silent no-op. Revisit if
+ * stream-open latency shows up in a profile.
+ */
+const STREAM_OPTIONS = { runOnLimitedConnection: true } as const;
+
+/** True for a circuit-relay ("limited") connection: libp2p stamps one with per-circuit `limits`;
+ * sniffing `/p2p-circuit` in the multiaddr covers transports that leave `limits` unpopulated. */
+function isLimitedConnection(c: Connection): boolean {
+	if ((c as { limits?: unknown }).limits != null) return true;
+	return c.remoteAddr?.toString?.().includes("/p2p-circuit") ?? false;
+}
+
+/**
+ * Open `protocol` to `peer`, reusing a healthy existing connection when there is one.
+ *
+ * Skips connections libp2p has not yet evicted from its index but that are no longer open, and
+ * prefers a direct connection over a relayed one — a relayed connection can be reset once the
+ * relay's per-circuit cap or reservation lapses, and after DCUtR upgrades a link to direct both
+ * briefly coexist. Falls back to the relayed connection when it is the only open path.
+ */
+async function openStream(node: Libp2p, peer: PeerId, protocol: string): Promise<Stream> {
+	const open = node.getConnections(peer).filter(c => c?.status === "open" && typeof c?.newStream === "function");
+	const chosen = open.find(c => !isLimitedConnection(c)) ?? open[0];
+	return chosen ? await chosen.newStream([protocol], STREAM_OPTIONS) : await node.dialProtocol(peer, [protocol], STREAM_OPTIONS);
+}
+
+/**
+ * Open `protocol` to `peer`, send `frame`, and read the bounded reply frame.
+ *
+ * NOTE: takes no `AbortSignal`, so a caller cannot set its own deadline. Bounded today anyway —
+ * `readFramed` self-times-out at 5s and `dialProtocol` falls back to libp2p's default dial
+ * timeout (~30s) — so an unresponsive peer is slow, not hung. If a caller ever needs a tighter
+ * deadline (`membership-source.fetch` walks candidate peers *sequentially*, so its worst case is
+ * peers × dial-timeout), thread a signal through {@link openStream} the way
+ * `libp2p-key-network.ts#connect` does.
+ */
 export async function requestResponse(
 	node: Libp2p,
 	peer: PeerId,
@@ -22,13 +79,12 @@ export async function requestResponse(
 	frame: Uint8Array,
 	maxBytes = DEFAULT_STREAM_MAX_BYTES,
 ): Promise<Uint8Array> {
-	const conns = node.getConnections(peer);
 	let stream: Stream | undefined;
 	try {
-		stream = conns.length > 0 ? await conns[0]!.newStream([protocol]) : await node.dialProtocol(peer, [protocol]);
-		stream.send(frame);
+		stream = await openStream(node, peer, protocol);
+		sendFramed(stream, frame);
 		await stream.close();
-		return await readAllBounded(stream, maxBytes);
+		return await readFramed(stream, maxBytes);
 	} finally {
 		if (stream != null) {
 			try {
@@ -42,11 +98,10 @@ export async function requestResponse(
 
 /** Open `protocol` to `peer` and send `frame` without awaiting a reply (fire-and-forget gossip). */
 export async function sendOneWay(node: Libp2p, peer: PeerId, protocol: string, frame: Uint8Array): Promise<void> {
-	const conns = node.getConnections(peer);
 	let stream: Stream | undefined;
 	try {
-		stream = conns.length > 0 ? await conns[0]!.newStream([protocol]) : await node.dialProtocol(peer, [protocol]);
-		stream.send(frame);
+		stream = await openStream(node, peer, protocol);
+		sendFramed(stream, frame);
 		await stream.close();
 	} finally {
 		if (stream != null) {
@@ -59,7 +114,14 @@ export async function sendOneWay(node: Libp2p, peer: PeerId, protocol: string, f
 	}
 }
 
-/** Register a request/response handler for `protocol`: read one bounded frame, reply with one frame. */
+/**
+ * Register a request/response handler for `protocol`: read one bounded frame, reply with one frame.
+ *
+ * A `handle` that returns `undefined` (a drop, a gate rejection, no serving engine) replies with an
+ * explicit **zero-length frame** rather than silence: `readFramed` treats end-of-stream as a
+ * truncation error, so "no reply" must travel in-band — the dialer's {@link requestResponse}
+ * resolves it as empty bytes, exactly what the old read-to-EOF returned for a silent close.
+ */
 export function handleRequestResponse(
 	node: Libp2p,
 	protocol: string,
@@ -69,11 +131,9 @@ export function handleRequestResponse(
 	void node.handle(protocol, (stream: Stream, connection: Connection) => {
 		void (async (): Promise<void> => {
 			try {
-				const frame = await readAllBounded(stream, maxBytes);
+				const frame = await readFramed(stream, maxBytes);
 				const reply = await handle(frame, connection.remotePeer);
-				if (reply !== undefined) {
-					stream.send(reply);
-				}
+				sendFramed(stream, reply ?? new Uint8Array(0));
 				await stream.close();
 			} catch {
 				try {

package/src/cohort-topic/threshold-crypto.ts

@@ -1,239 +1,239 @@
-/**
- * Cohort-topic `k − x` threshold-signature crypto — real collected Ed25519 multi-signature.
- *
- * Closes gap 1 (the interim single-signer `sha256(payload)` digest, which could never satisfy
- * `CohortSigner.verifyThreshold`'s `≥ minSigs` distinct-member rule at `minSigs = 14`). The scheme is
- * a **collected multisig**: `thresholdSig` is the aligned concatenation of fixed-width 64-byte Ed25519
- * signatures, one per `signers[i]`, each produced by that member's libp2p peer key over the *exact*
- * canonical payload. It needs **no trusted setup, no new crypto dependency, and no aggregation round**
- * (unlike BLS or FROST), maps directly onto the existing `(thresholdSig, signers)` contract, and reuses
- * the per-member peer-key signing primitive (`peer-sig.ts`) the codebase already uses for cluster-repo
- * commit signatures. Size is O(k) (≤ ~14 × 64 = 896 bytes at production `minSigs`) — negligible for
- * k ≤ 16; if size ever matters at larger k the scheme can be swapped behind the unchanged
- * {@link ICohortThresholdCrypto} port.
- *
- * **Coord-scoped.** `assemble(payload, minSigs)` carries no coord, so the adapter is constructed per
- * served coord (one per {@link import("./host.js").CoordEngine}): it knows the cohort around its coord,
- * the node's peer key (to add self's own signature without an RPC), and a `dialSign` seam over the
- * `/sign` protocol to collect the other members' endorsements.
- *
- * **Verify is synchronous** — `ICohortThresholdCrypto.verify` is called from the sync
- * `CohortSigner.verifyThreshold` on the participant path. {@link verifyCollectedMultisig} splits the
- * blob into `signers.length` 64-byte chunks and {@link verifyPeerSig}-checks each against the
- * corresponding signer's embedded Ed25519 key (noble, sync). Do not make it async.
- */
-
-import type { PrivateKey } from "@libp2p/interface";
-import type { ICohortThresholdCrypto, RingCoord, SignKind, SignReplyV1, SignRequestV1 } from "@optimystic/db-core";
-import { bytesToB64url, b64urlToBytes, compareBytes } from "@optimystic/db-core";
-import { signPeer, verifyPeerSig } from "./peer-sig.js";
-import { bytesToPeerIdString } from "./peer-codec.js";
-
-/** Width of an Ed25519 signature in bytes — the fixed stride of the concatenated `thresholdSig`. */
-export const ED25519_SIG_BYTES = 64;
-
-/** Default per-round deadline for collecting cohort endorsements (ms). */
-export const DEFAULT_SIGN_COLLECT_TIMEOUT_MS = 5_000;
-
-/**
- * Verify a collected Ed25519 multi-signature: `thresholdSig` must be exactly `signers.length × 64`
- * bytes, and chunk `i` must be a valid peer-key signature by `signers[i]` over `payload`. Pure and
- * synchronous; total (returns `false`, never throws). The db-core `CohortSigner.verifyThreshold` layer
- * adds the distinct-signer / `signers ⊆ cert.members` / `≥ minSigs` checks on top of this.
- */
-export function verifyCollectedMultisig(payload: Uint8Array, thresholdSig: Uint8Array, signers: readonly Uint8Array[]): boolean {
-	if (signers.length === 0) {
-		return false;
-	}
-	if (thresholdSig.length !== signers.length * ED25519_SIG_BYTES) {
-		return false;
-	}
-	for (let i = 0; i < signers.length; i++) {
-		const chunk = thresholdSig.subarray(i * ED25519_SIG_BYTES, (i + 1) * ED25519_SIG_BYTES);
-		if (!verifyPeerSig(signers[i]!, payload, chunk)) {
-			return false;
-		}
-	}
-	return true;
-}
-
-/**
- * Dependencies for a coord-scoped {@link FretCohortThresholdCrypto}. The host supplies these per
- * {@link import("./host.js").CoordEngine}; the `kind` selects the endorsement policy the dialed
- * members apply (membership cert vs promotion / demotion notice).
- */
-export interface CohortThresholdCryptoDeps {
-	/** What this signer assembles — sent in each {@link SignRequestV1} so members apply the right policy. */
-	readonly kind: SignKind;
-	/** The node's libp2p Ed25519 private key — signs self's own chunk locally (no RPC to self). */
-	readonly privateKey: PrivateKey;
-	/** Self's dialable member id (UTF-8 of the peer-id string); self is always a signer. */
-	readonly selfMember: Uint8Array;
-	/** The served coord whose cohort threshold-signs. */
-	readonly coord: () => RingCoord;
-	/** Current cohort epoch (raw bytes) for {@link coord}. */
-	readonly cohortEpoch: () => Uint8Array;
-	/** Current cohort member peer-id strings around {@link coord} (self may be included; excluded internally). */
-	readonly cohortMembers: () => string[];
-	/** Dial one cohort member's `/sign` RPC and return its reply. */
-	readonly dialSign: (peerIdStr: string, request: SignRequestV1) => Promise<SignReplyV1>;
-	/** Per-round collection deadline (ms). Default {@link DEFAULT_SIGN_COLLECT_TIMEOUT_MS}. */
-	readonly collectTimeoutMs?: number;
-	/**
-	 * Whether self may contribute its own signature to this assembly. Default `true` (self is always a
-	 * member of the cohort it signs over). The **rotation** producer scopes the assembly to the
-	 * *predecessor* cohort (`cohortMembers` = the prior epoch's members); when self was not a member of
-	 * that prior cohort it must NOT self-sign — its chunk would be dropped by the verifier (a signer not in
-	 * the predecessor cert's `members`), desyncing the count from what the verifier accepts. Returning
-	 * `false` then makes the quorum genuinely the outgoing cohort. See `cohort-topic-trust-anchor-rotation-production`.
-	 */
-	readonly selfEligible?: () => boolean;
-}
-
-/** A collected, verified per-member signature awaiting concatenation. */
-interface CollectedSig {
-	readonly signer: Uint8Array;
-	readonly sig: Uint8Array;
-}
-
-/**
- * Real coord-scoped {@link ICohortThresholdCrypto}. `assemble` signs locally, concurrently dials the
- * rest of the cohort over the `/sign` protocol, verifies each returned signature before counting it,
- * and concatenates `≥ minSigs` distinct signatures into the threshold blob — or throws if a quorum is
- * unreachable (it must **never** fabricate a single-signer sig, the interim bug). `verify` is the pure
- * split-and-check.
- */
-export class FretCohortThresholdCrypto implements ICohortThresholdCrypto {
-	constructor(private readonly deps: CohortThresholdCryptoDeps) {}
-
-	async assemble(payload: Uint8Array, minSigs: number): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }> {
-		const collected = new Map<string, CollectedSig>();
-		const selfStr = bytesToPeerIdString(this.deps.selfMember);
-
-		// Self is normally a signer — it is the acting member, even if a stale table omits it from its own
-		// assembly. Sign locally (no RPC to self). A rotation producer that was NOT in the predecessor cohort
-		// (`selfEligible` → false) skips this: its chunk would be dropped by the verifier (signer ∉ predecessor
-		// cert members), so it must collect a quorum purely from the outgoing cohort instead.
-		if (this.deps.selfEligible?.() ?? true) {
-			const selfSig = await signPeer(this.deps.privateKey, payload);
-			if (selfSig.length !== ED25519_SIG_BYTES) {
-				throw new Error(`cohort threshold sign: self produced a ${selfSig.length}-byte signature (expected ${ED25519_SIG_BYTES}); non-Ed25519 identity?`);
-			}
-			collected.set(bytesToB64url(this.deps.selfMember), { signer: this.deps.selfMember, sig: selfSig });
-		}
-
-		// Concurrently collect endorsements from the rest of the cohort, up to the deadline.
-		const others = this.deps.cohortMembers().filter((m) => m !== selfStr);
-		if (others.length > 0 && collected.size < minSigs) {
-			const request: SignRequestV1 = {
-				v: 1,
-				kind: this.deps.kind,
-				coord: bytesToB64url(this.deps.coord()),
-				cohortEpoch: bytesToB64url(this.deps.cohortEpoch()),
-				payload: bytesToB64url(payload),
-			};
-			const timeoutMs = this.deps.collectTimeoutMs ?? DEFAULT_SIGN_COLLECT_TIMEOUT_MS;
-			await Promise.all(others.map((peerStr) => this.collectFrom(peerStr, request, payload, collected, timeoutMs)));
-		}
-
-		if (collected.size < minSigs) {
-			// Quorum unreachable / unwilling: no notice this round. The promotion / cert path re-fires next
-			// tick. NEVER fabricate a single-signer sig — that is exactly the interim bug this replaces.
-			throw new Error(`cohort threshold sign: gathered ${collected.size} of ${minSigs} required signatures`);
-		}
-
-		// Deterministic order (ascending by signer id) so the concatenation is reproducible and aligns
-		// signers[i] ↔ chunk i for the verifier.
-		const ordered = [...collected.values()].sort((a, b) => compareBytes(a.signer, b.signer));
-		const signers = ordered.map((e) => e.signer);
-		const thresholdSig = concatSigs(ordered.map((e) => e.sig));
-		return { thresholdSig, signers };
-	}
-
-	verify(payload: Uint8Array, thresholdSig: Uint8Array, signers: readonly Uint8Array[]): boolean {
-		return verifyCollectedMultisig(payload, thresholdSig, signers);
-	}
-
-	/** Dial one member, verify-before-count its endorsement, and add it to `collected` (dropping bad/dupe). */
-	private async collectFrom(
-		peerStr: string,
-		request: SignRequestV1,
-		payload: Uint8Array,
-		collected: Map<string, CollectedSig>,
-		timeoutMs: number,
-	): Promise<void> {
-		try {
-			const reply = await withTimeout(this.deps.dialSign(peerStr, request), timeoutMs);
-			if (reply === undefined || "refused" in reply) {
-				return; // unreachable (timed out) or the member declined to endorse
-			}
-			const signerBytes = b64urlToBytes(reply.signer);
-			const sigBytes = b64urlToBytes(reply.signature);
-			if (sigBytes.length !== ED25519_SIG_BYTES) {
-				return; // a malformed chunk would desync the fixed-stride concatenation
-			}
-			// Verify before counting: a member must not be able to poison the blob with a bad signature.
-			if (!verifyPeerSig(signerBytes, payload, sigBytes)) {
-				return;
-			}
-			const key = bytesToB64url(signerBytes);
-			if (collected.has(key)) {
-				return; // a duplicate signer cannot pad the count toward minSigs
-			}
-			collected.set(key, { signer: signerBytes, sig: sigBytes });
-		} catch {
-			// Unreachable member or malformed reply — drop it; collection continues with the rest.
-		}
-	}
-}
-
-/**
- * A verify-only {@link ICohortThresholdCrypto} for the participant-side verifier, which never assembles
- * (it only checks inbound threshold-signed messages). `assemble` rejects so a misuse surfaces loudly
- * rather than fabricating a signature.
- */
-export function createVerifyOnlyThresholdCrypto(): ICohortThresholdCrypto {
-	return {
-		assemble: (): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }> =>
-			Promise.reject(new Error("verify-only cohort threshold crypto cannot assemble signatures")),
-		verify: verifyCollectedMultisig,
-	};
-}
-
-/** Concatenate equal-width signature chunks into one fixed-stride blob aligned with the signer order. */
-function concatSigs(sigs: readonly Uint8Array[]): Uint8Array {
-	const out = new Uint8Array(sigs.length * ED25519_SIG_BYTES);
-	for (let i = 0; i < sigs.length; i++) {
-		out.set(sigs[i]!, i * ED25519_SIG_BYTES);
-	}
-	return out;
-}
-
-/** Resolve `p`, or `undefined` if `timeoutMs` elapses first (bounds wall-clock against an unreachable peer). */
-function withTimeout<T>(p: Promise<T>, timeoutMs: number): Promise<T | undefined> {
-	return new Promise<T | undefined>((resolve) => {
-		let settled = false;
-		const timer = setTimeout(() => {
-			if (!settled) {
-				settled = true;
-				resolve(undefined);
-			}
-		}, timeoutMs);
-		void p.then(
-			(value) => {
-				if (!settled) {
-					settled = true;
-					clearTimeout(timer);
-					resolve(value);
-				}
-			},
-			() => {
-				if (!settled) {
-					settled = true;
-					clearTimeout(timer);
-					resolve(undefined);
-				}
-			},
-		);
-	});
-}
+/**
+ * Cohort-topic `k − x` threshold-signature crypto — real collected Ed25519 multi-signature.
+ *
+ * Closes gap 1 (the interim single-signer `sha256(payload)` digest, which could never satisfy
+ * `CohortSigner.verifyThreshold`'s `≥ minSigs` distinct-member rule at `minSigs = 14`). The scheme is
+ * a **collected multisig**: `thresholdSig` is the aligned concatenation of fixed-width 64-byte Ed25519
+ * signatures, one per `signers[i]`, each produced by that member's libp2p peer key over the *exact*
+ * canonical payload. It needs **no trusted setup, no new crypto dependency, and no aggregation round**
+ * (unlike BLS or FROST), maps directly onto the existing `(thresholdSig, signers)` contract, and reuses
+ * the per-member peer-key signing primitive (`peer-sig.ts`) the codebase already uses for cluster-repo
+ * commit signatures. Size is O(k) (≤ ~14 × 64 = 896 bytes at production `minSigs`) — negligible for
+ * k ≤ 16; if size ever matters at larger k the scheme can be swapped behind the unchanged
+ * {@link ICohortThresholdCrypto} port.
+ *
+ * **Coord-scoped.** `assemble(payload, minSigs)` carries no coord, so the adapter is constructed per
+ * served coord (one per {@link import("./host.js").CoordEngine}): it knows the cohort around its coord,
+ * the node's peer key (to add self's own signature without an RPC), and a `dialSign` seam over the
+ * `/sign` protocol to collect the other members' endorsements.
+ *
+ * **Verify is synchronous** — `ICohortThresholdCrypto.verify` is called from the sync
+ * `CohortSigner.verifyThreshold` on the participant path. {@link verifyCollectedMultisig} splits the
+ * blob into `signers.length` 64-byte chunks and {@link verifyPeerSig}-checks each against the
+ * corresponding signer's embedded Ed25519 key (noble, sync). Do not make it async.
+ */
+
+import type { PrivateKey } from "@libp2p/interface";
+import type { ICohortThresholdCrypto, RingCoord, SignKind, SignReplyV1, SignRequestV1 } from "@optimystic/db-core";
+import { bytesToB64url, b64urlToBytes, compareBytes } from "@optimystic/db-core";
+import { signPeer, verifyPeerSig } from "./peer-sig.js";
+import { bytesToPeerIdString } from "./peer-codec.js";
+
+/** Width of an Ed25519 signature in bytes — the fixed stride of the concatenated `thresholdSig`. */
+export const ED25519_SIG_BYTES = 64;
+
+/** Default per-round deadline for collecting cohort endorsements (ms). */
+export const DEFAULT_SIGN_COLLECT_TIMEOUT_MS = 5_000;
+
+/**
+ * Verify a collected Ed25519 multi-signature: `thresholdSig` must be exactly `signers.length × 64`
+ * bytes, and chunk `i` must be a valid peer-key signature by `signers[i]` over `payload`. Pure and
+ * synchronous; total (returns `false`, never throws). The db-core `CohortSigner.verifyThreshold` layer
+ * adds the distinct-signer / `signers ⊆ cert.members` / `≥ minSigs` checks on top of this.
+ */
+export function verifyCollectedMultisig(payload: Uint8Array, thresholdSig: Uint8Array, signers: readonly Uint8Array[]): boolean {
+	if (signers.length === 0) {
+		return false;
+	}
+	if (thresholdSig.length !== signers.length * ED25519_SIG_BYTES) {
+		return false;
+	}
+	for (let i = 0; i < signers.length; i++) {
+		const chunk = thresholdSig.subarray(i * ED25519_SIG_BYTES, (i + 1) * ED25519_SIG_BYTES);
+		if (!verifyPeerSig(signers[i]!, payload, chunk)) {
+			return false;
+		}
+	}
+	return true;
+}
+
+/**
+ * Dependencies for a coord-scoped {@link FretCohortThresholdCrypto}. The host supplies these per
+ * {@link import("./host.js").CoordEngine}; the `kind` selects the endorsement policy the dialed
+ * members apply (membership cert vs promotion / demotion notice).
+ */
+export interface CohortThresholdCryptoDeps {
+	/** What this signer assembles — sent in each {@link SignRequestV1} so members apply the right policy. */
+	readonly kind: SignKind;
+	/** The node's libp2p Ed25519 private key — signs self's own chunk locally (no RPC to self). */
+	readonly privateKey: PrivateKey;
+	/** Self's dialable member id (UTF-8 of the peer-id string); self is always a signer. */
+	readonly selfMember: Uint8Array;
+	/** The served coord whose cohort threshold-signs. */
+	readonly coord: () => RingCoord;
+	/** Current cohort epoch (raw bytes) for {@link coord}. */
+	readonly cohortEpoch: () => Uint8Array;
+	/** Current cohort member peer-id strings around {@link coord} (self may be included; excluded internally). */
+	readonly cohortMembers: () => string[];
+	/** Dial one cohort member's `/sign` RPC and return its reply. */
+	readonly dialSign: (peerIdStr: string, request: SignRequestV1) => Promise<SignReplyV1>;
+	/** Per-round collection deadline (ms). Default {@link DEFAULT_SIGN_COLLECT_TIMEOUT_MS}. */
+	readonly collectTimeoutMs?: number;
+	/**
+	 * Whether self may contribute its own signature to this assembly. Default `true` (self is always a
+	 * member of the cohort it signs over). The **rotation** producer scopes the assembly to the
+	 * *predecessor* cohort (`cohortMembers` = the prior epoch's members); when self was not a member of
+	 * that prior cohort it must NOT self-sign — its chunk would be dropped by the verifier (a signer not in
+	 * the predecessor cert's `members`), desyncing the count from what the verifier accepts. Returning
+	 * `false` then makes the quorum genuinely the outgoing cohort. See `cohort-topic-trust-anchor-rotation-production`.
+	 */
+	readonly selfEligible?: () => boolean;
+}
+
+/** A collected, verified per-member signature awaiting concatenation. */
+interface CollectedSig {
+	readonly signer: Uint8Array;
+	readonly sig: Uint8Array;
+}
+
+/**
+ * Real coord-scoped {@link ICohortThresholdCrypto}. `assemble` signs locally, concurrently dials the
+ * rest of the cohort over the `/sign` protocol, verifies each returned signature before counting it,
+ * and concatenates `≥ minSigs` distinct signatures into the threshold blob — or throws if a quorum is
+ * unreachable (it must **never** fabricate a single-signer sig, the interim bug). `verify` is the pure
+ * split-and-check.
+ */
+export class FretCohortThresholdCrypto implements ICohortThresholdCrypto {
+	constructor(private readonly deps: CohortThresholdCryptoDeps) {}
+
+	async assemble(payload: Uint8Array, minSigs: number): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }> {
+		const collected = new Map<string, CollectedSig>();
+		const selfStr = bytesToPeerIdString(this.deps.selfMember);
+
+		// Self is normally a signer — it is the acting member, even if a stale table omits it from its own
+		// assembly. Sign locally (no RPC to self). A rotation producer that was NOT in the predecessor cohort
+		// (`selfEligible` → false) skips this: its chunk would be dropped by the verifier (signer ∉ predecessor
+		// cert members), so it must collect a quorum purely from the outgoing cohort instead.
+		if (this.deps.selfEligible?.() ?? true) {
+			const selfSig = await signPeer(this.deps.privateKey, payload);
+			if (selfSig.length !== ED25519_SIG_BYTES) {
+				throw new Error(`cohort threshold sign: self produced a ${selfSig.length}-byte signature (expected ${ED25519_SIG_BYTES}); non-Ed25519 identity?`);
+			}
+			collected.set(bytesToB64url(this.deps.selfMember), { signer: this.deps.selfMember, sig: selfSig });
+		}
+
+		// Concurrently collect endorsements from the rest of the cohort, up to the deadline.
+		const others = this.deps.cohortMembers().filter((m) => m !== selfStr);
+		if (others.length > 0 && collected.size < minSigs) {
+			const request: SignRequestV1 = {
+				v: 1,
+				kind: this.deps.kind,
+				coord: bytesToB64url(this.deps.coord()),
+				cohortEpoch: bytesToB64url(this.deps.cohortEpoch()),
+				payload: bytesToB64url(payload),
+			};
+			const timeoutMs = this.deps.collectTimeoutMs ?? DEFAULT_SIGN_COLLECT_TIMEOUT_MS;
+			await Promise.all(others.map((peerStr) => this.collectFrom(peerStr, request, payload, collected, timeoutMs)));
+		}
+
+		if (collected.size < minSigs) {
+			// Quorum unreachable / unwilling: no notice this round. The promotion / cert path re-fires next
+			// tick. NEVER fabricate a single-signer sig — that is exactly the interim bug this replaces.
+			throw new Error(`cohort threshold sign: gathered ${collected.size} of ${minSigs} required signatures`);
+		}
+
+		// Deterministic order (ascending by signer id) so the concatenation is reproducible and aligns
+		// signers[i] ↔ chunk i for the verifier.
+		const ordered = [...collected.values()].sort((a, b) => compareBytes(a.signer, b.signer));
+		const signers = ordered.map((e) => e.signer);
+		const thresholdSig = concatSigs(ordered.map((e) => e.sig));
+		return { thresholdSig, signers };
+	}
+
+	verify(payload: Uint8Array, thresholdSig: Uint8Array, signers: readonly Uint8Array[]): boolean {
+		return verifyCollectedMultisig(payload, thresholdSig, signers);
+	}
+
+	/** Dial one member, verify-before-count its endorsement, and add it to `collected` (dropping bad/dupe). */
+	private async collectFrom(
+		peerStr: string,
+		request: SignRequestV1,
+		payload: Uint8Array,
+		collected: Map<string, CollectedSig>,
+		timeoutMs: number,
+	): Promise<void> {
+		try {
+			const reply = await withTimeout(this.deps.dialSign(peerStr, request), timeoutMs);
+			if (reply === undefined || "refused" in reply) {
+				return; // unreachable (timed out) or the member declined to endorse
+			}
+			const signerBytes = b64urlToBytes(reply.signer);
+			const sigBytes = b64urlToBytes(reply.signature);
+			if (sigBytes.length !== ED25519_SIG_BYTES) {
+				return; // a malformed chunk would desync the fixed-stride concatenation
+			}
+			// Verify before counting: a member must not be able to poison the blob with a bad signature.
+			if (!verifyPeerSig(signerBytes, payload, sigBytes)) {
+				return;
+			}
+			const key = bytesToB64url(signerBytes);
+			if (collected.has(key)) {
+				return; // a duplicate signer cannot pad the count toward minSigs
+			}
+			collected.set(key, { signer: signerBytes, sig: sigBytes });
+		} catch {
+			// Unreachable member or malformed reply — drop it; collection continues with the rest.
+		}
+	}
+}
+
+/**
+ * A verify-only {@link ICohortThresholdCrypto} for the participant-side verifier, which never assembles
+ * (it only checks inbound threshold-signed messages). `assemble` rejects so a misuse surfaces loudly
+ * rather than fabricating a signature.
+ */
+export function createVerifyOnlyThresholdCrypto(): ICohortThresholdCrypto {
+	return {
+		assemble: (): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }> =>
+			Promise.reject(new Error("verify-only cohort threshold crypto cannot assemble signatures")),
+		verify: verifyCollectedMultisig,
+	};
+}
+
+/** Concatenate equal-width signature chunks into one fixed-stride blob aligned with the signer order. */
+function concatSigs(sigs: readonly Uint8Array[]): Uint8Array {
+	const out = new Uint8Array(sigs.length * ED25519_SIG_BYTES);
+	for (let i = 0; i < sigs.length; i++) {
+		out.set(sigs[i]!, i * ED25519_SIG_BYTES);
+	}
+	return out;
+}
+
+/** Resolve `p`, or `undefined` if `timeoutMs` elapses first (bounds wall-clock against an unreachable peer). */
+function withTimeout<T>(p: Promise<T>, timeoutMs: number): Promise<T | undefined> {
+	return new Promise<T | undefined>((resolve) => {
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (!settled) {
+				settled = true;
+				resolve(undefined);
+			}
+		}, timeoutMs);
+		void p.then(
+			(value) => {
+				if (!settled) {
+					settled = true;
+					clearTimeout(timer);
+					resolve(value);
+				}
+			},
+			() => {
+				if (!settled) {
+					settled = true;
+					clearTimeout(timer);
+					resolve(undefined);
+				}
+			},
+		);
+	});
+}