@serfab/cadre-core 1.15.0 → 1.17.0

package/src/types.ts

@@ -17,8 +17,10 @@ import type { StrandNetworkStateStore } from './strand-network-state.js';
 import type { EnrolledMachineStore } from './enrolled-machine-store.js';
 import type { JoinedStrandStore } from './joined-strand-store.js';
 import type { PushNotifier } from './push-notifier.js';
-import type { CadreInviteSignedFields, RevocableTable } from './control-authorization.js';
-import type { CadreInvitation, CadreInviteAddressOutcome } from './cadre-invite-protocol.js';
+import type { CadreInviteSignedFields, OwnerGrantSignedFields, RevocableTable } from './control-authorization.js';
+import type { CadreInvitation } from './cadre-invite-protocol.js';
+import type { OwnerGrantBundle } from './owner-grant-protocol.js';
+import type { RedemptionAddressOutcome } from './member-redemption.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
 import type { FormationRejectionCode } from './strand-formation-rejection.js';
 import type { ListenTransportOptions } from './relay-addrs.js';
@@ -776,11 +778,10 @@ export interface CadreNodeConfig {
    * form). Mutually exclusive with {@link privateKey}. Absent ⇒ use `privateKey`
    * when set, else libp2p generates an ephemeral key.
    *
-   * In the single-key reference model the owner signing key is *derived from*
-   * the node identity (see {@link CadreNode.getIdentityOwnerKey}), so
-   * protecting the identity in a secure enclave protects the owner key too.
-   * A future separate-owner slot (`ownerKeyId`) is anticipated but not
-   * built here.
+   * The node signs owner writes through whatever owner signer the embedder wires
+   * (`CadreNode.useOwnerSigner`). An owner key has its own slot
+   * (`owner-key-store.ts`), which may be in this same store; this identity is never
+   * an owner key.
    */
   keyStore?: KeyStore;
 
