@serfab/cadre-core 0.9.0 → 0.10.0

package/src/peer-authorization.ts

@@ -1,48 +1,150 @@
 import debug from 'debug';
 import { digest, verify } from '@optimystic/quereus-plugin-crypto';
+import { controlAuthorizationFields } from './control-authorization.js';
+import type { ControlAction, ControlDomain, RevocableTable } from './control-authorization.js';
 
 const log = debug('sereus:cadre:peer-authorization');
 
 /**
- * Canonical digest an owner signs to authorize a peer.
+ * base64url SHA-256 digest over the shared domain-tagged field vector (see
+ * control-authorization.ts). The base64url twin of
+ * control-database.ts:buildAuthorizationMessage (which returns the same digest as raw
+ * bytes): sign either encoding with input encoding to match and the signed bytes agree.
+ */
+function taggedDigest(domain: ControlDomain, action: ControlAction, rowFields: string[]): string {
+  return digest(controlAuthorizationFields(domain, action, rowFields), 'sha256', 'base64url') as string;
+}
+
+/**
+ * Canonical digest an owner signs to vouch a peer's ENROLLMENT — the offline
+ * credential `cadre enroll register` verifies. No table checks this digest, so it
+ * carries its own `'Cadre.Enrollment'` domain tag to stay disjoint from every
+ * CadreControl table rule (pre-tag it collided with the `DeviceToken` owner digests,
+ * so an enrollment vouch doubled as a push-token delete approval).
  *
- * This is the exact byte construction {@link SeedBootstrapService.authorizePeer}
- * signs over when it inserts an authorized `CadrePeer` row:
- * `digest([peerId], 'sha256', 'base64url')`. Factored into one place so the
- * producer (owner signing) and the verifier (the offline `cadre enroll
- * register` check) can never drift apart — change the digest here and both move
- * together. The SQL mirror is the bare single-field `digest(coalesce(new.PeerId, old.PeerId))`.
+ * Factored into one place so the producer (owner signing) and the verifier (the
+ * offline `cadre enroll register` check) can never drift apart — change the digest
+ * here and both move together.
  */
 export function peerAuthorizationDigest(peerId: string): string {
-  return digest([peerId], 'sha256', 'base64url') as string;
+  return taggedDigest('Cadre.Enrollment', 'vouch', [peerId]);
+}
+
+/**
+ * The `CadreControl.DeviceToken` columns {@link deviceTokenAddDigest} binds, in the
+ * schema's order. A whole-row struct rather than six positional strings, so a caller
+ * cannot silently transpose `platform` and `token` (both opaque strings) and mint a
+ * signature over a row it did not mean to approve.
+ *
+ * Structurally satisfied by a `DeviceTokenRecord` spread with the row's `stampId`;
+ * `types.ts:DeviceTokenRecord` deliberately does NOT carry the stamp — it is the
+ * SELF-signed record shape, and the peer's own `Sig` does not cover `StampId`.
+ * `updatedAt` / `sig` are nullable because the columns are: both sign as `''` when
+ * absent, mirroring the schema's `coalesce(...)`.
+ */
+export interface DeviceTokenAuthorizedRow {
+  peerId: string;
+  platform: string;
+  token: string;
+  updatedAt: number | null;
+  sig: string | null;
+  stampId: string;
+}
+
+/**
+ * Canonical digest an owner signs to authorize a `DeviceToken` INSERT — the WHOLE row,
+ * ending in its single-use `StampId` nonce. SQL mirror:
+ * `digest('CadreControl.DeviceToken', 'add', new.PeerId, new.Platform, new.Token,
+ * coalesce(cast(new.UpdatedAt as text), ''), coalesce(new.Sig, ''), new.StampId)` in
+ * `DeviceToken.AuthorizedInsert`.
+ *
+ * Binding every column means a captured approval can only ever reproduce the exact row
+ * it approved — never one carrying attacker-chosen `Platform`/`Token`/`UpdatedAt` — and
+ * binding the stamp makes it single-use: while the row lives the `unique` column blocks
+ * a replay, and after a clear the stamp is retired permanently into
+ * `CadreControl.Revocation` (`DeviceToken.NotRevoked`). This matters more here than for
+ * `CadrePeer`: a resurrected push token has NO freshness ceiling to retire it
+ * (`CadreNode.resolveDeviceToken` defaults `maxAgeMs` to infinity by design), so stamp
+ * retirement is the only thing that sticks.
+ *
+ * Distinct from {@link deviceTokenRemoveDigest} so a captured insert approval can never
+ * be replayed to delete the token, and vice versa.
+ */
+export function deviceTokenAddDigest(row: DeviceTokenAuthorizedRow): string {
+  return taggedDigest('CadreControl.DeviceToken', 'add', [
+    row.peerId,
+    row.platform,
+    row.token,
+    row.updatedAt === null ? '' : String(row.updatedAt),
+    row.sig ?? '',
+    row.stampId,
+  ]);
+}
+
+/**
+ * Canonical digest an owner signs to authorize a `DeviceToken` DELETE, bound to the
+ * STORED row's (PeerId, StampId). SQL mirror:
+ * `digest('CadreControl.DeviceToken', 'remove', old.PeerId, old.StampId)` in
+ * `DeviceToken.AuthorizedDelete`.
+ *
+ * A narrower vector than {@link deviceTokenAddDigest} on purpose (the same split
+ * `CadrePeer` makes): the clear approval names only which row is being retired, so it
+ * cannot be re-cut into an insert approval, and it is dead the moment the stamp it
+ * names is tombstoned.
+ */
+export function deviceTokenRemoveDigest(peerId: string, stampId: string): string {
+  return taggedDigest('CadreControl.DeviceToken', 'remove', [peerId, stampId]);
 }
 
 /**
  * Canonical digest an owner signs to VOUCH a `CadrePeer` membership row (insert
- * and the owner re-touch update). Binds the peer id to the row's single-use
- * `StampId` nonce, so a captured signed insert cannot be replayed (the `StampId` is
- * unique) and — because {@link cadrePeerRemoveDigest} scopes a DIFFERENT payload — the
- * stored voucher (`VouchSig`) cannot be replayed to authorize a delete.
+ * and the owner re-touch update — same semantics, deliberately the same digest).
+ * Binds the peer id to the row's single-use `StampId` nonce, so a captured signed
+ * insert cannot be replayed — while the row lives the `unique` column blocks it, and
+ * after a removal the stamp is retired permanently into `CadreControl.Revocation`
+ * (`CadrePeer.NotRevoked`) — and, because {@link cadrePeerRemoveDigest} scopes a
+ * DIFFERENT payload, the stored voucher (`VouchSig`) cannot be replayed to authorize
+ * a delete. The domain tag keeps the stored, replicated `VouchSig` useless against
+ * every OTHER table's rules.
  *
- * The SQL mirror is `digest(new.PeerId, new.StampId)` (two TEXT fields), matching the
- * canonical multi-field framing in control-database.ts:buildAuthorizationMessage.
+ * SQL mirror: `digest('CadreControl.CadrePeer', 'vouch', new.PeerId, new.StampId)`.
  */
 export function cadrePeerVoucherDigest(peerId: string, stampId: string): string {
-  return digest([peerId, stampId], 'sha256', 'base64url') as string;
+  return taggedDigest('CadreControl.CadrePeer', 'vouch', [peerId, stampId]);
 }
 
 /**
  * Canonical digest an owner signs to REMOVE a `CadrePeer` row. Deliberately a
- * distinct payload from {@link cadrePeerVoucherDigest} (adds the `'remove'` action
- * tag) so the row's stored voucher — a signature over the voucher digest — can never
+ * distinct payload from {@link cadrePeerVoucherDigest} (the `'remove'` action tag)
+ * so the row's stored voucher — a signature over the voucher digest — can never
  * satisfy this delete check. The signature is supplied in write context and never
- * stored, so no reader can replay it; binding the live row's `StampId` also invalidates
- * any captured remove after a delete+reinsert (the nonce rotates).
+ * stored, so no reader can replay it; a captured remove is also dead after the
+ * delete lands, because a re-added row carries a FRESH `StampId` (the removed row's
+ * stamp is retired into `CadreControl.Revocation` and never reused).
  *
- * SQL mirror: `digest(old.PeerId, old.StampId, 'remove')`.
+ * SQL mirror: `digest('CadreControl.CadrePeer', 'remove', old.PeerId, old.StampId)`.
  */
 export function cadrePeerRemoveDigest(peerId: string, stampId: string): string {
-  return digest([peerId, stampId, 'remove'], 'sha256', 'base64url') as string;
+  return taggedDigest('CadreControl.CadrePeer', 'remove', [peerId, stampId]);
+}
+
+/**
+ * Canonical digest an owner signs to APPEND a `CadreControl.Revocation` tombstone —
+ * the row retiring `stampId` for the named guarded table, and recording `rowKey`
+ * (the removed row's primary key: OwnerKey.Key / ValidationKey.Key /
+ * CadrePeer.PeerId / DeviceToken.PeerId / Strand.Id) as which row was retired.
+ * SQL mirror:
+ * `digest('CadreControl.Revocation', 'remove', new.TableName, new.RowKey, new.StampId)`
+ * in `Revocation.Authorized`.
+ *
+ * Its own `'CadreControl.Revocation'` domain tag makes it disjoint from the
+ * `'CadreControl.CadrePeer'` (or `OwnerKey` / `ValidationKey` / `Strand`)
+ * `'remove'` digest the same owner signs in the SAME transaction for the delete
+ * this tombstone accompanies — a removal signature is not a retirement
+ * signature and cannot be replayed as one.
+ */
+export function revocationDigest(tableName: RevocableTable, rowKey: string, stampId: string): string {
+  return taggedDigest('CadreControl.Revocation', 'remove', [tableName, rowKey, stampId]);
 }
 
 /**
@@ -79,3 +181,79 @@ export function verifyPeerAuthorization(
     return false;
   }
 }
+
+/**
+ * Verify that `signature` is a valid owner ed25519 signature over the
+ * `CadrePeer` voucher digest for (`peerId`, `stampId`) — the read-side mirror
+ * of the voucher {@link ControlDatabase.insertCadrePeer} signs and persists into
+ * `VouchOwner`/`VouchSig` (see {@link cadrePeerVoucherDigest}).
+ *
+ * A `true` result means the holder of `ownerPublicKey` vouched THIS membership
+ * row (the peer id bound to the row's single-use `StampId` nonce). It says
+ * nothing about whether that owner key is itself trustworthy — the caller must
+ * separately check the key against the node-local trusted-owner anchor
+ * (`TrustedOwnerStore`), never the replicated `OwnerKey` table.
+ *
+ * Returns a boolean and never throws (same contract as
+ * {@link verifyPeerAuthorization}): malformed input or any crypto failure
+ * resolves to `false`, logged at debug.
+ */
+export function verifyCadrePeerVoucher(
+  peerId: string,
+  stampId: string,
+  ownerPublicKey: string,
+  signature: string
+): boolean {
+  try {
+    return verify(
+      cadrePeerVoucherDigest(peerId, stampId),
+      signature,
+      ownerPublicKey,
+      'ed25519',
+      'base64url',
+      'base64url',
+      'base64url'
+    );
+  } catch (error) {
+    log('verifyCadrePeerVoucher failed: %o', error);
+    return false;
+  }
+}
+
+/**
+ * Canonical digest a JOINING peer signs to consent to ONE `FormationUsage`
+ * redemption — the read-side mirror of `formationConsentMessage` in
+ * control-database.ts, base64url-encoded instead of raw bytes (see
+ * {@link taggedDigest}). That doc comment carries the field-vector rationale
+ * (notably why `strandId` is not signed); the two vectors must not drift, which
+ * peer-authorization.spec.ts pins by signing one form and verifying the other.
+ */
+export function formationConsentDigest(
+  token: string, usageStampId: string, peerKey: string, disclosure: string
+): string {
+  return taggedDigest('CadreControl.FormationUsage', 'consent', [token, usageStampId, peerKey, disclosure]);
+}
+
+/**
+ * Verify that `row.peerSig` is a valid ed25519 signature over the joining peer's
+ * consent digest (see {@link formationConsentDigest}) — the row's OWN `peerKey`.
+ *
+ * Unlike {@link verifyCadrePeerVoucher} there is no separate enrolled/owner row to
+ * look up: the identity IS the key carried on the row, so a forged consent would
+ * need that joiner's own private key. Returns a boolean and never throws (same
+ * contract as the siblings above): malformed input or any crypto failure resolves
+ * to `false`, logged at debug.
+ */
+export function verifyFormationConsent(row: {
+  token: string; usageStampId: string; peerKey: string; disclosure: string; peerSig: string;
+}): boolean {
+  try {
+    return verify(
+      formationConsentDigest(row.token, row.usageStampId, row.peerKey, row.disclosure),
+      row.peerSig, row.peerKey, 'ed25519', 'base64url', 'base64url', 'base64url'
+    );
+  } catch (error) {
+    log('verifyFormationConsent failed: %o', error);
+    return false;
+  }
+}

