@optimystic/db-p2p 0.13.5 → 0.14.0

package/src/cohort-topic/index.ts

@@ -0,0 +1,13 @@
+export * from "./protocols.js";
+export * from "./peer-codec.js";
+export * from "./peer-sig.js";
+export * from "./stream-util.js";
+export * from "./topic-router.js";
+export * from "./cohort-gossip-transport.js";
+export * from "./cohort-gossip-driver.js";
+export * from "./membership-source.js";
+export * from "./membership-publish-sink.js";
+export * from "./threshold-crypto.js";
+export * from "./size-estimator.js";
+export * from "./host.js";
+export * from "./change-bridge.js";

package/src/cohort-topic/membership-publish-sink.ts

@@ -0,0 +1,20 @@
+import type { IMembershipPublishSink } from "@optimystic/db-core";
+
+/**
+ * FRET-backed {@link IMembershipPublishSink}: holds the cohort's latest threshold-signed
+ * `MembershipCertV1` (already encoded) and serves it over `/optimystic/cohort-topic/1.0.0/membership`.
+ * A node publishes only its own cohort's cert, so the most-recent encoded cert is all the host's
+ * membership protocol handler needs to answer inbound requests.
+ */
+export class FretMembershipPublishSink implements IMembershipPublishSink {
+	private latestCert: Uint8Array | undefined;
+
+	publish(encodedCert: Uint8Array): void {
+		this.latestCert = encodedCert;
+	}
+
+	/** The most recently published encoded cert, or `undefined` if none yet (host serves this). */
+	latest(): Uint8Array | undefined {
+		return this.latestCert;
+	}
+}

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

@@ -0,0 +1,68 @@
+import type { IMembershipSource, RingCoord } from "@optimystic/db-core";
+import { bytesToB64url } from "@optimystic/db-core";
+import { peerIdFromString } from "@libp2p/peer-id";
+import type { Libp2p } from "libp2p";
+import type { CohortPeerResolver } from "./cohort-gossip-transport.js";
+import { requestResponse, DEFAULT_STREAM_MAX_BYTES } from "./stream-util.js";
+import { PROTOCOL_COHORT_MEMBERSHIP } from "./protocols.js";
+
+export interface FretMembershipSourceOptions {
+	readonly membershipProtocol?: string;
+	/** Cohort fan-out probed on a `fetch`. Default 16. */
+	readonly wants?: number;
+	readonly maxBytes?: number;
+}
+
+/**
+ * FRET-backed {@link IMembershipSource}: cohort membership snapshots over
+ * `/optimystic/cohort-topic/1.0.0/membership`. `current` serves the locally-cached encoded
+ * `MembershipCertV1`; `fetch` forces one refresh by requesting the cert from an assembled cohort
+ * member (the stale-cache retry the participant-side verifier drives). The host feeds inbound certs
+ * into the cache via {@link cache}.
+ */
+export class FretMembershipSource implements IMembershipSource {
+	private readonly byCoord = new Map<string, Uint8Array>();
+	private readonly membershipProtocol: string;
+	private readonly wants: number;
+	private readonly maxBytes: number;
+
+	constructor(private readonly node: Libp2p, private readonly resolver: CohortPeerResolver, options: FretMembershipSourceOptions = {}) {
+		this.membershipProtocol = options.membershipProtocol ?? PROTOCOL_COHORT_MEMBERSHIP;
+		this.wants = options.wants ?? 16;
+		this.maxBytes = options.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+	}
+
+	current(coord: RingCoord): Promise<Uint8Array | undefined> {
+		return Promise.resolve(this.byCoord.get(bytesToB64url(coord)));
+	}
+
+	/**
+	 * Synchronous local existence read over the in-memory cache: true iff a `MembershipCertV1` is cached for
+	 * `coord` (no network I/O). The parent-reference bootstrap-evidence verifier's existence view consults
+	 * this — an admission gate must never dial — so it reads the same `byCoord` map `current()` resolves from.
+	 */
+	has(coord: RingCoord): boolean {
+		return this.byCoord.has(bytesToB64url(coord));
+	}
+
+	async fetch(coord: RingCoord): Promise<Uint8Array | undefined> {
+		const request = coord; // the membership request frame is the raw coord bytes
+		for (const peerStr of this.resolver.cohortPeers(coord, this.wants)) {
+			try {
+				const reply = await requestResponse(this.node, peerIdFromString(peerStr), this.membershipProtocol, request, this.maxBytes);
+				if (reply.length > 0) {
+					this.cache(coord, reply);
+					return reply;
+				}
+			} catch {
+				// Try the next member; a stale-cache refetch tolerates an unreachable holder.
+			}
+		}
+		return undefined;
+	}
+
+	/** Cache an encoded cert for its coord (host feeds inbound/served certs here). */
+	cache(coord: RingCoord, encodedCert: Uint8Array): void {
+		this.byCoord.set(bytesToB64url(coord), encodedCert);
+	}
+}

