@serfab/cadre-core 1.16.0 → 1.17.0

package/dist/types.d.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';
@@ -723,11 +725,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;
     /** Slot id for the node identity in {@link keyStore}. Default: `'cadre/identity'`. */
@@ -900,7 +901,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.
      *
@@ -952,7 +953,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'>;
@@ -1175,16 +1176,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;
 }
 /**
  * A `CadreControl.JoinRequest` row: a join this party asked for through another party's
@@ -1305,7 +1311,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.
      */
@@ -1390,6 +1396,35 @@ 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
  */
@@ -1643,7 +1678,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
@@ -1820,25 +1855,27 @@ export interface CadrePeerRow {
 export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | 'vouchOwner' | 'vouchSig' | 'vouchUsage'>;
 /**
  * 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;
 }
 /**
@@ -1870,30 +1907,70 @@ 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. */
     peerSig: string;
 }
 /**
- * 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>;
     invites: Map<string, CadreInviteRow>;
 }
 /**
- * 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
@@ -1902,74 +1979,112 @@ 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. */
-    ownDependency: boolean;
-}
-/** Options for `CadreNode.removeMachine`. */
-export interface RemoveMachineOptions {
-    /** Dependents to re-vouch under this node's key before the removal; each must appear in the plan's `dependents`. */
-    revouch?: {
-        owners?: readonly string[];
-        peers?: readonly string[];
-    };
 }
 /** 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[];
+}
+/** 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.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[];
+        peers?: readonly 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;
+}
 /**
  * This node's own removal from its cadre, as it learned it: the `CadrePeer` tombstone naming
  * its peer id, read after it had seen its own live row (`CadreNode.removedFromCadre`, the
@@ -1999,14 +2114,34 @@ 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;
 }
 /**
  * One `CadreControl.Revocation` tombstone as read by
@@ -2197,7 +2332,7 @@ export interface ApnsCredentials {
     production?: boolean;
 }
 /**
- * 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 {
@@ -2205,10 +2340,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;
 }
 /**
  * Control network seed for bootstrapping new nodes.
@@ -2399,15 +2536,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.
@@ -2419,7 +2556,7 @@ export interface ApplySeedResult {
      * down. Treat a non-zero value as certain failure and zero as "no failure
      * observed".
      */
-    ownerDialsFailed: number;
+    preferredDialsFailed: number;
 }
 /**
  * Node network topology type for seed helper scenarios.
@@ -2427,18 +2564,13 @@ export interface ApplySeedResult {
 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;
@@ -2490,17 +2622,68 @@ 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.
  */

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAwFA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AAweF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,uFAAuF;IACvF,mFAAmF;IACnF,YAAY,EAAE,KAAM;IACpB,kFAAkF;IAClF,kFAAkF;IAClF,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,KAAM,EAAE,UAAU,EAAE,KAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAmBzC;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0FA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AAweF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,uFAAuF;IACvF,mFAAmF;IACnF,YAAY,EAAE,KAAM;IACpB,kFAAkF;IAClF,kFAAkF;IAClF,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,KAAM,EAAE,UAAU,EAAE,KAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAmBzC;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -51,6 +51,14 @@
     "./node-default-transports": {
       "types": "./dist/node-default-transports.d.ts",
       "import": "./dist/node-default-transports.js"
+    },
+    "./edge-node": {
+      "react-native": {
+        "types": "./dist/edge-node/index.d.ts",
+        "import": "./dist/edge-node/index.js"
+      },
+      "types": "./dist/edge-node/index.d.ts",
+      "import": "./dist/edge-node/index.js"
     }
   },
   "repository": {
@@ -101,13 +109,14 @@
     "@libp2p/tcp": "^11.0.28",
     "@libp2p/websockets": "^10.1.21",
     "@multiformats/multiaddr": "^13.0.3",
+    "@noble/ciphers": "^2.0.1",
     "@noble/hashes": "^2.0.0",
     "@optimystic/db-core": "^1.15.0",
     "@optimystic/db-p2p": "^1.15.0",
     "@optimystic/quereus-plugin-crypto": "^1.15.0",
     "@optimystic/quereus-plugin-optimystic": "^1.15.0",
     "@quereus/quereus": "^4.20.1",
-    "@serfab/quereus-plugin-sereus": "^1.16.0",
+    "@serfab/quereus-plugin-sereus": "^1.17.0",
     "debug": "^4.4.3",
     "libp2p": "^3.3.11",
     "uint8arrays": "^6.1.1"