package/src/peer-record.ts

@@ -3,24 +3,29 @@
  * 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 of a delimited string of the
- * authenticated fields. It is intentionally NOT JSON-canonicalized: a delimited
- * digest is trivially deterministic across node/browser/RN (plain string concat
- * + sha256, no key ordering) and — crucially — is reconstructable inside the
- * `CadrePeer.AuthorizedUpdate` SQL constraint from the row's own columns:
+ * 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(new.PeerId || '|' || new.Multiaddr || '|' || cast(new.UpdatedAt as text))
+ *   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 `'|'` delimiter is safe: a base58btc PeerId, a multiaddr (which uses
- * `/`), and a base-10 integer never contain it.
+ * 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';
 
 /**
@@ -51,8 +56,8 @@ const SIGNALING_PREFIX = '/p2p-circuit';
  * @param updatedAt - epoch-ms freshness stamp
  */
 export function peerRecordSignedPayload(peerId: string, multiaddr: string, updatedAt: number): string {
-  const joined = `${peerId}|${multiaddr}|${updatedAt}`;
-  return digest([joined], 'sha256', 'base64url') as string;
+  const fields = controlAuthorizationFields('CadreControl.CadrePeer', 'publish', [peerId, multiaddr, String(updatedAt)]);
+  return digest(fields, 'sha256', 'base64url') as string;
 }
 
 /**
@@ -117,6 +122,19 @@ 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

package/src/relay-addrs.ts

@@ -0,0 +1,111 @@
+/**
+ * Translate `network.relayAddrs` — the operator-facing "use these relay servers"
+ * setting — into the mechanism this repo already has for reserving a circuit-relay
+ * slot: a `…/p2p/<relayPeerId>/p2p-circuit` entry in the node's listen addrs.
+ *
+ * `@libp2p/circuit-relay-v2`'s transport is always present on the Node path
+ * (`../optimystic/packages/db-p2p/src/libp2p-node.ts` pushes `circuitRelayTransport()`
+ * unconditionally), and listening on a relay's circuit addr is what makes libp2p dial
+ * that relay and hold a reservation. Everything downstream of the listen list —
+ * the reservation itself, `CadreNode.circuitRelayTargets()` picking delegate-announce
+ * targets, strand nodes inheriting the listen addrs, the `/p2p-circuit`-first address
+ * publishing in `registerSelf` — then works unchanged.
+ *
+ * So `relayAddrs` is a second, friendlier door onto an existing mechanism:
+ *
+ *   effective listen addrs = listenAddrs ++ relayAddrs.map(a => a + '/p2p-circuit')
+ *
+ * NOTE: this is the FAIL-FAST route to a reservation — libp2p's transport manager
+ * throws when a configured circuit listener cannot listen, so naming a relay that
+ * is down means the node does not start. The fail-soft route is the bare
+ * `/p2p-circuit` search listener driven by `relay-reservation.ts`. The two are
+ * ALTERNATIVES, not layers: configuring `relayAddrs` on a node that already
+ * reserves via the search listener adds the fatal listener back and the node
+ * stops booting when its relay is down.
+ */
+
+import { multiaddr, type Component } from '@multiformats/multiaddr';
+import { circuitRelayTargetOrThrow } from './delegate-admission.js';
+import type { NetworkConfig } from './types.js';
+
+/**
+ * The direct listener a node keeps when it configures `relayAddrs` but no
+ * `listenAddrs`. Without this, naming a relay would silently REPLACE the node's
+ * direct TCP listener with a circuit-only one.
+ *
+ * NOTE: mirrors `createLibp2pNode`'s own default listen addr in
+ * `../optimystic/packages/db-p2p/src/libp2p-node.ts` (`/ip4/0.0.0.0/tcp/<port>`,
+ * and `CadreNode` passes `port: 0`) — that file is the source of truth. If it
+ * ever changes its default, this constant has to follow.
+ */
+const DEFAULT_DIRECT_LISTEN_ADDR = '/ip4/0.0.0.0/tcp/0';
+
+/**
+ * The circuit-listen multiaddr for each configured relay: `<relayAddr>/p2p-circuit`.
+ * An entry that already carries `/p2p-circuit` is passed through unchanged.
+ * Throws on an entry that is unparsable or names no relay peerId — this is
+ * operator configuration, so a typo must fail loudly at start rather than
+ * silently costing the node its reachability.
+ *
+ * Deliberately unlike `extractCircuitRelayTargets` (`delegate-admission.ts`), which
+ * SKIPS a bad entry: that one reads addresses discovered at runtime from peers, where
+ * one bad entry must not be fatal.
+ */
+export function relayCircuitAddrs(relayAddrs: readonly string[]): string[] {
+  return dedupe(relayAddrs.map(circuitListenAddr));
+}
+
+/**
+ * The listen multiaddrs a node actually binds: configured `listenAddrs` plus the
+ * circuit-listen addr of every configured relay, deduplicated, order-stable
+ * (configured entries first). Returns `undefined` when neither field is set, so
+ * callers keep omitting `listenAddrs` and inherit db-p2p's default.
+ */
+export function resolveListenAddrs(network: NetworkConfig | undefined): string[] | undefined {
+  const circuits = relayCircuitAddrs(network?.relayAddrs ?? []);
+  const listenAddrs = network?.listenAddrs;
+  if (!listenAddrs && circuits.length === 0) {
+    return undefined;
+  }
+  // An explicitly empty `listenAddrs` (the React Native "cannot listen" case) stays
+  // empty — but a relay named alongside it still gets its circuit listener, since
+  // acquiring one is the whole point of configuring a relay.
+  return dedupe([...(listenAddrs ?? [DEFAULT_DIRECT_LISTEN_ADDR]), ...circuits]);
+}
+
+/**
+ * One entry of {@link relayCircuitAddrs}: the addr the node listens on for this relay.
+ *
+ * NOTE: an entry carrying components AFTER `/p2p-circuit` — a full relayed DIAL addr,
+ * `…/p2p/<relay>/p2p-circuit/p2p/<someone else>` — is passed through as written and
+ * would be listened on verbatim. It validates (the relay it names is real), so only an
+ * operator who pastes a peer's relayed address into `relayAddrs` hits it; if that turns
+ * out to be a common paste, truncate at the `/p2p-circuit` component here.
+ */
+function circuitListenAddr(relayAddr: string): string {
+  const alreadyCircuit = parseComponents(relayAddr).some((c) => c.name === 'p2p-circuit');
+  const listenAddr = alreadyCircuit ? relayAddr : `${relayAddr}/p2p-circuit`;
+  try {
+    circuitRelayTargetOrThrow(listenAddr); // validates the relay peerId
+  } catch (err) {
+    throw new Error(
+      `network.relayAddrs entry names no relay peerId (expected <dial addr>/p2p/<relayPeerId>): ${relayAddr}`,
+      { cause: err }
+    );
+  }
+  return listenAddr;
+}
+
+/** Multiaddr components of `relayAddr`, with the config field named on a parse failure. */
+function parseComponents(relayAddr: string): Component[] {
+  try {
+    return multiaddr(relayAddr).getComponents();
+  } catch (err) {
+    throw new Error(`network.relayAddrs entry is not a valid multiaddr: ${relayAddr}`, { cause: err });
+  }
+}
+
+/** Exact-string dedupe, first occurrence wins, so the list is stable across restarts. */
+function dedupe(addrs: readonly string[]): string[] {
+  return [...new Set(addrs)];
+}