@optimystic/db-p2p 0.21.0 → 0.24.0

package/src/cluster/commit-cert.ts

@@ -1,139 +1,139 @@
-import type { ActionId, ClusterRecord, CollectionChangeEvent, CommitCert } from "@optimystic/db-core";
-import { fromString as uint8ArrayFromString } from 'uint8arrays';
-import { createLogger } from "../logger.js";
-
-const log = createLogger('commit-cert');
-
-/**
- * Build the {@link CommitCert} for a consensus-committed action from its {@link ClusterRecord}.
- *
- * The threshold signature is the cluster's `approve` **commit** signatures — the per-member Ed25519
- * commit votes the cohort already produced over the commit hash — concatenated in ascending
- * signer-id order, so the blob is reproducible and `signers[i]` aligns with chunk `i` (the
- * collected-multisig convention the cohort-topic verifier uses). This is the **authoritative**
- * commit cert: reactivity reuses these exact bytes as a notification's signature and never re-signs.
- *
- * `signedPayload` is the exact byte preimage every approving member signed — the cluster commit-vote
- * payload `utf8(commitHash + ":approve")`, identical across signers. The caller supplies it (this stays
- * pure and does **not** recompute the commit hash, since the canonical-JSON helper that derives it is
- * private to `ClusterMember` and duplicating it here risks drift). Reactivity sets a notification's
- * `digest` to base64url(signedPayload) so a subscriber's threshold-verify over `digest` reproduces the
- * exact signed image. Pure.
- */
-export function buildCommitCert(record: ClusterRecord, minSigs: number, signedPayload: Uint8Array): CommitCert {
-	const approvals = Object.entries(record.commits)
-		.filter(([, sig]) => sig.type === 'approve')
-		.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-	const signers = approvals.map(([peerId]) => peerId);
-	const thresholdSig = concatBytes(approvals.map(([, sig]) => uint8ArrayFromString(sig.signature, 'base64url')));
-	return { thresholdSig, signers, minSigs, signedPayload };
-}
-
-/**
- * The deterministic change-event/notification `actionId` for a durable invalidation, derived from the
- * `(invalidatedActionId, disputeId)` pair that uniquely identifies the reversal. An invalidation has no
- * transaction `actionId` of its own (it reverses one), but reactivity keys both the captured commit cert
- * and the emitted {@link CollectionChangeEvent} by an `actionId` so the bridge's cert extractor can
- * resolve the reused cert. Both the cluster member's cert capture and the invalidation-apply sink that
- * emits the change event derive this same id from the same pair, closing the loop. Distinct from the
- * per-block deterministic revert `actionId` in `dispute/invalidation.ts` (which also carries blockId+rev);
- * this is the single transaction-level id for the whole reversal.
- */
-export function invalidationActionId(invalidatedActionId: ActionId, disputeId: string): ActionId {
-	return `inv:${invalidatedActionId}:${disputeId}`;
-}
-
-function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
-	const total = parts.reduce((n, p) => n + p.length, 0);
-	const out = new Uint8Array(total);
-	let offset = 0;
-	for (const part of parts) {
-		out.set(part, offset);
-		offset += part.length;
-	}
-	return out;
-}
-
-/** Default retention for a captured commit cert — long enough for the post-commit change event to
- * resolve it, short enough that the store stays bounded under sustained commit load. */
-export const DEFAULT_COMMIT_CERT_TTL_MS = 60_000;
-
-/** Default cap on retained certs — a backstop against unbounded growth if commits ever stop emitting. */
-export const DEFAULT_COMMIT_CERT_MAX_ENTRIES = 4096;
-
-/**
- * Bounded, TTL'd cache of recently-committed {@link CommitCert}s keyed by `actionId`. The cluster
- * member records a cert here just before consensus applies the commit to local storage; the
- * change-notifier bridge's extractor reads it when the StorageRepo emits the matching
- * {@link CollectionChangeEvent}. Both happen on the same node within one commit, so the window is
- * tiny — but a TTL + cap keep the map from leaking if a commit ever lands without emitting a change
- * event (e.g. an idempotent re-commit, or a path with no catch-all subscriber).
- */
-export interface CommitCertStore {
-	/** Record `cert` for `actionId` (overwrites any prior entry). `now` is unix ms (injectable for tests). */
-	put(actionId: ActionId, cert: CommitCert, now?: number): void;
-	/** The cert for `actionId` if still retained, else `undefined`. */
-	get(actionId: ActionId, now?: number): CommitCert | undefined;
-}
-
-export interface CommitCertStoreOptions {
-	/** Retention per entry (ms). Default {@link DEFAULT_COMMIT_CERT_TTL_MS}. */
-	readonly ttlMs?: number;
-	/** Maximum retained entries (oldest evicted first). Default {@link DEFAULT_COMMIT_CERT_MAX_ENTRIES}. */
-	readonly maxEntries?: number;
-}
-
-/** Build an in-memory {@link CommitCertStore} (insertion-ordered Map → recency for eviction). */
-export function createCommitCertStore(options: CommitCertStoreOptions = {}): CommitCertStore {
-	const ttlMs = options.ttlMs ?? DEFAULT_COMMIT_CERT_TTL_MS;
-	const maxEntries = options.maxEntries ?? DEFAULT_COMMIT_CERT_MAX_ENTRIES;
-	const entries = new Map<ActionId, { cert: CommitCert; expiresAt: number }>();
-
-	const dropExpired = (now: number): void => {
-		for (const [actionId, entry] of entries) {
-			if (entry.expiresAt <= now) {
-				entries.delete(actionId);
-			}
-		}
-	};
-
-	return {
-		put(actionId, cert, now = Date.now()): void {
-			dropExpired(now);
-			// Re-insert so a refreshed key moves to the most-recent end (Map preserves insertion order).
-			entries.delete(actionId);
-			entries.set(actionId, { cert, expiresAt: now + ttlMs });
-			while (entries.size > maxEntries) {
-				const oldest = entries.keys().next().value;
-				if (oldest === undefined) break;
-				entries.delete(oldest);
-			}
-		},
-		get(actionId, now = Date.now()): CommitCert | undefined {
-			const entry = entries.get(actionId);
-			if (!entry) {
-				return undefined;
-			}
-			if (entry.expiresAt <= now) {
-				entries.delete(actionId);
-				return undefined;
-			}
-			return entry.cert;
-		},
-	};
-}
-
-/**
- * The bridge's `extractCommitCert` over a {@link CommitCertStore}: resolve a change event's committed
- * action to the cluster commit cert captured for it. Returns `undefined` (logged) when no cert is
- * retained — the bridge then skips origination rather than fabricating an unsigned notification.
- */
-export function makeClusterCommitCertExtractor(store: CommitCertStore): (event: CollectionChangeEvent) => CommitCert | undefined {
-	return (event) => {
-		const cert = store.get(event.actionId);
-		if (!cert) {
-			log('no commit cert retained for actionId=%s (collection=%s rev=%d); skipping origination', event.actionId, event.collectionId, event.rev);
-		}
-		return cert;
-	};
-}
+import type { ActionId, ClusterRecord, CollectionChangeEvent, CommitCert } from "@optimystic/db-core";
+import { fromString as uint8ArrayFromString } from 'uint8arrays';
+import { createLogger } from "../logger.js";
+
+const log = createLogger('commit-cert');
+
+/**
+ * Build the {@link CommitCert} for a consensus-committed action from its {@link ClusterRecord}.
+ *
+ * The threshold signature is the cluster's `approve` **commit** signatures — the per-member Ed25519
+ * commit votes the cohort already produced over the commit hash — concatenated in ascending
+ * signer-id order, so the blob is reproducible and `signers[i]` aligns with chunk `i` (the
+ * collected-multisig convention the cohort-topic verifier uses). This is the **authoritative**
+ * commit cert: reactivity reuses these exact bytes as a notification's signature and never re-signs.
+ *
+ * `signedPayload` is the exact byte preimage every approving member signed — the cluster commit-vote
+ * payload `utf8(commitHash + ":approve")`, identical across signers. The caller supplies it (this stays
+ * pure and does **not** recompute the commit hash, since the canonical-JSON helper that derives it is
+ * private to `ClusterMember` and duplicating it here risks drift). Reactivity sets a notification's
+ * `digest` to base64url(signedPayload) so a subscriber's threshold-verify over `digest` reproduces the
+ * exact signed image. Pure.
+ */
+export function buildCommitCert(record: ClusterRecord, minSigs: number, signedPayload: Uint8Array): CommitCert {
+	const approvals = Object.entries(record.commits)
+		.filter(([, sig]) => sig.type === 'approve')
+		.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+	const signers = approvals.map(([peerId]) => peerId);
+	const thresholdSig = concatBytes(approvals.map(([, sig]) => uint8ArrayFromString(sig.signature, 'base64url')));
+	return { thresholdSig, signers, minSigs, signedPayload };
+}
+
+/**
+ * The deterministic change-event/notification `actionId` for a durable invalidation, derived from the
+ * `(invalidatedActionId, disputeId)` pair that uniquely identifies the reversal. An invalidation has no
+ * transaction `actionId` of its own (it reverses one), but reactivity keys both the captured commit cert
+ * and the emitted {@link CollectionChangeEvent} by an `actionId` so the bridge's cert extractor can
+ * resolve the reused cert. Both the cluster member's cert capture and the invalidation-apply sink that
+ * emits the change event derive this same id from the same pair, closing the loop. Distinct from the
+ * per-block deterministic revert `actionId` in `dispute/invalidation.ts` (which also carries blockId+rev);
+ * this is the single transaction-level id for the whole reversal.
+ */
+export function invalidationActionId(invalidatedActionId: ActionId, disputeId: string): ActionId {
+	return `inv:${invalidatedActionId}:${disputeId}`;
+}
+
+function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
+	const total = parts.reduce((n, p) => n + p.length, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+
+/** Default retention for a captured commit cert — long enough for the post-commit change event to
+ * resolve it, short enough that the store stays bounded under sustained commit load. */
+export const DEFAULT_COMMIT_CERT_TTL_MS = 60_000;
+
+/** Default cap on retained certs — a backstop against unbounded growth if commits ever stop emitting. */
+export const DEFAULT_COMMIT_CERT_MAX_ENTRIES = 4096;
+
+/**
+ * Bounded, TTL'd cache of recently-committed {@link CommitCert}s keyed by `actionId`. The cluster
+ * member records a cert here just before consensus applies the commit to local storage; the
+ * change-notifier bridge's extractor reads it when the StorageRepo emits the matching
+ * {@link CollectionChangeEvent}. Both happen on the same node within one commit, so the window is
+ * tiny — but a TTL + cap keep the map from leaking if a commit ever lands without emitting a change
+ * event (e.g. an idempotent re-commit, or a path with no catch-all subscriber).
+ */
+export interface CommitCertStore {
+	/** Record `cert` for `actionId` (overwrites any prior entry). `now` is unix ms (injectable for tests). */
+	put(actionId: ActionId, cert: CommitCert, now?: number): void;
+	/** The cert for `actionId` if still retained, else `undefined`. */
+	get(actionId: ActionId, now?: number): CommitCert | undefined;
+}
+
+export interface CommitCertStoreOptions {
+	/** Retention per entry (ms). Default {@link DEFAULT_COMMIT_CERT_TTL_MS}. */
+	readonly ttlMs?: number;
+	/** Maximum retained entries (oldest evicted first). Default {@link DEFAULT_COMMIT_CERT_MAX_ENTRIES}. */
+	readonly maxEntries?: number;
+}
+
+/** Build an in-memory {@link CommitCertStore} (insertion-ordered Map → recency for eviction). */
+export function createCommitCertStore(options: CommitCertStoreOptions = {}): CommitCertStore {
+	const ttlMs = options.ttlMs ?? DEFAULT_COMMIT_CERT_TTL_MS;
+	const maxEntries = options.maxEntries ?? DEFAULT_COMMIT_CERT_MAX_ENTRIES;
+	const entries = new Map<ActionId, { cert: CommitCert; expiresAt: number }>();
+
+	const dropExpired = (now: number): void => {
+		for (const [actionId, entry] of entries) {
+			if (entry.expiresAt <= now) {
+				entries.delete(actionId);
+			}
+		}
+	};
+
+	return {
+		put(actionId, cert, now = Date.now()): void {
+			dropExpired(now);
+			// Re-insert so a refreshed key moves to the most-recent end (Map preserves insertion order).
+			entries.delete(actionId);
+			entries.set(actionId, { cert, expiresAt: now + ttlMs });
+			while (entries.size > maxEntries) {
+				const oldest = entries.keys().next().value;
+				if (oldest === undefined) break;
+				entries.delete(oldest);
+			}
+		},
+		get(actionId, now = Date.now()): CommitCert | undefined {
+			const entry = entries.get(actionId);
+			if (!entry) {
+				return undefined;
+			}
+			if (entry.expiresAt <= now) {
+				entries.delete(actionId);
+				return undefined;
+			}
+			return entry.cert;
+		},
+	};
+}
+
+/**
+ * The bridge's `extractCommitCert` over a {@link CommitCertStore}: resolve a change event's committed
+ * action to the cluster commit cert captured for it. Returns `undefined` (logged) when no cert is
+ * retained — the bridge then skips origination rather than fabricating an unsigned notification.
+ */
+export function makeClusterCommitCertExtractor(store: CommitCertStore): (event: CollectionChangeEvent) => CommitCert | undefined {
+	return (event) => {
+		const cert = store.get(event.actionId);
+		if (!cert) {
+			log('no commit cert retained for actionId=%s (collection=%s rev=%d); skipping origination', event.actionId, event.collectionId, event.rev);
+		}
+		return cert;
+	};
+}

package/src/cluster/i-transaction-state-store.ts

@@ -1,43 +1,43 @@
-import type { ClusterRecord } from "@optimystic/db-core";
-
-/** Serializable coordinator transaction state (excludes timers, Pending wrapper) */
-export interface PersistedCoordinatorState {
-	messageHash: string;
-	record: ClusterRecord;
-	lastUpdate: number;
-	/** Which phase was reached when last persisted */
-	phase: 'promising' | 'committing' | 'broadcasting';
-	/** Retry state for commit broadcast failures (excludes timer) */
-	retryState?: {
-		pendingPeers: string[];
-		attempt: number;
-		intervalMs: number;
-	};
-}
-
-/** Serializable participant transaction state (excludes timers) */
-export interface PersistedParticipantState {
-	messageHash: string;
-	record: ClusterRecord;
-	lastUpdate: number;
-}
-
-/** Platform-agnostic store for persisting 2PC transaction state. */
-export interface ITransactionStateStore {
-	// --- Coordinator state (keyed by messageHash) ---
-	saveCoordinatorState(messageHash: string, state: PersistedCoordinatorState): Promise<void>;
-	getCoordinatorState(messageHash: string): Promise<PersistedCoordinatorState | undefined>;
-	deleteCoordinatorState(messageHash: string): Promise<void>;
-	getAllCoordinatorStates(): Promise<PersistedCoordinatorState[]>;
-
-	// --- Participant state (keyed by messageHash) ---
-	saveParticipantState(messageHash: string, state: PersistedParticipantState): Promise<void>;
-	getParticipantState(messageHash: string): Promise<PersistedParticipantState | undefined>;
-	deleteParticipantState(messageHash: string): Promise<void>;
-	getAllParticipantStates(): Promise<PersistedParticipantState[]>;
-
-	// --- Executed transaction dedup guard ---
-	markExecuted(messageHash: string, timestamp: number): Promise<void>;
-	wasExecuted(messageHash: string): Promise<boolean>;
-	pruneExecuted(olderThan: number): Promise<void>;
-}
+import type { ClusterRecord } from "@optimystic/db-core";
+
+/** Serializable coordinator transaction state (excludes timers, Pending wrapper) */
+export interface PersistedCoordinatorState {
+	messageHash: string;
+	record: ClusterRecord;
+	lastUpdate: number;
+	/** Which phase was reached when last persisted */
+	phase: 'promising' | 'committing' | 'broadcasting';
+	/** Retry state for commit broadcast failures (excludes timer) */
+	retryState?: {
+		pendingPeers: string[];
+		attempt: number;
+		intervalMs: number;
+	};
+}
+
+/** Serializable participant transaction state (excludes timers) */
+export interface PersistedParticipantState {
+	messageHash: string;
+	record: ClusterRecord;
+	lastUpdate: number;
+}
+
+/** Platform-agnostic store for persisting 2PC transaction state. */
+export interface ITransactionStateStore {
+	// --- Coordinator state (keyed by messageHash) ---
+	saveCoordinatorState(messageHash: string, state: PersistedCoordinatorState): Promise<void>;
+	getCoordinatorState(messageHash: string): Promise<PersistedCoordinatorState | undefined>;
+	deleteCoordinatorState(messageHash: string): Promise<void>;
+	getAllCoordinatorStates(): Promise<PersistedCoordinatorState[]>;
+
+	// --- Participant state (keyed by messageHash) ---
+	saveParticipantState(messageHash: string, state: PersistedParticipantState): Promise<void>;
+	getParticipantState(messageHash: string): Promise<PersistedParticipantState | undefined>;
+	deleteParticipantState(messageHash: string): Promise<void>;
+	getAllParticipantStates(): Promise<PersistedParticipantState[]>;
+
+	// --- Executed transaction dedup guard ---
+	markExecuted(messageHash: string, timestamp: number): Promise<void>;
+	wasExecuted(messageHash: string): Promise<boolean>;
+	pruneExecuted(olderThan: number): Promise<void>;
+}

package/src/cluster/memory-transaction-state-store.ts

@@ -1,56 +1,56 @@
-import type { ITransactionStateStore, PersistedCoordinatorState, PersistedParticipantState } from "./i-transaction-state-store.js";
-
-/** In-memory ITransactionStateStore. Default when no persistent store is injected. */
-export class MemoryTransactionStateStore implements ITransactionStateStore {
-	private readonly coordinatorStates = new Map<string, PersistedCoordinatorState>();
-	private readonly participantStates = new Map<string, PersistedParticipantState>();
-	private readonly executedMap = new Map<string, number>();
-
-	async saveCoordinatorState(messageHash: string, state: PersistedCoordinatorState): Promise<void> {
-		this.coordinatorStates.set(messageHash, state);
-	}
-
-	async getCoordinatorState(messageHash: string): Promise<PersistedCoordinatorState | undefined> {
-		return this.coordinatorStates.get(messageHash);
-	}
-
-	async deleteCoordinatorState(messageHash: string): Promise<void> {
-		this.coordinatorStates.delete(messageHash);
-	}
-
-	async getAllCoordinatorStates(): Promise<PersistedCoordinatorState[]> {
-		return Array.from(this.coordinatorStates.values());
-	}
-
-	async saveParticipantState(messageHash: string, state: PersistedParticipantState): Promise<void> {
-		this.participantStates.set(messageHash, state);
-	}
-
-	async getParticipantState(messageHash: string): Promise<PersistedParticipantState | undefined> {
-		return this.participantStates.get(messageHash);
-	}
-
-	async deleteParticipantState(messageHash: string): Promise<void> {
-		this.participantStates.delete(messageHash);
-	}
-
-	async getAllParticipantStates(): Promise<PersistedParticipantState[]> {
-		return Array.from(this.participantStates.values());
-	}
-
-	async markExecuted(messageHash: string, timestamp: number): Promise<void> {
-		this.executedMap.set(messageHash, timestamp);
-	}
-
-	async wasExecuted(messageHash: string): Promise<boolean> {
-		return this.executedMap.has(messageHash);
-	}
-
-	async pruneExecuted(olderThan: number): Promise<void> {
-		for (const [hash, ts] of this.executedMap) {
-			if (ts < olderThan) {
-				this.executedMap.delete(hash);
-			}
-		}
-	}
-}
+import type { ITransactionStateStore, PersistedCoordinatorState, PersistedParticipantState } from "./i-transaction-state-store.js";
+
+/** In-memory ITransactionStateStore. Default when no persistent store is injected. */
+export class MemoryTransactionStateStore implements ITransactionStateStore {
+	private readonly coordinatorStates = new Map<string, PersistedCoordinatorState>();
+	private readonly participantStates = new Map<string, PersistedParticipantState>();
+	private readonly executedMap = new Map<string, number>();
+
+	async saveCoordinatorState(messageHash: string, state: PersistedCoordinatorState): Promise<void> {
+		this.coordinatorStates.set(messageHash, state);
+	}
+
+	async getCoordinatorState(messageHash: string): Promise<PersistedCoordinatorState | undefined> {
+		return this.coordinatorStates.get(messageHash);
+	}
+
+	async deleteCoordinatorState(messageHash: string): Promise<void> {
+		this.coordinatorStates.delete(messageHash);
+	}
+
+	async getAllCoordinatorStates(): Promise<PersistedCoordinatorState[]> {
+		return Array.from(this.coordinatorStates.values());
+	}
+
+	async saveParticipantState(messageHash: string, state: PersistedParticipantState): Promise<void> {
+		this.participantStates.set(messageHash, state);
+	}
+
+	async getParticipantState(messageHash: string): Promise<PersistedParticipantState | undefined> {
+		return this.participantStates.get(messageHash);
+	}
+
+	async deleteParticipantState(messageHash: string): Promise<void> {
+		this.participantStates.delete(messageHash);
+	}
+
+	async getAllParticipantStates(): Promise<PersistedParticipantState[]> {
+		return Array.from(this.participantStates.values());
+	}
+
+	async markExecuted(messageHash: string, timestamp: number): Promise<void> {
+		this.executedMap.set(messageHash, timestamp);
+	}
+
+	async wasExecuted(messageHash: string): Promise<boolean> {
+		return this.executedMap.has(messageHash);
+	}
+
+	async pruneExecuted(olderThan: number): Promise<void> {
+		for (const [hash, ts] of this.executedMap) {
+			if (ts < olderThan) {
+				this.executedMap.delete(hash);
+			}
+		}
+	}
+}

package/src/cluster/peer-key-binding.ts

@@ -1,37 +1,37 @@
-/**
- * Key ↔ peer-id binding predicate for the cluster/dispute vote paths.
- *
- * For a libp2p Ed25519 identity the peer-id **is** the multihash of the public key, so a public key
- * that a record self-asserts for a peer id can be checked against the id itself — no network lookup.
- * Both the cluster two-phase-commit path (`cluster-repo.ts`) and the dispute path (`dispute-service.ts`)
- * read a signing key straight from the record they are handed; without this check a coordinator could
- * attach a key it controls under an honest peer's id and have a forged vote verify. This predicate is
- * the gate that ties a self-asserted key back to the identity it claims.
- *
- * Mirrors the binding logic already used by the cohort-topic substrate in `cohort-topic/peer-sig.ts`
- * (`peerIdFromString(str).publicKey.raw`); intentionally NOT importing that module, which is
- * specialized for its own wire encoding.
- *
- * NOTE: this proves only that a vote attributed to peer id `X` was signed by the key `X` names. It does
- * NOT decide whether `X` is legitimately a cohort member — a coordinator that mints fresh keypairs and
- * uses each key's own derived id passes this check for every one of them. Sybil/membership is a separate
- * layer (cohort-topic membership certificates); do not assume it is solved here.
- */
-
-import { peerIdFromString } from "@libp2p/peer-id";
-
-/**
- * True iff `rawKey` is the Ed25519 public key that `peerIdStr` names. Total: returns `false` on a
- * non-Ed25519 id, a missing/mismatched key, or any malformed input — never throws.
- */
-export function peerIdBindsPublicKey(peerIdStr: string, rawKey: Uint8Array): boolean {
-	try {
-		const peerId = peerIdFromString(peerIdStr);
-		if (peerId.type !== 'Ed25519' || peerId.publicKey === undefined) return false;
-		const expected = peerId.publicKey.raw; // 32 bytes for Ed25519
-		if (expected.length !== rawKey.length) return false;
-		return expected.every((b, i) => b === rawKey[i]);
-	} catch {
-		return false;
-	}
-}
+/**
+ * Key ↔ peer-id binding predicate for the cluster/dispute vote paths.
+ *
+ * For a libp2p Ed25519 identity the peer-id **is** the multihash of the public key, so a public key
+ * that a record self-asserts for a peer id can be checked against the id itself — no network lookup.
+ * Both the cluster two-phase-commit path (`cluster-repo.ts`) and the dispute path (`dispute-service.ts`)
+ * read a signing key straight from the record they are handed; without this check a coordinator could
+ * attach a key it controls under an honest peer's id and have a forged vote verify. This predicate is
+ * the gate that ties a self-asserted key back to the identity it claims.
+ *
+ * Mirrors the binding logic already used by the cohort-topic substrate in `cohort-topic/peer-sig.ts`
+ * (`peerIdFromString(str).publicKey.raw`); intentionally NOT importing that module, which is
+ * specialized for its own wire encoding.
+ *
+ * NOTE: this proves only that a vote attributed to peer id `X` was signed by the key `X` names. It does
+ * NOT decide whether `X` is legitimately a cohort member — a coordinator that mints fresh keypairs and
+ * uses each key's own derived id passes this check for every one of them. Sybil/membership is a separate
+ * layer (cohort-topic membership certificates); do not assume it is solved here.
+ */
+
+import { peerIdFromString } from "@libp2p/peer-id";
+
+/**
+ * True iff `rawKey` is the Ed25519 public key that `peerIdStr` names. Total: returns `false` on a
+ * non-Ed25519 id, a missing/mismatched key, or any malformed input — never throws.
+ */
+export function peerIdBindsPublicKey(peerIdStr: string, rawKey: Uint8Array): boolean {
+	try {
+		const peerId = peerIdFromString(peerIdStr);
+		if (peerId.type !== 'Ed25519' || peerId.publicKey === undefined) return false;
+		const expected = peerId.publicKey.raw; // 32 bytes for Ed25519
+		if (expected.length !== rawKey.length) return false;
+		return expected.every((b, i) => b === rawKey[i]);
+	} catch {
+		return false;
+	}
+}