package/src/cohort-topic/peer-codec.ts

@@ -0,0 +1,31 @@
+/**
+ * Cohort-topic peer-id ↔ bytes bridge.
+ *
+ * db-core's substrate logic references peers as opaque `Uint8Array` ids ({@link PeerRef}`.id`); FRET +
+ * libp2p reference them as `PeerId` / peer-id strings. The cohort-member ids the substrate carries on
+ * the wire (a reply's `primary` / `backups` / `cohortMembers`) must round-trip back to a *dialable*
+ * libp2p peer, so this module pins one unambiguous encoding for them: the UTF-8 bytes of the canonical
+ * peer-id string. (The participant's own addressing coordinate `P` is a separate ring-coord value — see
+ * the host — so this encoding never needs to feed the ring hash.)
+ */
+
+import { peerIdFromString } from "@libp2p/peer-id";
+import type { PeerId } from "@libp2p/interface";
+
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** A cohort-member id as the substrate's opaque bytes: UTF-8 of the canonical peer-id string. */
+export function peerIdToBytes(peerId: PeerId | string): Uint8Array {
+	return utf8Encoder.encode(typeof peerId === "string" ? peerId : peerId.toString());
+}
+
+/** Reverse of {@link peerIdToBytes}: decode member bytes back to the canonical peer-id string. */
+export function bytesToPeerIdString(bytes: Uint8Array): string {
+	return utf8Decoder.decode(bytes);
+}
+
+/** Reverse of {@link peerIdToBytes}: decode member bytes back to a dialable {@link PeerId}. */
+export function bytesToPeerId(bytes: Uint8Array): PeerId {
+	return peerIdFromString(bytesToPeerIdString(bytes));
+}

package/src/cohort-topic/peer-sig.ts

