@serfab/cadre-core 1.13.0 → 1.14.0

package/dist/node-claim-payload.d.ts

@@ -0,0 +1,19 @@
+/** Version 1 of the payload; the only one either side reads. */
+export declare const NODE_CLAIM_PAYLOAD_PREFIX = "sereus-join:1.";
+export interface NodeClaimPayload {
+    /** The node's peer id. */
+    peerId: string;
+    /** Addresses the phone may dial the node at, each ending in `/p2p/<peerId>`. */
+    multiaddrs: string[];
+    /** The node's claim secret, base64url (`parseClaimSecret`). */
+    secret: string;
+}
+/** Encode a payload as the text the host shows. Refuses what {@link decodeNodeClaimPayload} would. */
+export declare function encodeNodeClaimPayload(payload: NodeClaimPayload): string;
+/**
+ * Decode the text a phone scanned or pasted. Refuses, naming the problem: any version but
+ * 1, a body that is not base64url JSON of the right shape, a peer id that does not parse,
+ * an empty address list, an address that does not parse or whose last `/p2p/` is not that
+ * peer id, and a secret {@link parseClaimSecret} refuses. The secret is never echoed.
+ */
+export declare function decodeNodeClaimPayload(text: string): NodeClaimPayload;

package/dist/node-claim-payload.js

