@serfab/cadre-core 0.9.0 → 0.10.0

package/src/seed-trust-policy.ts

@@ -8,25 +8,38 @@
  * The trust decision must therefore rest on an anchor that does not come from
  * the seed body:
  *
- *  1. DB-anchored — keys already in the receiver's `CadreControl.OwnerKey`
- *     table (steady state: the node is enrolled / has synced control state).
- *  2. Pinned out-of-band — keys handed to the node from outside the seed
- *     (carried by a `CadreInvite.ownerKeys`, or pinned by an operator).
+ *  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 (`dbAnchoredTrustPolicy`): a cold-start node with an empty
- * `OwnerKey` table and no pinned keys rejects the seed — a seed can no
- * longer vouch for its own signer.
+ * 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 known owner keys, sourced from its `OwnerKey`
-   * table — NOT from the seed. Empty for a cold-start node.
+   * 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>;
 }
@@ -36,21 +49,30 @@ export interface SeedTrustDecision {
   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 (DB/pinned anchors) or asynchronous (TOFU confirmation).
+ * May be synchronous (anchored/pinned) or asynchronous (TOFU confirmation).
  */
 export interface SeedTrustPolicy {
   evaluate(ctx: SeedTrustContext): Promise<SeedTrustDecision> | SeedTrustDecision;
 }
 
 /**
- * Default policy: trust only keys already present in the receiver's
- * `OwnerKey` table. A cold-start node (empty table) rejects every seed.
+ * 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 dbAnchoredTrustPolicy(): SeedTrustPolicy {
+export function anchoredTrustPolicy(): SeedTrustPolicy {
   return {
     evaluate({ signerKey, knownOwnerKeys }) {
       if (knownOwnerKeys.has(signerKey)) {
@@ -58,37 +80,48 @@ export function dbAnchoredTrustPolicy(): SeedTrustPolicy {
       }
       return {
         trusted: false,
-        reason: 'Signer key is not a known owner (DB-anchored trust policy)',
+        reason: 'Signer key is not an anchored owner (anchored trust policy)',
       };
     },
   };
 }
 
 /**
- * Cold-start policy: trust keys in the receiver's `OwnerKey` table 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.
+ * 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>): SeedTrustPolicy {
+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) || pinnedSet.has(signerKey)) {
+      if (knownOwnerKeys.has(signerKey)) {
         return { trusted: true };
       }
+      if (pinnedSet.has(signerKey)) {
+        return { trusted: true, anchorAs };
+      }
       return {
         trusted: false,
-        reason: 'Signer key is neither a known nor a pinned owner (pinned-key trust policy)',
+        reason: 'Signer key is neither an anchored nor a pinned owner (pinned-key trust policy)',
       };
     },
   };
 }
 
 /**
- * Opt-in interactive policy: trust keys already in the `OwnerKey` table,
- * and on an unknown key invoke `confirm` (e.g. a trust-circle UI prompt). The
- * key is trusted iff `confirm` resolves true. Not enabled by default.
+ * 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>
@@ -100,7 +133,7 @@ export function tofuTrustPolicy(
       }
       const accepted = await confirm(ctx);
       return accepted
-        ? { trusted: true }
+        ? { trusted: true, anchorAs: 'operator' }
         : { trusted: false, reason: 'TOFU confirmation declined for unknown signer key' };
     },
   };

package/src/strand-addr-protocol.ts

@@ -2,11 +2,13 @@
  * Control-network strand-address RPC.
  *
  * A strand runs as its own libp2p node (`strand-<id>`, random port), separate
- * from the control node (`control-<partyId>`) even though both share the same
- * peerId. To seed a strand's mesh, a node needs a sibling's **strand-network**
- * address — but `CadrePeer.Multiaddr` only stores the **control** node's
- * addresses. This protocol resolves the strand address on demand: a node asks
- * its connected co-cadre siblings "what are your live strand-`X` multiaddrs?" and
+ * from the control node (`control-<partyId>`), with its own transport peerId
+ * derived from the cadre identity key (`strand-transport-key.ts`). To seed a
+ * strand's mesh, a node needs a sibling's **strand-network** address — but
+ * `CadrePeer.Multiaddr` only stores the **control** node's addresses, and a
+ * control address now names a different peer entirely, not merely a different
+ * port. This protocol resolves the strand address on demand: a node asks its
+ * connected co-cadre siblings "what are your live strand-`X` multiaddrs?" and
  * uses the union of their answers as the seed.
  *
  * Modeled directly on `strand-wake-protocol.ts`: a dedicated libp2p protocol id,
@@ -16,13 +18,14 @@
  * one stream, so each side reads to EOF (under a read timeout) and decodes one
  * frame via the shared {@link decodeLengthPrefixedFrame} guard.
  *
- * **Authorization (v1):** the control network is single-party — only this party's
- * cadre peers connect (schema-gated `CadrePeer`). Like wake, the receiver gates
- * on cadre membership (via the injected `isMember`) and requires no further
- * signature; a non-member is refused with an empty address list. This is
- * defense-in-depth (the control mesh already restricts membership) kept for
- * parity with wake. Cross-party strand bootstrap is a different mechanism
- * (strand formation / `MemberPeer`) and is out of scope here.
+ * **Authorization (v1):** like wake, the receiver defers entirely to the injected
+ * `isMember` predicate and requires no further signature; a peer it rejects gets
+ * an empty address list. `CadreNode` injects its AUTHORIZED-membership predicate
+ * (`isAuthorizedMember`: voucher on the requester's `CadrePeer` row verified
+ * against the node-local trusted-owner anchor), so an outsider that published its
+ * own rows into the replicated control DB cannot harvest live strand addresses.
+ * Cross-party strand bootstrap is a different mechanism (strand formation /
+ * `MemberPeer`) and is out of scope here.
  */
 
 import debug from 'debug';
@@ -32,7 +35,7 @@ import { peerIdFromString } from '@libp2p/peer-id';
 import type { StrandAddrRequest, StrandAddrResponse } from './types.js';
 import { decodeLengthPrefixedFrame } from './seed-bootstrap.js';
 import { orderSignalingFirst } from './peer-record.js';
-import { type ControlStream, writeFrame, withTimeout, readStreamToEnd } from './control-stream.js';
+import { type ControlStream, writeFrame, withDeadline, exchangeFrame, readStreamToEnd } from './control-stream.js';
 
 const log = debug('sereus:cadre:strand-addr');
 
@@ -86,6 +89,16 @@ export interface StrandAddrServiceOptions {
    * decision logic is unit-testable without a full node.
    */
   getStrandMultiaddrs(strandId: string): string[];
+  /**
+   * Called when a member's request carries a `delegatePeerId` — the derived
+   * transport peerId its strand-`strandId` node runs as. Invoked only AFTER the
+   * `isMember` gate passed, with a validated (parseable, non-self) peerId.
+   * `CadreNode` injects its delegate-admission grant recorder so this node's
+   * connection gate — and thus its circuit-relay server, when it runs one —
+   * admits that peerId (see `delegate-admission.ts`). Optional: absent, an
+   * announce is ignored and the address lookup proceeds unchanged.
+   */
+  onDelegateAnnounce?(announcerPeerId: string, strandId: string, delegatePeerId: string): void;
   /**
    * Time to wait for the inbound request frame before aborting the read (ms).
    * Defaults to {@link DEFAULT_ADDR_READ_TIMEOUT_MS}. Bounds a buggy/compromised
@@ -209,22 +222,50 @@ export class StrandAddrService {
    * decision matrix can be unit-tested directly (mirrors wake's
    * `processWakeRequest`).
    *
-   * - Non-member sender → empty `multiaddrs` (refused).
+   * - Non-member sender → empty `multiaddrs` (refused), no delegate grant.
+   * - Member request carrying a `delegatePeerId` → recorded via
+   *   {@link StrandAddrServiceOptions.onDelegateAnnounce} before the lookup.
    * - Strand not running locally → empty `multiaddrs` (`getStrandMultiaddrs` → `[]`).
    * - Member + running strand → the strand's live, signaling-first multiaddrs.
    */
   async processAddrRequest(request: StrandAddrRequest, remotePeerId: string): Promise<StrandAddrResponse> {
     // Control-network membership is the v1 authorization: only this party's
-    // cadre peers may ask us for a strand address.
+    // cadre peers may ask us for a strand address (or announce a delegate).
     if (!(await this.options.isMember(remotePeerId))) {
       log('Refusing strand-addr from non-member %s', remotePeerId);
       return emptyResponse(request.strandId);
     }
 
+    this.recordDelegateAnnounce(request, remotePeerId);
+
     const multiaddrs = this.options.getStrandMultiaddrs(request.strandId);
     log('Strand-addr for %s → %d addr(s)', request.strandId, multiaddrs.length);
     return { strandId: request.strandId, multiaddrs };
   }
+
+  /**
+   * Validate and forward a member's delegate announcement. A malformed field
+   * (unparsable peerId) and a self-announcement (`delegatePeerId` equal to the
+   * announcer's own peerId — a member is admitted directly, never by grant)
+   * are logged and dropped; the address lookup proceeds either way.
+   */
+  private recordDelegateAnnounce(request: StrandAddrRequest, remotePeerId: string): void {
+    const { strandId, delegatePeerId } = request;
+    if (delegatePeerId === undefined || !this.options.onDelegateAnnounce) {
+      return;
+    }
+    if (delegatePeerId === remotePeerId) {
+      log('Ignoring self-announcement from %s (strand %s)', remotePeerId, strandId);
+      return;
+    }
+    try {
+      peerIdFromString(delegatePeerId);
+    } catch (err) {
+      log('Ignoring malformed delegatePeerId %o from %s: %o', delegatePeerId, remotePeerId, err);
+      return;
+    }
+    this.options.onDelegateAnnounce(remotePeerId, strandId, delegatePeerId);
+  }
 }
 
 /** A sibling to ask for its strand address. */
@@ -245,6 +286,13 @@ export interface CollectStrandAddrsOptions {
   timeoutMs?: number;
   /** Override the protocol id (defaults to {@link STRAND_ADDR_PROTOCOL}). */
   protocolId?: string;
+  /**
+   * The derived transport peerId the caller's own strand-`strandId` node runs
+   * (or is about to run) as. Set on every request this collection sends, so
+   * each receiver records a delegate admission grant for it — see
+   * {@link StrandAddrRequest.delegatePeerId}. Omit for a pure address lookup.
+   */
+  delegatePeerId?: string;
 }
 
 /**
@@ -268,7 +316,9 @@ export async function collectStrandAddrs(
   options: CollectStrandAddrsOptions = {}
 ): Promise<string[]> {
   const selfId = node.peerId.toString();
-  const request: StrandAddrRequest = { strandId };
+  const request: StrandAddrRequest = options.delegatePeerId !== undefined
+    ? { strandId, delegatePeerId: options.delegatePeerId }
+    : { strandId };
   const candidates = peers.filter(p => p.peerId !== selfId);
 
   // Concurrent dials; `dialOneSibling` swallows per-peer failure into `[]`, so
@@ -314,16 +364,13 @@ async function dialOneSibling(
   }
 
   for (const target of targets) {
-    // One controller per attempt: on timeout, `withTimeout`'s `onTimeout` aborts
-    // it, which aborts the in-flight dialProtocol (via the dial `signal`) and the
-    // live stream — so neither the connect nor the unbounded response-read leaks.
-    const controller = new AbortController();
     try {
-      const response = await withTimeout(
+      // One deadline per attempt: its signal aborts the in-flight dialProtocol and
+      // resets the live stream, so neither the connect nor the response-read leaks.
+      const response = await withDeadline(
         timeoutMs,
         `Strand-addr dial ${peer.peerId}`,
-        () => sendStrandAddr(node, target, protocolId, request, timeoutMs, controller.signal),
-        () => controller.abort(),
+        (signal) => sendStrandAddr(node, target, protocolId, request, timeoutMs, signal),
       );
       return response.multiaddrs;
     } catch (err) {
@@ -361,12 +408,10 @@ function describeTarget(target: PeerId | Multiaddr): string {
  * Open one stream to a target, send the request, half-close, and read the
  * response.
  *
- * `signal` is the per-attempt abort signal from {@link dialOneSibling}: it is
- * passed to `dialProtocol` so a timeout during connect aborts the dial, and once
- * the stream is open an abort listener resets the live stream — releasing the
- * otherwise unbounded response-read. `readFrame` still applies `timeoutMs` as a
- * backstop for the case where an abort does not propagate (e.g. a stream double
- * whose `abort()` is a no-op).
+ * `signal` is the per-attempt deadline from {@link dialOneSibling}: 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 response-read.
  */
 async function sendStrandAddr(
   node: Libp2p,
@@ -382,29 +427,15 @@ async function sendStrandAddr(
   // relay's data/duration cap, so opening it on the limited connection is safe
   // and is the whole point of dialing over the relay.
   const rawStream = await node.dialProtocol(target, protocolId, { runOnLimitedConnection: true, signal });
-  const stream = rawStream as unknown as ControlStream;
-
-  const abortErr = new Error('Strand-addr dial aborted by timeout');
-  const onAbort = (): void => stream.abort(abortErr);
-  // If the timeout already fired during connect, release the freshly-opened stream now.
-  if (signal.aborted) {
-    onAbort();
-    throw abortErr;
-  }
-  signal.addEventListener('abort', onAbort, { once: true });
 
-  try {
-    writeFrame(stream, request);
-    // close() half-closes the write end (EOF) while the read end stays open for
-    // the response — the same libp2p 3.x pattern as wake/seed delivery.
-    await stream.close();
-    const response = await readFrame<StrandAddrResponse>(stream, timeoutMs);
-    log('Strand-addr response: %d addr(s) for %s', response.multiaddrs.length, response.strandId);
-    return response;
-  } catch (err) {
-    stream.abort(err instanceof Error ? err : new Error(String(err)));
-    throw err;
-  } finally {
-    signal.removeEventListener('abort', onAbort);
-  }
+  const response = await exchangeFrame(
+    rawStream as unknown as ControlStream,
+    signal,
+    request,
+    (stream) => readFrame<StrandAddrResponse>(stream, timeoutMs),
+    'Strand-addr dial aborted by timeout',
+  );
+
+  log('Strand-addr response: %d addr(s) for %s', response.multiaddrs.length, response.strandId);
+  return response;
 }