@@ -0,0 +1,86 @@
+/**
+ * Cohort-topic shared Ed25519 sign/verify primitive (libp2p peer keys).
+ *
+ * Mirrors the established peer-key signing pattern in `cluster-repo.ts` / `dispute-service.ts`
+ * (`PrivateKey.sign` → base64url; verify against the peer's public key), specialized for the
+ * cohort-topic substrate:
+ *
+ * - **Signing** uses the node's libp2p `PrivateKey.sign` (async — fine on the participant outbound
+ *   path) and is the seam the threshold-assembly ticket reuses for per-member partial signatures.
+ * - **Verification is SYNCHRONOUS**, because the db-core verify ports (e.g. the participant-signature
+ *   predicates and `ICohortThresholdCrypto.verify`) are synchronous. libp2p's
+ *   `publicKeyFromRaw(raw).verify` is async, so this verifies with `@noble/curves/ed25519` directly
+ *   over the raw 32-byte key. noble's `ed25519.verify` (ZIP215) is a strict superset of the RFC8032
+ *   signatures the libp2p signer (Node/WebCrypto Ed25519) produces, so it accepts them.
+ *
+ * The signer id on the cohort wire is the UTF-8 bytes of the peer-id string (see `peer-codec.ts`).
+ * For an Ed25519 identity the public key is embedded in the identity multihash, so no network lookup
+ * is needed — `peerIdFromString(str).publicKey.raw` yields the raw key. Verification is **total**: any
+ * non-Ed25519 id, missing key, or malformed input returns `false` (it never throws). The cohort-topic
+ * substrate therefore assumes Ed25519 identities (the libp2p default; `generateKeyPair('Ed25519')`).
+ */
+
+import type { PrivateKey } from "@libp2p/interface";
+import { peerIdFromString } from "@libp2p/peer-id";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { bytesToPeerIdString } from "./peer-codec.js";
+
+/** Sign `payload` with the node's libp2p peer key. Async — libp2p `PrivateKey.sign` is async. */
+export async function signPeer(privateKey: PrivateKey, payload: Uint8Array): Promise<Uint8Array> {
+	return privateKey.sign(payload);
+}
+
+/**
+ * Sign `payload` with a libp2p Ed25519 peer key **synchronously** — the mirror of the synchronous
+ * {@link verifyPeerSig}. Use this where the signer seam is synchronous and the async {@link signPeer}
+ * cannot be awaited: e.g. the reactivity recover `signBackfill` / `signResume` `(unsigned) => string`
+ * ports, whose db-core driver builds the unsigned image internally (so a pre-signed value is impossible)
+ * and whose seam shape is `=> string`, not `=> Promise<string>`.
+ *
+ * libp2p's own `PrivateKey.sign` is async (Node / WebCrypto Ed25519), so this signs directly with
+ * `@noble/curves/ed25519` over the raw 32-byte seed. libp2p stores an Ed25519 private key as 64 bytes
+ * (`raw` = 32-byte seed ‖ 32-byte public key); noble's `ed25519.sign(message, secretKey)` takes the
+ * 32-byte seed. noble's signatures are RFC8032-compliant and deterministic, so both verify paths accept
+ * them: the libp2p `publicKeyFromRaw(raw).verify` (Node / WebCrypto) and the synchronous
+ * {@link verifyPeerSig} (noble, ZIP215) — symmetric with the verify direction's cross-acceptance, and
+ * byte-identical to what the async {@link signPeer} would produce for the same key + payload.
+ *
+ * Assumes an Ed25519 identity (the cohort-topic substrate's standing assumption). Throws on a
+ * non-Ed25519 key or an unexpected raw length — a programming error on the node's own key, never
+ * attacker-reachable input (the verify side, by contrast, is total and returns `false`).
+ */
+export function signPeerSig(privateKey: PrivateKey, payload: Uint8Array): Uint8Array {
+	if (privateKey.type !== "Ed25519") {
+		throw new Error(`signPeerSig: expected an Ed25519 private key, got "${privateKey.type}"`);
+	}
+	const raw = privateKey.raw;
+	// 64-byte libp2p form = seed ‖ public key; accept a bare 32-byte seed too.
+	const seed = raw.length === 64 ? raw.subarray(0, 32) : raw;
+	if (seed.length !== 32) {
+		throw new Error(`signPeerSig: expected a 32- or 64-byte Ed25519 raw key, got ${raw.length} bytes`);
+	}
+	return ed25519.sign(payload, seed);
+}
+
+/**
+ * Verify an Ed25519 peer-key signature synchronously. `signer` is the cohort-wire member id — the
+ * UTF-8 bytes of the peer-id string (see {@link bytesToPeerIdString}) — or that peer-id string
+ * directly. Returns `false` (never throws) on a non-Ed25519 id, a missing/short key, a malformed
+ * signature, or any decode failure.
+ */
+export function verifyPeerSig(signer: string | Uint8Array, payload: Uint8Array, sig: Uint8Array): boolean {
+	try {
+		const peerIdStr = typeof signer === "string" ? signer : bytesToPeerIdString(signer);
+		const peerId = peerIdFromString(peerIdStr);
+		if (peerId.type !== "Ed25519" || peerId.publicKey === undefined) {
+			return false;
+		}
+		const rawPub = peerId.publicKey.raw;
+		if (rawPub.length !== 32) {
+			return false;
+		}
+		return ed25519.verify(sig, payload, rawPub);
+	} catch {
+		return false;
+	}
+}

