@serfab/cadre-core 1.8.0 → 1.9.0

package/src/index.ts

@@ -128,61 +128,21 @@ export {
   type JoinedStrandRecord
 } from './joined-strand-store.js';
 
-// Node-local strand peer book: per strand, the strand peers this node has met and
-// their last-known addresses, dialed first on every launch so a restarted machine
-// re-finds the other parties. Same cross-platform split as the bootstrap-peer store
-// above — interface + in-memory + slot-backed stores here, Node-only file backend
-// behind the subpath '@serfab/cadre-core/strand-peer-book-file'.
-export {
-  MemoryStrandPeerBookStore,
-  PersistentStrandPeerBookStore,
-  mergeStrandPeerEntry,
-  sanitizeStrandPeerEntry,
-  strandPeerFreshness,
-  MAX_STRAND_PEERS,
-  STRAND_PEER_MAX_AGE_MS,
-  type StrandPeerBookStore,
-  type StrandPeerBookOptions,
-  type StrandPeerEntry
-} from './strand-peer-book.js';
-export {
-  StrandPeerObserver,
-  dialableAddrs,
-  connectedIdentifiedPeers,
-  STRAND_PEER_OBSERVE_THROTTLE_MS,
-  type StrandPeerObservation,
-  type StrandPeerObserverDeps,
-  type StrandPeerObserverOptions,
-  type ConnectedIdentifiedPeer
-} from './strand-peer-observer.js';
-// The signed book SWAP between strand peers (`/sereus/strand-peers/1.0.0`): the wire
-// protocol, signing and verification, and the per-strand driver that arms it.
-export {
-  STRAND_PEER_BOOK_PROTOCOL,
-  SIGNED_STRAND_PEER_ENTRY_VERSION,
-  STRAND_PEER_ISSUED_AT_SKEW_MS,
-  MAX_BOOK_FRAME_SIZE,
-  StrandPeerBookService,
-  exchangeStrandPeerBook,
-  signStrandPeerEntry,
-  signedStrandPeerEntryPayload,
-  verifySignedStrandPeerEntry,
-  verifyStrandPeerBookFrame,
-  trimBookFrameToFit,
-  assertBookFrameFits,
-  type SignedStrandPeerEntry,
-  type StrandPeerBookFrame,
-  type StrandPeerEntryVerdict,
-  type StrandPeerBookServiceDeps,
-  type ExchangeStrandPeerBookOptions
-} from './strand-peer-book-protocol.js';
-export {
-  StrandPeerBookSwap,
-  STRAND_PEER_BOOK_SWAP_THROTTLE_MS,
-  OWN_ENTRY_RESIGN_DEBOUNCE_MS,
-  type StrandPeerBookSwapDeps,
-  type StrandPeerBookSwapOptions
-} from './strand-peer-book-swap.js';
+// Node-local strand network state: per strand, the state Optimystic's db-p2p saves for
+// the strand node (its FRET routing table with each peer's signed address record), so a
+// restarted strand node re-imports the peers it was talking to. Same cross-platform
+// split as the bootstrap-peer store above — interface + in-memory + slot-backed stores
+// here, Node-only file backend behind '@serfab/cadre-core/strand-network-state-file'.
+export {
+  MemoryStrandNetworkStateStore,
+  PersistentStrandNetworkStateStore,
+  strandNetworkStatePersistence,
+  type StrandNetworkStateStore
+} from './strand-network-state.js';
+// The signed address records a running strand node's FRET table holds, as per-peer dial
+// addresses: what the periodic refresh re-merges into the node's address book, and a
+// diagnostic for "whom could this strand node redial right now?".
+export { strandFretPeerAddrs, type FretAddrHost, type FretPeerAddrs } from './strand-fret-addrs.js';
 
 // Storage scope keys — what `CadreNodeConfig.storage.provider` is called with. A
 // strand's key is its strand id; the control database's key carries the party id,

package/src/node-local-snapshot.ts

@@ -5,9 +5,9 @@
  *
  *  - the trusted-owner anchor (`trusted-owner-store.ts`),
  *  - the cold-start bootstrap-peer store (`bootstrap-peer-store.ts`),
