@serfab/cadre-core 0.9.0 → 0.11.0

package/src/peer-addr-book.ts

@@ -0,0 +1,250 @@
+/**
+ * Merging verified cadre addresses into a libp2p node's **address book** (its
+ * peerStore), so that every layer below cadre-core which dials by bare peer id
+ * — Optimystic's cluster client, repo client, FRET ping/announce, all funnelling
+ * into `libp2p.dialProtocol(peerId, …)` — has an address to use for a sibling
+ * whose connection has dropped, instead of failing with `NoValidAddressesError`
+ * until the next reconcile pass happens to re-dial it.
+ *
+ * Shared by the control-cohort reconcile pass and the strand one (both in
+ * `CadreNode`): each resolves a peer's addresses its own way and then needs
+ * exactly this write, with exactly this workaround.
+ *
+ * Two exports, in the order a caller uses them: {@link groupAddrsByPeerId} turns
+ * a flat address list into per-peer groups (the strand path starts from the
+ * peer-agnostic union the strand-addr RPC returns), and {@link mergePeerAddrs}
+ * writes one peer's group.
+ */
+
+import debug from 'debug';
+import { peerIdFromString } from '@libp2p/peer-id';
+import type { Address, Peer, PeerId, PeerStore, TagOptions } from '@libp2p/interface';
+import { multiaddr, CODE_P2P, CODE_P2P_CIRCUIT, type Multiaddr } from '@multiformats/multiaddr';
+
+const log = debug('sereus:cadre:peer-addr-book');
+
+/** Outcome of one address-book merge, for logging and tests. */
+export type MergeAddrsResult = 'merged' | 'restamped' | 'skipped' | 'failed';
+
+/**
+ * The slice of a libp2p node {@link mergePeerAddrs} touches. Structurally
+ * satisfied by `Libp2p`; narrow so a caller (or a test) can pass a bare
+ * peerStore holder.
+ */
+export interface PeerAddrBookHost {
+  peerStore: PeerStore;
+}
+
+/**
+ * Write `addrs` into `host`'s address book for `peerId`, best-effort. `peerId`
+ * may be the string form callers hold (a `CadrePeer.PeerId` column, a strand-addr
+ * RPC result); parsing it is part of the best-effort contract below, so no caller
+ * has to wrap this in a second try/catch of its own.
+ *
+ * - **Empty `addrs` writes nothing** and reports `'skipped'`. That is how a
+ *   revoked / stale / untrusted peer's existing entry is allowed to age out on
+ *   its own: the caller resolves `[]` for it, and nothing here refreshes it.
+ * - Otherwise the addresses are merged, and — see the timestamp trap below —
+ *   re-saved when the merge alone leaves them invisible (`'restamped'`).
+ * - Any throw (unparsable peer id, datastore failure, a peerStore double without
+ *   `merge`) is logged and folded to `'failed'`. Callers are best-effort loops:
+ *   an address-book failure must never abort a reconcile pass.
+ *
+ * NOTE: `peerStore.merge` cannot refresh an address's `observed` timestamp in
+ * `@libp2p/peer-store` 12.0.10 — `to-peer-pb.js` shadows its own loop variable
+ * (`…addresses?.find(addr => uint8ArrayEquals(addr.multiaddr, addr.multiaddr))`,
+ * always true, so it returns the FIRST stored address's timestamp), and every
+ * read filters out addresses older than `MAX_ADDRESS_AGE` (1 hour). So an entry
+ * silently dies at the one-hour mark and no amount of re-merging revives it —
+ * not even merging a brand-new address. The `save` below is the workaround:
+ * `save` is the one write path that omits `existingPeer` and therefore stamps
+ * `Date.now()`. Drop it once upstream stamps `Date.now()` on merge.
+ *
+ * NOTE: raising the store's own `maxAddressAge` (libp2p forwards `init.peerStore`
+ * straight into `persistentPeerStore`) would sidestep the bug in one line, and is
+ * deliberately NOT done: expiry is load-bearing here. Only *verified* addresses
+ * come through this helper, and the design relies on everything else — the
+ * cold-start seed entries, identify-learned addresses — still ageing out on the
+ * stock schedule. A global age bump would keep those alive too.
+ *
+ * NOTE: if the store ever REJECTS an address we hand it, the restamp repeats
+ * every pass forever — `allVisible` stays false, and `save` re-submits the same
+ * rejected address. libp2p wires the store's `addressFilter` to
+ * `connectionGater.filterMultiaddrForPeer`, which nothing in this repo implements
+ * today (`createMembershipConnectionGater` gates dials, not addresses), so the
+ * loop is unreachable. If an app ever supplies that gater hook via
+ * `NetworkConfig.connectionGater`, bound the retry — the cost is one redundant
+ * datastore write per gated sibling per reconcile pass.
+ */
+export async function mergePeerAddrs(
+  host: PeerAddrBookHost,
+  peerId: PeerId | string,
+  addrs: Multiaddr[]
+): Promise<MergeAddrsResult> {
+  if (addrs.length === 0) {
+    return 'skipped';
+  }
+  try {
+    const id = typeof peerId === 'string' ? peerIdFromString(peerId) : peerId;
+    const peer = await host.peerStore.merge(id, { multiaddrs: addrs });
+    // The returned Peer is already expiry-filtered, so it says whether the merge
+    // is actually VISIBLE — which is the only question that matters downstream.
+    if (allVisible(peer.addresses, addrs, id)) {
+      return 'merged';
+    }
+    await host.peerStore.save(id, restampData(peer, addrs, id));
+    return 'restamped';
+  } catch (error) {
+    log('mergePeerAddrs: address-book write for %s failed: %o', peerId.toString(), error);
+    return 'failed';
+  }
+}
+
+/**
+ * Group multiaddr strings by the peer id in their final `/p2p/` component — the
+ * attribution step between a flat, peer-agnostic address list and the per-peer
+ * writes {@link mergePeerAddrs} takes.
+ *
+ * The **last** `/p2p/` component is the addressed peer, not the first: a relayed
+ * address (`…/p2p/<relay>/p2p-circuit/p2p/<dst>`) names the relay first and the
+ * destination last, while a direct address (`…/tcp/…/p2p/<dst>`) names only the
+ * destination. Taking the last therefore attributes both shapes to the peer the
+ * address actually reaches.
+ *
+ * Three shapes are dropped rather than attributed, because none of them names a
+ * peer the address reaches: one that does not parse, one carrying no `/p2p/`
+ * component at all (a peer advertising a bare listen addr), and one whose
+ * `p2p-circuit` comes AFTER its last `/p2p/` (`…/p2p/<relay>/p2p-circuit`) — that
+ * last one is a relay hop with the destination missing, so its trailing peer id
+ * is the RELAY's and filing it under the relay would claim the relay is reachable
+ * at a circuit leading nowhere. Duplicates collapse within a group. Insertion
+ * order is preserved, both between groups and inside one.
+ */
+export function groupAddrsByPeerId(addrs: string[]): Map<string, Multiaddr[]> {
+  const groups = new Map<string, Multiaddr[]>();
+  const seen = new Set<string>();
+  for (const addr of addrs) {
+    const attributed = attributeAddr(addr);
+    if (!attributed) {
+      continue;
+    }
+    const key = `${attributed.peerId}\n${addr}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    const group = groups.get(attributed.peerId);
+    if (group) {
+      group.push(attributed.multiaddr);
+    } else {
+      groups.set(attributed.peerId, [attributed.multiaddr]);
+    }
+  }
+  return groups;
+}
+
+/**
+ * Parse one address and pull out the peer id it addresses (its last `/p2p/`
+ * value); null when the address is unparsable or names no destination. Every case
+ * is logged at the same level — an unattributable address is a sibling telling us
+ * something we cannot use, which is worth seeing but never worth throwing over.
+ */
+function attributeAddr(addr: string): { peerId: string; multiaddr: Multiaddr } | null {
+  let parsed: Multiaddr;
+  try {
+    parsed = multiaddr(addr);
+  } catch (error) {
+    log('groupAddrsByPeerId: skipping unparsable addr %s: %o', addr, error);
+    return null;
+  }
+  const peerId = lastAddressedPeerId(parsed);
+  if (peerId === null) {
+    log('groupAddrsByPeerId: skipping addr naming no destination peer: %s', addr);
+    return null;
+  }
+  return { peerId, multiaddr: parsed };
+}
+
+/**
+ * The peer id a parsed address reaches: its last `/p2p/` value, or null when it
+ * has none — or when a `p2p-circuit` sits after it, which makes that value the
+ * relay's rather than a destination's (see {@link groupAddrsByPeerId}). Walking
+ * backwards, meeting the circuit first is exactly that case.
+ */
+function lastAddressedPeerId(parsed: Multiaddr): string | null {
+  const components = parsed.getComponents();
+  for (let i = components.length - 1; i >= 0; i--) {
+    const component = components[i];
+    if (component.code === CODE_P2P_CIRCUIT) {
+      return null;
+    }
+    if (component.code === CODE_P2P && component.value) {
+      return component.value;
+    }
+  }
+  return null;
+}
+
+/**
+ * The peerStore strips a trailing `/p2p/<peerId>` from an address it stores when
+ * that id is the address's FIRST `/p2p/` component (`dedupe-addresses.js`), so a
+ * plain address round-trips without its suffix while a relayed one — whose first
+ * `/p2p/` names the relay — keeps it. Comparing and de-duplicating on this
+ * suffix-stripped form matches either shape.
+ */
+function addrKey(addr: string, peerId: PeerId): string {
+  const suffix = `/p2p/${peerId.toString()}`;
+  return addr.endsWith(suffix) ? addr.slice(0, -suffix.length) : addr;
+}
+
+/** Is every address in `addrs` readable back from the stored, expiry-filtered set? */
+function allVisible(stored: Address[], addrs: Multiaddr[], peerId: PeerId): boolean {
+  const keys = new Set(stored.map((a) => addrKey(a.multiaddr.toString(), peerId)));
+  return addrs.every((addr) => keys.has(addrKey(addr.toString(), peerId)));
+}
+
+/**
+ * The full `save` payload for a restamp: `save` re-uses the `patch` strategy with
+ * no existing peer, so every field it is not handed is DROPPED — and Optimystic
+ * classifies peers by their peerStore protocol list (`libp2p-key-network.ts`
+ * `membershipOf`), so losing protocols here would break cluster/repo routing.
+ * Everything therefore carries forward from the just-merged `peer`.
+ *
+ * The read-modify-write is NOT atomic against a concurrent `identify` write to
+ * the same entry. The loss window is milliseconds and costs at most one identify
+ * update, recovered by the next identify push — not worth a lock.
+ *
+ * A tag's remaining TTL is not carried: the public `Tag` type exposes only
+ * `value`, so the stored expiry is unreadable from here and the tag comes back
+ * non-expiring. `publicKey` is likewise not passed, which is lossless for the
+ * Ed25519 peer ids a cadre uses (the key is embedded in the id).
+ */
+function restampData(peer: Peer, addrs: Multiaddr[], peerId: PeerId): {
+  addresses: Address[];
+  protocols: string[];
+  metadata: Map<string, Uint8Array | undefined>;
+  tags: Map<string, TagOptions | undefined>;
+  peerRecordEnvelope?: Uint8Array;
+} {
+  const addresses = new Map<string, Address>();
+  for (const address of peer.addresses) {
+    addresses.set(addrKey(address.multiaddr.toString(), peerId), address);
+  }
+  for (const addr of addrs) {
+    const key = addrKey(addr.toString(), peerId);
+    if (!addresses.has(key)) {
+      // Uncertified, matching what `merge`'s own `multiaddrs` path would have
+      // stored; an address already present keeps whatever flag it carried.
+      addresses.set(key, { multiaddr: addr, isCertified: false });
+    }
+  }
+  return {
+    addresses: [...addresses.values()],
+    protocols: peer.protocols,
+    metadata: new Map<string, Uint8Array | undefined>(peer.metadata),
+    tags: new Map<string, TagOptions | undefined>(
+      [...peer.tags].map(([name, tag]) => [name, { value: tag.value }])
+    ),
+    peerRecordEnvelope: peer.peerRecordEnvelope
+  };
+}

package/src/peer-authorization.ts

@@ -1,81 +1,259 @@
-import debug from 'debug';
-import { digest, verify } from '@optimystic/quereus-plugin-crypto';
-
-const log = debug('sereus:cadre:peer-authorization');
-
-/**
- * Canonical digest an owner signs to authorize a peer.
- *
- * 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))`.
- */
-export function peerAuthorizationDigest(peerId: string): string {
-  return digest([peerId], 'sha256', 'base64url') as string;
-}
-
-/**
- * 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.
- *
- * The SQL mirror is `digest(new.PeerId, new.StampId)` (two TEXT fields), matching the
- * canonical multi-field framing in control-database.ts:buildAuthorizationMessage.
- */
-export function cadrePeerVoucherDigest(peerId: string, stampId: string): string {
-  return digest([peerId, stampId], 'sha256', 'base64url') as string;
-}
-
-/**
- * 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
- * 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).
- *
- * SQL mirror: `digest(old.PeerId, old.StampId, 'remove')`.
- */
-export function cadrePeerRemoveDigest(peerId: string, stampId: string): string {
-  return digest([peerId, stampId, 'remove'], 'sha256', 'base64url') as string;
-}
-
-/**
- * Verify that `signature` is a valid owner ed25519 signature over `peerId`'s
- * authorization digest, using `ownerPublicKey` (base64url).
- *
- * This is the mirror of the signing done in
- * {@link SeedBootstrapService.authorizePeer}: it checks the signature against
- * {@link peerAuthorizationDigest}. A `true` result means the holder of the
- * owner private key vouched for this peer ID — it does NOT mean the peer is
- * registered anywhere.
- *
- * Returns a boolean and never throws: malformed base64url, a bad/garbage key, or
- * any crypto failure resolves to `false` (callers want a verdict, not an
- * exception). The catch is logged at debug.
- */
-export function verifyPeerAuthorization(
-  peerId: string,
-  ownerPublicKey: string,
-  signature: string
-): boolean {
-  try {
-    return verify(
-      peerAuthorizationDigest(peerId),
-      signature,
-      ownerPublicKey,
-      'ed25519',
-      'base64url',
-      'base64url',
-      'base64url'
-    );
-  } catch (error) {
-    log('verifyPeerAuthorization failed: %o', error);
-    return false;
-  }
-}
+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');
+
+/**
+ * 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).
+ *
+ * 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 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 — 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.
+ *
+ * SQL mirror: `digest('CadreControl.CadrePeer', 'vouch', new.PeerId, new.StampId)`.
+ */
+export function cadrePeerVoucherDigest(peerId: string, stampId: string): 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} (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; 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('CadreControl.CadrePeer', 'remove', old.PeerId, old.StampId)`.
+ */
+export function cadrePeerRemoveDigest(peerId: string, stampId: string): 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]);
+}
+
+/**
+ * Verify that `signature` is a valid owner ed25519 signature over `peerId`'s
+ * authorization digest, using `ownerPublicKey` (base64url).
+ *
+ * This is the mirror of the signing done in
+ * {@link SeedBootstrapService.authorizePeer}: it checks the signature against
+ * {@link peerAuthorizationDigest}. A `true` result means the holder of the
+ * owner private key vouched for this peer ID — it does NOT mean the peer is
+ * registered anywhere.
+ *
+ * Returns a boolean and never throws: malformed base64url, a bad/garbage key, or
+ * any crypto failure resolves to `false` (callers want a verdict, not an
+ * exception). The catch is logged at debug.
+ */
+export function verifyPeerAuthorization(
+  peerId: string,
+  ownerPublicKey: string,
+  signature: string
+): boolean {
+  try {
+    return verify(
+      peerAuthorizationDigest(peerId),
+      signature,
+      ownerPublicKey,
+      'ed25519',
+      'base64url',
+      'base64url',
+      'base64url'
+    );
+  } catch (error) {
+    log('verifyPeerAuthorization failed: %o', error);
+    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;
+  }
+}