package/src/cohort-topic/protocols.ts

@@ -0,0 +1,71 @@
+/**
+ * Cohort-topic libp2p protocol IDs (`docs/cohort-topic.md` §FRET integration L432-460).
+ *
+ * Five protocols ride the same FRET/libp2p node:
+ *
+ * - `register`      — Register, renew, re-attach (`RegisterV1` / `RenewV1`, routed via `RouteAndMaybeAct`).
+ * - `cohort-gossip` — record replication, willingness, load barometers (`CohortGossipV1`).
+ * - `promote`       — threshold-signed promotion / demotion notices.
+ * - `membership`    — membership certificates (`MembershipCertV1`).
+ * - `sign`          — intra-cohort per-member endorsement for `k − x` threshold-signature assembly
+ *                     (`SignRequestV1` / `SignReplyV1`); a member collecting a threshold signature dials
+ *                     each cohort member here and concatenates the returned per-member Ed25519 sigs.
+ *
+ * The default (network-agnostic) IDs match the doc verbatim; {@link makeCohortTopicProtocols}
+ * mirrors FRET's `makeProtocols(networkName)` so a named network namespaces its cohort-topic
+ * protocols the same way FRET namespaces its routing protocols.
+ */
+
+/** Base path for the cohort-topic protocol family. */
+export const COHORT_TOPIC_BASE = "/optimystic/cohort-topic/1.0.0" as const;
+
+/** `RegisterV1` / `RenewV1` — register, renew, re-attach. */
+export const PROTOCOL_COHORT_REGISTER = `${COHORT_TOPIC_BASE}/register` as const;
+/** `CohortGossipV1` — record replication, willingness, load barometers. */
+export const PROTOCOL_COHORT_GOSSIP = `${COHORT_TOPIC_BASE}/cohort-gossip` as const;
+/** Threshold-signed promotion / demotion notices. */
+export const PROTOCOL_COHORT_PROMOTE = `${COHORT_TOPIC_BASE}/promote` as const;
+/** `MembershipCertV1` — membership certificates. */
+export const PROTOCOL_COHORT_MEMBERSHIP = `${COHORT_TOPIC_BASE}/membership` as const;
+/** `SignRequestV1` / `SignReplyV1` — intra-cohort per-member endorsement for threshold-signature assembly. */
+export const PROTOCOL_COHORT_SIGN = `${COHORT_TOPIC_BASE}/sign` as const;
+
+/** The five cohort-topic protocol IDs in registration order. */
+export interface CohortTopicProtocols {
+	readonly register: string;
+	readonly gossip: string;
+	readonly promote: string;
+	readonly membership: string;
+	readonly sign: string;
+}
+
+/** Default (network-agnostic) protocol IDs, matching `docs/cohort-topic.md` §FRET integration. */
+export const DEFAULT_COHORT_TOPIC_PROTOCOLS: CohortTopicProtocols = {
+	register: PROTOCOL_COHORT_REGISTER,
+	gossip: PROTOCOL_COHORT_GOSSIP,
+	promote: PROTOCOL_COHORT_PROMOTE,
+	membership: PROTOCOL_COHORT_MEMBERSHIP,
+	sign: PROTOCOL_COHORT_SIGN,
+};
+
+/**
+ * Namespaced cohort-topic protocol IDs for `networkName` (mirrors FRET's `makeProtocols`, which
+ * inserts the network segment even for `"default"` → `/optimystic/default/...`). Note this does NOT
+ * equal {@link DEFAULT_COHORT_TOPIC_PROTOCOLS}: the canonical, network-agnostic IDs omit the segment
+ * entirely (`/optimystic/cohort-topic/1.0.0/...`); use those unless you need per-network namespacing.
+ */
+export function makeCohortTopicProtocols(networkName = "default"): CohortTopicProtocols {
+	const base = `/optimystic/${networkName}/cohort-topic/1.0.0`;
+	return {
+		register: `${base}/register`,
+		gossip: `${base}/cohort-gossip`,
+		promote: `${base}/promote`,
+		membership: `${base}/membership`,
+		sign: `${base}/sign`,
+	};
+}
+
+/** All five protocol IDs as an array (for `node.handle` / `unhandle` over the set). */
+export function cohortTopicProtocolList(p: CohortTopicProtocols): string[] {
+	return [p.register, p.gossip, p.promote, p.membership, p.sign];
+}

