@serfab/cadre-core 0.9.0 → 0.11.0

package/dist/peer-addr-book.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 type { PeerId, PeerStore } from '@libp2p/interface';
+import { type Multiaddr } from '@multiformats/multiaddr';
+/** 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 declare function mergePeerAddrs(host: PeerAddrBookHost, peerId: PeerId | string, addrs: Multiaddr[]): Promise<MergeAddrsResult>;
+/**
+ * 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 declare function groupAddrsByPeerId(addrs: string[]): Map<string, Multiaddr[]>;

package/dist/peer-addr-book.js

@@ -0,0 +1,220 @@
+/**
+ * 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 { multiaddr, CODE_P2P, CODE_P2P_CIRCUIT } from '@multiformats/multiaddr';
+const log = debug('sereus:cadre:peer-addr-book');
+/**
+ * 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, peerId, addrs) {
+    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) {
+    const groups = new Map();
+    const seen = new Set();
+    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) {
+    let parsed;
+    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) {
+    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, peerId) {
+    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, addrs, peerId) {
+    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, addrs, peerId) {
+    const addresses = new Map();
+    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(peer.metadata),
+        tags: new Map([...peer.tags].map(([name, tag]) => [name, { value: tag.value }])),
+        peerRecordEnvelope: peer.peerRecordEnvelope
+    };
+}
+//# sourceMappingURL=peer-addr-book.js.map

package/dist/peer-addr-book.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-addr-book.js","sourceRoot":"","sources":["../src/peer-addr-book.ts"],"names":[],"mappings":"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"}

package/dist/peer-authorization.d.ts

@@ -1,36 +1,110 @@
+import type { RevocableTable } from './control-authorization.js';
 /**
- * Canonical digest an owner signs to authorize a peer.
+ * 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 declare function peerAuthorizationDigest(peerId: string): string;
+/**
+ * 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 declare function deviceTokenAddDigest(row: DeviceTokenAuthorizedRow): string;
+/**
+ * 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 declare function deviceTokenRemoveDigest(peerId: string, stampId: string): 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.
+ * 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 declare function cadrePeerVoucherDigest(peerId: string, stampId: string): 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
+ * 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 declare function cadrePeerRemoveDigest(peerId: string, stampId: string): string;
+/**
+ * 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 declare function revocationDigest(tableName: RevocableTable, rowKey: string, stampId: string): string;
 /**
  * Verify that `signature` is a valid owner ed25519 signature over `peerId`'s
  * authorization digest, using `ownerPublicKey` (base64url).
@@ -46,3 +120,46 @@ export declare function cadrePeerRemoveDigest(peerId: string, stampId: string):
  * exception). The catch is logged at debug.
  */
 export declare function verifyPeerAuthorization(peerId: string, ownerPublicKey: string, signature: string): boolean;
+/**
+ * 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 declare function verifyCadrePeerVoucher(peerId: string, stampId: string, ownerPublicKey: string, signature: string): boolean;
+/**
+ * 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 declare function formationConsentDigest(token: string, usageStampId: string, peerKey: string, disclosure: string): string;
+/**
+ * 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 declare function verifyFormationConsent(row: {
+    token: string;
+    usageStampId: string;
+    peerKey: string;
+    disclosure: string;
+    peerSig: string;
+}): boolean;