@serfab/cadre-core 0.10.0 → 0.12.0

package/src/relay-addrs.ts

@@ -1,32 +1,49 @@
 /**
  * Translate `network.relayAddrs` — the operator-facing "use these relay servers"
- * setting — into the mechanism this repo already has for reserving a circuit-relay
- * slot: a `…/p2p/<relayPeerId>/p2p-circuit` entry in the node's listen addrs.
+ * setting — into the listen entry a node needs before it can hold a circuit-relay
+ * slot, and validate the operator's entries while doing it.
  *
- * `@libp2p/circuit-relay-v2`'s transport is always present on the Node path
- * (`../optimystic/packages/db-p2p/src/libp2p-node.ts` pushes `circuitRelayTransport()`
- * unconditionally), and listening on a relay's circuit addr is what makes libp2p dial
- * that relay and hold a reservation. Everything downstream of the listen list —
- * the reservation itself, `CadreNode.circuitRelayTargets()` picking delegate-announce
- * targets, strand nodes inheriting the listen addrs, the `/p2p-circuit`-first address
- * publishing in `registerSelf` — then works unchanged.
+ * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen addr,
+ * and the same `relayAddrs` list resolves to either shape depending on WHO is
+ * listening ({@link RelayListenRoute}):
  *
- * So `relayAddrs` is a second, friendlier door onto an existing mechanism:
+ * | route          | listen entry                                | libp2p behaviour                                          |
+ * | -------------- | ------------------------------------------- | --------------------------------------------------------- |
+ * | `'configured'` | `<relayAddr>/p2p-circuit`, one per relay      | dial that relay from inside `listen()` and reserve, or throw |
+ * | `'search'`     | a single bare `/p2p-circuit`                  | register a pending reservation; open no connection          |
  *
- *   effective listen addrs = listenAddrs ++ relayAddrs.map(a => a + '/p2p-circuit')
+ * The CONTROL node takes the `'search'` route, and `CadreNode.start()` drives the
+ * reservation explicitly (`relay-reservation.ts`) once the control database is up.
+ * That ordering is the point: a configured circuit listener dials the relay from
+ * inside `libp2p.start()`, so the control database was being built while a sibling
+ * relay was already in this node's cohort — and a sibling that has not yet
+ * replicated this node's `CadrePeer` row correctly refuses its control-DB streams,
+ * which killed `start()` outright. See `cadre-node.ts` → `start()`.
  *
- * NOTE: this is the FAIL-FAST route to a reservation — libp2p's transport manager
- * throws when a configured circuit listener cannot listen, so naming a relay that
- * is down means the node does not start. The fail-soft route is the bare
- * `/p2p-circuit` search listener driven by `relay-reservation.ts`. The two are
- * ALTERNATIVES, not layers: configuring `relayAddrs` on a node that already
- * reserves via the search listener adds the fatal listener back and the node
- * stops booting when its relay is down.
+ * STRAND nodes keep the `'configured'` route (`strand-instance-manager.ts`): they
+ * inherit the control node's `NetworkConfig`, nothing drives an explicit
+ * reservation for them, and their relay connection cannot disturb a control-DB
+ * bring-up (a strand node's protocol ids are namespaced `/optimystic/strand-<id>/…`,
+ * so the relay is never in its cohort).
+ *
+ * `network.relayAddrs` is FAIL-FAST for the operator on both routes, just from
+ * different places: a malformed entry throws here at config resolution, and on the
+ * control node a first reservation attempt that does not land throws out of
+ * `start()` (`RelayReservationFailedError`). Naming a relay that is down still
+ * means the node does not come up.
+ *
+ * The bare `/p2p-circuit` search listener cannot open a connection on its own:
+ * libp2p fills a pending reservation from `RelayDiscovery`, which nominates a peer
+ * only once the relay-hop protocol id is in that peer's peer-store protocol list,
+ * and that list is written exclusively by IDENTIFY — which `@optimystic/db-p2p`
+ * namespaces per network, so a cadre node and a stock relay never identify each
+ * other. See `relay-reservation.ts`'s module doc and `docs/architecture.md`.
  */
 
 import { multiaddr, type Component } from '@multiformats/multiaddr';
 import { circuitRelayTargetOrThrow } from './delegate-admission.js';
 import type { NetworkConfig } from './types.js';