package/src/cohort-topic/reactivity-membership-gate.ts

@@ -0,0 +1,77 @@
+/**
+ * Reactivity origination membership gate (`docs/reactivity.md` §Anchor, `docs/internals.md`
+ * §Cohort-Topic Origination Bridge).
+ *
+ * Builds the `selfIsCohortMember(event)` predicate the change-notifier bridge gates each member commit
+ * on: this node is responsible for a collection's reactivity-topic fan-out iff it sits in the FRET
+ * cohort around `coord_0(H(currentTailId ‖ "reactivity"))`. The tail comes from `event.tailId` (the seam
+ * ticket put the committed `CommitRequest.tailId` on the change event), so the decision is synchronous —
+ * no async storage read, no per-collection registry. A tail-less event (a read-driven promotion) is
+ * never a member; those never originate and are cert-gated out downstream anyway.
+ *
+ * Extracted from the node assembly so the encoding + coord derivation are unit-testable in isolation and
+ * reusable by the future reactivity origination wiring.
+ */
+
+import {
+	createReactivityTopicAnchor,
+	createTierAddressing,
+	createRingHash,
+	type ReactivityTopicAnchor,
+	type TierAddressing,
+	type CollectionChangeEvent,
+} from "@optimystic/db-core";
+import type { FretService } from "p2p-fret";
+
+// The pinned `BlockId` → raw tail-bytes encoding now lives in the reactivity surface so the origination
+// gate (here) and the subscriber-side subscribe factory import the SAME function — see `reactivity/
+// topic-bytes.ts` for the load-bearing rationale. Re-exported so this module's existing callers (tests,
+// node wiring) keep importing `reactivityTailBytes` from the gate.
+export { reactivityTailBytes } from "../reactivity/topic-bytes.js";
+import { reactivityTailBytes } from "../reactivity/topic-bytes.js";
+
+/** Construction inputs for {@link createReactivitySelfMembershipGate}. */
+export interface ReactivitySelfMembershipGateDeps {
+	/** FRET membership read — the cohort assembler around a served coord (returns peer-id strings). */
+	readonly fret: Pick<FretService, "assembleCohort">;
+	/** This node's peer-id string, compared against the assembled cohort. */
+	readonly selfPeerId: string;
+	/**
+	 * Requested cohort size `wantK`. MUST equal the cohort-topic host's `wantK`, so the gate checks the
+	 * exact cohort the host serves; a mismatch silently breaks origination.
+	 */
+	readonly wantK: number;
+	/**
+	 * Reactivity topic anchor. Default db-core's {@link createReactivityTopicAnchor} (256-bit SHA-256),
+	 * byte-identical to the host's internal `new RingHash()` and the subscriber-side anchor.
+	 */
+	readonly anchor?: ReactivityTopicAnchor;
+	/**
+	 * Tier addressing. Default `createTierAddressing(createRingHash())`. `coord_0` is fan-out independent
+	 * (`H(0x00 ‖ topicId)`), so the default fan-out is irrelevant to the tier-0 reactivity coord.
+	 */
+	readonly addressing?: TierAddressing;
+}
+
+/**
+ * Build the synchronous `selfIsCohortMember(event)` gate for {@link attachCohortChangeBridge}.
+ *
+ * Returns `false` for a tail-less event; otherwise resolves `coord_0(H(event.tailId ‖ "reactivity"))`
+ * via the shared anchor + tier addressing and returns whether `fret.assembleCohort(coord, wantK)`
+ * includes this node's peer id. Pure aside from the live FRET read; membership churn between commits is
+ * fine because reactivity is hint-only.
+ */
+export function createReactivitySelfMembershipGate(
+	deps: ReactivitySelfMembershipGateDeps,
+): (event: CollectionChangeEvent) => boolean {
+	const anchor = deps.anchor ?? createReactivityTopicAnchor();
+	const addressing = deps.addressing ?? createTierAddressing(createRingHash());
+	return (event: CollectionChangeEvent): boolean => {
+		if (event.tailId === undefined) {
+			return false; // promotion / tail-less event never originates
+		}
+		const topicId = anchor.topicId(reactivityTailBytes(event.tailId));
+		const coord = addressing.coord0(topicId);
+		return deps.fret.assembleCohort(coord, deps.wantK).includes(deps.selfPeerId);
+	};
+}