- *  - the strand peer book (`strand-peer-book.ts`), whose entries are one map per
- *    strand rather than one value per key — the validation hook below is what
- *    lets it drop a single junk peer without dropping the strand.
+ *  - the strand network state (`strand-network-state.ts`): per strand, the state
+ *    Optimystic's db-p2p saved for the strand node, opaque here past a structural
+ *    check.
  *
  * ANOTHER node-local record — the enrolled-machine count
  * (`enrolled-machine-store.ts`) — reuses {@link DurableSlot} but deliberately
@@ -72,10 +72,10 @@ const ENVELOPE_VERSION = 1;
  *    in full is not an anchor. Trusting a *subset* of the keys a file claims is
  *    a silent, security-relevant downgrade, so the whole record is discarded
  *    and the node trusts no one until re-seeded out of band.
- *  - `'drop-entry'` (the bootstrap-peer store and the strand peer book): the
- *    record is a best-effort dial list and nothing in it is trust-bearing, so one
- *    junk entry must not discard a stranded node's only remaining way back to
- *    its party or its strand's peers.
+ *  - `'drop-entry'` (the bootstrap-peer store and the strand network state):
+ *    the record is a best-effort dial list and nothing in
+ *    it is trust-bearing, so one junk entry must not discard a stranded node's
+ *    only remaining way back to its party or its strand's peers.
  */
 export type UnusableEntryPolicy = 'discard-all' | 'drop-entry';
 
@@ -149,6 +149,11 @@ export class NodeLocalSnapshot<E> {
 		return this.entries.has(key);
 	}
 
