@serfab/cadre-core 0.10.0 → 0.12.0

package/src/peer-record.ts

@@ -1,164 +1,197 @@
-/**
- * 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;
-}
-
-/**
- * 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:
+ *
+ *   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;
+    },
+  };
+}

package/src/push-credentials.ts

@@ -1,84 +1,84 @@
-/**
- * push-credentials.ts — pure validation + log-redaction for {@link PushCredentials}.
- *
- * The platform-push credentials a deployment provisions (`cadre-host` from its
- * secret store, `cadre-provider` from per-tenant config) are written into a
- * spawned node's config under `CadreNodeConfig.push`. This module is the
- * dependency-free seam those provisioners share to (a) reject a *partial* set
- * before it reaches a node — a present platform block must carry all its required
- * fields, or it fails fast at provisioning rather than at first push — and (b)
- * produce a log-safe view that never leaks a private key.
- *
- * It imports only the *types* (erased at emit), so it pulls no node:crypto /
- * node:http2 edge — a provisioner can import these functions without dragging in
- * the FCM/APNs senders.
- */
-
-import type { PushCredentials, FcmCredentials, ApnsCredentials } from './types.js';
-
-/** Marker substituted for every secret field by {@link redactPushCredentials}. */
-export const REDACTED = '[redacted]';
-
-/**
- * Validate a resolved push-credential bundle, returning human-readable errors
- * (empty ⇒ valid). Each platform block is optional, but a *present* block must
- * carry every required field — a partial set (e.g. APNs `keyId` without
- * `privateKey`) is a misconfiguration that must surface at provisioning time, not
- * silently at the first wake. A bundle with neither platform is valid (push is
- * opt-in); callers that require at least one platform check that separately.
- */
-export function validatePushCredentials(push: PushCredentials): string[] {
-  const errors: string[] = [];
-  if (push.fcm) errors.push(...validateFcm(push.fcm));
-  if (push.apns) errors.push(...validateApns(push.apns));
-  return errors;
-}
-
-function validateFcm(fcm: FcmCredentials): string[] {
-  return missingFields('fcm', fcm as unknown as Record<string, unknown>, [
-    'projectId',
-    'clientEmail',
-    'privateKey',
-  ]);
-}
-
-function validateApns(apns: ApnsCredentials): string[] {
-  return missingFields('apns', apns as unknown as Record<string, unknown>, [
-    'keyId',
-    'teamId',
-    'bundleId',
-    'privateKey',
-  ]);
-}
-
-/** Names the required fields of `platform` that are missing or blank. */
-function missingFields(platform: string, obj: Record<string, unknown>, required: string[]): string[] {
-  return required
-    .filter((f) => typeof obj[f] !== 'string' || (obj[f] as string).trim().length === 0)
-    .map((f) => `push.${platform}.${f} is required when a ${platform} credential block is present`);
-}
-
-/**
- * Return a log-safe shallow copy of a push bundle with every private key replaced
- * by {@link REDACTED}. Use this for ANY debug/log line that touches push config —
- * `privateKey` fields are secrets and must never reach a log sink (the same rule
- * the startup/seed tokens follow).
- */
-export function redactPushCredentials(push: PushCredentials): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  if (push.fcm) {
-    out.fcm = { projectId: push.fcm.projectId, clientEmail: push.fcm.clientEmail, privateKey: REDACTED };
-  }
-  if (push.apns) {
-    out.apns = {
-      keyId: push.apns.keyId,
-      teamId: push.apns.teamId,
-      bundleId: push.apns.bundleId,
-      ...(push.apns.production !== undefined ? { production: push.apns.production } : {}),
-      privateKey: REDACTED,
-    };
-  }
-  if (push.cooldownMs !== undefined) out.cooldownMs = push.cooldownMs;
-  if (push.debounceMs !== undefined) out.debounceMs = push.debounceMs;
-  return out;
-}
+/**
+ * push-credentials.ts — pure validation + log-redaction for {@link PushCredentials}.
+ *
+ * The platform-push credentials a deployment provisions (`cadre-host` from its
+ * secret store, `cadre-provider` from per-tenant config) are written into a
+ * spawned node's config under `CadreNodeConfig.push`. This module is the
+ * dependency-free seam those provisioners share to (a) reject a *partial* set
+ * before it reaches a node — a present platform block must carry all its required
+ * fields, or it fails fast at provisioning rather than at first push — and (b)
+ * produce a log-safe view that never leaks a private key.
+ *
+ * It imports only the *types* (erased at emit), so it pulls no node:crypto /
+ * node:http2 edge — a provisioner can import these functions without dragging in
+ * the FCM/APNs senders.
+ */
+
+import type { PushCredentials, FcmCredentials, ApnsCredentials } from './types.js';
+
+/** Marker substituted for every secret field by {@link redactPushCredentials}. */
+export const REDACTED = '[redacted]';
+
+/**
+ * Validate a resolved push-credential bundle, returning human-readable errors
+ * (empty ⇒ valid). Each platform block is optional, but a *present* block must
+ * carry every required field — a partial set (e.g. APNs `keyId` without
+ * `privateKey`) is a misconfiguration that must surface at provisioning time, not
+ * silently at the first wake. A bundle with neither platform is valid (push is
+ * opt-in); callers that require at least one platform check that separately.
+ */
+export function validatePushCredentials(push: PushCredentials): string[] {
+  const errors: string[] = [];
+  if (push.fcm) errors.push(...validateFcm(push.fcm));
+  if (push.apns) errors.push(...validateApns(push.apns));
+  return errors;
+}
+
+function validateFcm(fcm: FcmCredentials): string[] {
+  return missingFields('fcm', fcm as unknown as Record<string, unknown>, [
+    'projectId',
+    'clientEmail',
+    'privateKey',
+  ]);
+}
+
+function validateApns(apns: ApnsCredentials): string[] {
+  return missingFields('apns', apns as unknown as Record<string, unknown>, [
+    'keyId',
+    'teamId',
+    'bundleId',
+    'privateKey',
+  ]);
+}
+
+/** Names the required fields of `platform` that are missing or blank. */
+function missingFields(platform: string, obj: Record<string, unknown>, required: string[]): string[] {
+  return required
+    .filter((f) => typeof obj[f] !== 'string' || (obj[f] as string).trim().length === 0)
+    .map((f) => `push.${platform}.${f} is required when a ${platform} credential block is present`);
+}
+
+/**
+ * Return a log-safe shallow copy of a push bundle with every private key replaced
+ * by {@link REDACTED}. Use this for ANY debug/log line that touches push config —
+ * `privateKey` fields are secrets and must never reach a log sink (the same rule
+ * the startup/seed tokens follow).
+ */
+export function redactPushCredentials(push: PushCredentials): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (push.fcm) {
+    out.fcm = { projectId: push.fcm.projectId, clientEmail: push.fcm.clientEmail, privateKey: REDACTED };
+  }
+  if (push.apns) {
+    out.apns = {
+      keyId: push.apns.keyId,
+      teamId: push.apns.teamId,
+      bundleId: push.apns.bundleId,
+      ...(push.apns.production !== undefined ? { production: push.apns.production } : {}),
+      privateKey: REDACTED,
+    };
+  }
+  if (push.cooldownMs !== undefined) out.cooldownMs = push.cooldownMs;
+  if (push.debounceMs !== undefined) out.debounceMs = push.debounceMs;
+  return out;
+}