@serfab/cadre-core 1.16.0 → 1.17.0

package/dist/owner-keys.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Owner keys as an app lists, adds and removes them (`CadreNode.listOwnerKeys`,
+ * `CadreNode.addOwner`, `CadreNode.planOwnerKeyRemoval`, `CadreNode.removeOwner`): the
+ * projection of the live `OwnerKey` rows an owner-key screen shows, the read-only plan behind a
+ * removal's confirmation step, the check that a requested re-vouch stays inside that plan, and
+ * the by-name refusals. Pure; the reads and writes themselves are `CadreNode`'s and
+ * `ControlDatabase`'s.
+ */
+import type { CadreOwnerKey, CadrePeerRow, OwnerGrantStatus, OwnerKeyAddRefusal, OwnerKeyDependents, OwnerKeyRemovalPlan, OwnerKeyRemovalRefusal, OwnerKeyRow, RemoveOwnerOptions } from './types.js';
+/**
+ * `CadreNode.addOwner` refused by name, before any write. `code` says which rule
+ * ({@link OwnerKeyAddRefusal}), for an app to switch on; the message is for a log.
+ */
+export declare class OwnerKeyAddRefusedError extends Error {
+    readonly code: OwnerKeyAddRefusal;
+    readonly key: string;
+    constructor(key: string, code: OwnerKeyAddRefusal);
+}
+/**
+ * `CadreNode.removeOwner` refused by name, before any write. `code` says which rule
+ * ({@link OwnerKeyRemovalRefusal}), for an app to switch on; the message is for a log.
+ */
+export declare class OwnerKeyRemovalRefusedError extends Error {
+    readonly code: OwnerKeyRemovalRefusal;
+    readonly key: string;
+    constructor(key: string, code: OwnerKeyRemovalRefusal);
+}
+/** An owner key as an approval prompt names it: `"label" (key)`, or the key alone when it has no label. */
+export declare function namedOwnerKey(key: string, label: string | null): string;
+/**
+ * One {@link CadreOwnerKey} per live row, in the rows' order. `heldKey` is the key of this
+ * node's owner signer, if one is wired; `anchor` is this node's trusted-owner anchor.
+ */
+export declare function describeOwnerKeys(rows: readonly OwnerKeyRow[], heldKey: string | null, anchor: ReadonlySet<string>): CadreOwnerKey[];
+/** What {@link planOwnerKeyRemoval} judges from: one node's live rows and its own standing. */
+export interface OwnerKeyRemovalPlanInput {
+    key: string;
+    /** Live `CadrePeer` rows (`ControlDatabase.queryCadrePeers`). */
+    rows: readonly CadrePeerRow[];
+    /** Live `OwnerKey` rows (`ControlDatabase.queryOwnerKeyRows`). */
+    owners: readonly OwnerKeyRow[];
+    /** Every owner grant with its standing (`ControlDatabase.listOwnerGrantStatuses`); the live ones the key issued are the plan's `grants`. */
+    grants: readonly OwnerGrantStatus[];
+    selfPeerId: string | null;
+    /** The key of this node's owner signer when it is an enrolled owner (`CadreNode.ownerSignerEnrolledIn`), or null when it cannot sign owner writes. */
+    selfOwnerKey: string | null;
+    /** This node's trusted-owner anchor, for the listed entry's `trusted`. */
+    anchor: ReadonlySet<string>;
+}
+/**
+ * The plan for removing owner key `key` from these rows. The refusals come first and by name: a
+ * node that cannot sign; a key with no live row; the only live owner key (`MinOneOwner`), ahead
+ * of `self` so a sole owner asking to remove its own key hears the rule no other owner could
+ * get past either; and this node's own key, since the schema's remove branch wants a signer
+ * other than the removed key. With this node enrolled, a different live key always leaves two
+ * owners in one read, so `last-owner` reaches only that case, and concurrent removals elsewhere
+ * leave the schema to decide.
+ *
+ * `dependents` are the rows the key vouched, which every reader judges against its anchor
+ * through `VouchOwner`: once the key is removed they stop passing the membership predicate on
+ * every machine unless re-vouched first. This node's own rows are not among them. Its own
+ * `CadrePeer` row is re-vouched unasked (`revouchesOwnRow`): left on the removed key, every other
+ * machine would drop the remover. Its own `OwnerKey` row is reported as `ownDependency`, since
+ * re-vouching it would mean signing its own removal.
+ *
+ * `grants` are the live owner grants the key issued: a redemption wants a live issuer, so they
+ * stop working with the removal. They are listed, not withdrawn (`removeOwner` leaves them: a
+ * tombstone over a grant that can no longer be redeemed would add nothing).
+ */
+export declare function planOwnerKeyRemoval(input: OwnerKeyRemovalPlanInput): OwnerKeyRemovalPlan;
+/**
+ * The re-vouch `CadreNode.removeOwner` makes: what the caller asked for, checked against the
+ * plan, plus this node's own row (`selfPeerId`, first) when `plan.revouchesOwnRow`. Every
+ * requested key and peer must be in `plan.dependents`, so a caller cannot re-vouch a row the
+ * removed key never vouched. Throws naming the offenders, before anything is written.
+ * Duplicates are dropped.
+ */
+export declare function revouchWithinPlan(plan: OwnerKeyRemovalPlan, revouch: RemoveOwnerOptions['revouch'], selfPeerId: string | null): OwnerKeyDependents;