@@ -0,0 +1,120 @@
+/**
+ * The claim payload: what a host shows as a QR code (and as text) for a node that is
+ * waiting to be claimed, and what the owner's phone scans to claim it.
+ *
+ * `sereus-join:1.<base64url of canonical JSON>` where the JSON is
+ * `{ multiaddrs, peerId, secret }`: the node's peer id, every address the phone may
+ * dial it at (each ending in `/p2p/<peerId>`), and the node's one-time claim secret
+ * (`claim-proof.ts`). The phone hands all three to `CadreNode.claimNode`. The payload
+ * carries no party id: the claim supplies it, and the node records it.
+ *
+ * The decoder lives here, beside the encoder, because the phone and the host both need
+ * it and neither depends on the other. Imports only `@multiformats/multiaddr`,
+ * `@libp2p/peer-id` and `uint8arrays`, so it loads on React Native and in the browser.
+ */
+import { peerIdFromString } from '@libp2p/peer-id';
+import { multiaddr, CODE_P2P, CODE_P2P_CIRCUIT } from '@multiformats/multiaddr';
+import { fromString as uint8ArrayFromString, toString as uint8ArrayToString } from 'uint8arrays';
+import { canonicalJson } from './canonical-json.js';
+import { parseClaimSecret } from './claim-proof.js';
+/** Version 1 of the payload; the only one either side reads. */
+export const NODE_CLAIM_PAYLOAD_PREFIX = 'sereus-join:1.';
+/** Encode a payload as the text the host shows. Refuses what {@link decodeNodeClaimPayload} would. */
+export function encodeNodeClaimPayload(payload) {
+    const checked = requireNodeClaimPayload(payload);
+    const json = canonicalJson({ multiaddrs: checked.multiaddrs, peerId: checked.peerId, secret: checked.secret });
+    return `${NODE_CLAIM_PAYLOAD_PREFIX}${uint8ArrayToString(new TextEncoder().encode(json), 'base64url')}`;
+}
+/**
+ * Decode the text a phone scanned or pasted. Refuses, naming the problem: any version but
+ * 1, a body that is not base64url JSON of the right shape, a peer id that does not parse,
+ * an empty address list, an address that does not parse or whose last `/p2p/` is not that
+ * peer id, and a secret {@link parseClaimSecret} refuses. The secret is never echoed.
+ */
+export function decodeNodeClaimPayload(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith(NODE_CLAIM_PAYLOAD_PREFIX)) {
+        throw new Error(`A claim payload must start with "${NODE_CLAIM_PAYLOAD_PREFIX}" (this one starts with "${trimmed.slice(0, NODE_CLAIM_PAYLOAD_PREFIX.length)}")`);
+    }
+    let parsed;
+    try {
+        const json = new TextDecoder().decode(uint8ArrayFromString(trimmed.slice(NODE_CLAIM_PAYLOAD_PREFIX.length), 'base64url'));
+        parsed = JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error('A claim payload must carry base64url-encoded JSON after its prefix', { cause: error });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('A claim payload must decode to a JSON object');
+    }
+    const { peerId, multiaddrs, secret } = parsed;
+    if (typeof peerId !== 'string')
+        throw new Error('A claim payload must name the node\'s peer id');
+    if (!Array.isArray(multiaddrs) || !multiaddrs.every((a) => typeof a === 'string')) {
+        throw new Error('A claim payload must carry the node\'s addresses as a list of strings');
+    }
+    if (typeof secret !== 'string')
+        throw new Error('A claim payload must carry the claim secret');
+    return requireNodeClaimPayload({ peerId, multiaddrs, secret });
+}
+/** The shape rules both directions apply. Returns the payload with its fields trimmed. */
+function requireNodeClaimPayload(payload) {
+    const peerId = parsePeerId(payload.peerId);
+    const multiaddrs = payload.multiaddrs.map((a) => a.trim());
+    if (multiaddrs.length === 0)
+        throw new Error('A claim payload must carry at least one address for the node');
+    for (const addr of multiaddrs)
+        requireAddressOf(addr, peerId);
+    // The secret is checked, never kept in a message: see `parseClaimSecret`.
+    parseClaimSecret(payload.secret);
+    return { peerId: peerId.toString(), multiaddrs, secret: payload.secret.trim() };
+}
+function parsePeerId(text) {
+    try {
+        return peerIdFromString(text.trim());
+    }
+    catch (error) {
+        throw new Error(`A claim payload's peer id does not parse ("${text}")`, { cause: error });
+    }
+}
+/** `addr` parses, and its destination (the last `/p2p/`, past any relay hop) is `peerId`. */
+function requireAddressOf(addr, peerId) {
+    let destination;
+    try {
+        destination = destinationPeerIdOf(addr);
+    }
+    catch (error) {
+        throw new Error(`A claim payload address does not parse ("${addr}")`, { cause: error });
+    }
+    if (destination === null) {
+        throw new Error(`A claim payload address must end in /p2p/${peerId.toString()} ("${addr}" names no peer)`);
+    }
+    let named;
+    try {
+        named = peerIdFromString(destination);
+    }
+    catch (error) {
+        throw new Error(`A claim payload address names a peer id that does not parse ("${addr}")`, { cause: error });
+    }
+    if (!named.equals(peerId)) {
+        throw new Error(`A claim payload address names another peer ("${addr}" is not an address of ${peerId.toString()})`);
+    }
+}
+/**
+ * The peer an address reaches: its last `/p2p/` component. A relayed address
+ * (`…/p2p/<relay>/p2p-circuit/p2p/<destination>`) names its destination after the
+ * circuit hop; one that ends at the hop names nobody. Same rule as
+ * `groupAddrsByPeerId` in `peer-addr-book.ts`.
+ */
+function destinationPeerIdOf(addr) {
+    const components = multiaddr(addr).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;
+}
+//# sourceMappingURL=node-claim-payload.js.map

package/dist/node-claim-payload.js.map

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

package/dist/owner-anchor-sync.d.ts

