@serfab/cadre-core 1.13.0 → 1.14.0

package/src/seed-bootstrap.ts

@@ -1,24 +1,31 @@
 import debug from 'debug';
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
 import { digest, sign, verify, getPublicKey } from '@optimystic/quereus-plugin-crypto';
-import type { Libp2p, Connection } from '@libp2p/interface';
+import type { Libp2p, Connection, PeerId, Stream } from '@libp2p/interface';
 import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
 import { peerIdFromString } from '@libp2p/peer-id';
 import { type ControlStream, withDeadline, exchangeFrame, readStreamToEnd, replyAndClose } from './control-stream.js';
-import { dialPeerAddrs, SelfRelayOnlyError, DEFAULT_PEER_DIAL_BUDGET, type PeerDialBudget } from './peer-dial.js';
+import {
+  dialPeerAddrs,
+  SelfRelayOnlyError,
+  PeerUnreachableError,
+  DEFAULT_PEER_DIAL_BUDGET,
+  type PeerDialBudget,
+} from './peer-dial.js';
+import { withTrailingPeerId } from './peer-record.js';
 import { relayedRequestBudgetMs } from './link-budget.js';
 import type {
   ControlNetworkSeed,
   SeedPeer,
   SeedMessage,
   SeedAckMessage,
+  SeedRefusalCode,
+  SeedDeliveryTarget,
   AuthorizePeerOptions,
   ApplySeedResult,
   AddDroneOptions,
-  AddPhoneOptions,
   DroneInitResult,
-  InviteResult,
-  CadreInvite,
+  CadreInviteRow,
   PeerAddressRecord,
   DeviceTokenRecord,
   RevocationRow,
@@ -28,6 +35,7 @@ import type { ControlDatabase } from './control-database.js';
 import { generateStampId } from './control-database.js';
 import { canonicalJson } from './canonical-json.js';
 import { deviceTokenAddDigest } from './peer-authorization.js';
+import { ed25519PublicKeyB64FromPeerId } from './ed25519-key.js';
 import {
   type SeedTrustPolicy,
   type SeedTrustDecision,
@@ -79,28 +87,6 @@ export function decodeLengthPrefixedFrame(data: Uint8Array, maxLength = MAX_SEED
   return data.subarray(4, 4 + length);
 }
 
-/**
- * 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 function ed25519PublicKeyB64FromPeerId(peerId: string): string | null {
-  try {
-    const parsed = peerIdFromString(peerId);
-    if (parsed.type !== 'Ed25519' || !parsed.publicKey) {
-      return null;
-    }
-    return uint8ArrayToString(parsed.publicKey.raw, 'base64url');
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Canonical byte representation of the authenticated seed fields.
  *
@@ -116,12 +102,39 @@ export function canonicalSeedPayload(
   return canonicalJson({ partyId: seed.partyId, peers: seed.peers });
 }
 
+/**
+ * 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 function seedDigest(seed: Pick<ControlNetworkSeed, 'partyId' | 'peers'>): string {
+  return digest([canonicalSeedPayload(seed)], 'sha256', 'base64url') as string;
+}
+
 /**
  * An {@link ApplySeedResult} for a seed refused before the owner-dial loop ran,
  * so the dial counters read zero rather than being absent.
  */
-function seedRejected(error: string): ApplySeedResult {
-  return { success: false, peersAdded: 0, error, ownerDialsAttempted: 0, ownerDialsFailed: 0 };
+function seedRejected(error: string, code?: SeedRefusalCode): ApplySeedResult {
+  return {
+    success: false,
+    peersAdded: 0,
+    error,
+    ...(code !== undefined ? { code } : {}),
+    ownerDialsAttempted: 0,
+    ownerDialsFailed: 0,
+  };
+}
+
+/** What rides beside a seed into {@link SeedBootstrapService.verifyAndMergeSeed}. */
+interface SeedApplyOptions {
+  /** Per-call policy override, used instead of the service-configured default for this seed only. */
+  trustPolicy?: SeedTrustPolicy;
+  /** The claim proof the message carried, when the seed came over the wire. */
+  claimProof?: string;
+  /** The delivering peer, when the seed came over the wire. */
+  remotePeerId?: string;
 }
 
 /** What dialing a seed's owner peers produced — the owner-dial half of an {@link ApplySeedResult}. */
@@ -143,6 +156,60 @@ function parseDialAddrs(addrs: readonly string[]): Multiaddr[] {
   return parsed;
 }
 
+/**
+ * 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 async function mergeSeedPeers(node: Libp2p, peers: readonly SeedPeer[]): Promise<number> {
+  let peersAdded = 0;
+  for (const peer of peers) {
+    if (peer.multiaddrs.length === 0) {
+      continue;
+    }
+    try {
+      const peerId = peerIdFromString(peer.peerId);
+      const addrs = peer.multiaddrs.map(ma => multiaddr(ma));
+      await node.peerStore.merge(peerId, { multiaddrs: addrs });
+      peersAdded++;
+      log('Added peer to store: %s with %d addrs', peer.peerId, addrs.length);
+    } catch (error) {
+      log('Failed to add peer %s: %o', peer.peerId, error);
+    }
+  }
+  return peersAdded;
+}
+
+/** Opens a seed delivery's stream under the delivery deadline's signal. */
+type SeedStreamOpener = (signal: AbortSignal) => Promise<Stream>;
+
+/**
+ * A delivery target's addresses, each bound to its peer id (`withTrailingPeerId`) so the dial
+ * authenticates the node it aims at rather than trusting whoever answers. An address that does
+ * not parse, or that names another peer, throws: that is the caller's mistake, not the node
+ * being unreachable.
+ */
+function deliveryDialAddrs(peerId: string, addrs: readonly string[]): Multiaddr[] {
+  return addrs.map((text) => {
+    const bound = withTrailingPeerId(multiaddr(text), peerId);
+    if (!bound) {
+      throw new Error(`Seed delivery to ${peerId}: address ${text} names another peer`);
+    }
+    return bound;
+  });
+}
+
+/**
+ * A connection to `peerId` that `node` already holds and a seed stream can use: open and without
+ * relay limits, the rule libp2p applies when `dialProtocol` reuses a connection.
+ */
+function openUnlimitedConnection(node: Libp2p, peerId: PeerId): Connection | undefined {
+  return node.getConnections(peerId).find((c) => c.status === 'open' && c.limits === undefined);
+}
+
 /**
  * Configuration for the SeedBootstrapService
  */
@@ -153,13 +220,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
@@ -203,18 +263,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
@@ -224,8 +286,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;
@@ -320,10 +382,10 @@ export 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
@@ -447,7 +509,7 @@ export class SeedBootstrapService {
    */
   async insertSelfDeviceToken(record: DeviceTokenRecord): Promise<void> {
     const stampId = generateStampId(record.peerId);
-    const signature = this.signDigest(deviceTokenAddDigest({ ...record, stampId }));
+    const signature = this.signDigest(deviceTokenAddDigest(this.config.partyId, { ...record, stampId }));
     if (!this.controlDatabase) {
       throw new Error('Control database not initialized');
     }
@@ -557,7 +619,7 @@ export 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.
    *
@@ -606,6 +668,43 @@ export class SeedBootstrapService {
     log('Peer %s removed successfully (stamp retired)', peerId);
   }
 
+  /**
+   * 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.
+   */
+  async addOwner(ownerPublicKey: string): Promise<boolean> {
+    const ownerKey = this.requireOwnerPublicKey();
+    if (!this.controlDatabase) {
+      throw new Error('Control database not initialized');
+    }
+    return await this.controlDatabase.insertOwnerKeyVouched(
+      ownerPublicKey, ownerKey, message => this.signMessageBytes(message),
+    );
+  }
+
+  /**
+   * 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.
+   */
+  async removeOwner(ownerPublicKey: string): Promise<boolean> {
+    const ownerKey = this.requireOwnerPublicKey();
+    if (!this.controlDatabase) {
+      throw new Error('Control database not initialized');
+    }
+    return await this.controlDatabase.deleteOwnerKey(
+      ownerPublicKey, ownerKey, message => this.signMessageBytes(message),
+    );
+  }
+
   /**
    * 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
@@ -692,6 +791,42 @@ export class SeedBootstrapService {
     );
   }
 
+  /**
+   * 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.
+   */
+  async insertCadreInvite(invite: Parameters<ControlDatabase['insertCadreInvite']>[0]): Promise<CadreInviteRow> {
+    // Fail fast on a keyless service before any DB work (see removePeer).
+    const ownerKey = this.requireOwnerPublicKey();
+    if (!this.controlDatabase) {
+      throw new Error('Control database not initialized');
+    }
+    return await this.controlDatabase.insertCadreInvite(invite, ownerKey, message => this.signMessageBytes(message));
+  }
+
+  /**
+   * 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.
+   */
+  async withdrawCadreInvite(key: string): Promise<boolean> {
+    const ownerKey = this.requireOwnerPublicKey();
+    if (!this.controlDatabase) {
+      throw new Error('Control database not initialized');
+    }
+    return await this.controlDatabase.withdrawCadreInvite(key, ownerKey, message => this.signMessageBytes(message));
+  }
+
   /**
    * Create a seed from the current control network state.
    * The seed contains peer information and is signed by an owner.
@@ -717,10 +852,8 @@ export class SeedBootstrapService {
     };
     
     // Sign the seed over its canonical byte representation
-    const seedJson = canonicalSeedPayload(seedData);
-    const seedDigest = digest([seedJson], 'sha256', 'base64url') as string;
     const signature = sign(
-      seedDigest,
+      seedDigest(seedData),
       this.config.ownerPrivateKey,
       'ed25519',
       'base64url',
@@ -751,11 +884,11 @@ export 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.
    */
   async applySeed(
@@ -776,22 +909,27 @@ export class SeedBootstrapService {
    */
   private async verifyAndMergeSeed(
     seed: ControlNetworkSeed,
-    options?: { trustPolicy?: SeedTrustPolicy }
+    options?: SeedApplyOptions
   ): Promise<ApplySeedResult> {
     if (!this.libp2pNode) {
       return seedRejected('Service not initialized');
     }
 
-    // NOTE: `seed.partyId` is never checked against `config.partyId`. Nothing
-    // downstream reads it — trust is keyed on `signerKey` vs the anchor, and the
-    // anchor a stray-party seed could write into belongs to THIS party, which
-    // only a caller-supplied pin for that signer can reach. If applying a seed
-    // ever branches on its partyId (or the anchor becomes multi-party), reject a
+    // NOTE: `seed.partyId` is never checked against `config.partyId`. Trust is keyed on
+    // `signerKey` vs the anchor, and the anchor a stray-party seed could write into
+    // belongs to THIS party, which only a caller-supplied pin for that signer can reach.
+    // The one reader of the seed's party is the claim policy, which records it as the
+    // party the node now serves (`CadreNodeConfig.claim.record`): a mismatch is still not
+    // rejected there because an unclaimed node's own party is a placeholder, and the
+    // claim seed is the first thing to name the real one. If any other path ever
+    // branches on the seed's partyId (or the anchor becomes multi-party), reject a
     // mismatch here instead.
     log('Applying seed for party: %s', seed.partyId);
 
-    // Validate the seed signature
-    if (!this.validateSeedSignature(seed)) {
+    // One digest serves the signature check and the trust context: a claim proof is
+    // bound to the seed through the same value the signature covers.
+    const digestB64 = seedDigest(seed);
+    if (!this.validateSeedSignature(seed, digestB64)) {
       return seedRejected('Invalid seed signature');
     }
 
@@ -807,34 +945,20 @@ export class SeedBootstrapService {
       partyId: seed.partyId,
       signerKey: seed.signerKey,
       knownOwnerKeys,
+      // Optional-chained like `dialSeedOwners`: partial libp2p handles (unit-test doubles)
+      // omit `peerId`. A real node always has one, and a proof bound to a real peer id can
+      // only fail against '' — the safe direction.
+      localPeerId: this.libp2pNode.peerId?.toString() ?? '',
+      seedDigest: digestB64,
+      claimProof: options?.claimProof,
+      remotePeerId: options?.remotePeerId,
     });
     if (!decision.trusted) {
-      return seedRejected(decision.reason ?? 'Signer key not trusted by trust policy');
+      return seedRejected(decision.reason ?? 'Signer key not trusted by trust policy', decision.code);
     }
     await this.anchorAcceptedSigner(seed.signerKey, decision);
 
-    let peersAdded = 0;
-
-    // Add peers to the peer store
-    for (const peer of seed.peers) {
-      try {
-        // Import peer multiaddrs into the peer store
-        if (peer.multiaddrs.length > 0) {
-          const peerId = peerIdFromString(peer.peerId);
-          const addrs = peer.multiaddrs.map(ma => multiaddr(ma));
-
-          await this.libp2pNode.peerStore.merge(peerId, {
-            multiaddrs: addrs
-          });
-
-          peersAdded++;
-          log('Added peer to store: %s with %d addrs', peer.peerId, addrs.length);
-        }
-      } catch (error) {
-        log('Failed to add peer %s: %o', peer.peerId, error);
-      }
-    }
-
+    const peersAdded = await mergeSeedPeers(this.libp2pNode, seed.peers);
     log('Merged seed: %d peers added', peersAdded);
     return { success: true, peersAdded, ownerDialsAttempted: 0, ownerDialsFailed: 0 };
   }
@@ -897,7 +1021,7 @@ export class SeedBootstrapService {
 
   /**
    * 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.
@@ -905,14 +1029,19 @@ export 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 async anchorAcceptedSigner(signerKey: string, decision: SeedTrustDecision): Promise<void> {
     if (!decision.anchorAs || !this.config.trustedOwners) {
@@ -946,56 +1075,120 @@ export 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.
    */
-  async deliverSeed(targetMultiaddr: string, seed: ControlNetworkSeed): Promise<SeedAckMessage> {
+  async deliverSeed(
+    target: SeedDeliveryTarget,
+    seed: ControlNetworkSeed,
+    options?: { claimProof?: string },
+  ): Promise<SeedAckMessage> {
     if (!this.libp2pNode) {
       throw new Error('Service not initialized');
     }
-    // Capture the node so the closure below needs no non-null assertion.
-    const node = this.libp2pNode;
-    const addr = multiaddr(targetMultiaddr);
-
-    log('Delivering seed to: %s', targetMultiaddr);
+    const label = typeof target === 'string' ? target : target.peerId;
+    log('Delivering seed to: %s', label);
 
+    const openStream = await this.seedStreamOpener(this.libp2pNode, target);
     return await withDeadline(
       this.seedDeliverTimeoutMs,
-      `Seed delivery to ${targetMultiaddr}`,
-      (signal) => this.sendSeed(node, addr, seed, signal),
+      `Seed delivery to ${label}`,
+      (signal) => this.sendSeed(openStream, seed, options?.claimProof, signal),
     );
   }
 
+  /**
+   * 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 async seedStreamOpener(node: Libp2p, target: SeedDeliveryTarget): Promise<SeedStreamOpener> {
+    if (typeof target === 'string') {
+      const addr = multiaddr(target);
+      return (signal) => node.dialProtocol(addr, SEED_PROTOCOL, { signal });
+    }
+    const peerId = peerIdFromString(target.peerId);
+    const addrs = deliveryDialAddrs(target.peerId, target.multiaddrs);
+    await mergeSeedPeers(node, [{ peerId: target.peerId, multiaddrs: target.multiaddrs, isOwner: false }]);
+    if (addrs.length === 0) {
+      return (signal) => node.dialProtocol(peerId, SEED_PROTOCOL, { signal });
+    }
+    const connection = await this.connectForDelivery(node, peerId, addrs);
+    return (signal) => connection.newStream(SEED_PROTOCOL, { signal });
+  }
+
+  /**
+   * A connection to `peerId` for {@link deliverSeed}: one already open, or one dialed from
+   * `addrs` by {@link dialPeerAddrs} — 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 async connectForDelivery(node: Libp2p, peerId: PeerId, addrs: readonly Multiaddr[]): Promise<Connection> {
+    const open = openUnlimitedConnection(node, peerId);
+    if (open) {
+      log('Seed delivery to %s reuses an open connection', peerId);
+      return open;
+    }
+    // NOTE: a relayed address can return a limited connection, on which `sendSeed`'s stream
+    // open then fails as a plain error rather than `PeerUnreachableError`, though nothing was
+    // sent. Claim codes carry no relay addresses today; if a delivery target ever may, count a
+    // limited connection as unreachable here.
+    try {
+      return await dialPeerAddrs(node, addrs, this.dialBudget, `Seed delivery dial of ${peerId}`);
+    } catch (error) {
+      throw new PeerUnreachableError(peerId.toString(), error);
+    }
+  }
+
   /**
    * 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 async sendSeed(
-    node: Libp2p,
-    addr: Multiaddr,
+    openStream: SeedStreamOpener,
     seed: ControlNetworkSeed,
+    claimProof: string | undefined,
     signal: AbortSignal,
   ): Promise<SeedAckMessage> {
-    const rawStream = await node.dialProtocol(addr, SEED_PROTOCOL, { signal });
+    const rawStream = await openStream(signal);
 
     const message: SeedMessage = {
       partyId: seed.partyId,
       peers: seed.peers,
       signature: seed.signature,
       signerKey: seed.signerKey,
+      ...(claimProof !== undefined ? { claimProof } : {}),
     };
 
     const ack = await exchangeFrame(
@@ -1046,17 +1239,17 @@ export class SeedBootstrapService {
 
   /**
    * 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 = seedDigest(seed)): boolean {
     try {
-      // Reconstruct the signed bytes via the shared canonical payload builder so
-      // verification is independent of key order. The payload is the fixed
-      // `{ partyId, peers }` the producer emits.
-      const seedJson = canonicalSeedPayload(seed);
-      const seedDigest = digest([seedJson], 'sha256', 'base64url') as string;
-
+      // The digest is over the shared canonical payload, so verification is
+      // independent of key order; the payload is the fixed `{ partyId, peers }`
+      // the producer emits.
       return verify(
-        seedDigest,
+        digestB64,
         seed.signature,
         seed.signerKey,
         'ed25519',
@@ -1071,52 +1264,16 @@ export class SeedBootstrapService {
   }
 
   /**
-   * 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 async queryPeers(): Promise<SeedPeer[]> {
     if (!this.controlDatabase) {
       return [];
     }
-
-    const ownerKeys = await this.controlDatabase.getOwnerKeys();
-    const rows = await this.controlDatabase.queryCadrePeers();
-
-    return rows.map(({ peerId, multiaddr }) => {
-      // Derive the peer's ed25519 key from its PeerId; a non-Ed25519 peer or an
-      // unparsable id yields null and is treated as a non-owner rather than
-      // failing the whole seed creation.
-      const pubKeyB64 = ed25519PublicKeyB64FromPeerId(peerId);
-      const isOwner = pubKeyB64 !== null && ownerKeys.has(pubKeyB64);
-
-      return {
-        peerId,
-        multiaddrs: multiaddr ? multiaddr.split(',') : [],
-        isOwner,
-        ...(isOwner ? { publicKey: pubKeyB64 } : {}),
-      };
-    });
+    return await this.controlDatabase.querySeedPeers();
   }
 
   /**
@@ -1167,12 +1324,16 @@ export class SeedBootstrapService {
     this.activeStreams++;
     let acked = false;
     try {
-      const seed = await this.readSeedFrame(stream);
+      const { seed, claimProof } = await this.readSeedFrame(stream);
       this.eventCallbacks.onSeedReceived?.(seed.partyId, remotePeerId);
 
-      const merged = await this.verifyAndMergeSeed(seed);
+      const merged = await this.verifyAndMergeSeed(seed, { claimProof, remotePeerId });
       acked = true;
-      await replyAndClose(stream, { accepted: merged.success, reason: merged.error } satisfies SeedAckMessage, 'Seed');
+      await replyAndClose(
+        stream,
+        { accepted: merged.success, reason: merged.error, code: merged.code } satisfies SeedAckMessage,
+        'Seed',
+      );
 
       if (merged.success) {
         await this.dialSeedOwners(seed);
@@ -1193,8 +1354,12 @@ export class SeedBootstrapService {
     }
   }
 
-  /** Read the inbound seed frame to EOF (bounded and size-capped) and decode it. */
-  private async readSeedFrame(stream: ControlStream): Promise<ControlNetworkSeed> {
+  /**
+   * 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 async readSeedFrame(stream: ControlStream): Promise<{ seed: ControlNetworkSeed; claimProof?: string }> {
     const data = await readStreamToEnd(stream, {
       maxBytes: MAX_SEED_SIZE,
       timeoutMs: this.seedReadTimeoutMs,
@@ -1202,10 +1367,13 @@ export class SeedBootstrapService {
     });
     const message = JSON.parse(new TextDecoder().decode(decodeLengthPrefixedFrame(data))) as SeedMessage;
     return {
-      partyId: message.partyId,
-      peers: message.peers,
-      signature: message.signature,
-      signerKey: message.signerKey,
+      seed: {
+        partyId: message.partyId,
+        peers: message.peers,
+        signature: message.signature,
+        signerKey: message.signerKey,
+      },
+      claimProof: message.claimProof,
     };
   }
 
@@ -1263,104 +1431,6 @@ export class SeedBootstrapService {
     return { seed, encodedSeed };
   }
 
-  /**
-   * 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
-   */
-  async createInvite(token?: string, expiresIn?: number): Promise<InviteResult> {
-    if (!this.libp2pNode) {
-      throw new Error('Service not initialized');
-    }
-
-    log('Creating invite for phone');
-
-    // Get this node's dialable addresses. When an inviteAddressResolver is
-    // configured (typically by `@serfab/cadre-host`'s NatService), it takes
-    // priority — it may substitute a DDNS hostname and externally-mapped
-    // port for the raw LAN multiaddrs libp2p reports.
-    let ownerAddrs: string[];
-    if (this.config.inviteAddressResolver) {
-      try {
-        ownerAddrs = await this.config.inviteAddressResolver();
-      } catch (err) {
-        log('inviteAddressResolver threw, falling back to libp2pNode.getMultiaddrs(): %o', err);
-        ownerAddrs = this.libp2pNode.getMultiaddrs().map(a => a.toString());
-      }
-    } else {
-      ownerAddrs = this.libp2pNode.getMultiaddrs().map(a => a.toString());
-    }
-
-    // Carry the cadre's owner keys out-of-band so a cold-start invitee can pin
-    // the trusted owner set before applying any seed.
-    //
-    // Sourced ONLY from this node's own anchor, never from the replicated
-    // OwnerKey table: the invitee anchors whatever arrives here
-    // (CadreNode.trustOwnerKeys with source 'invite'), so handing over the
-    // pollutable table would let a stranger's genesis-inserted key ride an
-    // otherwise-legitimate invite straight into the new node's anchor —
-    // poisoning the very store this whole trust chain rests on. No anchor wired
-    // (a directly-constructed service) means no pins to hand out: an invite
-    // without `ownerKeys` costs the invitee an extra out-of-band step, whereas a
-    // table-sourced one silently hands it an unanchored key.
-    const ownerKeys = Array.from(this.config.trustedOwners?.all() ?? []);
-
-    const now = Date.now();
-    const invite: CadreInvite = {
-      partyId: this.config.partyId,
-      ownerAddrs,
-      ownerKeys: ownerKeys.length ? ownerKeys : undefined,
-      token,
-      createdAt: now,
-      expiresAt: expiresIn ? now + expiresIn : undefined,
-    };
-
-    const encodedInvite = this.encodeInvite(invite);
-
-    log('Invite created with %d owner addresses, %d owner keys', ownerAddrs.length, ownerKeys.length);
-
-    return { invite, encodedInvite };
-  }
-
-  /**
-   * 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
-   */
-  async acceptPhone(options: AddPhoneOptions, issuedInvite?: CadreInvite): Promise<void> {
-    const { phonePeerId, token } = options;
-
-    log('Accepting phone: %s', phonePeerId);
-
-    // Validate token if invite provided
-    if (issuedInvite) {
-      if (issuedInvite.token && issuedInvite.token !== token) {
-        throw new Error('Invalid invite token');
-      }
-      if (issuedInvite.expiresAt && Date.now() > issuedInvite.expiresAt) {
-        throw new Error('Invite has expired');
-      }
-    }
-
-    // Authorize the phone peer (no multiaddrs - phone is NAT'd)
-    await this.authorizePeer({ peerId: phonePeerId });
-
-    log('Phone %s accepted and authorized', phonePeerId);
-  }
-
   /**
    * Add a phone to the cadre with relay support.
    *
@@ -1398,51 +1468,4 @@ export class SeedBootstrapService {
 
     return { seed, encodedSeed };
   }
-
-  /**
-   * Encode an invite for out-of-band delivery.
-   */
-  encodeInvite(invite: CadreInvite): string {
-    const json = JSON.stringify(invite);
-    return uint8ArrayToString(new TextEncoder().encode(json), 'base64url');
-  }
-
-  /**
-   * Decode an invite from base64url encoding.
-   */
-  decodeInvite(encoded: string): CadreInvite {
-    const bytes = uint8ArrayFromString(encoded, 'base64url');
-    const json = new TextDecoder().decode(bytes);
-    return JSON.parse(json) as 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
-   */
-  async dialInvite(invite: CadreInvite): Promise<void> {
-    if (!this.libp2pNode) {
-      throw new Error('Service not initialized');
-    }
-
-    // Check expiration
-    if (invite.expiresAt && Date.now() > invite.expiresAt) {
-      throw new Error('Invite has expired');
-    }
-
-    log('Dialing invite owner with %d addresses', invite.ownerAddrs.length);
-
-    const addrs = parseDialAddrs(invite.ownerAddrs);
-    if (addrs.length === 0) {
-      throw new Error('No owner addresses available');
-    }
-    // Each address on its own time limit, so one that never answers cannot hold
-    // the invitee back from the rest (`dialPeerAddrs`).
-    const connection = await dialPeerAddrs(this.libp2pNode, addrs, this.dialBudget, 'Invite owner dial');
-    log('Connected to owner at: %s', connection.remoteAddr.toString());
-  }
 }
-