package/src/cohort-topic/size-estimator.ts

@@ -0,0 +1,16 @@
+import type { ISizeEstimator } from "@optimystic/db-core";
+import type { FretService } from "p2p-fret";
+
+/**
+ * FRET-backed {@link ISizeEstimator}: feeds `d_max` from FRET's network-size estimate
+ * (`FretService.getNetworkSizeEstimate`). A clean, total binding — db-core's `d_max` computer applies
+ * the low-confidence clamp itself, so this adapter only forwards FRET's `(size_estimate, confidence)`.
+ */
+export class FretSizeEstimator implements ISizeEstimator {
+	constructor(private readonly fret: FretService) {}
+
+	estimate(): { nEst: number; confidence: number } {
+		const { size_estimate, confidence } = this.fret.getNetworkSizeEstimate();
+		return { nEst: size_estimate, confidence };
+	}
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Cohort-topic libp2p stream helpers.
+ *
+ * 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.
+ */
+
+import type { Libp2p } from "libp2p";
+import type { Connection, PeerId, Stream } from "@libp2p/interface";
+import { readAllBounded } 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. */
+export async function requestResponse(
+	node: Libp2p,
+	peer: PeerId,
+	protocol: string,
+	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);
+		await stream.close();
+		return await readAllBounded(stream, maxBytes);
+	} finally {
+		if (stream != null) {
+			try {
+				await stream.close();
+			} catch {
+				/* already closed */
+			}
+		}
+	}
+}
+
+/** 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);
+		await stream.close();
+	} finally {
+		if (stream != null) {
+			try {
+				await stream.close();
+			} catch {
+				/* already closed */
+			}
+		}
+	}
+}
+
+/** Register a request/response handler for `protocol`: read one bounded frame, reply with one frame. */
+export function handleRequestResponse(
+	node: Libp2p,
+	protocol: string,
+	handle: (frame: Uint8Array, from: PeerId) => Promise<Uint8Array | undefined>,
+	maxBytes = DEFAULT_STREAM_MAX_BYTES,
+): void {
+	void node.handle(protocol, (stream: Stream, connection: Connection) => {
+		void (async (): Promise<void> => {
+			try {
+				const frame = await readAllBounded(stream, maxBytes);
+				const reply = await handle(frame, connection.remotePeer);
+				if (reply !== undefined) {
+					stream.send(reply);
+				}
+				await stream.close();
+			} catch {
+				try {
+					stream.abort(new Error("cohort-topic stream handler error"));
+				} catch {
+					/* already aborted */
+				}
+			}
+		})();
+	});
+}