+import type { RelayReservationState } from './relay-reservation.js';
 
 /**
  * The direct listener a node keeps when it configures `relayAddrs` but no
@@ -40,6 +57,21 @@ import type { NetworkConfig } from './types.js';
  */
 const DEFAULT_DIRECT_LISTEN_ADDR = '/ip4/0.0.0.0/tcp/0';
 
+/**
+ * libp2p's relay SEARCH listener: registers one pending reservation and dials
+ * nothing. One entry covers every configured relay — the pending reservation is
+ * per-listener, not per-relay, and `relay-reservation.ts` fills it with whichever
+ * relay answers first.
+ */
+export const RELAY_SEARCH_LISTEN_ADDR = '/p2p-circuit';
+
+/**
+ * Which listener shape `network.relayAddrs` resolves to for this caller — see the
+ * table in the module doc. Defaults to `'configured'` everywhere except the
+ * control node's own libp2p options.
+ */
+export type RelayListenRoute = 'configured' | 'search';
+
 /**
  * The circuit-listen multiaddr for each configured relay: `<relayAddr>/p2p-circuit`.
  * An entry that already carries `/p2p-circuit` is passed through unchanged.
@@ -57,20 +89,95 @@ export function relayCircuitAddrs(relayAddrs: readonly string[]): string[] {
 
 /**
  * The listen multiaddrs a node actually binds: configured `listenAddrs` plus the
- * circuit-listen addr of every configured relay, deduplicated, order-stable
- * (configured entries first). Returns `undefined` when neither field is set, so
- * callers keep omitting `listenAddrs` and inherit db-p2p's default.
+ * relay listen entry `route` calls for, deduplicated, order-stable (configured
+ * entries first). Returns `undefined` when neither field is set, so callers keep
+ * omitting `listenAddrs` and inherit db-p2p's default.
+ *
+ * Every `relayAddrs` entry is validated on BOTH routes — the `'search'` route
+ * discards the resolved circuit addrs, but an operator typo must fail at config
+ * resolution either way.
  */
