@serfab/cadre-core 1.13.0 → 1.15.0

package/dist/seed-bootstrap.d.ts

@@ -1,7 +1,7 @@
 import type { Libp2p } from '@libp2p/interface';
 import { type PeerDialBudget } from './peer-dial.js';
-import type { ControlNetworkSeed, SeedAckMessage, AuthorizePeerOptions, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, PeerAddressRecord, DeviceTokenRecord, RevocationRow, RevocationLedgerOpenResult } from './types.js';
-import type { ControlDatabase } from './control-database.js';
+import type { ControlNetworkSeed, SeedPeer, SeedAckMessage, SeedDeliveryTarget, AuthorizePeerOptions, ApplySeedResult, AddDroneOptions, DroneInitResult, CadreInviteRow, PeerAddressRecord, DeviceTokenRecord, RevocationRow, RevocationLedgerOpenResult } from './types.js';
+import type { ControlDatabase, MachineRemovalWrites } from './control-database.js';
 import { type SeedTrustPolicy } from './seed-trust-policy.js';
 import type { TrustedOwnerStore } from './trusted-owner-store.js';
 /** Protocol ID for seed delivery */
@@ -15,17 +15,6 @@ export declare const SEED_PROTOCOL = "/sereus/seed/1.0.0";
  * the body is handed straight to `TextDecoder`.
  */
 export declare function decodeLengthPrefixedFrame(data: Uint8Array, maxLength?: number): Uint8Array;
-/**
- * Derive the base64url ed25519 public key embedded in an Ed25519 libp2p PeerId.
- *
- * An Ed25519 PeerId is an identity multihash of the public key, so
- * `peerIdFromString(id).publicKey.raw` is the 32-byte ed25519 key whose
- * base64url form matches the `OwnerKey.Key` representation (and
- * `ed25519KeyPairFromLibp2p().publicKeyB64`). Returns null for a non-Ed25519
- * id, a missing embedded key, or any parse failure — callers treat null as
- * "not an owner" rather than throwing.
- */
-export declare function ed25519PublicKeyB64FromPeerId(peerId: string): string | null;
 /**
  * Canonical byte representation of the authenticated seed fields.
  *
@@ -36,6 +25,22 @@ export declare function ed25519PublicKeyB64FromPeerId(peerId: string): string |
  * the fields the producer actually emits.
  */
 export declare function canonicalSeedPayload(seed: Pick<ControlNetworkSeed, 'partyId' | 'peers'>): string;
+/**
+ * The digest a seed's signature covers: sha256 over {@link canonicalSeedPayload},
+ * base64url. One function so the signer (`createSeed`), the verifier
+ * (`validateSeedSignature`) and the claim proof (`claim-proof.ts`, which binds a
+ * proof to one seed through this value) all name the same bytes.
+ */
+export declare function seedDigest(seed: Pick<ControlNetworkSeed, 'partyId' | 'peers'>): string;
+/**
+ * Merge a peer list's addresses into `node`'s peer store, so the node can dial them: the
+ * seed's peers after its signature and trust checks, the dial hints a member returns on
+ * a cadre invitation redemption (`cadre-invite-protocol.ts`), or the node a seed is being
+ * delivered to ({@link SeedBootstrapService.deliverSeed}). Best-effort per peer — one
+ * unparsable entry costs that peer, not the rest — and a peer with no address is skipped,
+ * since there is nothing to dial. Returns how many peers were merged.
+ */
+export declare function mergeSeedPeers(node: Libp2p, peers: readonly SeedPeer[]): Promise<number>;
 /**
  * Configuration for the SeedBootstrapService
  */