package/dist/owner-keys.js

@@ -0,0 +1,133 @@
+/**
+ * Owner keys as an app lists, adds and removes them (`CadreNode.listOwnerKeys`,
+ * `CadreNode.addOwner`, `CadreNode.planOwnerKeyRemoval`, `CadreNode.removeOwner`): the
+ * projection of the live `OwnerKey` rows an owner-key screen shows, the read-only plan behind a
+ * removal's confirmation step, the check that a requested re-vouch stays inside that plan, and
+ * the by-name refusals. Pure; the reads and writes themselves are `CadreNode`'s and
+ * `ControlDatabase`'s.
+ */
+/**
+ * `CadreNode.addOwner` refused by name, before any write. `code` says which rule
+ * ({@link OwnerKeyAddRefusal}), for an app to switch on; the message is for a log.
+ */
+export class OwnerKeyAddRefusedError extends Error {
+    constructor(key, code) {
+        super(`Cannot add owner key ${key}: ${OWNER_KEY_ADD_REFUSAL_REASON[code]}`);
+        this.name = 'OwnerKeyAddRefusedError';
+        this.code = code;
+        this.key = key;
+    }
+}
+const OWNER_KEY_ADD_REFUSAL_REASON = {
+    'alone': 'this node has no connection to the rest of the cadre, and an owner key added now would reach no other machine; try again once connected',
+};
+/**
+ * `CadreNode.removeOwner` refused by name, before any write. `code` says which rule
+ * ({@link OwnerKeyRemovalRefusal}), for an app to switch on; the message is for a log.
+ */
+export class OwnerKeyRemovalRefusedError extends Error {
+    constructor(key, code) {
+        super(`Cannot remove owner key ${key}: ${OWNER_KEY_REMOVAL_REFUSAL_REASON[code]}`);
+        this.name = 'OwnerKeyRemovalRefusedError';
+        this.code = code;
+        this.key = key;
+    }
+}
+const OWNER_KEY_REMOVAL_REFUSAL_REASON = {
+    'not-an-owner': 'this node holds no enrolled owner key',
+    'unknown': 'it is not a live owner key here',
+    'last-owner': 'it is the only live owner key',
+    'self': 'it is the owner key of this node, and an owner key cannot sign its own removal; ask another owner key',
+    'alone': 'this node has no connection to the rest of the cadre, and an owner key re-vouched now would reach no other machine; try again once connected',
+};
+/** An owner key as an approval prompt names it: `"label" (key)`, or the key alone when it has no label. */
+export function namedOwnerKey(key, label) {
+    return label === null ? key : `"${label}" (${key})`;
+}
+/**
+ * One {@link CadreOwnerKey} per live row, in the rows' order. `heldKey` is the key of this
+ * node's owner signer, if one is wired; `anchor` is this node's trusted-owner anchor.
+ */
+export function describeOwnerKeys(rows, heldKey, anchor) {
+    return rows.map((row) => ({
+        key: row.key,
+        label: row.label,
+        vouchedBy: row.vouchOwner,
+        heldHere: row.key === heldKey,
+        trusted: anchor.has(row.key),
+    }));
+}
+/**
+ * The plan for removing owner key `key` from these rows. The refusals come first and by name: a
+ * node that cannot sign; a key with no live row; the only live owner key (`MinOneOwner`), ahead
+ * of `self` so a sole owner asking to remove its own key hears the rule no other owner could
+ * get past either; and this node's own key, since the schema's remove branch wants a signer
+ * other than the removed key. With this node enrolled, a different live key always leaves two
+ * owners in one read, so `last-owner` reaches only that case, and concurrent removals elsewhere
+ * leave the schema to decide.
+ *
+ * `dependents` are the rows the key vouched, which every reader judges against its anchor
+ * through `VouchOwner`: once the key is removed they stop passing the membership predicate on
+ * every machine unless re-vouched first. This node's own rows are not among them. Its own
+ * `CadrePeer` row is re-vouched unasked (`revouchesOwnRow`): left on the removed key, every other
+ * machine would drop the remover. Its own `OwnerKey` row is reported as `ownDependency`, since
+ * re-vouching it would mean signing its own removal.
+ *
+ * `grants` are the live owner grants the key issued: a redemption wants a live issuer, so they
+ * stop working with the removal. They are listed, not withdrawn (`removeOwner` leaves them: a
+ * tombstone over a grant that can no longer be redeemed would add nothing).
+ */
+export function planOwnerKeyRemoval(input) {
+    const row = input.owners.find((owner) => owner.key === input.key) ?? null;
+    return {
+        ownerKey: row === null ? null : describeOwnerKeys([row], input.selfOwnerKey, input.anchor)[0],
+        refusal: removalRefusalFor(input, row !== null),
+        dependents: dependentsOf(input),
+        revouchesOwnRow: input.rows.some((own) => own.peerId === input.selfPeerId && own.vouchOwner === input.key),
+        ownDependency: input.owners.some((own) => own.key === input.selfOwnerKey && own.vouchOwner === input.key),
+        grants: input.grants.filter((status) => status.live && status.grant.issuerKey === input.key).map((status) => status.grant),
+    };
+}
+function removalRefusalFor(input, live) {
+    if (input.selfOwnerKey === null) {
+        return 'not-an-owner';
+    }
+    if (!live) {
+        return 'unknown';
+    }
+    if (input.owners.length <= 1) {
+        return 'last-owner';
+    }
+    if (input.key === input.selfOwnerKey) {
+        return 'self';
+    }
+    return null;
+}
+function dependentsOf(input) {
+    return {
+        owners: input.owners
+            .filter((owner) => owner.vouchOwner === input.key && owner.key !== input.key && owner.key !== input.selfOwnerKey)
+            .map((owner) => owner.key),
+        peers: input.rows
+            .filter((row) => row.vouchOwner === input.key && row.peerId !== input.selfPeerId)
+            .map((row) => row.peerId),
+    };
+}
+/**
+ * The re-vouch `CadreNode.removeOwner` makes: what the caller asked for, checked against the
+ * plan, plus this node's own row (`selfPeerId`, first) when `plan.revouchesOwnRow`. Every
+ * requested key and peer must be in `plan.dependents`, so a caller cannot re-vouch a row the
+ * removed key never vouched. Throws naming the offenders, before anything is written.
+ * Duplicates are dropped.
+ */
+export function revouchWithinPlan(plan, revouch, selfPeerId) {
+    const owners = [...new Set(revouch?.owners ?? [])];
+    const peers = [...new Set(revouch?.peers ?? [])];
+    const strayOwners = owners.filter((key) => !plan.dependents.owners.includes(key));
+    const strayPeers = peers.filter((peerId) => !plan.dependents.peers.includes(peerId));
+    if (strayOwners.length > 0 || strayPeers.length > 0) {
+        throw new Error(`removeOwner: re-vouch names rows the removed owner key did not vouch: ${[...strayOwners, ...strayPeers].join(', ')}`);
+    }
+    return { owners, peers: plan.revouchesOwnRow && selfPeerId !== null ? [selfPeerId, ...peers] : peers };
+}
+//# sourceMappingURL=owner-keys.js.map

