@serfab/cadre-core 1.13.0 → 1.14.0

package/dist/types.d.ts

@@ -16,7 +16,8 @@ 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 { RevocableTable } from './control-authorization.js';
+import type { CadreInviteSignedFields, RevocableTable } from './control-authorization.js';
+import type { CadreInvitation } from './cadre-invite-protocol.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
 import type { FormationRejectionCode } from './strand-formation-rejection.js';
 /**
@@ -534,7 +535,7 @@ export interface NetworkConfig {
         /**
          * Limit on dialing ONE peer — all of its candidate addresses together — in
          * ms. Bounds a reconcile pass at (dialed siblings) × this. The same limit
-         * applies to the owner dials of `applySeed` and to `dialInvite`. Defaults to
+         * applies to the owner dials of `applySeed`. Defaults to
          * {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS}.
          */
         dialTimeoutMs?: number;
@@ -777,7 +778,7 @@ export interface CadreNodeConfig {
      * should enable it, because a node without it neither announces nor serves as part of the
      * group a notification is rooted at. Enabling registers Optimystic's change-notification
      * protocol handlers on the strand node, which the closed-strand per-stream gate does not
-     * cover, and each watched table pays a cold-start proof of work on every node build. Both
+     * cover, and each watched table registers again on every node build. Both
      * are spelled out in `docs/strands.md` → "Change notifications (reactivity)". The control
      * node never gets it.
      */
@@ -860,9 +861,43 @@ export interface CadreNodeConfig {
      * inside SeedBootstrapService when unset — a node whose node-local trusted-owner
      * anchor was never seeded then rejects every seed. A per-call
      * `applySeed(seed, { trustPolicy })` override still wins over this default for
-     * callers that hold out-of-band material (e.g. a pinned key from a CadreInvite).
+     * callers that hold out-of-band material (e.g. an operator-pinned owner key).
      */
     seedTrustPolicy?: SeedTrustPolicy;
+    /**
+     * Start this node waiting to be CLAIMED: it belongs to nobody until someone delivers
+     * a seed carrying a proof of this one-time secret (`claim-proof.ts`,
+     * `claimSecretTrustPolicy`), and that signer becomes its anchored owner. The node
+     * turns its seed listener on itself and, while unclaimed, lets a stranger do nothing
+     * but deliver a seed: connections are admitted, control-database streams and relay
+     * reservations are refused (`CadreNode.isAwaitingClaim`).
+     *
+     * 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
+     * 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.
+     *
+     * The claim also decides which party the node serves: `controlNetwork.partyId` on an
+     * unclaimed node is a placeholder, and the real party is the claim seed's. The node
+     * itself keeps serving the placeholder for the rest of the process — everything it
+     * holds is keyed on the party it started with — so `record` is where the embedder
+     * learns the claimed party, and it is the embedder's job to restart into it.
+     */
+    claim?: {
+        /** The one-time claim secret, base64url of 32 bytes. Never written to replicated state or logs. */
+        secret: string;
+        /**
+         * Record the claim durably: called with the seed's party and the claimant's key after
+         * the proof verifies and BEFORE the claimant is anchored, and awaited. A rejection
+         * refuses the claim `claim-not-persisted` with nothing anchored, so the claimant
+         * retries. Record first, anchor second: a crash between the two leaves a record and
+         * an empty anchor, and an embedder that starts from its record (cadre-cli does)
+         * then comes up claimed by that owner, who is accepted idempotently when it retries.
+         * The other order would leave an anchored node with no record of its party.
+         */
+        record: (claim: NodeClaimRecord) => Promise<void>;
+    };
     /**
      * Node-local trusted-owner anchor (see `trusted-owner-store.ts`): the
      * NON-replicated, per-party record of owner keys established out of band —
@@ -883,16 +918,18 @@ export interface CadreNodeConfig {
         /**
          * Owner keys (base64url ed25519) established out of band and seeded into
          * the store during start(): operator pins (e.g. cadre-cli
-         * `--pin-owner-key` / `CADRE_OWNER_KEYS`) or a `CadreInvite.ownerKeys`
-         * already known at config time. Seeding is idempotent across restarts.
+         * `--pin-owner-key` / `CADRE_OWNER_KEYS`). A cadre invitation's `ownerKeys`
+         * are pinned at redemption instead (`CadreNode.redeemCadreInvitation`).
+         * Seeding is idempotent across restarts.
          */
         pinnedKeys?: string[];
         /**
          * Provenance recorded for {@link pinnedKeys}. Default: 'operator'.
          * ('genesis' is reserved for the node's own founding key, seeded
-         * internally by `initializeSeedBootstrap`.)
+         * internally by `initializeSeedBootstrap`; 'chain' is written only by the
+         * anchor sync, `CadreNode.syncOwnerAnchor`.)
          */
-        pinnedSource?: Exclude<TrustSource, 'genesis'>;
+        pinnedSource?: Exclude<TrustSource, 'genesis' | 'chain'>;
     };
     /**
      * Node-local cold-start bootstrap-peer store (see `bootstrap-peer-store.ts`):
@@ -1124,13 +1161,11 @@ export interface StrandRow {
     FounderOwnerKey: string | null;
 }
 /**
- * A `CadreControl.PendingJoin` row: a join this party asked for through another party's
- * invitation, readable by every machine of the party. Each outcome carries only its own
- * columns (the schema's `OutcomeShape` check): `'joined'` sets `StrandId` (and, for a
- * closed strand, `MembershipInvite`), `'failed'` sets `FailureCode`, and a pending row
- * (`Outcome: null`) sets neither.
+ * A `CadreControl.JoinRequest` row: a join this party asked for through another party's
+ * invitation, readable by every machine of the party. The row never changes; its outcome is
+ * a `JoinSuccess` or `JoinFailure` row keyed by `StampId` (see {@link PendingJoin}).
  */
-export interface PendingJoinRow {
+export interface JoinRequestRow {
     /** base64url sha256 of the invitation token (`pendingJoinId`). */
     Id: string;
     /** `CadreNode.encodeInvitation` of the invitation. A bearer credential. */
@@ -1141,30 +1176,45 @@ export interface PendingJoinRow {
     RequestedAt: number;
     /** Epoch ms; no attempt starts at or after it. */
     ExpiresAt: number;
-    Outcome: null | 'joined' | 'failed';
-    /** Epoch ms the outcome was recorded; null while pending. */
-    OutcomeAt: number | null;
-    /** `'joined'`: the strand the formation returned. */
-    StrandId: string | null;
-    /** `'joined'`, closed strand: JSON of the {@link StrandMembershipInvite} the formation delivered. */
-    MembershipInvite: string | null;
-    /** `'failed'`: a `FormationRejectionCode`, `'expired'` or `'local'`. Not constrained by the schema. */
-    FailureCode: string | null;
-    /** `'failed'`: human-readable text. */
-    FailureReason: string | null;
-    /** Single-use nonce of this row incarnation; `ControlDatabase.replacePendingJoin` names it as the row it replaces. */
+    /** Single-use nonce of this request incarnation; its outcome rows name it. */
     StampId: string;
 }
+/**
+ * The outcome of a {@link JoinRequestRow}: a `CadreControl.JoinSuccess` row (`'joined'`) or
+ * a `CadreControl.JoinFailure` row (`'failed'`), without the request stamp that keys it.
+ */
+export type JoinOutcome = {
+    kind: 'joined';
+    /** Epoch ms the outcome was recorded. */
+    RecordedAt: number;
+    /** The strand the formation returned. */
+    StrandId: string;
+    /** Closed strand: JSON of the {@link StrandMembershipInvite} the formation delivered. */
+    MembershipInvite: string | null;
+} | {
+    kind: 'failed';
+    /** Epoch ms the outcome was recorded. */
+    RecordedAt: number;
+    /** A `FormationRejectionCode`, `'expired'` or `'local'`. Not constrained by the schema. */
+    Code: string;
+    /** Human-readable text. */
+    Reason: string;
+};
+/** A join request with its outcome, as `ControlDatabase.queryPendingJoins` reads the three tables. */
+export interface PendingJoin extends JoinRequestRow {
+    /** Null while pending. */
+    outcome: JoinOutcome | null;
+}
 /**
  * A join this party asked for through `CadreNode.requestJoin`, as one machine sees it.
  *
- * `pending`, `joined` and `failed` come from the party-wide `PendingJoin` row and read the same
+ * `pending`, `joined` and `failed` come from the party-wide join request and its outcome row and read the same
  * on every machine. `trying` (an attempt is running on this machine) and `waiting` (this
  * machine's last attempt failed in a way worth retrying) are this machine's own view of a
  * pending row, so two machines can report different states for it.
  */
 export interface PendingJoinStatus {
-    /** `PendingJoin.Id`: the sha256 of the invitation token. */
+    /** `JoinRequest.Id`: the sha256 of the invitation token. */
     id: string;
     sAppId: string;
     /** Epoch ms. */
@@ -1377,7 +1427,7 @@ export interface StrandMembershipInvite {
      * whoever holds it can `consumeInvite` exactly once. Same sensitivity class and
      * handling as `memberPrivateKey` — delivered only inside the validated,
      * post-approval formation result. The inviting side never writes it to its control
-     * DB. The joining side may copy it into its own `PendingJoin` row
+     * DB. The joining side may copy it into its own `JoinSuccess` row
      * (`MembershipInvite`), owner-signed and party-private like
      * `JoinedStrand.MemberPrivateKey`, so a join finished on one machine of the party
      * can be seated by whichever machine launches the strand first.
@@ -1627,6 +1677,18 @@ export interface CadreNodeEvents {
         partyId: string;
         error: string;
     };
+    /**
+     * Emitted once on a node started with `CadreNodeConfig.claim`, when a seed carrying a
+     * valid claim proof has been recorded (`claim.record`) and has durably anchored its
+     * signer as this node's owner. Carries the claim's party beside the owner key: the
+     * party this node should serve from now on, which its own config did not know. Fires
+     * BEFORE the seed is acknowledged to the claimant, its peers merged and its owners
+     * dialed, so it precedes that seed's `seed:applied`; an embedder that restarts into
+     * the claimed party on this event should wait for that `seed:applied` (or `seed:error`)
+     * so the acknowledgement is not lost with the node. `CadreNode.isAwaitingClaim` is the
+     * matching predicate for a reader that subscribed too late to see the event.
+     */
+    'claim:accepted': NodeClaimRecord;
 }
 /**
  * A peer's self-published, freshness-stamped, self-signed address record.
@@ -1657,29 +1719,130 @@ export interface PeerAddressRecord {
 }
 /**
  * One `CadreControl.CadrePeer` row as read by `ControlDatabase.queryCadrePeers`:
- * the addressing columns plus the persisted membership voucher.
+ * the addressing columns plus the persisted membership proof.
  *
- * The voucher triple (`stampId`, `vouchOwner`, `vouchSig`) is what
+ * A row carries exactly one proof. An owner-vouched row has `vouchSig`, the owner's
+ * signature over the row's (`peerId`, `stampId`), which
  * {@link CadreNode.listAuthorizedMembers} re-checks against the node-local
- * trusted-owner anchor — it is null on a row written before the voucher columns
- * existed, and all three must be present for the row to be authorizable. Named
- * (rather than restated inline at each read site) so a future column addition
- * cannot reach the query without the predicate seeing it.
+ * trusted-owner anchor. An invitation-admitted row has `vouchSig` null and
+ * `vouchUsage` naming the `CadreInviteUsage` row that admitted it; the reader
+ * verifies the chain row → usage → invitation instead (`verifyInvitationAdmission`),
+ * with `vouchOwner` the invitation's issuer. All columns are null on a row written
+ * before they existed, and such a row is never authorizable. Named (rather than
+ * restated inline at each read site) so a future column addition cannot reach the
+ * query without the predicate seeing it.
  */
 export interface CadrePeerRow {
     /** libp2p peer ID (base58btc) — the row key. */
     peerId: string;
     /** Comma-joined dialable multiaddrs as stored, or null when unpublished. */
     multiaddr: string | null;
-    /** Single-use anti-replay nonce the voucher signature is bound to. */
+    /** Single-use anti-replay nonce the voucher signature, or the usage row, is bound to. */
     stampId: string | null;
-    /** ed25519 public key (base64url) of the owner that vouched this row. */
+    /** ed25519 public key (base64url) of the owner that vouched this row, or that issued the invitation that admitted it. */
     vouchOwner: string | null;
-    /** That owner's signature over `digest('CadreControl.CadrePeer', 'vouch', peerId, stampId)`, base64url. */
+    /** That owner's signature over `digest('CadreControl.CadrePeer', 'vouch', partyId, peerId, stampId)`, base64url; null on an invitation-admitted row. */
     vouchSig: string | null;
+    /** The `CadreInviteUsage.UsageStampId` that admitted this row; null on an owner-vouched row. */
+    vouchUsage: string | null;
+}
+/** The proof-bearing subset of a {@link CadrePeerRow} — what the authorized-membership predicate reads. */
+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.
+ */
+export interface OwnerKeyRow {
+    /** ed25519 public key (base64url) — the row key. */
+    key: string;
+    /** 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. */
+    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. */
+    vouchSig: string | null;
+    /** The `CadreInviteUsage.UsageStampId` that admitted this row; null otherwise. */
+    vouchUsage: string | null;
+}
+/**
+ * One `CadreControl.CadreInvite` row: an owner-signed invitation to join the cadre,
+ * as `ControlDatabase.insertCadreInvite` returns it and `queryCadreInvite` reads it.
+ * Every column is here because the row travels: the holder carries it inside the
+ * invitation bundle and a member re-seats it verbatim (`seatCadreInvite`), so
+ * `expiresAt` is the engine-canonical `datetime` string the row stores, not epoch
+ * ms — the `'add'` signature covers that exact text. The signed subset is
+ * `CadreInviteSignedFields` (`control-authorization.ts`).
+ */
+export interface CadreInviteRow extends CadreInviteSignedFields {
+    /** 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.CadreInviteUsage` row: a redemption of a {@link CadreInviteRow},
+ * as `ControlDatabase.queryCadreInviteUsages` reads it. The two signatures are
+ * stored so any reader can re-verify the admission chain (`verifyInvitationAdmission`).
+ */
+export interface CadreInviteUsageRow {
+    /** The redemption's single-use nonce (the row key), signed into both signatures. */
+    usageStampId: string;
+    /** The `CadreInvite.Key` redeemed. */
+    inviteKey: string;
+    /** The admitted device's libp2p peer id — the identity multihash of `peerKey`. */
+    peerId: string;
+    /** The admitted device's ed25519 public key (base64url). */
+    peerKey: string;
+    /** The `CadrePeer.StampId` this redemption seated (or found 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.
+ */
+export interface InvitationChain {
+    usages: Map<string, CadreInviteUsageRow>;
+    invites: Map<string, CadreInviteRow>;
+}
+/**
+ * One {@link CadreInviteRow} with its standing, as `ControlDatabase.listCadreInviteStatuses`
+ * (and `CadreNode.listCadreInvitations`) reports it. `live` is the redemption's own test:
+ * not withdrawn, unexpired, uses left, issuer still an owner here.
+ */
+export interface CadreInviteStatus {
+    invite: CadreInviteRow;
+    live: boolean;
+    withdrawn: boolean;
+    /** Redemptions this node holds for it (`CadreInviteUsage` rows). */
+    usesRecorded: number;
+}
+/**
+ * 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.
+ */
+export interface CadreInviteRedemptionResult {
+    alreadyMember: boolean;
+    peerStampId: string;
+    ownerStampId: string | null;
 }
-/** The voucher-bearing subset of a {@link CadrePeerRow} — what the authorized-membership predicate reads. */
-export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | 'vouchOwner' | 'vouchSig'>;
 /**
  * One `CadreControl.Revocation` tombstone as read by
  * `ControlDatabase.queryRevocations`: the identity triple plus the `ReissuedAt`
@@ -1697,6 +1860,10 @@ export interface RevocationRow {
     stampId: string;
     /** Monotonic re-issue counter; carries no semantics (see the schema comment). */
     reissuedAt: number;
+    /** The owner key that filed the tombstone (`Revocation.SignerKey`). */
+    signerKey: string;
+    /** That owner's signature over the tombstone's `'remove'` digest (`Revocation.SignerSig`). */
+    signerSig: string;
 }
 /**
  * Outcome of `ControlDatabase.openRevocationLedger`: `'opened'` when this call filed the
@@ -1907,6 +2074,47 @@ export interface SeedMessage {
     signature: string;
     /** The owner key that signed this message */
     signerKey: string;
+    /**
+     * Proof that the sender holds the receiving node's one-time claim secret
+     * (`claim-proof.ts`), sent only when claiming a brand-new node. Rides beside
+     * the seed rather than inside `ControlNetworkSeed`: it is not part of what the
+     * owner signs, and a claimed node never needs it again.
+     *
+     * The protocol id stays `/sereus/seed/1.0.0` and no version field is added:
+     * there is no backwards compatibility yet, a receiver without this feature
+     * ignores the field and refuses by its anchored policy, and a sender without it
+     * gets a definite refusal (`claim-proof-invalid`) from an unclaimed node.
+     */
+    claimProof?: string;
+}
+/**
+ * Why a seed was refused, for callers that must branch on the cause without
+ * parsing the human-readable `reason`. The phone claiming a node needs to tell
+ * "someone else already claimed it" from "wrong secret".
+ *
+ *  - `already-claimed`: the node's anchor already holds an owner key other than
+ *    the signer's; the claim secret is no longer consulted.
+ *  - `claim-proof-invalid`: the node is unclaimed and the seed carried no claim
+ *    proof, or a proof that does not verify.
+ *  - `claim-rate-limited`: too many failed proofs recently; the proof was not
+ *    verified. Retry after the window.
+ *  - `claim-not-persisted`: the proof verified but the node could not durably
+ *    record the claim; nothing was anchored, so the same claim may be retried.
+ */
+export type SeedRefusalCode = 'already-claimed' | 'claim-proof-invalid' | 'claim-rate-limited' | 'claim-not-persisted';
+/**
+ * What a claim settles for the node that accepted it: the party it serves from now on
+ * and the owner it belongs to. Both come from the claim seed — the party is the seed's
+ * `partyId`, the owner the key that signed it — because an unclaimed node's own
+ * configured party is a placeholder; nobody could know the real one before the claim.
+ * Handed to `CadreNodeConfig.claim.record` before the owner is anchored, and carried by
+ * `claim:accepted`.
+ */
+export interface NodeClaimRecord {
+    /** The party the claim seed named: the cadre this node now serves. */
+    partyId: string;
+    /** The claimant's ed25519 owner key (base64url): the key the claim anchors. */
+    ownerKey: string;
 }
 /**
  * Acknowledgment message from new node to instigator.
@@ -1916,6 +2124,8 @@ export interface SeedAckMessage {
     accepted: boolean;
     /** Reason for rejection (if not accepted) */
     reason?: string;
+    /** Machine-readable refusal cause, when the refusing policy supplies one. */
+    code?: SeedRefusalCode;
 }
 /**
  * Request sent over the control network's `WAKE_PROTOCOL` from a same-cadre peer
@@ -1968,12 +2178,14 @@ export interface StrandAddrRequest {
  *
  * - `ok` — looked up; `multiaddrs` is the truth, possibly empty (strand not running here).
  * - `unavailable` — the responder could not answer: over its concurrency cap, the
- *   request was unreadable, or its own lookup threw (e.g. a control-database read failed).
- * - `refused` — the requester is not an authorized member in the responder's
- *   current view (possibly because its `CadrePeer` row has not replicated there yet);
- *   any `delegatePeerId` it carried was NOT recorded.
+ *   request was unreadable, or its own lookup threw.
+ *
+ * A requester the responder does not count as an authorized member (possibly because
+ * its `CadrePeer` row has not replicated there yet) gets no response at all: the
+ * responder's protocol guard resets the stream, and any `delegatePeerId` it carried
+ * is not recorded.
  */
-export type StrandAddrStatus = 'ok' | 'unavailable' | 'refused';
+export type StrandAddrStatus = 'ok' | 'unavailable';
 /**
  * Response to a {@link StrandAddrRequest}, carrying the responder's strand-node
  * multiaddrs, returned on the same stream.
@@ -1998,6 +2210,17 @@ export interface AuthorizePeerOptions {
     /** Optional multiaddrs for the peer */
     multiaddrs?: string[];
 }
+/**
+ * Where `deliverSeed` sends a seed: one multiaddr string, dialed as given, or a
+ * peer id with its known addresses. The object form merges the addresses into
+ * the peer store and dials by peer id, so an existing connection is reused and
+ * libp2p tries every address under the one delivery deadline. It is what a phone
+ * uses to claim a node from the addresses it scanned.
+ */
+export type SeedDeliveryTarget = string | {
+    peerId: string;
+    multiaddrs: string[];
+};
 /**
  * Result of applying a seed to a node.
  */
@@ -2008,6 +2231,8 @@ export interface ApplySeedResult {
     peersAdded: number;
     /** Error message if not successful */
     error?: string;
+    /** 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
@@ -2023,7 +2248,8 @@ export interface ApplySeedResult {
      * `CadreNode.dialColdStartBootstrap`), so this is a signal, not a fatal error.
      *
      * Zero failures is NOT proof of a live connection: the receiving node's
-     * membership gate denies AFTER the dialer's upgrade completes (see
+     * connection gate decides AFTER the dialer's upgrade completes, and closes a
+     * provisionally admitted connection at its deadline (see
      * `createMembershipConnectionGater`), so a dial can resolve and then be torn
      * down. Treat a non-zero value as certain failure and zero as "no failure
      * observed".
@@ -2035,30 +2261,37 @@ export interface ApplySeedResult {
  */
 export type NodeTopology = 'public' | 'nat';
 /**
- * Invite code for phone-to-server enrollment.
- * Used when a server invites a phone to join the cadre.
+ * 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.
  */
-export interface CadreInvite {
-    /** Party ID of the cadre */
-    partyId: string;
-    /** Multiaddrs to dial the owner */
-    ownerAddrs: string[];
-    /**
-     * Owner ed25519 public keys (base64url) of the cadre, carried out-of-band
-     * so a cold-start invitee can pin the trusted owner set before applying
-     * any seed (the seed itself cannot vouch for its own signer). Populated by
-     * `createInvite` from the issuer's OWN node-local trusted-owner anchor —
-     * not its replicated `OwnerKey` table, because the invitee anchors whatever
-     * arrives here and a stranger's genesis-inserted key must not ride an
-     * otherwise-legitimate invite into a fresh node's anchor.
-     */
-    ownerKeys?: string[];
-    /** Optional invite token for validation */
-    token?: string;
-    /** Timestamp when invite was created */
-    createdAt: number;
-    /** Optional expiration timestamp */
-    expiresAt?: number;
+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).
+     */
+    expiresInMs?: number;
+    /** How many redemptions it allows; default 1. */
+    uses?: number;
+}
+/** What `CadreNode.createCadreInvitation` returns: the bundle, and the same encoded for sharing. */
+export interface CreateCadreInvitationResult {
+    invitation: CadreInvitation;
+    /** `encodeCadreInvitation(invitation)`: base64url JSON for a QR code, a paste or a link. */
+    encoded: string;
+}
+/** 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;
 }
 /**
  * Options for adding a drone via provider API.
@@ -2069,15 +2302,6 @@ export interface AddDroneOptions {
     /** Multiaddrs of the drone (returned from provider) */
     droneMultiaddrs: string[];
 }
-/**
- * Options for adding a phone via invite flow.
- */
-export interface AddPhoneOptions {
-    /** Peer ID of the phone (sent by phone when it connects) */
-    phonePeerId: string;
-    /** Invite token for validation (must match issued invite) */
-    token?: string;
-}
 /**
  * Result of preparing a seed for drone initialization.
  */
@@ -2087,12 +2311,3 @@ export interface DroneInitResult {
     /** Base64url encoded seed for transport */
     encodedSeed: string;
 }
-/**
- * Result of creating an invite for a phone.
- */
-export interface InviteResult {
-    /** The invite to share out-of-band */
-    invite: CadreInvite;
-    /** Base64url encoded invite for QR/link */
-    encodedInvite: string;
-}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAqFA;;;;;;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;AA0dF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;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":"AAsFA;;;;;;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;AA0dF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;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.13.0",
+  "version": "1.14.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -77,7 +77,7 @@
     "@libp2p/tcp": "^11.0.28",
     "@libp2p/webrtc": "6.0.33",
     "@libp2p/websockets": "^10.1.21",
-    "@optimystic/db-p2p-storage-fs": "^1.11.0",
+    "@optimystic/db-p2p-storage-fs": "^1.12.0",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
@@ -93,12 +93,13 @@
     "@libp2p/peer-id": "^6.0.15",
     "@libp2p/peer-record": "^9.0.16",
     "@multiformats/multiaddr": "^13.0.3",
-    "@optimystic/db-core": "^1.11.0",
-    "@optimystic/db-p2p": "^1.11.0",
-    "@optimystic/quereus-plugin-crypto": "^1.11.0",
-    "@optimystic/quereus-plugin-optimystic": "^1.11.0",
+    "@noble/hashes": "^2.0.0",
+    "@optimystic/db-core": "^1.12.0",
+    "@optimystic/db-p2p": "^1.12.0",
+    "@optimystic/quereus-plugin-crypto": "^1.12.0",
+    "@optimystic/quereus-plugin-optimystic": "^1.12.0",
     "@quereus/quereus": "^4.20.1",
-    "@serfab/quereus-plugin-sereus": "^1.13.0",
+    "@serfab/quereus-plugin-sereus": "^1.14.0",
     "debug": "^4.4.3",
     "libp2p": "^3.3.11",
     "uint8arrays": "^6.1.1"