@@ -46,13 +51,6 @@ export interface SeedBootstrapConfig {
     ownerPrivateKey?: string;
     /** Owner public key (base64url) - derived from private key if not provided */
     ownerPublicKey?: string;
-    /**
-     * Optional async resolver returning the multiaddrs to embed in invites.
-     * When unset, `libp2pNode.getMultiaddrs()` is used. Hosts behind NAT supply
-     * this (via `@serfab/cadre-host`'s NatService) to substitute the host's
-     * DDNS hostname and externally-mapped port.
-     */
-    inviteAddressResolver?: () => Promise<string[]>;
     /**
      * Trust anchor for incoming seeds. Decides whether a signature-verified
      * `signerKey` should be trusted, against the receiver's anchored owner
@@ -96,18 +94,20 @@ export interface SeedBootstrapConfig {
      */
     linkRoundTripMs?: number;
     /**
-     * Time {@link SeedBootstrapService.deliverSeed} waits for the whole exchange —
-     * dial, write, ack read — before aborting (ms). Bounds the SENDER against a seed
-     * target that accepts the stream and then never replies; the target is a
-     * not-yet-trusted node during onboarding, so this is the more exposed
+     * Time {@link SeedBootstrapService.deliverSeed} waits for the request — opening the
+     * stream, write, ack read — before aborting (ms). For a multiaddr string, or a peer id
+     * with no addresses, opening the stream includes the dial; for a peer id with addresses
+     * the connection is formed first, outside this limit and within {@link dialBudget}.
+     * Bounds the SENDER against a seed target that accepts the stream and then never replies;
+     * the target is a not-yet-trusted node during onboarding, so this is the more exposed
      * direction than the receiver knobs above.
      *
      * Defaults to `relayedRequestBudgetMs(linkRoundTripMs)` (`link-budget.ts`; 28.5 s at the
-     * default declaration): one dial that may need a relay, then one request and its answer.
-     * Delivery does not set `runOnLimitedConnection`, so it does not use a limited relayed
-     * connection today; the relayed-dial count is the upper bound on the dial it can use, the
-     * same choice `CadreNode.controlDialBudget` makes for every address. It holds only link work
-     * because the receiver acks before its owner dials.
+     * default declaration): one dial that may need a relay, then one request and its answer —
+     * sized for the forms that dial inside it. Delivery does not set `runOnLimitedConnection`,
+     * so it does not use a limited relayed connection today; the relayed-dial count is the upper
+     * bound on the dial it can use, the same choice `CadreNode.controlDialBudget` makes for every
+     * address. It holds only link work because the receiver acks before its owner dials.
      *
      * NOTE: no transfer allowance — a seed is a peer list of a few KB, and `MAX_SEED_SIZE` (1 MiB)
      * is a defensive cap. If seeds ever grow toward that cap, add an allowance the way
@@ -117,8 +117,8 @@ export interface SeedBootstrapConfig {
     /**
      * Time limits for each peer this service dials from a list of addresses —
      * {@link SeedBootstrapService.applySeed}'s owner dials and
-     * {@link SeedBootstrapService.dialInvite} — per address and per peer (see
-     * `peer-dial.ts`). Defaults to {@link DEFAULT_PEER_DIAL_BUDGET}; a `CadreNode`
+     * {@link SeedBootstrapService.deliverSeed}'s dial of a peer id with addresses — per
+     * address and per peer (see `peer-dial.ts`). Defaults to {@link DEFAULT_PEER_DIAL_BUDGET}; a `CadreNode`
      * passes its `network.controlCohort` limits.
      */
     dialBudget?: PeerDialBudget;
@@ -182,10 +182,10 @@ export declare class SeedBootstrapService {
      * `registerHandler` (default true) gates registration of the shared inbound
      * `/sereus/seed/1.0.0` handler on `libp2pNode`. Persistent services
      * (`initializeSeedBootstrap`, `enableSeedListener`) own that handler and leave
-     * it on. The throwaway temp services CadreNode builds in `applySeed` /
-     * `dialInvite` pass `false`: they only need the stored `libp2pNode` /
-     * `controlDatabase` for dialing and known-key lookup, and must NOT bind a
-     * discarded closure to the shared node (a handler leak, and a second
+     * it on. The throwaway temp service CadreNode builds in `applySeed` passes
+     * `false`: it only needs the stored `libp2pNode` / `controlDatabase` for
+     * dialing and known-key lookup, and must NOT bind a discarded closure to the
+     * shared node (a handler leak, and a second
      * `handle()` of the same protocol throws `DuplicateProtocolHandlerError`).
      *
      * Rejects when libp2p refuses the registration; the node and database are
@@ -319,7 +319,7 @@ export declare class SeedBootstrapService {
      *
      * The `CadrePeer.AuthorizedDelete` (`check on delete`) constraint validates a
      * signature over the DISTINCT 'remove'-tagged digest
-     * `digest('CadreControl.CadrePeer', 'remove', old.PeerId, old.StampId)` by an owner
+     * `digest('CadreControl.CadrePeer', 'remove', party_id(), old.PeerId, old.StampId)` by an owner
      * key — deliberately NOT the insert voucher digest, so the row's stored `VouchSig` can
      * never be replayed to delete.
      *
@@ -339,6 +339,42 @@ export declare class SeedBootstrapService {
      * owner-key precondition and the absent-row gate the notify depends on (below).
      */
     removePeer(peerId: string): Promise<void>;
+    /**
+     * Seat `ownerPublicKey` as a further owner, signed by this service's owner key. The
+     * liveness check, the stamp, the signature and the membership notify are
+     * {@link ControlDatabase.insertOwnerKeyVouched}'s; what stays here is the owner-key
+     * precondition, checked before any read (see {@link removePeer}).
+     *
+     * @returns `true` when the row was seated, `false` when the key is already a live owner.
+     */
+    addOwner(ownerPublicKey: string): Promise<boolean>;
+    /**
+     * Remove `ownerPublicKey` from the owners, signed by this service's owner key: the delete
+     * and its `Revocation` tombstone in one transaction. The by-name refusals (self-removal,
+     * the last owner), the digests and the membership notify are
+     * {@link ControlDatabase.deleteOwnerKey}'s; what stays here is the owner-key precondition,
+     * checked before any read (see {@link removePeer}).
+     *
+     * @returns `true` when the row was removed, `false` when the key is not a live owner here.
+     */
+    removeOwner(ownerPublicKey: string): Promise<boolean>;
+    /**
+     * Re-vouch another owner's row under this service's owner key, so it stands on a remaining
+     * owner's signature before the owner that added it is removed
+     * ({@link ControlDatabase.revouchOwnerKey}; for `CadreNode.removeMachine` only). What stays
+     * here is the owner-key precondition, checked before any read (see {@link removePeer}).
+     *
+     * @returns `true` when the row was re-vouched, `false` when the key is not a live owner here.
+     */
+    revouchOwner(ownerPublicKey: string): Promise<boolean>;
+    /**
+     * Remove a machine completely, signed by this service's owner key: its `CadrePeer` row, its
+     * `OwnerKey` row when `target.ownerKey` names one, its `DeviceToken` row, and the
+     * withdrawal of every invitation in `target.inviteKeys`, all in one transaction
+     * ({@link ControlDatabase.removeMachine}). What stays here is the owner-key precondition,
+     * checked before any read (see {@link removePeer}).
+     */
+    removeMachine(target: Parameters<ControlDatabase['removeMachine']>[0]): Promise<MachineRemovalWrites>;
     /**
      * Owner "re-touch" of an existing `CadrePeer` membership row: bump `UpdatedAt` and
      * re-vouch the row so it is re-emitted as a fresh, broadcasting transaction. This is
@@ -387,6 +423,27 @@ export declare class SeedBootstrapService {
      *   initialized.
      */
     openRevocationLedger(): Promise<RevocationLedgerOpenResult>;
+    /**
+     * Owner-signed INSERT of a `CadreInvite` row — an invitation any member machine can redeem
+     * on this owner's behalf ({@link ControlDatabase.insertCadreInvite}). The keypair mint, the
+     * expiry and use-count defaults, and the bundle the holder receives are
+     * `CadreNode.createCadreInvitation`'s; what stays here is the owner-key precondition and
+     * the signature, as {@link insertSelfDeviceToken} keeps them for device tokens.
+     *
+     * @returns the row as stored, which the invitation bundle carries verbatim.
+     * @throws if no owner private key is configured or the control database is not initialized.
+     */
+    insertCadreInvite(invite: Parameters<ControlDatabase['insertCadreInvite']>[0]): Promise<CadreInviteRow>;
+    /**
+     * Owner-signed WITHDRAWAL of a `CadreInvite`: the `Revocation` tombstone over its stamp, with
+     * the row kept ({@link ControlDatabase.withdrawCadreInvite}). What stays here is the
+     * owner-key precondition.
+     *
+     * @returns `true` when this call filed the tombstone, `false` when the row is absent here or
+     *   already withdrawn.
+     * @throws if no owner private key is configured or the control database is not initialized.
+     */
+    withdrawCadreInvite(key: string): Promise<boolean>;
     /**
      * Create a seed from the current control network state.
      * The seed contains peer information and is signed by an owner.
@@ -405,11 +462,11 @@ export declare class SeedBootstrapService {
      *
      * A key accepted via a pin/TOFU is persisted into the anchor (the policy says
      * so via `SeedTrustDecision.anchorAs`), so the next seed from that owner is
-     * anchored without re-supplying the invite.
+     * anchored without re-supplying the pin.
      *
      * @param seed - The seed to apply (already transport-decoded).
      * @param options.trustPolicy - Per-call policy override (e.g. a
-     *   `pinnedKeyTrustPolicy` derived from a `CadreInvite`) used instead of the
+     *   `pinnedKeyTrustPolicy` built from an operator pin) used instead of the
      *   service-configured default for this seed only.
      */
     applySeed(seed: ControlNetworkSeed, options?: {
@@ -436,7 +493,7 @@ export declare class SeedBootstrapService {
     private dialSeedOwners;
     /**
      * Persist a signer that a pin/TOFU accepted into the node-local anchor, so a
-     * later seed from the same owner is anchored without re-supplying the invite
+     * later seed from the same owner is anchored without re-supplying the pin
      * or re-prompting. Only the policy decides this happens (`anchorAs` is unset
      * when the key was already anchored, so a plain re-apply writes nothing) and
      * `trust()` is idempotent, keeping the original provenance for a known key.
@@ -444,14 +501,19 @@ export declare class SeedBootstrapService {
      * Failure to PERSIST does not fail the seed: `trust()` reflects the key in the
      * in-memory anchor synchronously, so this seed and the rest of the session are
      * unaffected — only durability across a restart is lost, and that is logged.
+     * That holds for pins and TOFU, which are re-supplied at the next start; a claim
+     * is the opposite case, so `claimSecretTrustPolicy` anchors its signer itself,
+     * awaits durability, and never sets `anchorAs` (the type excludes `'claim'`).
      *
      * NOTE: anchoring a key can flip `CadrePeer` rows ALREADY present from
      * unauthorized to authorized, which the write-driven membership-gate refresh
-     * (`ControlDatabase.mutateCadrePeer`) cannot see — no row was written. Every
-     * anchor mutation today rides seed application, and both seed paths refresh the
-     * gate explicitly afterwards (`CadreNode.applySeed`, `onSeedApplied`). If some
-     * future path anchors an owner OUTSIDE seed application, it owes the same
-     * `CadreNode.refreshMembershipGate()` — or the anchor needs its own hub.
+     * (`ControlDatabase.mutateCadrePeer`) cannot see — no row was written. The anchor
+     * is mutated from two places: here, on seed application, where both seed paths
+     * refresh the gate explicitly afterwards (`CadreNode.applySeed`, `onSeedApplied`);
+     * and by the anchor sync (`CadreNode.syncOwnerAnchor`), which runs INSIDE the
+     * membership refresh, ahead of the membership read, so its changes are judged by
+     * the same pass. If some future path anchors an owner outside both, it owes the
+     * same `CadreNode.refreshMembershipGate()` — or the anchor needs its own hub.
      */
     private anchorAcceptedSigner;
     /**
@@ -465,26 +527,59 @@ export declare class SeedBootstrapService {
     /**
      * Deliver a seed directly to a peer via the /sereus/seed/1.0.0 protocol.
      *
-     * Sender hardening: the whole exchange — dial, write, ack read — is bounded by
-     * {@link seedDeliverTimeoutMs}, and the ack is capped at {@link MAX_SEED_SIZE}.
-     * The target is a NOT-YET-TRUSTED node the instigator chose to dial during
-     * onboarding, so an unbounded read here is strictly more exposed than the
-     * membership-gated receiver paths: without the bound a target that accepts the
-     * stream and never replies parks this call forever, and one that streams
-     * arbitrary bytes as a fake ack exhausts memory.
+     * `target` is a multiaddr string, dialed as given, or a peer id with its addresses
+     * ({@link SeedDeliveryTarget}). For the second, the connection is formed first and on
+     * its own limits ({@link connectForDelivery}): an open one is reused, otherwise each
+     * address is dialed in turn, so one that never answers cannot use up the time a later
+     * one needed. Its addresses are also merged into the peer store, so identify and later
+     * dials see them. A peer id with no addresses is dialed by id, which reuses an open
+     * connection or tries the peer store's addresses. `options.claimProof` rides beside
+     * the seed in the message when the target is a brand-new node being claimed
+     * (`claim-proof.ts`).
+     *
+     * Sender hardening: the request — opening the stream (with its dial, for the forms
+     * that dial by `dialProtocol`), write, ack read — is bounded by {@link seedDeliverTimeoutMs},
+     * and the ack is capped at {@link MAX_SEED_SIZE}. The target is a NOT-YET-TRUSTED node the
+     * instigator chose to dial during onboarding, so an unbounded read here is strictly more
+     * exposed than the membership-gated receiver paths: without the bound a target that accepts
+     * the stream and never replies parks this call forever, and one that streams arbitrary bytes
+     * as a fake ack exhausts memory. A peer id with addresses can therefore take up to
+     * `dialBudget.totalMs` plus {@link seedDeliverTimeoutMs} (114.5 s at the default declared
+     * link) when none of its addresses answers.
+     *
+     * @throws {PeerUnreachableError} for a peer id with addresses, when no connection to it
+     *   formed; nothing was sent. Anything else thrown after the connection formed means the
+     *   node was reached and the exchange failed.
      */
-    deliverSeed(targetMultiaddr: string, seed: ControlNetworkSeed): Promise<SeedAckMessage>;
+    deliverSeed(target: SeedDeliveryTarget, seed: ControlNetworkSeed, options?: {
+        claimProof?: string;
+    }): Promise<SeedAckMessage>;
+    /**
+     * The part of {@link deliverSeed} that runs before its deadline: how the delivery's stream
+     * will be opened, with any connection it needs already formed.
+     */
+    private seedStreamOpener;
+    /**
+     * A connection to `peerId` for {@link deliverSeed}, from {@link dialPeerAddrs}: one already
+     * open without relay limits, or one dialed from `addrs` — each address on
+     * `dialBudget.perAddressMs`, the whole peer within `dialBudget.totalMs`, direct addresses
+     * before relayed ones and the given order otherwise.
+     *
+     * @throws {PeerUnreachableError} when no connection formed, with the dial's error as `cause`.
+     */
+    private connectForDelivery;
     /**
      * Open one stream to the target, send the seed frame, half-close, and read the ack.
      *
-     * `signal` is the deadline from {@link deliverSeed}: it goes to `dialProtocol` so
-     * a timeout during connect aborts the dial, and into {@link exchangeFrame} so a
-     * timeout after the stream is open resets it — releasing the otherwise unbounded
+     * `signal` is the deadline from {@link deliverSeed}: it goes to `openStream` so a
+     * timeout while dialing or opening the stream aborts it, and into {@link exchangeFrame}
+     * so a timeout after the stream is open resets it — releasing the otherwise unbounded
      * ack-read.
      *
      * Deliberately NOT `runOnLimitedConnection`: a wake sets it because a wake is a
-     * tiny frame over a relay, whereas a seed is up to 1MB and this delivery path
-     * does not dial relay addresses today. Changing that is a separate decision.
+     * tiny frame over a relay, whereas a seed is up to 1MB, so a relayed address that
+     * forms only a limited connection fails here when the stream is opened. Changing
+     * that is a separate decision.
      */
     private sendSeed;
     /**
@@ -502,32 +597,16 @@ export declare class SeedBootstrapService {
     getRelayAddress(): Promise<string | null>;
     /**
      * Validate a seed's signature.
+     *
+     * @param digestB64 - The seed's {@link seedDigest}, when the caller already computed it
+     *   (`verifyAndMergeSeed` shares one digest between this check and the trust context).
      */
-    validateSeedSignature(seed: ControlNetworkSeed): boolean;
+    validateSeedSignature(seed: ControlNetworkSeed, digestB64?: string): boolean;
     /**
-     * Query peers from the control database.
-     *
-     * Owner identity is sourced from the `OwnerKey` table, not from the
-     * transport peer ID. An Ed25519 libp2p PeerId embeds its public key (identity
-     * multihash), so each peer's ed25519 key is derivable from its `PeerId`; a
-     * peer is an owner iff that derived key is in the `OwnerKey` set.
-     * This makes any owner node markable — not just the local one — and ties
-     * `isOwner` to the control table rather than to `peerId === self`.
-     *
-     * Read through {@link ControlDatabase.queryCadrePeers}, not a raw `CadrePeer`
-     * select: that reader drops any row whose `StampId` is retired in
-     * `CadreControl.Revocation`, so a removed member's addresses are never packed
-     * into a seed and pushed into a joiner's peerstore (`applySeed` adds every
-     * seed peer's addrs and dials the owner-flagged ones). A revoked peer is off
-     * the addressable surface everywhere, and this is one of its exits.
-     *
-     * NOTE: this is the one owner lookup deliberately left on the REPLICATED
-     * table rather than the node-local anchor. `SeedPeer.isOwner` is a dial hint
-     * — the receiver dials owner-flagged peers first — not a trust decision, and
-     * the receiver re-derives real trust from its own anchor. So a polluted table
-     * costs at most a wasted dial, while anchoring here would silently drop
-     * legitimate co-owners this node never pinned. If `isOwner` ever gates
-     * anything the receiver TRUSTS, move it to the anchor.
+     * The peers a seed carries: the control database's own projection
+     * ({@link ControlDatabase.querySeedPeers}, shared with the cadre invitation redemption
+     * reply), which reads through the revocation filter and flags owners from the replicated
+     * `OwnerKey` table — a dial hint, not a trust decision (the NOTE at `projectSeedPeers`).
      */
     private queryPeers;
     /**
@@ -559,7 +638,11 @@ export declare class SeedBootstrapService {
      * the exchange.
      */
     private handleSeedStream;
-    /** Read the inbound seed frame to EOF (bounded and size-capped) and decode it. */
+    /**
+     * Read the inbound seed frame to EOF (bounded and size-capped) and decode it. The
+     * claim proof comes back beside the seed: it is not part of what the owner signed, so
+     * `ControlNetworkSeed` does not carry it.
+     */
     private readSeedFrame;
     /**
      * Shutdown the service.
@@ -585,31 +668,6 @@ export declare class SeedBootstrapService {
      * @returns Seed and encoded seed for drone initialization
      */
     addDrone(options: AddDroneOptions): Promise<DroneInitResult>;
-    /**
-     * Create an invite for a phone to join the cadre.
-     *
-     * Use this when a server (public IP) wants to invite a phone (NAT'd).
-     * The invite is shared out-of-band (QR code, link, etc.) and contains
-     * the server's address so the phone can dial in.
-     *
-     * @param token - Optional invite token for validation
-     * @param expiresIn - Optional expiration time in milliseconds
-     * @returns Invite and encoded invite for sharing
-     */
-    createInvite(token?: string, expiresIn?: number): Promise<InviteResult>;
-    /**
-     * Accept a phone connection using an invite.
-     *
-     * Use this when a phone dials in with an invite token. This method:
-     * 1. Validates the token if provided
-     * 2. Authorizes the phone peer
-     *
-     * After this, the phone can sync the control database normally.
-     *
-     * @param options - Phone peer info and invite token
-     * @param issuedInvite - The original invite for validation
-     */
-    acceptPhone(options: AddPhoneOptions, issuedInvite?: CadreInvite): Promise<void>;
     /**
      * Add a phone to the cadre with relay support.
      *
@@ -621,20 +679,4 @@ export declare class SeedBootstrapService {
      * @returns Seed with relay addresses for out-of-band delivery
      */
     addPhoneWithRelay(phonePeerId: string): Promise<DroneInitResult>;
-    /**
-     * Encode an invite for out-of-band delivery.
-     */
-    encodeInvite(invite: CadreInvite): string;
-    /**
-     * Decode an invite from base64url encoding.
-     */
-    decodeInvite(encoded: string): CadreInvite;
-    /**
-     * Dial an owner from an invite.
-     * Use this on a phone after receiving an invite to connect to the owner.
-     *
-     * @param invite - The invite received out-of-band
-     * @returns Connection to the owner
-     */
-    dialInvite(invite: CadreInvite): Promise<void>;
 }