@serfab/cadre-core 1.14.0 → 1.16.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:
 //

package/src/peer-record.ts

@@ -1,202 +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 and the node-local `party_id()`:
- *
- *   digest('CadreControl.CadrePeer', 'publish', party_id(),
- *          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; 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 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 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
- */
-export function peerRecordSignedPayload(partyId: string, peerId: string, multiaddr: string, updatedAt: number): string {
-  const fields = controlAuthorizationFields('CadreControl.CadrePeer', 'publish', partyId, [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 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: { peerId: string; publicKey: string; addrs: string[]; updatedAt: number },
-  privateKeyB64: string
-): PeerAddressRecord {
-  const payloadDigest = peerRecordSignedPayload(partyId, 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`, 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);
-  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;
+    },
+  };
+}

package/src/primary-lan-address.ts

@@ -0,0 +1,47 @@
+/**
+ * Node-only: the machine's main LAN address, for {@link selectNodeClaimAddresses}'s `lan`.
+ *
+ * The address the OS would send from to reach the internet, learned by "connecting" a UDP
+ * socket to a public address: a UDP connect only picks a route and sends nothing. On a
+ * server that also has Docker bridges, a VPN or other interfaces, that is the one a phone on
+ * the same network reaches. A subpath module (`@serfab/cadre-core/primary-lan-address`), like
+ * `key-store-file`, so `node:dgram` never reaches a React Native bundle.
+ */
+import dgram from 'node:dgram';
+import debug from 'debug';
+
+const log = debug('sereus:cadre:primary-lan-address');
+
+/** Any public IPv4 address works: nothing is sent to it. */
+const ROUTE_PROBE = { host: '1.1.1.1', port: 53 } as const;
+
+/**
+ * The machine's primary IPv4 address, or undefined when there is no route (offline) or the
+ * probe fails. Callers then fall back to keeping every LAN address. `probe` is for tests.
+ */
+export async function primaryLanAddress(probe: { host: string; port: number } = ROUTE_PROBE): Promise<string | undefined> {
+	return new Promise((resolve) => {
+		const socket = dgram.createSocket('udp4');
+		let settled = false;
+		const finish = (address?: string): void => {
+			if (settled) return;
+			settled = true;
+			socket.close();
+			resolve(address);
+		};
+		socket.on('error', (err) => {
+			log('route probe failed: %s', err.message);
+			finish();
+		});
+		socket.connect(probe.port, probe.host, (err?: Error) => {
+			// A failed connect reports here, not as 'error', and leaves the socket bound to
+			// 0.0.0.0, so its address() must not be read.
+			if (err) {
+				log('no route to probe: %s', err.message);
+				finish();
+				return;
+			}
+			finish(socket.address().address);
+		});
+	});
+}