-export function resolveListenAddrs(network: NetworkConfig | undefined): string[] | undefined {
-  const circuits = relayCircuitAddrs(network?.relayAddrs ?? []);
+export function resolveListenAddrs(
+  network: NetworkConfig | undefined,
+  route: RelayListenRoute = 'configured'
+): string[] | undefined {
+  const configured = relayCircuitAddrs(network?.relayAddrs ?? []);
+  const relayEntries = route === 'search'
+    ? (configured.length > 0 ? [RELAY_SEARCH_LISTEN_ADDR] : [])
+    : configured;
   const listenAddrs = network?.listenAddrs;
-  if (!listenAddrs && circuits.length === 0) {
+  if (route === 'search') {
+    rejectConfiguredCircuitListenAddrs(listenAddrs ?? []);
+  }
+  if (!listenAddrs && relayEntries.length === 0) {
     return undefined;
   }
   // An explicitly empty `listenAddrs` (the React Native "cannot listen" case) stays
-  // empty — but a relay named alongside it still gets its circuit listener, since
-  // acquiring one is the whole point of configuring a relay.
-  return dedupe([...(listenAddrs ?? [DEFAULT_DIRECT_LISTEN_ADDR]), ...circuits]);
+  // empty — but a relay named alongside it still gets its listen entry, since
+  // acquiring a slot is the whole point of configuring a relay.
+  return dedupe([...(listenAddrs ?? [DEFAULT_DIRECT_LISTEN_ADDR]), ...relayEntries]);
+}
+
+/**
+ * Thrown out of `CadreNode.start()` when the boot-path reservation drive for
+ * `network.relayAddrs` produces no `/p2p-circuit` address on its FIRST attempt.
+ *
+ * This is what keeps `network.relayAddrs` fail-fast now that the control node
+ * takes the `'search'` route: libp2p's own `UnsupportedListenAddressesError` used
+ * to abort start from inside `listen()`, and an operator who names a relay is
+ * telling the node it has no other reachability — coming up undialable is worse
+ * than not coming up. Names the relays and the reservation's own reason, both of
+ * which the libp2p error omitted.
+ */
+export class RelayReservationFailedError extends Error {
+  constructor(
+    readonly relayAddrs: readonly string[],
+    readonly state: RelayReservationState
+  ) {
+    super(
+      `network.relayAddrs reservation failed (status: ${state.status}): ` +
+      `${state.error ?? 'no /p2p-circuit address appeared'} — relays: ${relayAddrs.join(', ')}`
+    );
+    this.name = 'RelayReservationFailedError';
+  }
+}
+
+/**
+ * A hand-written `<relay>/p2p-circuit` entry in `network.listenAddrs` is the
+ * CONFIGURED listener shape, and it is unusable on the `'search'` route: libp2p
+ * dials that relay from inside `listen()`, the bring-up quiet period
+ * (`membership-connection-gater.ts`) denies exactly that dial, `listen()` fails, and
+ * the transport manager's default `FATAL_ALL` aborts `libp2p.start()`. The operator
+ * would see `UnsupportedListenAddressesError` from deep inside bring-up with nothing
+ * naming the cause, so name it here instead.
+ *
+ * `network.relayAddrs` is the exact replacement — same relay, and the reservation is
+ * driven after bring-up, which is the whole point of the route.
+ */
+function rejectConfiguredCircuitListenAddrs(listenAddrs: readonly string[]): void {
+  const configured = listenAddrs.filter(isConfiguredCircuitListenAddr);
+  if (configured.length > 0) {
+    throw new Error(
+      'network.listenAddrs names a relay directly ' +
+      `(${configured.join(', ')}), which a control node cannot listen on: libp2p would ` +
+      'dial that relay during control-database bring-up, when the node accepts no ' +
+      'connections. Move the relay to network.relayAddrs, which reserves after bring-up.'
+    );
+  }
+}
+
+/** `<something>/p2p-circuit` — the configured shape, as opposed to the bare search addr. */
+function isConfiguredCircuitListenAddr(listenAddr: string): boolean {
+  if (listenAddr === RELAY_SEARCH_LISTEN_ADDR) {
+    return false;
+  }
+  try {
+    return multiaddr(listenAddr).getComponents().some((c) => c.name === 'p2p-circuit');
+  } catch {
+    // Not our error to raise: libp2p reports an unparsable listen addr itself, and
+    // this helper only ever ADDS a denial.
+    return false;
+  }
 }
 
 /**

package/src/relay-reservation.ts

@@ -4,28 +4,32 @@
  * (live) status derivation.
  *
  * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen
- * address, and the two shapes are alternatives, not layers:
+ * address:
  *
  * | listen addr                                       | libp2p behaviour                                                                     | unreachable relay          |
  * | ------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------- |
  * | `<dial addr>/p2p/<relayPeerId>/p2p-circuit`        | CONFIGURED reservation: dial that exact relay and reserve, or fail                     | `listen()` throws          |
  * | bare `/p2p-circuit`                                | SEARCH mode: register a pending reservation, to be filled by relay discovery           | nothing throws, no reserve |
  *
- * The configured shape is what `relay-addrs.ts` builds out of `network.relayAddrs`.
- * It is **fail-fast by construction**: libp2p's transport manager throws
- * `UnsupportedListenAddressesError` when any configured listen address fails to
- * listen under the default `FATAL_ALL` fault tolerance, so naming a relay that is
- * down means the node does not start. Good for a server; wrong for a browser tab,
- * which must still boot (solo, undialable) when its relay is down.
- *
- * So a browser-shaped node listens on bare `/p2p-circuit` and needs someone to
- * (a) dial the relay and (b) fill the pending reservation that listener created,
- * then report whether one actually landed. That is this module. It is **fail-soft
- * by construction**: nothing here throws.
- *
- * Do NOT "consolidate" the two by also setting `network.relayAddrs` on a node
- * that reserves this way — that re-introduces the fatal configured listener
- * alongside the search listener and the tab stops booting when the relay is down.
+ * A search listener needs someone to (a) dial the relay and (b) fill the pending
+ * reservation it created, then report whether one actually landed. That is this
+ * module. It is **fail-soft by construction**: nothing here throws.
+ *
+ * EVERY cadre CONTROL node now takes that route — `network.relayAddrs` resolves
+ * to the bare search entry (`relay-addrs.ts` → `RelayListenRoute`) and
+ * `CadreNode.start()` drives this module once the control database is up. The
+ * configured shape would dial the relay from inside `libp2p.start()`, putting a
+ * sibling in this node's cohort before its own control database existed, and a
+ * sibling that has not yet replicated this node's `CadrePeer` row correctly
+ * refuses its control-DB streams — which killed `start()` outright.
+ *
+ * So the two shapes are no longer alternative ROUTES, only alternative failure
+ * postures on top of the same drive: a node that names `network.relayAddrs` gets
+ * a `RelayReservationFailedError` out of `start()` when the first attempt lands
+ * nothing (fail-fast, the operator asked for this relay), while a node that calls
+ * `CadreNode.reserveRelays()` itself gets a non-`reserved` status and stays up
+ * (fail-soft, the browser-tab posture). Configuring both is now redundant, not
+ * fatal. STRAND nodes still take the configured shape — see `relay-addrs.ts`.
  *
  * ⚠️ WHY THE RESERVATION IS REQUESTED EXPLICITLY RATHER THAN LEFT TO DISCOVERY.
  * libp2p fills a search listener's pending reservation from `RelayDiscovery`,
@@ -68,7 +72,8 @@ const log = debug('sereus:cadre:relay-reservation');
 
 /**
  * Relay-reservation posture for a node that reserves through the SEARCH listen
- * addr (bare `/p2p-circuit`) rather than a configured `network.relayAddrs` entry.
+ * addr (bare `/p2p-circuit`) — every cadre control node, whether its relays came
+ * from `network.relayAddrs` or from an explicit `CadreNode.reserveRelays()` call.
  *  - `none`     — no relay addrs supplied; the node is undialable by design.
  *  - `dialing`  — a drive is in flight.
  *  - `reserved` — the node currently holds at least one `/p2p-circuit` addr.

package/src/seed-bootstrap.ts

@@ -404,7 +404,7 @@ export class SeedBootstrapService {
       insert into CadreControl.DeviceToken (PeerId, Platform, Token, UpdatedAt, Sig, StampId)
         with context OwnerKey = ?, Signature = ?
         values (?, ?, ?, ?, ?, ?)
-    `, [this.ownerPublicKey, signature, record.peerId, record.platform, record.token, record.updatedAt, record.sig, stampId]);
+    `, [this.ownerPublicKey, signature, record.peerId, record.platform, record.token, record.updatedAt, record.sig, stampId], 'device-token-insert');
     log('Device token inserted (owner-signed): %s', record.peerId);
   }
 
@@ -751,8 +751,8 @@ export class SeedBootstrapService {
     // `ApplySeedResult.ownerDialsFailed`). Recovery is not this loop's job —
     // `CadreNode.dialColdStartBootstrap` retries these same addresses on every
     // control-cohort reconcile pass until the control database has siblings.
-    // `createSeed` projects EVERY CadrePeer row, so an owner applying a seed
-    // minted after it joined finds ITSELF in the owner list. Dialing self always
+    // `createSeed` projects every non-revoked CadrePeer row, so an owner applying
+    // a seed minted after it joined finds ITSELF in the owner list. Dialing self always
     // throws, which would report a healthy owner as "seeded but stranded".
     // Optional-chained: partial libp2p handles (unit-test doubles) omit `peerId`,
     // and an undefined self simply matches nothing.
@@ -966,6 +966,13 @@ export class SeedBootstrapService {
    * 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
@@ -980,29 +987,22 @@ export class SeedBootstrapService {
     }
 
     const ownerKeys = await this.controlDatabase.getOwnerKeys();
-    const db = this.controlDatabase.getDatabase();
-    const peers: SeedPeer[] = [];
-
-    // Query CadrePeer table
-    for await (const row of db.eval('select PeerId, Multiaddr from CadreControl.CadrePeer')) {
-      const peerId = row.PeerId as string;
-      const multiaddr = row.Multiaddr as string | null;
+    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);
 
-      peers.push({
+      return {
         peerId,
         multiaddrs: multiaddr ? multiaddr.split(',') : [],
         isOwner,
         ...(isOwner ? { publicKey: pubKeyB64 } : {}),
-      });
-    }
-
-    return peers;
+      };
+    });
   }
 
   /**

package/src/seed-trust-policy.ts

@@ -1,140 +1,140 @@
-/**
- * Trust-anchor policy for control-network seeds.
- *
- * A seed carries an ed25519 signature over its body and the `signerKey` that
- * produced it. Verifying that signature only proves the seed is internally
- * consistent — it does NOT prove the signer is an owner, because both the
- * signer key and the seed's own `isOwner` peer flags are attacker-supplied.
- * The trust decision must therefore rest on an anchor that does not come from
- * the seed body:
- *
- *  1. Anchored — keys in the receiver's NODE-LOCAL `TrustedOwnerStore`: the
- *     non-replicated, per-party record of owner keys established out of band
- *     (founding the party, the `CadreInvite` that enrolled this node, an
- *     operator pin). Deliberately NOT the replicated `CadreControl.OwnerKey`
- *     table — any connecting node can genesis-insert its own key there and let
- *     it replicate, so that table can be made to say "yes" by a stranger.
- *  2. Pinned out-of-band — keys handed to the node for this seed only (carried
- *     by a `CadreInvite.ownerKeys`, or pinned by an operator) without having
- *     been anchored yet.
- *  3. TOFU (opt-in) — an explicit confirmation callback invoked on first sight
- *     of an unknown signer key. Interactive hosts only; off by default.
- *
- * Secure default (`anchoredTrustPolicy`): a node with an empty anchor and no
- * pinned keys rejects the seed — a seed can no longer vouch for its own signer,
- * and neither can a polluted replicated table.
- *
- * A key accepted via anchor 2 or 3 is reported back through
- * {@link SeedTrustDecision.anchorAs} so `applySeed` can persist it into the
- * node-local anchor, and later seeds from the same owner are accepted without
- * re-supplying the invite/confirmation.
- */
-import type { TrustSource } from './trusted-owner-store.js';
-
-export interface SeedTrustContext {
-  /** Party the seed claims to belong to. */
-  partyId: string;
-  /** ed25519 base64url signer key — already signature-verified by `applySeed`. */
-  signerKey: string;
-  /**
-   * The receiver's anchored owner keys, sourced from its node-local
-   * `TrustedOwnerStore` — NOT from the seed, and NOT from the replicated
-   * `OwnerKey` table. Empty for a node whose anchor was never seeded.
-   */
-  knownOwnerKeys: ReadonlySet<string>;
-}
-
-export interface SeedTrustDecision {
-  /** Whether the signer key is trusted. */
-  trusted: boolean;
-  /** Human-readable reason, surfaced as the seed-apply error when not trusted. */
-  reason?: string;
-  /**
-   * Set when the key was trusted via an anchor OUTSIDE the node-local store (a
-   * pinned key, a TOFU confirmation): the provenance to record it under, so
-   * `applySeed` persists it and the next seed from that owner is anchored
-   * without re-supplying the pin. Omitted when the key was already anchored
-   * (nothing to persist) or not trusted at all.
-   */
-  anchorAs?: Exclude<TrustSource, 'genesis'>;
-}
-
-/**
- * Decides whether a signature-verified seed's signer key should be trusted.
- * May be synchronous (anchored/pinned) or asynchronous (TOFU confirmation).
- */
-export interface SeedTrustPolicy {
-  evaluate(ctx: SeedTrustContext): Promise<SeedTrustDecision> | SeedTrustDecision;
-}
-
-/**
- * Default policy: trust only keys already in the receiver's node-local
- * trusted-owner anchor. A node whose anchor was never seeded (no genesis, no
- * invite pin, no operator pin) rejects every seed.
- */
-export function anchoredTrustPolicy(): SeedTrustPolicy {
-  return {
-    evaluate({ signerKey, knownOwnerKeys }) {
-      if (knownOwnerKeys.has(signerKey)) {
-        return { trusted: true };
-      }
-      return {
-        trusted: false,
-        reason: 'Signer key is not an anchored owner (anchored trust policy)',
-      };
-    },
-  };
-}
-
-/**
- * Cold-start policy: trust anchored keys plus a set pinned out-of-band
- * (typically `CadreInvite.ownerKeys` or operator config). Lets an unenrolled
- * invitee accept its first seed without the seed vouching for itself.
- *
- * @param anchorAs - provenance under which a pin-only acceptance is persisted
- *   into the node-local anchor ('invite' by default — the invite-redemption
- *   case; pass 'operator' for an operator-supplied pin).
- */
-export function pinnedKeyTrustPolicy(
-  pinned: Iterable<string>,
-  anchorAs: Exclude<TrustSource, 'genesis'> = 'invite'
-): SeedTrustPolicy {
-  const pinnedSet = new Set(pinned);
-  return {
-    evaluate({ signerKey, knownOwnerKeys }) {
-      if (knownOwnerKeys.has(signerKey)) {
-        return { trusted: true };
-      }
-      if (pinnedSet.has(signerKey)) {
-        return { trusted: true, anchorAs };
-      }
-      return {
-        trusted: false,
-        reason: 'Signer key is neither an anchored nor a pinned owner (pinned-key trust policy)',
-      };
-    },
-  };
-}
-
-/**
- * Opt-in interactive policy: trust keys already in the node-local anchor, and
- * on an unknown key invoke `confirm` (e.g. a trust-circle UI prompt). The key is
- * trusted iff `confirm` resolves true, and a confirmed key is persisted into the
- * anchor as an 'operator' pin (a human at the console is the same provenance as
- * an explicit operator pin) so the prompt is not repeated. Not enabled by default.
- */
-export function tofuTrustPolicy(
-  confirm: (ctx: SeedTrustContext) => Promise<boolean>
-): SeedTrustPolicy {
-  return {
-    async evaluate(ctx) {
-      if (ctx.knownOwnerKeys.has(ctx.signerKey)) {
-        return { trusted: true };
-      }
-      const accepted = await confirm(ctx);
-      return accepted
-        ? { trusted: true, anchorAs: 'operator' }
-        : { trusted: false, reason: 'TOFU confirmation declined for unknown signer key' };
-    },
-  };
-}
+/**
+ * Trust-anchor policy for control-network seeds.
+ *
+ * A seed carries an ed25519 signature over its body and the `signerKey` that
+ * produced it. Verifying that signature only proves the seed is internally
+ * consistent — it does NOT prove the signer is an owner, because both the
+ * signer key and the seed's own `isOwner` peer flags are attacker-supplied.
+ * The trust decision must therefore rest on an anchor that does not come from
+ * the seed body:
+ *
+ *  1. Anchored — keys in the receiver's NODE-LOCAL `TrustedOwnerStore`: the
+ *     non-replicated, per-party record of owner keys established out of band
+ *     (founding the party, the `CadreInvite` that enrolled this node, an
+ *     operator pin). Deliberately NOT the replicated `CadreControl.OwnerKey`
+ *     table — any connecting node can genesis-insert its own key there and let
+ *     it replicate, so that table can be made to say "yes" by a stranger.
+ *  2. Pinned out-of-band — keys handed to the node for this seed only (carried
+ *     by a `CadreInvite.ownerKeys`, or pinned by an operator) without having
+ *     been anchored yet.
+ *  3. TOFU (opt-in) — an explicit confirmation callback invoked on first sight
+ *     of an unknown signer key. Interactive hosts only; off by default.
+ *
+ * Secure default (`anchoredTrustPolicy`): a node with an empty anchor and no
+ * pinned keys rejects the seed — a seed can no longer vouch for its own signer,
+ * and neither can a polluted replicated table.
+ *
+ * A key accepted via anchor 2 or 3 is reported back through
+ * {@link SeedTrustDecision.anchorAs} so `applySeed` can persist it into the
+ * node-local anchor, and later seeds from the same owner are accepted without
+ * re-supplying the invite/confirmation.
+ */
+import type { TrustSource } from './trusted-owner-store.js';
+
+export interface SeedTrustContext {
+  /** Party the seed claims to belong to. */
+  partyId: string;
+  /** ed25519 base64url signer key — already signature-verified by `applySeed`. */
+  signerKey: string;
+  /**
+   * The receiver's anchored owner keys, sourced from its node-local
+   * `TrustedOwnerStore` — NOT from the seed, and NOT from the replicated
+   * `OwnerKey` table. Empty for a node whose anchor was never seeded.
+   */
+  knownOwnerKeys: ReadonlySet<string>;
+}
+
+export interface SeedTrustDecision {
+  /** Whether the signer key is trusted. */
+  trusted: boolean;
+  /** Human-readable reason, surfaced as the seed-apply error when not trusted. */
+  reason?: string;
+  /**
+   * Set when the key was trusted via an anchor OUTSIDE the node-local store (a
+   * pinned key, a TOFU confirmation): the provenance to record it under, so
+   * `applySeed` persists it and the next seed from that owner is anchored
+   * without re-supplying the pin. Omitted when the key was already anchored
+   * (nothing to persist) or not trusted at all.
+   */
+  anchorAs?: Exclude<TrustSource, 'genesis'>;
+}
+
+/**
+ * Decides whether a signature-verified seed's signer key should be trusted.
+ * May be synchronous (anchored/pinned) or asynchronous (TOFU confirmation).
+ */
+export interface SeedTrustPolicy {
+  evaluate(ctx: SeedTrustContext): Promise<SeedTrustDecision> | SeedTrustDecision;
+}
+
+/**
+ * Default policy: trust only keys already in the receiver's node-local
+ * trusted-owner anchor. A node whose anchor was never seeded (no genesis, no
+ * invite pin, no operator pin) rejects every seed.
+ */
+export function anchoredTrustPolicy(): SeedTrustPolicy {
+  return {
+    evaluate({ signerKey, knownOwnerKeys }) {
+      if (knownOwnerKeys.has(signerKey)) {
+        return { trusted: true };
+      }
+      return {
+        trusted: false,
+        reason: 'Signer key is not an anchored owner (anchored trust policy)',
+      };
+    },
+  };
+}
+
+/**
+ * Cold-start policy: trust anchored keys plus a set pinned out-of-band
+ * (typically `CadreInvite.ownerKeys` or operator config). Lets an unenrolled
+ * invitee accept its first seed without the seed vouching for itself.
+ *
+ * @param anchorAs - provenance under which a pin-only acceptance is persisted
+ *   into the node-local anchor ('invite' by default — the invite-redemption
+ *   case; pass 'operator' for an operator-supplied pin).
+ */
+export function pinnedKeyTrustPolicy(
+  pinned: Iterable<string>,
+  anchorAs: Exclude<TrustSource, 'genesis'> = 'invite'
+): SeedTrustPolicy {
+  const pinnedSet = new Set(pinned);
+  return {
+    evaluate({ signerKey, knownOwnerKeys }) {
+      if (knownOwnerKeys.has(signerKey)) {
+        return { trusted: true };
+      }
+      if (pinnedSet.has(signerKey)) {
+        return { trusted: true, anchorAs };
+      }
+      return {
+        trusted: false,
+        reason: 'Signer key is neither an anchored nor a pinned owner (pinned-key trust policy)',
+      };
+    },
+  };
+}
+
+/**
+ * Opt-in interactive policy: trust keys already in the node-local anchor, and
+ * on an unknown key invoke `confirm` (e.g. a trust-circle UI prompt). The key is
+ * trusted iff `confirm` resolves true, and a confirmed key is persisted into the
+ * anchor as an 'operator' pin (a human at the console is the same provenance as
+ * an explicit operator pin) so the prompt is not repeated. Not enabled by default.
+ */
+export function tofuTrustPolicy(
+  confirm: (ctx: SeedTrustContext) => Promise<boolean>
+): SeedTrustPolicy {
+  return {
+    async evaluate(ctx) {
+      if (ctx.knownOwnerKeys.has(ctx.signerKey)) {
+        return { trusted: true };
+      }
+      const accepted = await confirm(ctx);
+      return accepted
+        ? { trusted: true, anchorAs: 'operator' }
+        : { trusted: false, reason: 'TOFU confirmation declined for unknown signer key' };
+    },
+  };
+}