@serfab/cadre-core 1.13.0 → 1.15.0

package/src/peer-join-backfill.ts

@@ -34,6 +34,12 @@ import { peerJoinPushBudget } from './link-budget.js';
 // If Optimystic ever grows a cohort-join catch-up of its own, delete this module rather
 // than running two.
 //
+// NOTE: strand nodes pass db-p2p no `kvStore`, so Optimystic's under-replication ledger (the
+// copies a node owes peers) dies at every restart. This module's whole-store push on connect is
+// what delivers a write a machine made alone after it restarts (`joiner-first-commit-over-slow-relay`,
+// restart arm). If this module is narrowed (the cohort filter above) or deleted, give strand
+// nodes a persistent kvStore first.
+//
 // Membership — the one place the two networks differ, expressed as the optional
 // `authorizePeer` dep:
 //
@@ -315,10 +321,16 @@ export class PeerJoinBackfill {
   private readonly createPushClient: (peerId: PeerId) => PeerJoinBackfillPushClient;
   private started = false;
   private stopped = false;
-  /** Peers fully caught up this runtime (never retried until the runtime is rebuilt). */
+  /**
+   * Peers fully caught up this runtime (never rescheduled until the runtime is rebuilt; only
+   * {@link forceCatchUpPeer} pushes to one again).
+   */
   private readonly done = new Set<string>();
-  /** Peers with a catch-up currently running (suppresses concurrent duplicates). */
-  private readonly inFlight = new Set<string>();
+  /**
+   * Peers with a catch-up currently running, each with that run (suppresses concurrent
+   * duplicates; {@link forceCatchUpPeer} waits on the run).
+   */
+  private readonly inFlight = new Map<string, Promise<PeerJoinBackfillResult>>();
   /**
    * Peers whose (re-)schedule arrived while their OWN run was in flight, replayed once
    * that run finishes. Load-bearing for the gated path: the gate's authorization check is
@@ -464,7 +476,53 @@ export class PeerJoinBackfill {
     if (this.stopped || this.done.has(key) || this.inFlight.has(key)) {
       return emptyResult();
     }
-    this.inFlight.add(key);
+    return await this.trackRun(peerId);
+  }
+
+  /**
+   * Run one peer's catch-up now and wait for it, whatever this instance remembers about the
+   * peer: wait out a run already in flight for it, then push the whole store again even when
+   * the peer is memoized as caught up. Never rejects; an all-zero result only when stopped.
+   *
+   * For a caller that must know the peer holds this store before it proceeds, where
+   * {@link catchUpPeer}'s empty answer would hide a run that was denied (a `peer:identify`
+   * run can pass the gate a moment before the caller authorized the peer) or a memo older
+   * than the commits since.
+   */
+  async forceCatchUpPeer(peerId: PeerId): Promise<PeerJoinBackfillResult> {
+    const key = peerId.toString();
+    for (let pending = this.inFlight.get(key); pending; pending = this.inFlight.get(key)) {
+      await pending;
+    }
+    if (this.stopped) {
+      return emptyResult();
+    }
+    return await this.trackRun(peerId);
+  }
+
+  /**
+   * Register one run in {@link inFlight} before its first await, so no second run for the
+   * peer can start beside it, and replay a schedule that arrived while it ran.
+   */
+  private async trackRun(peerId: PeerId): Promise<PeerJoinBackfillResult> {
+    const key = peerId.toString();
+    const run = this.settleRun(peerId);
+    this.inFlight.set(key, run);
+    try {
+      return await run;
+    } finally {
+      this.inFlight.delete(key);
+      // Replay a schedule that arrived mid-run. `schedulePeer` re-checks `done`, so a run
+      // that finished clean re-arms nothing; a denied or failed one gets its retry.
+      if (this.rearmAfterFlight.delete(key)) {
+        this.schedulePeer(peerId);
+      }
+    }
+  }
+
+  /** One run and what follows from its outcome: the memo, or a backoff re-arm. Never rejects. */
+  private async settleRun(peerId: PeerId): Promise<PeerJoinBackfillResult> {
+    const key = peerId.toString();
     try {
       const { result, clean, pushFailed } = await this.runCatchUp(peerId);
       // NOTE: a run that hit `maxBlocks` is still "clean" and still memoizes the peer, so
@@ -496,13 +554,6 @@ export class PeerJoinBackfill {
       // metadata reads too — a backfill fault must never surface through a libp2p event.
       log('[%s] catch-up peer=%s failed: %o', this.deps.label, key, error);
       return emptyResult();
-    } finally {
-      this.inFlight.delete(key);
-      // Replay a schedule that arrived mid-run. `schedulePeer` re-checks `done`, so a run
-      // that finished clean re-arms nothing; a denied or failed one gets its retry.
-      if (this.rearmAfterFlight.delete(key)) {
-        this.schedulePeer(peerId);
-      }
     }
   }
 

package/src/peer-record.ts

@@ -1,197 +1,159 @@
-/**
- * Peer-address record helpers: the single source of truth for the bytes a node
- * signs when publishing its own `CadrePeer` row and re-verifies when resolving
- * another peer's row.
- *
- * The signed payload is a single SHA-256 digest over the shared domain-tagged
- * field vector (see control-authorization.ts) — the crypto plugin's injective
- * multi-field encoding, so no field split is ambiguous. It is intentionally NOT
- * JSON-canonicalized (deterministic across node/browser/RN, no key ordering)
- * and — crucially — is reconstructable inside the `CadrePeer.AuthorizedUpdate`
- * SQL constraint from the row's own columns:
- *
- *   digest('CadreControl.CadrePeer', 'publish',
- *          new.PeerId, new.Multiaddr, cast(new.UpdatedAt as text))
- *
- * Keep {@link peerRecordSignedPayload} and that constraint byte-for-byte in
- * sync. The `'publish'` action tag marks this as a peer's SELF-signed record
- * (signed with the peer's own key, not an owner key) and keeps it disjoint from
- * every owner-signed digest.
- *
- * `publicKey` is deliberately excluded from the payload — it is the key the
- * signature is verified *with* (so a signature already commits to exactly one
- * key), and its binding to `peerId` is checked separately at resolve time.
- */
-
-import type { Multiaddr } from '@multiformats/multiaddr';
-import { digest, sign, verify } from '@optimystic/quereus-plugin-crypto';
-import { controlAuthorizationFields } from './control-authorization.js';
-import type { PeerAddressRecord, PeerResolveTrustPolicy } from './types.js';
-
-/**
- * Default freshness ceiling for resolved peer-address records (15 minutes).
- * A record older than this is treated as stale and filtered out, so a resolver
- * never hands back a dead relay reservation. The publish path re-stamps at
- * roughly half this interval (see {@link DEFAULT_PEER_RECORD_HEARTBEAT_MS}).
- */
-export const DEFAULT_PEER_RECORD_MAX_AGE_MS = 15 * 60 * 1000;
-
-/**
- * TTL heartbeat interval for re-publishing the self record — half the freshness
- * ceiling, so a record is refreshed well before it can go stale.
- */
-export const DEFAULT_PEER_RECORD_HEARTBEAT_MS = DEFAULT_PEER_RECORD_MAX_AGE_MS / 2;
-
-/** The signaling/relay prefix a WebRTC (or any relayed) dial path consumes. */
-const SIGNALING_PREFIX = '/p2p-circuit';
-
-/**
- * Build the base64url SHA-256 digest that the self-signature covers. Mirrors the
- * `CadrePeer.AuthorizedUpdate` constraint exactly; both sides take the default
- * base64url output of a single `digest(...)`, which round-trips cleanly (unlike
- * concatenating several base64url digests).
- *
- * @param peerId - base58btc libp2p peer id (the row key)
- * @param multiaddr - the comma-joined `Multiaddr` string EXACTLY as stored
- * @param updatedAt - epoch-ms freshness stamp
- */
-export function peerRecordSignedPayload(peerId: string, multiaddr: string, updatedAt: number): string {
-  const fields = controlAuthorizationFields('CadreControl.CadrePeer', 'publish', [peerId, multiaddr, String(updatedAt)]);
-  return digest(fields, 'sha256', 'base64url') as string;
-}
-
-/**
- * Sign a peer-address record with the ed25519 private key behind its `peerId`.
- * Returns a fully-populated {@link PeerAddressRecord} (the `addrs` order is
- * preserved and is the order signed over).
- *
- * @param fields - the record fields to sign (signaling addr first by convention)
- * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
- */
-export function signPeerRecord(
-  fields: { peerId: string; publicKey: string; addrs: string[]; updatedAt: number },
-  privateKeyB64: string
-): PeerAddressRecord {
-  const payloadDigest = peerRecordSignedPayload(fields.peerId, fields.addrs.join(','), fields.updatedAt);
-  const sig = sign(
-    payloadDigest,
-    privateKeyB64,
-    'ed25519',
-    'base64url',
-    'base64url',
-    'base64url'
-  ) as string;
-  return { peerId: fields.peerId, publicKey: fields.publicKey, addrs: [...fields.addrs], updatedAt: fields.updatedAt, sig };
-}
-
-/**
- * Verify a record's self-signature against its own `publicKey`. Reconstructs the
- * signed bytes from the record exactly as {@link signPeerRecord} produced them.
- * Returns false on a missing key/sig or any verification failure.
- */
-export function verifyPeerRecordSignature(record: PeerAddressRecord): boolean {
-  if (!record.publicKey || !record.sig) {
-    return false;
-  }
-  const payloadDigest = peerRecordSignedPayload(record.peerId, record.addrs.join(','), record.updatedAt);
-  return verify(
-    payloadDigest,
-    record.sig,
-    record.publicKey,
-    'ed25519',
-    'base64url',
-    'base64url',
-    'base64url'
-  );
-}
-
-/**
- * Freshness predicate: true when `updatedAt` is a positive stamp within
- * `maxAgeMs` of `now`. A non-positive `updatedAt` (never self-published) is
- * never fresh.
- */
-export function isPeerRecordFresh(updatedAt: number, maxAgeMs: number, now: number): boolean {
-  if (!(updatedAt > 0)) {
-    return false;
-  }
-  return now - updatedAt <= maxAgeMs;
-}
-
-/** True if `addr` is a `/p2p-circuit` signaling/relay multiaddr. */
-export function isSignalingAddr(addr: string): boolean {
-  return addr.includes(SIGNALING_PREFIX);
-}
-
-/**
- * The peer id a multiaddr terminates in, or `null` when it names none.
- *
- * The LAST `/p2p/` component is the dial target: a circuit address
- * (`…/p2p/<relay>/p2p-circuit/p2p/<target>`) names the relay first and the peer
- * being reached last. Replaces the deprecated `Multiaddr.getPeerId()`, which
- * cannot express that distinction.
- */
-export function trailingPeerId(addr: Multiaddr): string | null {
-  const p2p = addr.getComponents().filter((c) => c.name === 'p2p');
-  return p2p.length > 0 ? (p2p[p2p.length - 1].value ?? null) : null;
-}
-
-/**
- * `addr` guaranteed to terminate in `/p2p/<peerId>` — the shape every dial path
- * needs — or `null` when it cannot, because the address already terminates in a
- * DIFFERENT peer id and therefore does not reach `peerId` at all.
- *
- * Three input shapes, matching what a `CadrePeer` record can legitimately carry:
- *
- * - no `/p2p/` component (`/ip4/1.2.3.4/tcp/4001`) — the suffix is appended;
- * - a relay hop with the destination missing (`…/p2p/<relay>/p2p-circuit`) — the
- *   last component is the circuit, not a peer id, so the suffix is appended and
- *   the address becomes the full `…/p2p/<relay>/p2p-circuit/p2p/<peerId>`;
- * - already terminating in `/p2p/<X>` — returned untouched when `X` is `peerId`,
- *   dropped otherwise.
- *
- * This is deliberately the same rule libp2p applies internally in
- * `calculateMultiaddrs` (append when the LAST component is not `p2p`) followed by
- * its wrong-peer-id filter, so a normalized list matches what libp2p would have
- * built anyway. Normalizing before the dial is what keeps a list from mixing
- * suffixed and unsuffixed entries, which `getPeerAddress` rejects outright
- * ("Multiaddrs must all have the same peer id or have no peer id") — taking the
- * whole peer down with it, not just the odd address.
- *
- * Never use before signature verification: verification runs against the
- * original on-record strings.
- */
-export function withTrailingPeerId(addr: Multiaddr, peerId: string): Multiaddr | null {
-  const components = addr.getComponents();
-  if (components[components.length - 1]?.name !== 'p2p') {
-    return addr.encapsulate(`/p2p/${peerId}`);
-  }
-  return trailingPeerId(addr) === peerId ? addr : null;
-}
-
-/**
- * Return `addrs` with signaling (`/p2p-circuit`) addrs first, otherwise stable.
- * Used to present the WebRTC dial input ahead of direct addrs. Does NOT mutate
- * the input and must not be used before signature verification (verification
- * uses the original on-record order).
- */
-export function orderSignalingFirst(addrs: string[]): string[] {
-  const signaling = addrs.filter(isSignalingAddr);
-  const rest = addrs.filter(a => !isSignalingAddr(a));
-  return [...signaling, ...rest];
-}
-
-/**
- * Default resolve trust gate: trust any peer that has a `CadrePeer` row.
- *
- * A row only exists because an owner signed its `AuthorizedInsert`, so row
- * presence already means "owner-vouched member". This is the seam where a
- * stricter policy (trust circle, pinned keys) plugs in — see
- * {@link PeerResolveTrustPolicy}.
- */
-export function currentMemberTrustPolicy(): PeerResolveTrustPolicy {
-  return {
-    evaluate() {
-      return true;
-    },
-  };
-}
+/**
+ * Peer-address record helpers: the single source of truth for the bytes a node
+ * signs when publishing its own `CadrePeer` row and re-verifies when resolving
+ * another peer's row.
+ *
+ * The signed payload is a single SHA-256 digest over the shared domain-tagged
+ * field vector (see control-authorization.ts) — the crypto plugin's injective
+ * multi-field encoding, so no field split is ambiguous. It is intentionally NOT
+ * JSON-canonicalized (deterministic across node/browser/RN, no key ordering)
+ * and — crucially — is reconstructable inside the `CadrePeer.AuthorizedUpdate`
+ * SQL constraint from the row's own columns and the node-local `party_id()`:
+ *
+ *   digest('CadreControl.CadrePeer', 'publish', party_id(),
+ *          new.PeerId, new.Multiaddr, cast(new.UpdatedAt as text),
+ *          coalesce(new.Profile, ''))
+ *
+ * Keep {@link peerRecordSignedPayload} and that constraint byte-for-byte in
+ * sync. The `'publish'` action tag marks this as a peer's SELF-signed record
+ * (signed with the peer's own key, not an owner key) and keeps it disjoint from
+ * every owner-signed digest; the party id keeps a record published into one
+ * party's table from verifying in another's. A node signs and verifies with its
+ * own party: these records come only from its own party's control database.
+ *
+ * `publicKey` is deliberately excluded from the payload — it is the key the
+ * signature is verified *with* (so a signature already commits to exactly one
+ * key), and its binding to `peerId` is checked separately at resolve time.
+ */
+
+import { digest, sign, verify } from '@optimystic/quereus-plugin-crypto';
+import { controlAuthorizationFields } from './control-authorization.js';
+import type { NodeProfile, PeerAddressRecord, PeerResolveTrustPolicy } from './types.js';
+
+/**
+ * Default freshness ceiling for resolved peer-address records (15 minutes).
+ * A record older than this is treated as stale and filtered out, so a resolver
+ * never hands back a dead relay reservation. The publish path re-stamps at
+ * roughly half this interval (see {@link DEFAULT_PEER_RECORD_HEARTBEAT_MS}).
+ */
+export const DEFAULT_PEER_RECORD_MAX_AGE_MS = 15 * 60 * 1000;
+
+/**
+ * TTL heartbeat interval for re-publishing the self record — half the freshness
+ * ceiling, so a record is refreshed well before it can go stale.
+ */
+export const DEFAULT_PEER_RECORD_HEARTBEAT_MS = DEFAULT_PEER_RECORD_MAX_AGE_MS / 2;
+
+/** The signaling/relay prefix a WebRTC (or any relayed) dial path consumes. */
+const SIGNALING_PREFIX = '/p2p-circuit';
+
+/**
+ * Build the base64url SHA-256 digest that the self-signature covers. Mirrors the
+ * `CadrePeer.AuthorizedUpdate` constraint exactly; both sides take the default
+ * base64url output of a single `digest(...)`, which round-trips cleanly (unlike
+ * concatenating several base64url digests).
+ *
+ * @param partyId - the party whose `CadrePeer` table the record is published into
+ * @param peerId - base58btc libp2p peer id (the row key)
+ * @param multiaddr - the comma-joined `Multiaddr` string EXACTLY as stored
+ * @param updatedAt - epoch-ms freshness stamp
+ * @param profile - the publisher's node profile; null signs as `''`, as the constraint coalesces it
+ */
+export function peerRecordSignedPayload(
+  partyId: string, peerId: string, multiaddr: string, updatedAt: number, profile: NodeProfile | null
+): string {
+  const fields = controlAuthorizationFields('CadreControl.CadrePeer', 'publish', partyId, [peerId, multiaddr, String(updatedAt), profile ?? '']);
+  return digest(fields, 'sha256', 'base64url') as string;
+}
+
+/**
+ * Sign a peer-address record with the ed25519 private key behind its `peerId`.
+ * Returns a fully-populated {@link PeerAddressRecord} (the `addrs` order is
+ * preserved and is the order signed over).
+ *
+ * @param partyId - the party whose `CadrePeer` table the record is published into
+ * @param fields - the record fields to sign (signaling addr first by convention)
+ * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
+ */
+export function signPeerRecord(
+  partyId: string,
+  fields: Omit<PeerAddressRecord, 'sig'>,
+  privateKeyB64: string
+): PeerAddressRecord {
+  const payloadDigest = peerRecordSignedPayload(partyId, fields.peerId, fields.addrs.join(','), fields.updatedAt, fields.profile);
+  const sig = sign(
+    payloadDigest,
+    privateKeyB64,
+    'ed25519',
+    'base64url',
+    'base64url',
+    'base64url'
+  ) as string;
+  return { peerId: fields.peerId, publicKey: fields.publicKey, addrs: [...fields.addrs], updatedAt: fields.updatedAt, profile: fields.profile, sig };
+}
+
+/**
+ * Verify a record's self-signature against its own `publicKey`, for `partyId`.
+ * Reconstructs the signed bytes from the record exactly as {@link signPeerRecord}
+ * produced them. Returns false on a missing key/sig or any verification failure.
+ */
+export function verifyPeerRecordSignature(partyId: string, record: PeerAddressRecord): boolean {
+  if (!record.publicKey || !record.sig) {
+    return false;
+  }
+  const payloadDigest = peerRecordSignedPayload(partyId, record.peerId, record.addrs.join(','), record.updatedAt, record.profile);
+  return verify(
+    payloadDigest,
+    record.sig,
+    record.publicKey,
+    'ed25519',
+    'base64url',
+    'base64url',
+    'base64url'
+  );
+}
+
+/**
+ * Freshness predicate: true when `updatedAt` is a positive stamp within
+ * `maxAgeMs` of `now`. A non-positive `updatedAt` (never self-published) is
+ * never fresh.
+ */
+export function isPeerRecordFresh(updatedAt: number, maxAgeMs: number, now: number): boolean {
+  if (!(updatedAt > 0)) {
+    return false;
+  }
+  return now - updatedAt <= maxAgeMs;
+}
+
+/** True if `addr` is a `/p2p-circuit` signaling/relay multiaddr. */
+export function isSignalingAddr(addr: string): boolean {
+  return addr.includes(SIGNALING_PREFIX);
+}
+
+/**
+ * Return `addrs` with signaling (`/p2p-circuit`) addrs first, otherwise stable.
+ * Used to present the WebRTC dial input ahead of direct addrs. Does NOT mutate
+ * the input and must not be used before signature verification (verification
+ * uses the original on-record order).
+ */
+export function orderSignalingFirst(addrs: string[]): string[] {
+  const signaling = addrs.filter(isSignalingAddr);
+  const rest = addrs.filter(a => !isSignalingAddr(a));
+  return [...signaling, ...rest];
+}
+
+/**
+ * Default resolve trust gate: trust any peer that has a `CadrePeer` row.
+ *
+ * A row only exists because an owner signed its `AuthorizedInsert`, so row
+ * presence already means "owner-vouched member". This is the seam where a
+ * stricter policy (trust circle, pinned keys) plugs in — see
+ * {@link PeerResolveTrustPolicy}.
+ */
+export function currentMemberTrustPolicy(): PeerResolveTrustPolicy {
+  return {
+    evaluate() {
+      return true;
+    },
+  };
+}