@@ -0,0 +1,22 @@
+import type { TrustSource } from './trusted-owner-store.js';
+import type { InvitationChain, OwnerKeyRow, RevocationRow } from './types.js';
+export interface OwnerAnchorInputs {
+    /** The party whose table is being read; every stored proof is judged for it, so a voucher or tombstone signed for another party neither seats nor removes a key. */
+    partyId: string;
+    /** The anchor at the start of the pass, every key with its provenance (`TrustedOwnerStore.sources`). */
+    anchor: ReadonlyMap<string, TrustSource>;
+    /** `OwnerKey` rows as read; rows whose stamp a tombstone in `tombstones` retires are dropped here too. */
+    rows: readonly OwnerKeyRow[];
+    /** `Revocation` rows; only those with `tableName === 'OwnerKey'` are consulted. */
+    tombstones: readonly RevocationRow[];
+    /** The usage and invitation rows, when some owner row is invitation-admitted; null skips those rows. */
+    chain: InvitationChain | null;
+}
+export interface OwnerAnchorDerivation {
+    /** The keys the anchor should hold after this pass. */
+    target: ReadonlySet<string>;
+    /** Keys whose verifiable removal was NOT applied because the anchor would have emptied. */
+    refusedRemovals: readonly string[];
+}
+/** The rule above, as one pure function. */
+export declare function deriveOwnerAnchor({ partyId, anchor, rows, tombstones, chain }: OwnerAnchorInputs): OwnerAnchorDerivation;

package/dist/owner-anchor-sync.js