@@ -972,7 +973,7 @@ export interface CadreNodeConfig {
    *
    * A node has exactly one cold-start trust source, so `claim` beside a non-empty
    * `trustedOwners.pinnedKeys` or a `seedTrustPolicy` fails `start()` closed, and
-   * `initializeSeedBootstrap` (an owner key) refuses on such a node: a hosted node never
+   * `useOwnerSigner` (an owner key) refuses on such a node: a hosted node never
    * holds an owner key. A claimed node restarted with this still set ignores it (its
    * anchor is non-empty), so the operator need not remove it.
    *
@@ -1025,7 +1026,7 @@ export interface CadreNodeConfig {
     /**
      * Provenance recorded for {@link pinnedKeys}. Default: 'operator'.
      * ('genesis' is reserved for the node's own founding key, seeded
-     * internally by `initializeSeedBootstrap`; 'chain' is written only by the
+     * internally by `useOwnerSigner`; 'chain' is written only by the
      * anchor sync, `CadreNode.syncOwnerAnchor`.)
      */
     pinnedSource?: Exclude<TrustSource, 'genesis' | 'chain'>;
@@ -1272,16 +1273,21 @@ export interface StrandRow {
   MemberPrivateKey: string | null;
   Type: 'o' | 'c';
   /**
-   * ed25519 (base64url) owner key of the MACHINE that published this row — the
-   * signer of the owner-signed `Strand` insert (`== context.OwnerKey`, pinned by
-   * the schema's `AuthorizedInsert`). Identifies the founding machine, so a
-   * launch with no explicit `founder` flag derives "am I the founder?" by
-   * comparing it to the node's own owner key (see `CadreNode.launchStrand`).
-   * `null` on a consent-seated strand (the unsigned `FormationUsage` branch
-   * records no trustworthy signer). Provenance, not content —
-   * `strandRowMismatches` excludes it from the identical-content comparison.
+   * ed25519 (base64url) owner key that signed the owner-signed `Strand` insert
+   * (`== context.OwnerKey`, pinned by the schema's `AuthorizedInsert`). `null` on a
+   * consent-seated strand (the unsigned `FormationUsage` branch records no
+   * signer). Provenance, not content — `strandRowMismatches` excludes it from the
+   * identical-content comparison.
    */
   FounderOwnerKey: string | null;
+  /**
+   * Peer id of the machine that runs the founder bootstrap, named by the owner
+   * signature on the insert (`CadreNode.publishStrand` writes its own). A launch
+   * with no explicit `founder` flag founds iff this is its own peer id (see
+   * `CadreNode.launchStrand`), so two machines holding one owner key never both
+   * found. `null` on a consent-seated strand. Provenance, as {@link FounderOwnerKey}.
+   */
+  FounderPeerId: string | null;
 }
 
 /**
@@ -1404,7 +1410,7 @@ export interface StrandConfig {
    * unset and writes nothing — it receives those rows via Optimystic sync.
    *
    * When unset, founder-ness is DERIVED from the row: this node founds iff
-   * {@link StrandRow.FounderOwnerKey} equals its own owner key. An explicit
+   * {@link StrandRow.FounderPeerId} is its own peer id. An explicit
    * `true`/`false` wins over the derivation — the formation/responder flows pass
    * it deliberately, since a consent-seated row carries a null column.
    */
@@ -1492,6 +1498,37 @@ export interface FoundStrandResult {
   founded: boolean;
 }
 
+/**
+ * Options for {@link CadreNode.foundStrand}. Passing them selects the form that returns once
+ * the row is published ({@link FoundStrandBackgroundResult}), for a caller that needs only the
+ * row: minting an invitation reads just its id and membership key.
+ *
+ * An invitation redeemed before the start finishes is refused, retryably: a closed host
+ * strand answers `host-strand-unavailable` and leaves the token unspent. For an open host
+ * strand the approval is sent, but carries no strand addresses, because the strand node does
+ * not exist yet.
+ */
+export interface FoundStrandOptions {
+  /** Return once the row is published; the start continues in {@link FoundStrandBackgroundResult.ready}. */
+  background: true;
+}
+
+/** What {@link CadreNode.foundStrand} returns with `{ background: true }`: the row is published; the local start continues. */
+export interface FoundStrandBackgroundResult {
+  /** The live control-plane row: freshly published, or the one already there. Same as {@link FoundStrandResult.strandRow}. */
+  strandRow: StrandRow;
+  /** Same as {@link FoundStrandResult.founded}. */
+  founded: boolean;
+  /**
+   * Settles when the local start does. Resolves with the instance `addStrand` returns.
+   * Rejects with the start's own error. After a launch failure the strand stays published
+   * and the strand watcher keeps retrying it. After a first-sync timeout (only an adopted,
+   * not-founded row waits for one) the instance stays up and still syncing, so wait with
+   * {@link CadreNode.whenStrandWritable}.
+   */
+  ready: Promise<StrandInstance>;
+}
+
 /**
  * Result of creating a new cadre peer
  */
@@ -1742,7 +1779,7 @@ export interface CadreNodeEvents {
    * Also emitted for a strand this node joined from ANOTHER party, which no control
    * row names: the node remembers every such join (see
    * {@link CadreNodeConfig.joinedStrands}) and offers it here on each start, as a row
-   * with `FounderOwnerKey: null` carrying the closed strand's `MemberPrivateKey`. That
+   * with null founder columns carrying the closed strand's `MemberPrivateKey`. That
    * row is the product of the formation's consent, so claiming it needs no second one.
    *
    * **Fired once per strand per session, and it can fire before your listener is
@@ -1915,25 +1952,27 @@ export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | '
 
 /**
  * One live `CadreControl.OwnerKey` row as `ControlDatabase.queryOwnerKeyRows` reads it: the
- * key and the persisted proof of how it was seated. The three proof shapes are the schema's
- * (`OwnerKey.Authorized`): the founding row (all three null), an owner-signed add (`vouchOwner`
- * and `vouchSig`, the signer's signature over `ownerKeyAddDigest(key, stampId)`), or an
- * owner-granting invitation redeemed by consent (`vouchOwner` the issuer, `vouchSig` null,
- * `vouchUsage` the `CadreInviteUsage` row). Rows whose stamp is retired in `Revocation`, and
- * the stampless row the schema permits but no writer produces, never reach a reader, so
- * `stampId` is non-null here. The anchor sync (`deriveOwnerAnchor`) judges
- * the proof against the keys it already trusts, never against the table itself.
+ * key, its label and the persisted proof of how it was seated. The three proof shapes are the
+ * schema's (`OwnerKey.Authorized`): the founding row (all three null), an owner-signed add
+ * (`vouchOwner` and `vouchSig`, the signer's signature over `ownerKeyAddDigest(key, label, stampId)`), or an
+ * owner grant redeemed by consent (`vouchOwner` the issuer, `vouchSig` null, `vouchUsage` the
+ * `OwnerGrantUsage` row). Rows whose stamp is
+ * retired in `Revocation`, and the stampless row the schema permits but no writer produces,
+ * never reach a reader, so `stampId` is non-null here. The anchor sync (`deriveOwnerAnchor`)
+ * judges the proof against the keys it already trusts, never against the table itself.
  */
 export interface OwnerKeyRow {
   /** ed25519 public key (base64url) — the row key. */
   key: string;
+  /** The user's name for the key, bound into an owner-signed add or into the grant that seated it; null when none was given. */
+  label: string | null;
   /** Single-use anti-replay nonce the voucher signature, or the usage row, is bound to. */
   stampId: string;
-  /** The owner that signed the add, or that issued the invitation that admitted it; null on the founding row. */
+  /** The owner that signed the add, or that issued the grant that seated it; null on the founding row. */
   vouchOwner: string | null;
-  /** That owner's signature over the row's `'add'` digest, base64url; null on the founding row and on an invitation-admitted row. */
+  /** That owner's signature over the row's `'add'` digest, base64url; null on the founding row and on a consent-seated row. */
   vouchSig: string | null;
-  /** The `CadreInviteUsage.UsageStampId` that admitted this row; null otherwise. */
+  /** The `OwnerGrantUsage.UsageStampId` that seated this row; null otherwise. */
   vouchUsage: string | null;
 }
 
@@ -1967,10 +2006,8 @@ export interface CadreInviteUsageRow {
   peerId: string;
   /** The admitted device's ed25519 public key (base64url). */
   peerKey: string;
-  /** The `CadrePeer.StampId` this redemption seated (or found seated). */
+  /** The `CadrePeer.StampId` this redemption seated. */
   peerStampId: string;
-  /** The `OwnerKey.StampId` this redemption seated, when the invitation grants ownership; else null. */
-  ownerStampId: string | null;
   /** The invitation private key's signature over the `'redeem'` digest, base64url. */
   inviteSig: string;
   /** The device's signature over the `'consent'` digest, base64url. */
@@ -1978,11 +2015,9 @@ export interface CadreInviteUsageRow {
 }
 
 /**
- * The usage and invitation rows an invitation-admitted row is verified through, keyed by
- * `UsageStampId` and `CadreInvite.Key`: a `CadrePeer` row through `verifyInvitationAdmission`
- * (`CadreNode.listAuthorizedMembers`) and an `OwnerKey` row through
- * `verifyInvitationOwnerAdmission` (`deriveOwnerAnchor`). Loaded once per membership refresh
- * (`CadreNode.loadInvitationChain`) and shared by both readers.
+ * The usage and invitation rows an invitation-admitted `CadrePeer` row is verified through
+ * (`verifyInvitationAdmission`, `CadreNode.listAuthorizedMembers`), keyed by `UsageStampId`
+ * and `CadreInvite.Key`. Loaded once per membership refresh (`CadreNode.loadInvitationChain`).
  */
 export interface InvitationChain {
   usages: Map<string, CadreInviteUsageRow>;
@@ -1990,9 +2025,56 @@ export interface InvitationChain {
 }
 
 /**
- * One machine of the cadre as `CadreNode.listMachines` reports it: a live `CadrePeer` row,
- * or a live `OwnerKey` whose key derives a peer id with no `CadrePeer` row (an owner key
- * seated for a machine not yet admitted, or a founder that never self-published).
+ * One `CadreControl.OwnerGrant` row: an owner-signed grant of ownership to whoever holds its
+ * private half, as `ControlDatabase.insertOwnerGrant` returns it and `queryOwnerGrant` reads
+ * it. Every column is here because the row travels, as a {@link CadreInviteRow} does: the
+ * holder carries it inside the grant bundle and a member re-seats it verbatim
+ * (`seatOwnerGrant`), so `expiresAt` is the engine-canonical `datetime` string the row
+ * stores. The signed subset is `OwnerGrantSignedFields` (`control-authorization.ts`); the
+ * grant names no machine and no peer id.
+ */
+export interface OwnerGrantRow extends OwnerGrantSignedFields {
+  /** The owner that signed the row (`IssuerKey`, base64url ed25519); a reader checks it against its anchor. */
+  issuerKey: string;
+  /** That owner's `'add'` signature over the row (`IssuerSig`, base64url). */
+  issuerSig: string;
+}
+
+/**
+ * One `CadreControl.OwnerGrantUsage` row: a redemption of an {@link OwnerGrantRow}, as
+ * `ControlDatabase.queryOwnerGrantUsages` reads it. Both signatures are stored so any reader
+ * can re-verify the chain grant → usage → `OwnerKey` row (`verifyOwnerGrantAdmission`).
+ */
+export interface OwnerGrantUsageRow {
+  /** The redemption's single-use nonce (the row key), signed into both signatures. */
+  usageStampId: string;
+  /** The `OwnerGrant.Key` redeemed. */
+  grantKey: string;
+  /** The owner key seated (base64url ed25519): the holder's, fresh or already held. */
+  seatedKey: string;
+  /** The `OwnerKey.StampId` this redemption seated. */
+  seatedStampId: string;
+  /** The grant private key's signature over the `'redeem'` digest, base64url. */
+  grantSig: string;
+  /** The seated key's signature over the `'consent'` digest, base64url. */
+  ownerSig: string;
+}
+
+/**
+ * The usage and grant rows a grant-seated `OwnerKey` row is verified through, keyed by
+ * `UsageStampId` and `OwnerGrant.Key` (`verifyOwnerGrantAdmission`, from `deriveOwnerAnchor`).
+ * The grant twin of {@link InvitationChain}, loaded beside it by `CadreNode.syncOwnerAnchor`
+ * when some owner row is consent-seated; a row's `vouchUsage` is looked up in this chain
+ * first and in the invitation chain otherwise.
+ */
+export interface OwnerGrantChain {
+  usages: Map<string, OwnerGrantUsageRow>;
+  grants: Map<string, OwnerGrantRow>;
+}
+
+/**
+ * One machine of the cadre as `CadreNode.listMachines` reports it: a live `CadrePeer` row. An
+ * owner key is not a machine; `CadreNode.listOwnerKeys` lists those.
  *
  * `profile` and `lastPublishedAt` are the machine's own claim only when the row's
  * self-signature verifies; both are null otherwise, so an owner re-vouch that bumped
@@ -2001,58 +2083,108 @@ export interface InvitationChain {
  */
 export interface CadreMachine {
   peerId: string;
-  /** ed25519 public key (base64url) behind `peerId`; null when the id is not ed25519. */
+  /** The machine's ed25519 identity key (base64url) behind `peerId`; null when the id is not ed25519. Never an owner key (`listOwnerKeys` lists those). */
   publicKey: string | null;
   /** This node itself. */
   isSelf: boolean;
-  /** `publicKey` is a live `OwnerKey` here. */
-  isOwner: boolean;
-  /** Has a live `CadrePeer` row; false for an owner key with no machine row. */
-  isMember: boolean;
   /** Passes this node's authorized-membership predicate now (`CadreNode.listAuthorizedMembers`; always false for self, which that set excludes). */
   trusted: boolean;
   /** The machine's self-published node profile; null until it publishes, or when its signature does not verify. */
   profile: NodeProfile | null;
   /** `UpdatedAt` of its self-signed record, re-stamped while it runs; null on the same terms as `profile`. */
   lastPublishedAt: number | null;
-  /** `CadrePeer.VouchOwner` (or `OwnerKey.VouchOwner` for an owner-only entry): the owner that vouched it, or the issuer of the invitation that admitted it. */
+  /** `CadrePeer.VouchOwner`: the owner key that vouched it, or the issuer of the invitation that admitted it. */
   vouchedBy: string | null;
 }
 
+/** One live owner key as `CadreNode.listOwnerKeys` lists it, for an app's owner-key screen. */
+export interface CadreOwnerKey {
+  /** ed25519 public key (base64url). */
+  key: string;
+  /** The user's name for the key ("phone", "paper backup"); null when none was given. */
+  label: string | null;
+  /** `OwnerKey.VouchOwner`: the owner that signed its add, or that issued the owner grant that seated it; null on the founding key. */
+  vouchedBy: string | null;
+  /** This node's owner signer holds it. */
+  heldHere: boolean;
+  /** In this node's trusted-owner anchor, so this node accepts what it signs. */
+  trusted: boolean;
+}
+
+/** Why `CadreNode.addOwner` refuses by name (`OwnerKeyAddRefusedError.code`). */
+export type OwnerKeyAddRefusal =
+  /** No control connection while the party has other members: the row would stay on this node, and nothing re-issues an `OwnerKey` add. */
+  | 'alone';
+
 /** Why `CadreNode.removeMachine` refuses by name (`MachineRemovalRefusedError.code`). */
 export type MachineRemovalRefusal =
   /** This node holds no enrolled owner key, so it cannot sign the removal. */
   | 'not-an-owner'
-  /** The machine is this node: an owner cannot sign its own `OwnerKey` removal, so ask another owner. */
-  | 'self'
-  /** The machine holds the only live owner key here (`MinOneOwner`). */
-  | 'last-owner';
+  /** The machine is this node: leaving a cadre is the embedder's flow (stop the node, delete its data), not a removal. */
+  | 'self';
 
 /**
  * What `CadreNode.removeMachine` would do for one machine, read without writing
- * (`CadreNode.planMachineRemoval`), for an app's confirmation step.
+ * (`CadreNode.planMachineRemoval`), for an app's confirmation step. A machine vouches nothing
+ * (a `VouchOwner` is an owner key), so removing one strands no other row.
  */
 export interface MachineRemovalPlan {
   /** The machine as listed, or null when no live row names it here (already removed). */
   machine: CadreMachine | null;
   refusal: MachineRemovalRefusal | null;
-  /** The machine's key is a live owner key, so the removal also retires it. */
-  removesOwnerKey: boolean;
-  /** Rows the machine's owner key vouched, which stop passing the membership predicate everywhere once it is removed unless re-vouched first. Empty unless `removesOwnerKey`. */
-  dependents: {
-    /** Live `OwnerKey` rows whose `VouchOwner` is the machine's key, this node's own excluded. */
-    owners: string[];
-    /** Live `CadrePeer` rows whose `VouchOwner` is the machine's key, the machine itself and this node excluded. */
-    peers: string[];
-  };
   /** Live `CadreInvite` keys the machine could redeem to come back: targeted at it, or already redeemed by it with uses left. */
   invitations: string[];
-  /** This node's own `OwnerKey` or `CadrePeer` row was vouched by the machine. It cannot re-vouch its own rows; another owner has to re-add it afterwards. */
+}
+
+/** What `CadreNode.removeMachine` wrote. All false and empty when no live row named the machine here. */
+export interface MachineRemovalResult {
+  removedPeer: boolean;
+  removedDeviceToken: boolean;
+  /** `CadreInvite` keys whose withdrawal tombstone this call filed. */
+  withdrawnInvitations: string[];
+}
+
+/** Why `CadreNode.removeOwner` refuses by name (`OwnerKeyRemovalRefusedError.code`). */
+export type OwnerKeyRemovalRefusal =
+  /** This node holds no enrolled owner key, so it cannot sign the removal. */
+  | 'not-an-owner'
+  /** No live `OwnerKey` row names the key here (never an owner, or already removed). */
+  | 'unknown'
+  /** The key is the only live owner key (`MinOneOwner`); no owner can remove it. */
+  | 'last-owner'
+  /** The key is this node's own owner key: an owner cannot sign its own row's removal (`A.Key <> old.Key`), so ask another owner key. */
+  | 'self'
+  /** A re-vouch of an `OwnerKey` row was asked for while this node has no control connection and the party has other members: the re-added row has no re-issue path. Decided at call time, so never planned. */
+  | 'alone';
+
+/** The rows sharing the owner keys' voucher column that a removed owner key strands unless re-vouched first. */
+export interface OwnerKeyDependents {
+  /** Live `OwnerKey` rows whose `VouchOwner` is the key, this node's own excluded. */
+  owners: string[];
+  /** Live `CadrePeer` rows (peer ids) whose `VouchOwner` is the key, this node's own excluded. */
+  peers: string[];
+}
+
+/**
+ * What `CadreNode.removeOwner` would do for one owner key, read without writing
+ * (`CadreNode.planOwnerKeyRemoval`), for an app's confirmation step.
+ */
+export interface OwnerKeyRemovalPlan {
+  /** The key as `CadreNode.listOwnerKeys` lists it, or null when no live row names it here. */
+  ownerKey: CadreOwnerKey | null;
+  refusal: Exclude<OwnerKeyRemovalRefusal, 'alone'> | null;
+  /** Rows the key vouched, which stop passing the membership predicate on every machine once it is removed unless re-vouched first. */
+  dependents: OwnerKeyDependents;
+  /** This node's own `CadrePeer` row was vouched by the key, so `removeOwner` re-vouches it under this node's key first, unasked: left on the removed key, every other machine would drop this node. */
+  revouchesOwnRow: boolean;
+  /** This node's own `OwnerKey` row was vouched by the key. It cannot re-vouch that row (the re-add's delete would be its own removal); it keeps its place in every anchor that already derived it, and another owner can re-vouch it afterwards. */
   ownDependency: boolean;
+  /** Live owner grants the key issued, which stop being redeemable once it is removed (`OwnerGrantUsage.Authorized` wants a live issuer): an app says "the backup made with this key stops working". Withdrawn, expired and spent grants are not listed. */
+  grants: OwnerGrantRow[];
 }
 
-/** Options for `CadreNode.removeMachine`. */
-export interface RemoveMachineOptions {
+/** Options for `CadreNode.removeOwner`. */
+export interface RemoveOwnerOptions {
   /** Dependents to re-vouch under this node's key before the removal; each must appear in the plan's `dependents`. */
   revouch?: {
     owners?: readonly string[];
@@ -2060,18 +2192,12 @@ export interface RemoveMachineOptions {
   };
 }
 
-/** What `CadreNode.removeMachine` wrote. All false and empty when no live row named the machine here. */
-export interface MachineRemovalResult {
-  removedPeer: boolean;
-  removedOwnerKey: boolean;
-  removedDeviceToken: boolean;
-  /** `CadreInvite` keys whose withdrawal tombstone this call filed. */
-  withdrawnInvitations: string[];
-  /** Dependents re-vouched under this node's key before the removal. */
-  revouched: {
-    owners: string[];
-    peers: string[];
-  };
+/** What `CadreNode.removeOwner` wrote. */
+export interface OwnerKeyRemovalResult {
+  /** The `OwnerKey` row and its tombstone were written; false only when another owner's removal reached this node between the plan and the write. */
+  removed: boolean;
+  /** Rows re-vouched under this node's key before the removal: the dependents asked for, and this node's own row when the plan's `revouchesOwnRow`. */
+  revouched: OwnerKeyDependents;
 }
 
 /**
@@ -2105,14 +2231,36 @@ export interface CadreInviteStatus {
 
 /**
  * What `ControlDatabase.redeemCadreInvite` did. `alreadyMember` is the idempotent
- * retry after a dropped reply: the device's row (and, for an owner-granting
- * invitation, its `OwnerKey` row) was already present, so nothing was written and
- * no seat was spent. The stamps are the live rows' either way.
+ * retry after a dropped reply: the device's row was already present, so nothing was
+ * written and no seat was spent. The stamp is the live row's either way.
  */
 export interface CadreInviteRedemptionResult {
   alreadyMember: boolean;
   peerStampId: string;
-  ownerStampId: string | null;
+}
+
+/**
+ * One {@link OwnerGrantRow} with its standing, as `ControlDatabase.listOwnerGrantStatuses`
+ * reports it. `live` is the redemption's own test: not withdrawn, unexpired, uses left,
+ * issuer still an owner here.
+ */
+export interface OwnerGrantStatus {
+  grant: OwnerGrantRow;
+  live: boolean;
+  withdrawn: boolean;
+  /** Redemptions this node holds for it (`OwnerGrantUsage` rows). */
+  usesRecorded: number;
+}
+
+/**
+ * What `ControlDatabase.redeemOwnerGrant` did. `alreadyOwner` is the idempotent retry after
+ * a dropped reply, and the case of a holder seating a key that is already an owner: the
+ * key's live `OwnerKey` row was already present, so nothing was written and no use was
+ * spent. `seatedStampId` is the live row's either way.
+ */
+export interface OwnerGrantRedemptionResult {
+  alreadyOwner: boolean;
+  seatedStampId: string;
 }
 
 /**
@@ -2329,7 +2477,7 @@ export interface ApnsCredentials {
 // ============================================================================
 
 /**
- * A peer entry in a control network seed.
+ * A peer entry in a control network seed, or in a cadre invitation redemption reply.
  * Contains connection information for a cadre peer.
  */
 export interface SeedPeer {
@@ -2337,10 +2485,12 @@ export interface SeedPeer {
   peerId: string;
   /** Multiaddrs for connecting to this peer */
   multiaddrs: string[];
-  /** Whether this peer holds an owner key */
-  isOwner: boolean;
-  /** ed25519 public key (base64url) — present on owner peers for signerKey verification */
-  publicKey?: string;
+  /**
+   * Dial this peer first: the machine that minted the seed (or answered the redemption) and
+   * every always-on machine (`CadrePeer.Profile = 'storage'`). A dial hint only — it grants
+   * nothing, and says nothing about owner keys (`projectSeedPeers`).
+   */
+  preferred: boolean;
 }
 
 /**
@@ -2553,15 +2703,15 @@ export interface ApplySeedResult {
   /** Machine-readable refusal cause, when the refusing trust policy supplied one. */
   code?: SeedRefusalCode;
   /**
-   * Owner-flagged seed peers this apply attempted to dial. Zero when the seed
-   * carried no owner peer with an address, or when the seed was rejected before
+   * Preferred seed peers (`SeedPeer.preferred`) this apply attempted to dial. Zero when the
+   * seed carried no preferred peer with an address, or when the seed was rejected before
    * the dial loop ran.
    */
-  ownerDialsAttempted: number;
+  preferredDialsAttempted: number;
   /**
-   * How many of those dials threw. `ownerDialsAttempted > 0 && ownerDialsFailed
-   * === ownerDialsAttempted` means "seeded but stranded": the seed itself was
-   * accepted (`success: true`) but no owner could be reached, so this node has
+   * How many of those dials threw. `preferredDialsAttempted > 0 && preferredDialsFailed
+   * === preferredDialsAttempted` means "seeded but stranded": the seed itself was
+   * accepted (`success: true`) but no preferred peer could be reached, so this node has
    * no connection to bootstrap its control database from. The node retries those
    * addresses on every control-cohort reconcile pass (see
    * `CadreNode.dialColdStartBootstrap`), so this is a signal, not a fatal error.
@@ -2573,7 +2723,7 @@ export interface ApplySeedResult {
    * down. Treat a non-zero value as certain failure and zero as "no failure
    * observed".
    */
-  ownerDialsFailed: number;
+  preferredDialsFailed: number;
 }
 
 // ============================================================================
@@ -2587,18 +2737,13 @@ export type NodeTopology = 'public' | 'nat';
 
 /**
  * What an owner asks `CadreNode.createCadreInvitation` for. The invitation is a keypair the
- * node mints; whoever holds the returned bundle can redeem it at any member machine.
+ * node mints; whoever holds the returned bundle can redeem it at any member machine. It admits
+ * a machine and grants nothing else; ownership is an owner grant (`CreateOwnerGrantOptions`).
  */
 export interface CreateCadreInvitationOptions {
   /** The one device that may redeem it; omit for whoever redeems first. */
   peerId?: string;
-  /** Whether redemption also makes the device an owner (seats an `OwnerKey` row). */
-  grantsOwner: boolean;
-  /**
-   * Lifetime from now, in ms. Defaults to 15 minutes for an untargeted owner-granting
-   * invitation — a bearer credential for admin rights — and 24 hours otherwise. A negative
-   * value mints an already-expired invitation (tests).
-   */
+  /** Lifetime from now, in ms; default 24 hours. A negative value mints an already-expired invitation (tests). */
   expiresInMs?: number;
   /** How many redemptions it allows; default 1. */
   uses?: number;
@@ -2653,19 +2798,75 @@ export type CadreJoinProgress =
        * least one member answered with a retryable refusal (issuer-unknown, busy, conflict, internal).
        */
       reason: 'no-member-answered' | 'member-not-ready';
-      outcomes: readonly CadreInviteAddressOutcome[];
+      outcomes: readonly RedemptionAddressOutcome[];
     };
 
 /** What `CadreNode.redeemCadreInvitation` returns once a member accepted. */
 export interface RedeemCadreInvitationResult {
   /** The member machine that admitted this device, when its address named one. */
   peerId: string | null;
-  /** Whether the invitation also seated this device's key as an owner. */
-  grantsOwner: boolean;
   /** When the member accepted, ISO 8601. */
   redeemedAt: string;
 }
 
+/**
+ * What an owner asks `CadreNode.createOwnerGrant` for. The grant is a keypair the node mints;
+ * whoever holds the returned bundle can become an owner of this cadre through any member
+ * machine, so it is a bearer credential for admin rights.
+ */
+export interface CreateOwnerGrantOptions {
+  /** The label every key the grant seats will carry; trimmed, at most 64 characters, blank meaning none. */
+  label?: string;
+  /**
+   * Lifetime from now, in ms; default 15 minutes. `null` means NO expiry and must be passed
+   * explicitly: a backup grant, kept as carefully as an owner key. A negative value mints an
+   * already-expired grant (tests).
+   */
+  expiresInMs?: number | null;
+  /** How many redemptions it allows; default 1. */
+  uses?: number;
+}
+
+/** What `CadreNode.createOwnerGrant` returns: the bundle, the same encoded for sharing, and how far it reaches. */
+export interface CreateOwnerGrantResult {
+  grant: OwnerGrantBundle;
+  /** `encodeOwnerGrant(grant)`: `sereus-owner-grant:1.` and base64url JSON, for a QR code, a paste or a file. */
+  encoded: string;
+  /** Whether a holder could redeem it once the minting machine is gone; see {@link CadreInvitationReach}. */
+  reach: CadreInvitationReach;
+}
+
+/** How `CadreNode.redeemOwnerGrant` and `joinWithOwnerGrant` dial the grant's members: the invitation's options, with the same meanings. */
+export type RedeemOwnerGrantOptions = RedeemCadreInvitationOptions;
+
+/** What `CadreNode.redeemOwnerGrant` returns once the key is seated. */
+export interface RedeemOwnerGrantResult {
+  /** The key seated as an owner: the signer's public key. */
+  ownerKey: string;
+  /** The key was already a live owner, so nothing was written and no use of the grant was spent. */
+  alreadyOwner: boolean;
+  /** The member machine that wrote the row, when the redemption went over the protocol and its address named one; null on the local path. */
+  memberPeerId: string | null;
+}
+
+/** What `CadreNode.joinWithOwnerGrant` returns once this node is a member and its key an owner. */
+export interface JoinWithOwnerGrantResult {
+  /** The member machine that admitted this node, when its address named one. */
+  peerId: string | null;
+  /** When the member admitted this node, ISO 8601. */
+  redeemedAt: string;
+  /** The key seated as an owner: the signer's public key. */
+  ownerKey: string;
+  /** The key was already a live owner of the party, so the grant spent no use. */
+  alreadyOwner: boolean;
+  /**
+   * The signer was wired as this node's owner signer, because its `OwnerKey` row reached this
+   * node within the bound. False when the row had not synced in time: the node is a member and
+   * the key an owner all the same, and `CadreNode.wireOwnKeyIfOwner(signer)` wires it later.
+   */
+  ownerWired: boolean;
+}
+
 /**
  * Options for adding a drone via provider API.
  */