package/dist/owner-keys.js.map

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

package/dist/owner-signer.d.ts

@@ -0,0 +1,54 @@
+/** What a backend that asks the user shows them. */
+export interface OwnerSigningRequest {
+    /** The cadre the signatures are for. Every owner digest already binds it (`party_id()`); a prompting backend shows it. */
+    partyId: string;
+    /** What the user is approving, in plain words ("Remove the machine 12D3…", "Add owner key ‹label›"). */
+    action: string;
+}
+/** Signs one message (the raw bytes of an owner digest, e.g. `buildAuthorizationMessage` output); resolves to a base64url Ed25519 signature. */
+export type OwnerSign = (message: Uint8Array) => Promise<string>;
+/**
+ * An owner key the node can ask for signatures.
+ *
+ * One action, one {@link approve} call, however many rows it signs: the control schema verifies
+ * one signature per row, and one owner action writes several (a removal signs the delete and its
+ * `Revocation` tombstone; a machine removal signs many). A hardware or biometric backend prompts
+ * once per call, as PIV touch caching and the platform vaults' authentication-validity windows
+ * allow. Handing the signer every digest up front was declined: each writer reads the stamps it
+ * signs inside its write lock, so precomputing them would duplicate each writer's digest
+ * construction outside it.
+ */
+export interface OwnerSigner {
+    /** base64url Ed25519 public key — the `OwnerKey.Key` this signer signs for. */
+    readonly publicKey: string;
+    /**
+     * Run one user-approved action. A backend that prompts does so at most once per call and may
+     * keep the user's presence until `body` settles. Rejects with {@link OwnerSigningDeclinedError}
+     * when the user declines, and with whatever `body` rejects with otherwise.
+     */
+    approve<T>(request: OwnerSigningRequest, body: (sign: OwnerSign) => Promise<T>): Promise<T>;
+}
+/**
+ * Run `body` inside the caller's open approval when it passes `sign`, else inside one new
+ * approval of `signer` for `request`. An owner write that is sometimes a whole action and
+ * sometimes one step of a larger one takes an optional `sign` and goes through this, so the
+ * larger action still asks once.
+ */
+export declare function withinOwnerApproval<T>(signer: OwnerSigner, request: OwnerSigningRequest, sign: OwnerSign | undefined, body: (sign: OwnerSign) => Promise<T>): Promise<T>;
+/** Thrown by a prompting backend when the user declines or the prompt times out. */
+export declare class OwnerSigningDeclinedError extends Error {
+    readonly request: OwnerSigningRequest;
+    constructor(request: OwnerSigningRequest, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * An {@link OwnerSigner} over a private key held in memory: never prompts, signs whatever its
+ * `approve` body asks. Its signed input is the digest bytes, base64url-encoded, so its signatures
+ * are byte-for-byte those of any signer that signs the raw bytes with the same key (Ed25519 is
+ * deterministic).
+ *
+ * @param privateKeyB64 - The owner key's 32-byte Ed25519 seed, base64url.
+ * @throws If `privateKeyB64` is not a 32-byte seed in base64url.
+ */
+export declare function softwareOwnerSigner(privateKeyB64: string): OwnerSigner;

package/dist/owner-signer.js

@@ -0,0 +1,51 @@
+/**
+ * The owner signer: the one interface a node's owner signatures go through
+ * (`docs/architecture.md` → Owner Keys → The owner signer).
+ *
+ * cadre-core needs owner signatures, never an owner private key, so a backend that keeps the
+ * key where the node cannot read it (a hardware key, a vault behind biometrics) fits the same
+ * seam as {@link softwareOwnerSigner}.
+ *
+ * Imports only `@optimystic/quereus-plugin-crypto` and `uint8arrays`, so it loads on React
+ * Native and in the browser.
+ */
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import { sign } from '@optimystic/quereus-plugin-crypto';
+import { ed25519PublicKeyFromPrivate, requireEd25519PrivateKeyB64 } from './ed25519-key.js';
+/**
+ * Run `body` inside the caller's open approval when it passes `sign`, else inside one new
+ * approval of `signer` for `request`. An owner write that is sometimes a whole action and
+ * sometimes one step of a larger one takes an optional `sign` and goes through this, so the
+ * larger action still asks once.
+ */
+export async function withinOwnerApproval(signer, request, sign, body) {
+    return sign ? await body(sign) : await signer.approve(request, body);
+}
+/** Thrown by a prompting backend when the user declines or the prompt times out. */
+export class OwnerSigningDeclinedError extends Error {
+    constructor(request, options) {
+        super(`Owner approval was declined or timed out: ${request.action}`, options);
+        this.name = 'OwnerSigningDeclinedError';
+        this.request = request;
+    }
+}
+/**
+ * An {@link OwnerSigner} over a private key held in memory: never prompts, signs whatever its
+ * `approve` body asks. Its signed input is the digest bytes, base64url-encoded, so its signatures
+ * are byte-for-byte those of any signer that signs the raw bytes with the same key (Ed25519 is
+ * deterministic).
+ *
+ * @param privateKeyB64 - The owner key's 32-byte Ed25519 seed, base64url.
+ * @throws If `privateKeyB64` is not a 32-byte seed in base64url.
+ */
+export function softwareOwnerSigner(privateKeyB64) {
+    const privateKey = requireEd25519PrivateKeyB64(privateKeyB64, 'owner private key');
+    const signMessage = async (message) => sign(uint8ArrayToString(message, 'base64url'), privateKey, 'ed25519', 'base64url', 'base64url', 'base64url');
+    return {
+        publicKey: ed25519PublicKeyFromPrivate(privateKey),
+        async approve(_request, body) {
+            return await body(signMessage);
+        },
+    };
+}
+//# sourceMappingURL=owner-signer.js.map

package/dist/owner-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-signer.js","sourceRoot":"","sources":["../src/owner-signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,mCAAmC,CAAC;AACzD,OAAO,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAmC5F;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,MAAmB,EACnB,OAA4B,EAC5B,IAA2B,EAC3B,IAAqC;IAErC,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACtE,CAAC;AAED,oFAAoF;AACpF,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAGnD,YAAY,OAA4B,EAAE,OAA6B;QACtE,KAAK,CAAC,6CAA6C,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;QAC9E,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,aAAqB;IACxD,MAAM,UAAU,GAAG,2BAA2B,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC;IACnF,MAAM,WAAW,GAAc,KAAK,EAAE,OAAO,EAAE,EAAE,CAChD,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,CAAW,CAAC;IACxH,OAAO;QACN,SAAS,EAAE,2BAA2B,CAAC,UAAU,CAAC;QAClD,KAAK,CAAC,OAAO,CAAI,QAA6B,EAAE,IAAqC;YACpF,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC;QAChC,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/peer-authorization.d.ts

@@ -1,5 +1,5 @@
-import type { CadreInviteSignedFields, RevocableTable } from './control-authorization.js';
-import type { CadreInviteRow, CadreInviteUsageRow, CadrePeerVoucherFields, OwnerKeyRow, RevocationRow } from './types.js';
+import type { CadreInviteSignedFields, OwnerGrantSignedFields, RevocableTable } from './control-authorization.js';
+import type { CadreInviteRow, CadreInviteUsageRow, CadrePeerVoucherFields, OwnerGrantRow, OwnerGrantUsageRow, 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
@@ -117,16 +117,18 @@ export declare function verifyRevocationSigner(partyId: string, row: RevocationR
 /**
  * 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).
+ * `digest('CadreControl.OwnerKey', 'add', party_id(), new.Key, coalesce(new.Label, ''), 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;
+export declare function ownerKeyAddDigest(partyId: string, key: string, label: string | null, 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.
+ * over {@link ownerKeyAddDigest} for (`partyId`, `key`, `label`, `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;
+export declare function verifyOwnerKeyVoucher(partyId: string, key: string, label: string | null, stampId: string, vouchOwner: string, vouchSig: string): boolean;
 /**
  * Verify that `signature` is a valid owner ed25519 signature over `peerId`'s
  * authorization digest, using `ownerPublicKey` (base64url).
@@ -236,8 +238,20 @@ export declare function verifyCadreInviteRedemption(partyId: string, fields: {
  * 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}.
+ * replicated `OwnerKey` table can be polluted. The chain is
+ *
+ *   row --vouchUsage--> usage --inviteKey--> invitation --issuerKey--> anchored owner
+ *
+ * and every link is verified: the issuer is anchored (`isAnchored`) and is the row's
+ * `vouchOwner`; the usage is the row's `vouchUsage`, names this peer id and this exact row
+ * incarnation (`peerStampId`), and names this invitation; a targeted invitation names the
+ * redeeming device; the stored `peerKey` really is the key behind the usage's `peerId` (the
+ * schema cannot unwrap a multihash, so a writer could assert any pair); the invitation's
+ * stored `'add'` signature verifies over the row rebuilt from its columns; the holder's
+ * `'redeem'` signature verifies with the invitation key and the device's `'consent'`
+ * signature with its own key. All three signatures are judged for `partyId`. A machine
+ * invitation admits a machine and nothing else, so no `OwnerKey` row is ever verified
+ * through this chain; a grant-seated owner row is {@link verifyOwnerGrantAdmission}'s.
  *
  * Expiry, use count and withdrawal are deliberately NOT re-checked: they were conditions
  * at redemption (`CadreInviteUsage.Authorized`), and membership persists until an owner
@@ -249,12 +263,63 @@ export declare function verifyCadreInviteRedemption(partyId: string, fields: {
  */
 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}.
+ * Canonical digest an owner signs to seat an `OwnerGrant` row — the read-side mirror of
+ * `ownerGrantAddMessage` in control-database.ts, base64url instead of raw bytes. The whole
+ * row is bound, the label included, through the one field builder both sides share
+ * (`ownerGrantRowFields`). SQL mirror: `OwnerGrant.AuthorizedInsert`.
+ */
+export declare function ownerGrantAddDigest(partyId: string, row: OwnerGrantSignedFields): string;
+/**
+ * Canonical digest the HOLDER of an `OwnerGrant`'s private key signs to redeem it once:
+ * proof of possession, verified against the grant key itself
+ * (`OwnerGrantUsage.GrantPossessed`). Binds the redemption's nonce and the key being seated,
+ * so one redemption cannot be re-presented for another key or another use. Mirror of
+ * `ownerGrantRedeemMessage` in control-database.ts.
+ */
+export declare function ownerGrantRedeemDigest(partyId: string, grantKey: string, usageStampId: string, seatedKey: string): string;
+/**
+ * Canonical digest the key being SEATED signs to prove it is held by the redeemer
+ * (`OwnerGrantUsage.OwnerConsented`), over the same fields as {@link ownerGrantRedeemDigest}
+ * under a distinct action tag, so the holder's and the key's signatures are never
+ * interchangeable. Mirror of `ownerGrantConsentMessage` in control-database.ts.
+ */
+export declare function ownerGrantConsentDigest(partyId: string, grantKey: string, usageStampId: string, seatedKey: string): string;
+/**
+ * Does an `OwnerGrant` row carry a valid `'add'` signature by its own `issuerKey`, for
+ * `partyId`? The grant twin of {@link verifyCadreInviteRow}, with the same contract: whether
+ * that issuer IS an owner is the caller's question, and a malformed row verifies as `false`.
+ */
+export declare function verifyOwnerGrantRow(partyId: string, grant: OwnerGrantRow): boolean;
+/**
+ * The two signatures an owner-grant redemption carries, checked before any database work:
+ * the holder's `'redeem'` signature with the grant key and the seated key's `'consent'`
+ * signature with itself, both over (`grantKey`, `usageStampId`, `seatedKey`). The grant twin
+ * of {@link verifyCadreInviteRedemption}, with the same contract: the schema
+ * (`OwnerGrantUsage.GrantPossessed` / `OwnerConsented`) stays the authority, this turns a bad
+ * signature into a clean refusal instead of a constraint failure at commit. Never throws.
+ */
+export declare function verifyOwnerGrantRedemption(partyId: string, fields: {
+    grantKey: string;
+    usageStampId: string;
+    seatedKey: string;
+}, grantSig: string, ownerSig: string): boolean;
+/**
+ * Is a grant-seated `OwnerKey` row (`vouchSig` null, `vouchUsage` naming an `OwnerGrantUsage`
+ * row) an owner this node should derive into its anchor? The read-side mirror of the grant
+ * branch of `OwnerKey.Authorized` (`owner-anchor-sync.ts` → `deriveOwnerAnchor`). The chain is
+ *
+ *   row --vouchUsage--> usage --grantKey--> grant --issuerKey--> anchored owner
+ *
+ * and every link is verified: the issuer is anchored and is the row's `vouchOwner`; the usage
+ * is the row's `vouchUsage` and names this key and this exact row incarnation
+ * (`seatedStampId`); the usage names this grant; the row carries the grant's label; the
+ * grant's stored `'add'` signature verifies over the row rebuilt from its columns; the
+ * holder's `'redeem'` signature verifies with the grant key and the seated key's `'consent'`
+ * signature with itself. All three signatures are judged for `partyId`.
+ *
+ * Expiry, use count and withdrawal are deliberately NOT re-checked, as
+ * {@link verifyInvitationAdmission} omits them: they were conditions at redemption
+ * (`OwnerGrantUsage.Authorized`), and ownership persists until an owner removes the row.
+ * Same never-throws contract as the siblings.
  */
-export declare function verifyInvitationOwnerAdmission(partyId: string, row: OwnerKeyRow, usage: CadreInviteUsageRow, invite: CadreInviteRow, isAnchored: (ownerKey: string) => boolean): boolean;
+export declare function verifyOwnerGrantAdmission(partyId: string, row: OwnerKeyRow, usage: OwnerGrantUsageRow, grant: OwnerGrantRow, isAnchored: (ownerKey: string) => boolean): boolean;