@@ -0,0 +1,143 @@
+/**
+ * How the node-local trusted-owner anchor follows the replicated `OwnerKey` table along
+ * VERIFIABLE chains — the pure rule, with no I/O, so it can be tested without a database.
+ * `CadreNode.syncOwnerAnchor` reads the table, the tombstones and the invitation chain,
+ * calls {@link deriveOwnerAnchor}, and applies the difference to the store.
+ *
+ * Why not simply trust the table: an empty local copy can seat any key through the
+ * schema's genesis branch and that row replicates (`docs/architecture.md` → "Node-local
+ * trusted-owner anchor"). So every node grows its anchor only through rows whose stored
+ * proof verifies against a key it already trusts, on every membership refresh. The terms
+ * used throughout:
+ *
+ * - **base**: the anchor's entries whose provenance is not `chain` (trusted out of band).
+ * - **live row**: an `OwnerKey` row whose stamp no tombstone retires.
+ * - **kept**: a `chain` entry that still has a live row. A derived entry is state, not
+ *   recomputed from the base each pass: it entered through a proof that verified then, and
+ *   it stays until its own row is retired or a verifiable tombstone removes it. This is what
+ *   lets an owner rotate (A adds A', A' removes A): A' keeps its place after A's row is
+ *   retired, although nothing could re-derive it from the remaining base.
+ * - **derivable from S**: a live row whose stored proof verifies against S — owner-signed
+ *   (`vouchSig` set): `vouchOwner` is in S and `verifyOwnerKeyVoucher` holds;
+ *   invitation-admitted (`vouchSig` null, `vouchUsage` set): `verifyInvitationOwnerAdmission`
+ *   holds with S as the anchor. The founding row (all three null) is never derivable:
+ *   founders enter anchors only out of band.
+ * - **derived**: the least fixpoint from base ∪ kept — add every key whose live row is
+ *   derivable from what is already in the set, until nothing changes. **chainDerived** is the
+ *   keys whose live row was derivable in this pass, base keys included.
+ * - **removed**: a key K in derived is removed when an `OwnerKey` tombstone names K, its
+ *   signer is in derived and is not K, its stored signature verifies
+ *   (`verifyRevocationSigner`), AND K is not in chainDerived. The last condition is what
+ *   makes a re-add win over an older tombstone: a removed owner re-added under a fresh
+ *   stamp has a live derivable row again, and the old stamp's tombstone no longer applies.
+ * - **target** = derived minus removed. If that would be empty, no removal is applied this
+ *   pass (target = derived) and the refused removals are reported for the caller to log.
+ *
+ * Every tombstone is judged against the pass-start set (derived) at once, so the outcome
+ * does not depend on the order they are read in: a signer that is itself removed in this
+ * pass still counts, and a mutual removal of the last two owners is refused rather than
+ * decided by read order.
+ *
+ * An owner C that a removed owner B had added therefore stays where it was already derived
+ * (its row is live) and cannot be derived on a machine that never held it (the chain from
+ * that machine's base runs through B's retired row) until a remaining owner re-adds it or
+ * an invitation pins it there. The rotation case above is the same shape with C = A', so the
+ * two cannot be told apart from replicated state; keeping is the only rule under which a
+ * sole owner can rotate at all.
+ */
+import { verifyInvitationOwnerAdmission, verifyOwnerKeyVoucher, verifyRevocationSigner } from './peer-authorization.js';
+/** The rule above, as one pure function. */
+export function deriveOwnerAnchor({ partyId, anchor, rows, tombstones, chain }) {
+    const ownerTombstones = tombstones.filter(tombstone => tombstone.tableName === 'OwnerKey');
+    // NOTE: a stamp is retired by any tombstone that names it, verified or not — the same
+    // reading `queryCadrePeers` and `getOwnerKeys` give the table. A forged tombstone can
+    // therefore prune a derived entry (its row goes) but never seat or keep one; if tombstone
+    // pollution is ever closed at the write side, judge retirement by the verified signer too.
+    const retired = new Set(ownerTombstones.map(tombstone => tombstone.stampId));
+    const liveRows = rows.filter(row => !retired.has(row.stampId));
+    const derived = passStartSet(anchor, liveRows);
+    const chainDerived = deriveFixpoint(partyId, derived, liveRows, chain);
+    const removed = removedKeys(partyId, derived, chainDerived, ownerTombstones);
+    if (removed.size > 0 && removed.size === derived.size) {
+        return { target: derived, refusedRemovals: Array.from(removed) };
+    }
+    const target = new Set(Array.from(derived).filter(key => !removed.has(key)));
+    return { target, refusedRemovals: [] };
+}
+/** base ∪ kept: every out-of-band entry, and every `chain` entry whose row is still live. */
+function passStartSet(anchor, liveRows) {
+    const liveKeys = new Set(liveRows.map(row => row.key));
+    const start = new Set();
+    for (const [key, source] of anchor) {
+        if (source !== 'chain' || liveKeys.has(key)) {
+            start.add(key);
+        }
+    }
+    return start;
+}
+/**
+ * Grow `derived` to the least fixpoint and return chainDerived: every key whose live row was
+ * derivable. A row is judged once its voucher is in the set, and settled either way then:
+ * trust only grows within a pass, and a proof that failed against a trusted voucher cannot
+ * pass later, so no row is verified twice.
+ */
+function deriveFixpoint(partyId, derived, liveRows, chain) {
+    const chainDerived = new Set();
+    const pending = new Set(liveRows);
+    let progress = true;
+    while (progress) {
+        progress = false;
+        for (const row of pending) {
+            if (row.vouchOwner === null || !derived.has(row.vouchOwner)) {
+                continue;
+            }
+            pending.delete(row);
+            if (proofVerifies(partyId, row, derived, chain)) {
+                chainDerived.add(row.key);
+                derived.add(row.key);
+                progress = true;
+            }
+        }
+    }
+    return chainDerived;
+}
+/** Does `row`'s stored proof verify against `trusted`, for `partyId`, by the kind of proof it carries (see the module doc)? */
+function proofVerifies(partyId, row, trusted, chain) {
+    if (row.vouchOwner === null) {
+        return false;
+    }
+    if (row.vouchSig !== null) {
+        return verifyOwnerKeyVoucher(partyId, row.key, row.stampId, row.vouchOwner, row.vouchSig);
+    }
+    if (row.vouchUsage === null) {
+        return false;
+    }
+    const usage = chain?.usages.get(row.vouchUsage);
+    const invite = usage === undefined ? undefined : chain?.invites.get(usage.inviteKey);
+    if (usage === undefined || invite === undefined) {
+        return false;
+    }
+    return verifyInvitationOwnerAdmission(partyId, row, usage, invite, key => trusted.has(key));
+}
+/**
+ * The keys of `derived` that a verifiable tombstone removes (see the module doc), every
+ * tombstone judged against the same pass-start set. A tombstone for a key outside `derived`
+ * changes nothing and is skipped before any signature work.
+ */
+function removedKeys(partyId, derived, chainDerived, ownerTombstones) {
+    const removed = new Set();
+    for (const tombstone of ownerTombstones) {
+        const key = tombstone.rowKey;
+        if (!derived.has(key) || chainDerived.has(key) || removed.has(key)) {
+            continue;
+        }
+        if (tombstone.signerKey === key || !derived.has(tombstone.signerKey)) {
+            continue;
+        }
+        if (verifyRevocationSigner(partyId, tombstone)) {
+            removed.add(key);
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=owner-anchor-sync.js.map

package/dist/owner-anchor-sync.js.map

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

package/dist/peer-authorization.d.ts

@@ -1,4 +1,5 @@
-import type { RevocableTable } from './control-authorization.js';
+import type { CadreInviteSignedFields, RevocableTable } from './control-authorization.js';
+import type { CadreInviteRow, CadreInviteUsageRow, CadrePeerVoucherFields, OwnerKeyRow, RevocationRow } from './types.js';
 /**
  * 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
@@ -34,7 +35,7 @@ export interface DeviceTokenAuthorizedRow {
 /**
  * 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,
+ * `digest('CadreControl.DeviceToken', 'add', party_id(), new.PeerId, new.Platform, new.Token,
  * coalesce(cast(new.UpdatedAt as text), ''), coalesce(new.Sig, ''), new.StampId)` in
  * `DeviceToken.AuthorizedInsert`.
  *
@@ -50,11 +51,11 @@ export interface DeviceTokenAuthorizedRow {
  * 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;
+export declare function deviceTokenAddDigest(partyId: string, 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
+ * `digest('CadreControl.DeviceToken', 'remove', party_id(), old.PeerId, old.StampId)` in
  * `DeviceToken.AuthorizedDelete`.
  *
  * A narrower vector than {@link deviceTokenAddDigest} on purpose (the same split
@@ -62,7 +63,7 @@ export declare function deviceTokenAddDigest(row: DeviceTokenAuthorizedRow): str
  * 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;
+export declare function deviceTokenRemoveDigest(partyId: string, peerId: string, stampId: string): string;
 /**
  * Canonical digest an owner signs to VOUCH a `CadrePeer` membership row (insert
  * and the owner re-touch update — same semantics, deliberately the same digest).
@@ -74,9 +75,9 @@ export declare function deviceTokenRemoveDigest(peerId: string, stampId: string)
  * 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)`.
+ * SQL mirror: `digest('CadreControl.CadrePeer', 'vouch', party_id(), new.PeerId, new.StampId)`.
  */
-export declare function cadrePeerVoucherDigest(peerId: string, stampId: string): string;
+export declare function cadrePeerVoucherDigest(partyId: string, peerId: string, stampId: string): string;
 /**
  * Canonical digest an owner signs to REMOVE a `CadrePeer` row. Deliberately a
  * distinct payload from {@link cadrePeerVoucherDigest} (the `'remove'` action tag)
@@ -86,16 +87,16 @@ export declare function cadrePeerVoucherDigest(peerId: string, stampId: string):
  * 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)`.
+ * SQL mirror: `digest('CadreControl.CadrePeer', 'remove', party_id(), old.PeerId, old.StampId)`.
  */
-export declare function cadrePeerRemoveDigest(peerId: string, stampId: string): string;
+export declare function cadrePeerRemoveDigest(partyId: string, 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)`
+ * `digest('CadreControl.Revocation', 'remove', party_id(), new.TableName, new.RowKey, new.StampId)`
  * in `Revocation.Authorized`.
  *
  * Its own `'CadreControl.Revocation'` domain tag makes it disjoint from the
@@ -104,7 +105,28 @@ export declare function cadrePeerRemoveDigest(peerId: string, stampId: string):
  * 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;
+export declare function revocationDigest(partyId: string, tableName: RevocableTable, rowKey: string, stampId: string): string;
+/**
+ * Does a `Revocation` row's stored signer pair (`SignerKey` / `SignerSig`) verify over the
+ * tombstone's own triple, for `partyId`? The read-side mirror of `Revocation.Authorized`,
+ * for a node that received the row by replication and must decide whether to honour it.
+ * Whether `row.signerKey` is an owner this node trusts is the caller's question, as for
+ * {@link verifyCadrePeerVoucher}. Never throws: a malformed row verifies as `false`.
+ */
+export declare function verifyRevocationSigner(partyId: string, row: RevocationRow): boolean;
+/**
+ * Canonical digest an owner signs to seat a further `OwnerKey` row — the signed-add branch
+ * of `OwnerKey.Authorized`, which stores the pair as `VouchOwner` / `VouchSig`. SQL mirror:
+ * `digest('CadreControl.OwnerKey', 'add', party_id(), new.Key, new.StampId)`. The removal
+ * digest needs no builder here: it is the generic guarded `'remove'` digest over (Key, StampId).
+ */
+export declare function ownerKeyAddDigest(partyId: string, key: string, stampId: string): string;
+/**
+ * Does an owner-signed `OwnerKey` row's stored voucher verify — `vouchSig` by `vouchOwner`
+ * over {@link ownerKeyAddDigest} for (`partyId`, `key`, `stampId`)? Whether `vouchOwner` is
+ * anchored is the caller's question, as for {@link verifyCadrePeerVoucher}. Never throws.
+ */
+export declare function verifyOwnerKeyVoucher(partyId: string, key: string, stampId: string, vouchOwner: string, vouchSig: string): boolean;
 /**
  * Verify that `signature` is a valid owner ed25519 signature over `peerId`'s
  * authorization digest, using `ownerPublicKey` (base64url).
@@ -122,12 +144,13 @@ export declare function revocationDigest(tableName: RevocableTable, rowKey: stri
 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
+ * `CadrePeer` voucher digest for (`partyId`, `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
+ * row (the peer id bound to the row's single-use `StampId` nonce) in THIS party: a
+ * voucher copied from another party's table that shares the owner key fails. 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.
@@ -136,14 +159,14 @@ export declare function verifyPeerAuthorization(peerId: string, ownerPublicKey:
  * {@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;
+export declare function verifyCadrePeerVoucher(partyId: string, 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.
+ * {@link unboundTaggedDigest}). That doc comment carries the field-vector rationale
+ * (notably why neither `strandId` nor the party id is 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;
 /**
@@ -163,3 +186,75 @@ export declare function verifyFormationConsent(row: {
     disclosure: string;
     peerSig: string;
 }): boolean;
+/**
+ * Canonical digest an owner signs to seat a `CadreInvite` row — the read-side mirror
+ * of `cadreInviteAddMessage` in control-database.ts, base64url instead of raw bytes
+ * (see {@link taggedDigest}). The whole row is bound, nullable columns as `''` and
+ * `ExpiresAt` in its stored canonical form, through the one field builder both sides
+ * share (`cadreInviteRowFields`). SQL mirror: `CadreInvite.AuthorizedInsert`.
+ */
+export declare function cadreInviteAddDigest(partyId: string, row: CadreInviteSignedFields): string;
+/**
+ * Canonical digest the HOLDER of a `CadreInvite`'s private key signs to redeem it once:
+ * proof of possession, verified against the invitation key itself
+ * (`CadreInviteUsage.InvitePossessed`). Binds the redemption's single-use nonce and the
+ * device being admitted, so one redemption cannot be re-presented for another device
+ * or another use. Mirror of `cadreInviteRedeemMessage` in control-database.ts.
+ */
+export declare function cadreInviteRedeemDigest(partyId: string, inviteKey: string, usageStampId: string, peerKey: string): string;
+/**
+ * Canonical digest the DEVICE signs to consent to being admitted by one redemption
+ * (`CadreInviteUsage.PeerConsented`), over the same fields as
+ * {@link cadreInviteRedeemDigest} under a distinct action tag, so the holder's and
+ * the device's signatures are never interchangeable. Mirror of
+ * `cadreInviteConsentMessage` in control-database.ts.
+ */
+export declare function cadreInviteConsentDigest(partyId: string, inviteKey: string, usageStampId: string, peerKey: string): string;
+/**
+ * Does a `CadreInvite` row carry a valid `'add'` signature by its own `issuerKey`, for
+ * `partyId`? The redeeming device runs this over the row a member replies with, after
+ * checking the issuer against its pinned owner keys and the reply's party against the
+ * invitation's, and a member over a bundle's copy it does not hold yet
+ * (`ControlDatabase.isCadreInviteLive`); whether that issuer IS an owner is the caller's question.
+ * Never throws: a malformed row verifies as `false`.
+ */
+export declare function verifyCadreInviteRow(partyId: string, invite: CadreInviteRow): boolean;
+/**
+ * The two signatures a redemption carries, checked before any database work: the holder's
+ * `'redeem'` signature with the invitation key, and the device's `'consent'` signature with
+ * its own key, both over (`inviteKey`, `usageStampId`, `peerKey`). The pre-check twin of
+ * `CadreInviteUsage.InvitePossessed` / `PeerConsented`, as `verifyFormationConsent` is for
+ * formation: the schema stays the authority, this turns a bad signature into a clean
+ * refusal instead of a constraint failure at commit. Never throws.
+ */
+export declare function verifyCadreInviteRedemption(partyId: string, fields: {
+    inviteKey: string;
+    usageStampId: string;
+    peerKey: string;
+}, inviteSig: string, peerSig: string): boolean;
+/**
+ * Is an invitation-admitted `CadrePeer` row (`vouchSig` null, `vouchUsage` set) a
+ * member this node should trust? The read-side mirror of the consent branch of
+ * `CadrePeer.AuthorizedInsert`, re-checked against THIS node's anchor because the
+ * replicated `OwnerKey` table can be polluted. The usage must name this peer id and this
+ * exact row incarnation (`peerStampId`); every other link is {@link verifyAdmissionChain}.
+ *
+ * Expiry, use count and withdrawal are deliberately NOT re-checked: they were conditions
+ * at redemption (`CadreInviteUsage.Authorized`), and membership persists until an owner
+ * removes the row — exactly as an owner-vouched row's membership does. Keeping a device
+ * out is removing its row AND withdrawing the invitation.
+ *
+ * Returns a boolean and never throws (the siblings' contract): malformed input or any
+ * crypto failure resolves to `false`, logged at debug.
+ */
+export declare function verifyInvitationAdmission(partyId: string, row: CadrePeerVoucherFields, usage: CadreInviteUsageRow, invite: CadreInviteRow, isAnchored: (ownerKey: string) => boolean): boolean;
+/**
+ * Is an invitation-admitted `OwnerKey` row (`vouchSig` null, `vouchUsage` set) an owner
+ * this node should derive into its anchor? The read-side mirror of the consent branch of
+ * `OwnerKey.Authorized` (`owner-anchor-sync.ts` → `deriveOwnerAnchor`): the invitation
+ * must grant ownership, and the usage must name this key (`peerKey`) and this exact row
+ * incarnation (`ownerStampId`); every other link is {@link verifyAdmissionChain}. Same
+ * never-throws contract and the same deliberate omissions as
+ * {@link verifyInvitationAdmission}.
+ */
+export declare function verifyInvitationOwnerAdmission(partyId: string, row: OwnerKeyRow, usage: CadreInviteUsageRow, invite: CadreInviteRow, isAnchored: (ownerKey: string) => boolean): boolean;