+	/** The entry held for `key`, if any. Needs no copy: {@link put} replaces an entry, never mutates it. */
+	get(key: string): E | undefined {
+		return this.entries.get(key);
+	}
+
 	/** Fresh copy of the keys — a snapshot decoupled from later {@link put} / {@link remove} calls. */
 	keySnapshot(): Set<string> {
 		return new Set(this.entries.keys());

package/src/peer-join-backfill.ts

@@ -148,10 +148,9 @@ export const MAX_BLOCK_MESSAGE_BYTES = 8 * 1024 * 1024;
  * protocol — the one gate that decides whether {@link PeerJoinBackfill} schedules a peer at
  * all. A peer that lacks it (a bare circuit relay, a bootstrap node, a stranger the control
  * network's inbound gate admitted without membership) cannot receive a push no matter how
- * long it is dialed, since the protocol id is namespaced per network. Exported because a
- * later strand peer-address ticket's identify-driven observation needs the identical test.
+ * long it is dialed, since the protocol id is namespaced per network.
  */
-export function speaksBlockTransfer(protocols: readonly string[], protocolPrefix: string): boolean {
+function speaksBlockTransfer(protocols: readonly string[], protocolPrefix: string): boolean {
   return protocols.includes(buildBlockTransferProtocol(protocolPrefix));
 }
 

package/src/strand-formation-protocol.ts

@@ -72,11 +72,10 @@ const DEFAULT_MAX_CONCURRENT_SESSIONS = 100;
  * handful of entries (one per listen transport, plus a circuit-relay reservation), so
  * 16 is generous for the honest case while keeping the result frame bounded against a
  * peer that would pad it — either direction, since both sides run the list through
- * {@link sanitizeStrandAddrs}. Exported because the same bound has to hold on the
- * initiator's stored copy: `CadreNode` accumulates across repeat formations against one
- * strand, so it caps the accumulation rather than only each arriving list.
+ * {@link sanitizeStrandAddrs}. The initiator's kept copy is one arriving list, replaced by
+ * the next formation against the same strand, so the same bound holds there.
  */
-export const MAX_STRAND_ADDRS = 16;
+const MAX_STRAND_ADDRS = 16;
 
 // ── Roles ────────────────────────────────────────────────────────────────────
 

package/src/strand-fret-addrs.ts

@@ -0,0 +1,145 @@
+/**
+ * Reading the signed address records a running strand node's FRET routing table holds,
+ * as per-peer addresses ready for that node's own address book (`peer-addr-book.ts`).
+ *
+ * Why a strand node needs this. libp2p's peerStore hides every address one hour after
+ * it was first observed (the `NOTE:` on `mergePeerAddrs`), and FRET does not re-apply
+ * the records it holds: it hands a record to the peerStore when a neighbour's snapshot
+ * delivers it or a saved table is imported, and the peerStore refuses a record whose
+ * sequence number it already has. So a strand node that has been up for more than an
+ * hour would have no address for a peer whose connection then drops, although FRET
+ * still holds that peer's record. `CadreNode.refreshStrandPeerAddrs` re-merges the
+ * records on every pass, which is what keeps another party's strand nodes dialable;
+ * own-party siblings are re-resolved separately, over the strand-addr RPC.
+ *
+ * How long a record is available here is FRET's rule, not this module's: while FRET
+ * holds the entry, and at most 14 days after the record was last confirmed (a peer
+ * connected at export time counts as confirmed then).
+ *
+ * Every record is opened and verified here rather than taken on FRET's word. A record
+ * is self-certifying, the table is reached through a structural type rather than an
+ * interface this package depends on, and the address book write is attributed from what
+ * the record proves, not from the id the table filed it under.
+ */
+
+import debug from 'debug';
+import { PeerRecord, RecordEnvelope } from '@libp2p/peer-record';
+import { peerIdFromPublicKey } from '@libp2p/peer-id';
+import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
+import { fromString as uint8ArrayFromString } from 'uint8arrays';
+import { withTrailingPeerId } from './peer-record.js';
+
+const log = debug('sereus:cadre:strand-fret-addrs');
+
+/** The slice of FRET's exported routing table read here (`SerializedTable` in `p2p-fret`). */
+interface FretTableSlice {
+  entries: ReadonlyArray<{
+    id: string;
+    /** `envelope` is the base64url of a marshaled libp2p record envelope. */
+    addressRecord?: { envelope: string };
+  }>;
+}
+
+/** The slice of FRET's libp2p service called here. */
+interface FretTableSource {
+  exportTable(): FretTableSlice;
+}
+
+/**
+ * The slice of a strand's libp2p node this module touches. Structurally satisfied by
+ * `Libp2p`; db-p2p registers FRET as `services.fret`.
+ */
+export interface FretAddrHost {
+  peerId: { toString(): string };
+  services?: Record<string, unknown>;
+}
+
+/** What one read of a strand node's FRET table yields. */
+export interface FretPeerAddrs {
+  /** Peer id → the addresses its record lists, each bound to that peer. Table order. */
+  peers: Map<string, Multiaddr[]>;
+  /**
+   * Records left out because they did not decode, did not verify, or were not signed
+   * by and about the peer the table filed them under.
+   */
+  rejected: number;
+}
+
+/**
+ * The addresses of every peer `host`'s FRET table holds a usable signed record for,
+ * `host` itself excluded. A node with no FRET service (a db-p2p build without it, a
+ * test double) reads as an empty table. One bad record never costs the others: it is
+ * counted in `rejected` and skipped.
+ *
+ * Throws only what `exportTable()` throws, which a caller treats like any other
+ * failure of a pass over a node that may be mid-teardown.
+ */
+export async function strandFretPeerAddrs(host: FretAddrHost): Promise<FretPeerAddrs> {
+  const result: FretPeerAddrs = { peers: new Map(), rejected: 0 };
+  const fret = host.services?.fret;
+  if (!isFretTableSource(fret)) {
+    return result;
+  }
+  const selfId = host.peerId.toString();
+  for (const entry of fret.exportTable().entries) {
+    if (entry.id === selfId || entry.addressRecord === undefined) {
+      continue;
+    }
+    const addrs = await verifiedRecordAddrs(entry.id, entry.addressRecord.envelope);
+    if (addrs === null) {
+      result.rejected++;
+    } else if (addrs.length > 0) {
+      result.peers.set(entry.id, addrs);
+    }
+  }
+  return result;
+}
+
+function isFretTableSource(service: unknown): service is FretTableSource {
+  return typeof service === 'object' && service !== null
+    && typeof (service as { exportTable?: unknown }).exportTable === 'function';
+}
+
+/**
+ * The addresses one record lists, bound to `peerId`; null when the record must not be
+ * used. `openAndCertify` proves only that the envelope's own key signed it, so the
+ * signer and the peer the payload describes are each held against `peerId` here:
+ * without that, any peer could sign a record rewriting another peer's addresses.
+ */
+async function verifiedRecordAddrs(peerId: string, envelope: string): Promise<Multiaddr[] | null> {
+  try {
+    const opened = await RecordEnvelope.openAndCertify(uint8ArrayFromString(envelope, 'base64url'), PeerRecord.DOMAIN);
+    const record = PeerRecord.createFromProtobuf(opened.payload);
+    const signer = peerIdFromPublicKey(opened.publicKey).toString();
+    const subject = record.peerId.toString();
+    if (signer !== peerId || subject !== peerId) {
+      log('skipping the address record filed under %s: signed by %s about %s', peerId, signer, subject);
+      return null;
+    }
+    return bindToPeer(record.multiaddrs.map((addr) => addr.toString()), peerId);
+  } catch (error) {
+    log('skipping the address record filed under %s: %o', peerId, error);
+    return null;
+  }
+}
+
+/**
+ * A record names its peer once, in `peerId`, so its addresses carry no trailing
+ * `/p2p/<peerId>` and a relay-only peer's circuit address ends at the relay hop
+ * (`…/p2p/<relay>/p2p-circuit`). Each is given the suffix that makes it a complete
+ * dial target; one already terminating in a different peer id does not reach this peer
+ * and is dropped.
+ *
+ * Takes strings because `@libp2p/peer-record` carries its own `@multiformats/multiaddr`
+ * copy, a structurally different type from the one `withTrailingPeerId` takes.
+ */
+function bindToPeer(addrs: string[], peerId: string): Multiaddr[] {
+  const bound: Multiaddr[] = [];
+  for (const addr of addrs) {
+    const withPeer = withTrailingPeerId(multiaddr(addr), peerId);
+    if (withPeer !== null) {
+      bound.push(withPeer);
+    }
+  }
+  return bound;
+}

package/src/strand-instance-manager.ts

@@ -4,9 +4,7 @@ import { createLibp2pNode, type IRawStorage } from '@optimystic/db-p2p';
 import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { StrandDatabase } from './strand-database.js';
 import { PeerJoinBackfill, type PeerJoinBackfillConfig } from './peer-join-backfill.js';
-import { StrandPeerObserver, type StrandPeerObservation } from './strand-peer-observer.js';
-import { StrandPeerBookSwap } from './strand-peer-book-swap.js';
-import type { StrandPeerBookStore } from './strand-peer-book.js';
+import { strandNetworkStatePersistence, type StrandNetworkStateStore } from './strand-network-state.js';
 import {
   StrandRevocationEnforcer,
   createRevocationConnectionGater,
@@ -274,26 +272,14 @@ export interface StartStrandConfig {
   announceDelegateToRelay?: (strandId: string, relayAddr: string, delegatePeerId: string) => Promise<void>;
 
   /**
-   * Called when the strand's libp2p node identifies a STRAND peer — one whose
-   * identify result names this strand's block-transfer protocol, so never the
-   * circuit relay or a bootstrap node — with the addresses it is dialable at
-   * (`strand-peer-observer.ts`). Throttled per peer; must not throw. `CadreNode`
-   * wires it to the node-local strand peer book, which is what lets a restarted
-   * machine dial the peers it was talking to. Absent ⇒ nothing is observed.
-   * Retained with the launch config, so a hibernation wake re-arms it on the
-   * rebuilt node.
+   * The node-local strand network state (`strand-network-state.ts`): this strand's
+   * slice of it is handed to db-p2p as `persistence`, so the strand node saves its
+   * FRET routing table (with each peer's signed address record) on every connection
+   * and re-imports it when it is next built. Absent ⇒ nothing is saved and the node
+   * starts with an empty table. `CadreNode` passes its store. Retained with the launch
+   * config, so a hibernation wake rebuilds the node over the same state.
    */
-  onStrandPeerIdentified?: (strandId: string, observation: StrandPeerObservation) => void;
-
-  /**
-   * The node-local strand peer book the book SWAP reads and writes
-   * (`strand-peer-book-swap.ts`): the strand node signs its own addresses with
-   * {@link privateKey}, exchanges signed entries with every strand peer it identifies,
-   * and files what verifies. Absent ⇒ no swap runs — a peer that dials this node's
-   * swap handler gets no answer. `CadreNode` passes its book store. Retained with the
-   * launch config, so a hibernation wake re-arms the swap on the rebuilt node.
-   */
-  strandPeerBook?: StrandPeerBookStore;
+  networkState?: StrandNetworkStateStore;
 }
 
 /**
@@ -428,24 +414,6 @@ export class StrandInstanceManager {
    * missed writes).
    */
   private backfills: Map<string, PeerJoinBackfill> = new Map();
-  /**
-   * The per-strand peer-book observation writer (`strand-peer-observer.ts`), keyed
-   * by strand id. Same lifecycle rationale as {@link backfills}: started in
-   * `buildStrandRuntime` right after the libp2p node exists, stopped and dropped in
-   * `releaseRuntime`, so quiesce → resume re-arms it on the rebuilt node. Only
-   * present when the launch config supplied `onStrandPeerIdentified`.
-   */
-  private peerObservers: Map<string, StrandPeerObserver> = new Map();
-
-  /**
-   * Per-strand strand peer book SWAP driver ({@link StrandPeerBookSwap}) — the signed
-   * exchange of book entries between strand peers. Same lifetime as the peer-book
-   * observer above: armed in `buildStrandRuntime` right after the libp2p node exists
-   * (its protocol handler must be registered before an early peer dials it), stopped
-   * and dropped in `releaseRuntime`. Only present when the launch config supplied
-   * `strandPeerBook`.
-   */
-  private peerBookSwaps: Map<string, StrandPeerBookSwap> = new Map();
   /**
    * The per-strand revoked-peer enforcer (closed strands only), keyed by strand
    * id. Same lifecycle rationale as {@link backfills}: created in
@@ -821,6 +789,18 @@ export class StrandInstanceManager {
           enableRingZulu: config.profile === 'storage'
         },
         ...(config.privateKey && { privateKey: config.privateKey }),
+        // Built per runtime, not per launch: the adapter stops saving once the strand's
+        // state is forgotten, and a rebuilt runtime is what starts it saving again.
+        //
+        // NOTE: the saved state also restores which peers db-p2p saw serving the strand,
+        // and it counts them in the cohort until FRET finds them unreachable. A node built
+        // while every other member is offline therefore fails its first writes ("Failed to
+        // get super-majority") — for 4-6 s on loopback, the window a running node already
+        // sees when a member drops. If apps report failed sends after relaunching alone on
+        // a slow relayed link, retry the write in the app or raise it upstream (db-p2p's
+        // remembered-serving fallback); dropping `persistence` brings back the split
+        // restart.
+        ...(config.networkState && { persistence: strandNetworkStatePersistence(config.networkState, strandId) }),
         ...(config.network?.transports && { transports: config.network.transports }),
         ...(config.network?.noiseCrypto && { noiseCrypto: config.network.noiseCrypto }),
         // Unconditional, and the same default the control node takes: every node of
@@ -851,48 +831,6 @@ export class StrandInstanceManager {
 
       instance.libp2pNode = node;
 
-      // The peer-book observation writer, armed BEFORE the database bring-up below
-      // (unlike the backfill) because the bootstrap dials that follow `libp2p.start()`
-      // land during that bring-up, and they are exactly the peers worth remembering:
-      // identify for an early peer may already have fired by the time anything after
-      // the database initializes runs. Registered in the map immediately so the
-      // failure rollback (releaseRuntime) stops it like every other runtime component.
-      const onStrandPeerIdentified = config.onStrandPeerIdentified;
-      if (onStrandPeerIdentified) {
-        const observer = new StrandPeerObserver({
-          label: strandId,
-          libp2p: node,
-          protocolPrefix,
-          onObserved: (observation) => onStrandPeerIdentified(strandId, observation)
-        });
-        this.peerObservers.set(strandId, observer);
-        observer.start();
-      }
-
-      // The strand peer book SWAP, armed at the same moment and for the same reason as
-      // the observer: a peer that dials this node's swap handler before it is registered
-      // fails its exchange and sits out a ten-minute throttle. The own entry is signed
-      // now and re-signed on every address change, which covers the relay reservation
-      // landing below (`self:peer:update` fires when the circuit addr is added), so no
-      // separate post-relay step is needed. Registered in the map immediately so the
-      // failure rollback (releaseRuntime) stops it like every other runtime component.
-      //
-      // NOTE: this is a third `peer:identify` listener per running strand, beside the
-      // observer's and the backfill's — see the backfill's NOTE below for when to fold
-      // them into one dispatcher.
-      if (config.strandPeerBook) {
-        const swap = new StrandPeerBookSwap({
-          strandId,
-          libp2p: node,
-          protocolPrefix,
-          store: config.strandPeerBook,
-          privateKey: config.privateKey,
-          linkRoundTripMs: config.network?.linkRoundTripMs
-        });
-        this.peerBookSwaps.set(strandId, swap);
-        swap.start();
-      }
-
       // One reservation supervisor PER RELAY, started now so the first attempts
       // overlap the database bring-up below (the relay is never in a strand's
       // Optimystic cohort — its protocol ids are namespaced `/optimystic/strand-<id>/…`
@@ -1106,20 +1044,6 @@ export class StrandInstanceManager {
       backfill.stop();
       this.backfills.delete(instance.strandId);
     }
-    // The peer-book observer goes with the node it listened on; a resume re-arms
-    // one on the rebuilt node.
-    const peerObserver = this.peerObservers.get(instance.strandId);
-    if (peerObserver) {
-      peerObserver.stop();
-      this.peerObservers.delete(instance.strandId);
-    }
-    // The book swap likewise: unsubscribed and its handler unregistered while the node is
-    // still up; a resume re-arms one, which re-signs the own entry over the new addresses.
-    const peerBookSwap = this.peerBookSwaps.get(instance.strandId);
-    if (peerBookSwap) {
-      this.peerBookSwaps.delete(instance.strandId);
-      await peerBookSwap.stop();
-    }
     // The revoked-peer enforcer goes with the runtime it gated: a resume
     // rebuilds it with a fresh (initially empty, fail-open) snapshot.
     const revocationEnforcer = this.revocationEnforcers.get(instance.strandId);

package/src/strand-network-state-file.ts

@@ -0,0 +1,40 @@
+/**
+ * Node-only file-backed {@link StrandNetworkStateStore}: one JSON file per party
+ * under a configured directory (the node's state directory — `cadre-cli` passes
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated network
+ * state of every strand this node runs (each strand node's saved FRET routing
+ * table, with its peers' signed address records).
+ *
+ * Nothing but the file itself lives here: the envelope, load policy, per-entry
+ * check and the serialised snapshot writes are cross-platform in
+ * `PersistentStrandNetworkStateStore` / `node-local-snapshot.ts`, and the file is a
+ * `FileDurableSlot`. This module exists only so the `node:fs` edge stays out of the
+ * package's cross-platform default entry (`./index.js`) — import it from the
+ * dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileStrandNetworkStateStore } from '@serfab/cadre-core/strand-network-state-file';
+ * ```
+ *
+ * Same isolation pattern as `bootstrap-peer-store-file.ts` / `key-store-file.ts`.
+ */
+import { FileDurableSlot } from './file-durable-slot.js';
+import { PersistentStrandNetworkStateStore } from './strand-network-state.js';
+import type { StrandNetworkStateStore } from './strand-network-state.js';
+
+/** Base name of the store file: `<dir>/strand-network.<encoded partyId>.json`. */
+const SLOT_NAME = 'strand-network';
+
+/**
+ * File-backed {@link StrandNetworkStateStore}. Open via {@link open}, which loads
+ * the existing file and returns the cross-platform store over it; an absent,
+ * corrupt, or wrong-party file is a cold start (no saved state) while a
+ * present-but-unreadable file throws. Those rules and their reasoning live on
+ * `NodeLocalSnapshot.open`.
+ */
+export const FileStrandNetworkStateStore = {
+	/** Load (or cold-start) the party's strand network state from a file in `dir`. */
+	async open(dir: string, partyId: string): Promise<StrandNetworkStateStore> {
+		return PersistentStrandNetworkStateStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
+	}
+};