@serfab/cadre-core 1.7.0 → 1.9.0

package/src/strand-formation-protocol.ts

@@ -19,16 +19,22 @@
  */
 
 import debug from 'debug';
-import { multiaddr } from '@multiformats/multiaddr';
+import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
 import type { Libp2p } from '@libp2p/interface';
 import type { StrandFormationDisclosure, StrandMembershipInvite } from './types.js';
-import { type ControlStream, writeFrame, withTimeout } from './control-stream.js';
+import { type ControlStream, writeFrame, withDeadline, withTimeout } from './control-stream.js';
 import { canonicalJson } from './canonical-json.js';
 import { requireEd25519PublicKeyB64 } from './ed25519-key.js';
 import { verifyFormationConsent } from './peer-authorization.js';
 // seed-bootstrap imports neither this protocol nor the manager/solicitation layers,
 // so this import introduces no cycle.
 import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
+import {
+  formationDeadlines,
+  resolveProvisionTimeoutMs,
+  responderClampReserveMs,
+  splitProvisionBudget
+} from './strand-formation-deadlines.js';
 
 const log = debug('sereus:cadre:formation-proto');
 
@@ -47,66 +53,16 @@ export const INVALID_TOKEN_REASON = 'Invalid token';
 /** Maximum formation message size (1MB). */
 const MAX_FORMATION_MSG_SIZE = 1024 * 1024;
 
-/** Default whole-session timeout (ms). */
-const DEFAULT_SESSION_TIMEOUT_MS = 30_000;
-/** Default per-step (single read/write) timeout (ms). */
-const DEFAULT_STEP_TIMEOUT_MS = 5_000;
-/**
- * Default provisioning budget (ms) — distinct from {@link DEFAULT_STEP_TIMEOUT_MS} because
- * `provisionStrand` is real work (DB writes, and an outbound approval-hook HTTP call when
- * the invite carries a `ValidationUrl`), not a bare wire read/write.
- *
- * Ordering is deliberate — each layer must be able to fail and report before the layer above
- * it gives up:
- *
- *   approval hook (10 s, `formation-approval.ts`)
- *     < responder provisioning (12 s)
- *     < initiator await-response (15 s)
- *     < session (30 s)
- *
- * The 3 s margin between responder provisioning and initiator await-response is the wire
- * latency budget for the result frame to travel back.
- *
- * The last {@link PROVISION_SETTLE_GRACE_MS} of this budget is a settle grace, so the default
- * WORK budget (12 s − 2 s = 10 s) EQUALS the hook's own 10 s: a dead hook races 'Formation
- * approval unavailable, retry' against 'Formation provisioning timed out'. Both are retryable
- * and both leave the invite unspent, so the race is benign.
- */
-const DEFAULT_PROVISION_TIMEOUT_MS = 12_000;
-/**
- * Settle grace (ms), carved OUT of `provisionTimeoutMs` — never added on top, so the budget
- * ladder above is untouched. The listener aborts the provisioning hook when the work budget
- * ({@link splitProvisionBudget}) expires, then waits up to this grace for the work to settle
- * anyway: once the `FormationUsage` insert has been issued nothing can un-spend it (the table
- * is append-only), so a provisioning that lands late is ADOPTED and reported as a real
- * approval rather than lying "timed out" over a spent invite. A hook that observes the
- * abort before writing leaves the invite unspent.
- */
-const PROVISION_SETTLE_GRACE_MS = 2_000;
-/**
- * Wire-latency margin (ms) added to the responder's provisioning budget to get the
- * initiator's await-response budget — the travel time for the result frame to come back
- * after the responder finishes (see {@link DEFAULT_PROVISION_TIMEOUT_MS}).
- * `StrandFormationManager` reuses this constant so a CONFIGURED budget preserves the same
- * margin the defaults do, instead of applying the same number to both sides and racing the
- * initiator's own timeout against the responder's clean rejection reply. The responder's
- * clamp ({@link provisionCeilingMs}) holds the same margin back, so the ordering survives a
- * budget large enough that BOTH roles get clamped.
- *
- * NOTE: 3 s is a fixed assumption about how long the result frame takes to travel back. If
- * formation ever runs over paths where that frame can take longer (a slow circuit relay, a
- * congested mobile link), the margin is too thin and the initiator's timeout races the
- * responder's reply again — raise it, or derive it from an observed round-trip.
- */
-export const PROVISION_RESPONSE_TRAVEL_MARGIN_MS = 3_000;
-/** Default initiator await-response budget (ms); see {@link DEFAULT_PROVISION_TIMEOUT_MS}. */
-const DEFAULT_INITIATOR_PROVISION_TIMEOUT_MS = DEFAULT_PROVISION_TIMEOUT_MS + PROVISION_RESPONSE_TRAVEL_MARGIN_MS;
 /**
  * Default cap on concurrent inbound formation sessions.
- * NOTE: a longer provisioning budget holds a session's slot longer, so a slow hook can
- * exhaust this cap and make the listener reject fresh joiners with 'Too many concurrent
- * formation sessions'. Fine at the current default; revisit if `provisionTimeoutMs` is
- * raised well above its default or this cap is lowered.
+ *
+ * NOTE: a session holds its slot for its whole provisioning budget, 171 s at the default
+ * declared link ({@link formationDeadlines}), so a slow hook or commit holds slots for
+ * minutes. Only a caller holding a valid token AND a valid consent signature reaches
+ * provisioning — a stranger is cut at the contact wait (7 s at the default) or at the first
+ * validation read — so the exposure is one invitee opening many sessions with one token. If
+ * invitation tokens are ever published where untrusted parties can read them, cap in-flight
+ * sessions per token rather than lowering this.
  */
 const DEFAULT_MAX_CONCURRENT_SESSIONS = 100;
 
@@ -116,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 ────────────────────────────────────────────────────────────────────
 
@@ -380,62 +335,6 @@ export function isValidResponderCreatesResult(response: FormationResultMessage):
   return true;
 }
 
-/**
- * Ceiling for a resolved provisioning budget.
- *
- * The session budget also has to cover the wire step that PRECEDES provisioning (the
- * responder's contact read, the initiator's dial-connect), so a whole step is held back
- * rather than triggering only on a literal overrun.
- *
- * `reserveMs` is the EXTRA room only the responder holds back, so its own budget still
- * lands strictly before the initiator's larger await-response budget even when both are
- * clamped — without it, any configured budget at or above `sessionTimeoutMs -
- * stepTimeoutMs` clamps both roles onto the same number and the responder's clean
- * rejection races the initiator's timeout again. Capped at half the remaining room (like
- * {@link splitProvisionBudget}) so a small session config still spends most of it working.
- */
-function provisionCeilingMs(sessionTimeoutMs: number, stepTimeoutMs: number, reserveMs: number): number {
-  const roomMs = sessionTimeoutMs - stepTimeoutMs;
-  return Math.max(1, roomMs - Math.min(reserveMs, Math.floor(roomMs / 2)));
-}
-
-/**
- * Resolve a caller-supplied provisioning budget: `0`/negative means "unset" (use
- * `defaultMs`). If the result would let provisioning outlive the session — no result
- * frame is ever sent, exactly the failure this budget exists to prevent — clamp it to
- * {@link provisionCeilingMs} and log a warning.
- */
-function resolveProvisionTimeoutMs(
-  configured: number | undefined,
-  defaultMs: number,
-  sessionTimeoutMs: number,
-  stepTimeoutMs: number,
-  role: string,
-  reserveMs = 0
-): number {
-  const requested = configured && configured > 0 ? configured : defaultMs;
-  const ceilingMs = provisionCeilingMs(sessionTimeoutMs, stepTimeoutMs, reserveMs);
-  if (requested >= ceilingMs) {
-    log(
-      '%s provisionTimeoutMs %dms leaves no room under sessionTimeoutMs %dms (step %dms, reserve %dms); clamping to %dms',
-      role, requested, sessionTimeoutMs, stepTimeoutMs, reserveMs, ceilingMs
-    );
-    return ceilingMs;
-  }
-  return requested;
-}
-
-/**
- * Split a resolved provisioning budget into the WORK budget and the trailing settle grace.
- *
- * The grace is carved OUT of the budget (see {@link PROVISION_SETTLE_GRACE_MS}), and capped at
- * half of it so a small configured budget still spends at least half its time doing work.
- */
-function splitProvisionBudget(provisionTimeoutMs: number): { workMs: number; graceMs: number } {
-  const graceMs = Math.min(PROVISION_SETTLE_GRACE_MS, Math.floor(provisionTimeoutMs / 2));
-  return { workMs: provisionTimeoutMs - graceMs, graceMs };
-}
-
 // ── Responder (listener) ─────────────────────────────────────────────────────
 
 export interface FormationListenerOptions {
@@ -471,14 +370,22 @@ export interface FormationListenerOptions {
    * per-strand address lookup.
    */
   resolveStrandAddrs?(strandId: string): string[];
+  /**
+   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
+   * every deadline below takes its default ({@link formationDeadlines}). The default
+   * declaration when omitted.
+   */
+  linkRoundTripMs?: number;
+  /** Whole-session budget; default `sessionMs` of the derived ladder. */
   sessionTimeoutMs?: number;
+  /** Budget for the contact-frame read; default `awaitContactMs` of the derived ladder. */
   stepTimeoutMs?: number;
   /**
-   * Budget for the `provisionStrand` hook call — distinct from `stepTimeoutMs` because
-   * provisioning is real work, not a bare wire read/write. Default 12 s; `0`/unset uses
-   * the default; a value that would outlive the session is clamped ({@link
-   * provisionCeilingMs}). See {@link DEFAULT_PROVISION_TIMEOUT_MS} for the full ordering
-   * rationale.
+   * Budget for the `provisionStrand` hook call, work plus settle grace — distinct from
+   * `stepTimeoutMs` because provisioning is real work, not a bare wire read. Default
+   * `provisionWorkMs + provisionGraceMs` of the derived ladder (171 s at the default
+   * declaration); `0`/unset uses the default; a value that would outlive the session is
+   * clamped ({@link resolveProvisionTimeoutMs}). See {@link formationDeadlines} for the ordering.
    */
   provisionTimeoutMs?: number;
   maxConcurrentSessions?: number;
@@ -493,7 +400,7 @@ export interface FormationListenerOptions {
 export class FormationListener {
   private readonly options: FormationListenerOptions;
   private readonly sessionTimeoutMs: number;
-  private readonly stepTimeoutMs: number;
+  private readonly awaitContactMs: number;
   private readonly provisionWorkMs: number;
   private readonly provisionGraceMs: number;
   private readonly maxConcurrentSessions: number;
@@ -503,13 +410,14 @@ export class FormationListener {
 
   constructor(options: FormationListenerOptions) {
     this.options = options;
-    this.sessionTimeoutMs = options.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
-    this.stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+    const deadlines = formationDeadlines(options.linkRoundTripMs);
+    this.sessionTimeoutMs = options.sessionTimeoutMs ?? deadlines.sessionMs;
+    this.awaitContactMs = options.stepTimeoutMs ?? deadlines.awaitContactMs;
     const split = splitProvisionBudget(resolveProvisionTimeoutMs(
-      options.provisionTimeoutMs, DEFAULT_PROVISION_TIMEOUT_MS,
-      this.sessionTimeoutMs, this.stepTimeoutMs, 'FormationListener',
-      PROVISION_RESPONSE_TRAVEL_MARGIN_MS
-    ));
+      options.provisionTimeoutMs, deadlines.provisionWorkMs + deadlines.provisionGraceMs,
+      this.sessionTimeoutMs, this.awaitContactMs + deadlines.validationMs, 'FormationListener',
+      responderClampReserveMs(deadlines, this.awaitContactMs)
+    ), deadlines.provisionGraceMs);
     this.provisionWorkMs = split.workMs;
     this.provisionGraceMs = split.graceMs;
     this.maxConcurrentSessions = options.maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS;
@@ -520,21 +428,22 @@ export class FormationListener {
     return this.activeSessions;
   }
 
-  register(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): void {
+  /** Register the formation handler on `node`. Rejects when libp2p refuses the registration. */
+  async register(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): Promise<void> {
     if (this.registered.has(node)) {
       log('node already registered');
       return;
     }
-    void node.handle(protocolId, async (rawStream: unknown, _connection: unknown) => {
+    await node.handle(protocolId, async (rawStream: unknown, _connection: unknown) => {
       await this.handleStream(rawStream as ControlStream);
     });
     this.registered.add(node);
     log('formation listener registered (%s)', protocolId);
   }
 
-  unregister(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): void {
+  async unregister(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): Promise<void> {
     if (!this.registered.has(node)) return;
-    void node.unhandle(protocolId);
+    await node.unhandle(protocolId);
     this.registered.delete(node);
     log('formation listener unregistered (%s)', protocolId);
   }
@@ -559,8 +468,8 @@ export class FormationListener {
   }
 
   /**
-   * Run the provisioning hook under its WORK budget — the configured provisioning budget minus
-   * the trailing settle grace ({@link splitProvisionBudget}, {@link PROVISION_SETTLE_GRACE_MS}).
+   * Run the provisioning hook under its WORK budget — the provisioning budget minus the
+   * trailing settle grace ({@link splitProvisionBudget}).
    *
    * When the work budget expires the hook's signal is aborted, then
    * {@link settleWithinGrace} waits out the grace for the aborted work to settle anyway.
@@ -600,11 +509,16 @@ export class FormationListener {
    * inside the grace its outcome is ADOPTED — the joiner is told the truth (approved, or the
    * hook's own rejection reason) rather than "timed out" over a spent invite.
    *
-   * NOTE: one window stays open — a work budget that expires after the `FormationUsage`
-   * insert was issued AND a commit that outlasts the grace. The joiner is told 'timed out'
-   * while its one-time invite is in fact spent, and since every retry mints a fresh keypair
-   * no recovery path can match it. Nothing can un-spend an append-only row, so the late-settle
-   * logging below is the observability for it; widen the grace only if it is seen in the wild.
+   * The grace is derived to contain one seat read plus one commit at the declared link
+   * ({@link formationDeadlines}), which is exactly what runs after the insert attempt passes
+   * its abort check, so at that link the late outcome lands inside it.
+   *
+   * NOTE: a commit that outlasts even the derived grace (a link slower than declared, or a
+   * configured `provisionTimeoutMs` whose half-cap shrank the grace) still tells the joiner
+   * 'timed out' while its one-time invite is in fact spent, and since every retry mints a
+   * fresh keypair no recovery path can match it. Nothing can un-spend an append-only row, so
+   * the late-settle logging below is the observability for it; if it is seen in the wild,
+   * raise the declared link rather than this grace.
    */
   private async settleWithinGrace(
     id: number,
@@ -706,7 +620,7 @@ export class FormationListener {
 
     try {
       const reader = new FrameReader(stream);
-      const contact = await withTimeout(this.stepTimeoutMs, `Formation await-contact#${id}`, () => reader.read<FormationContactMessage>());
+      const contact = await withTimeout(this.awaitContactMs, `Formation await-contact#${id}`, () => reader.read<FormationContactMessage>());
       log('formation session #%d contact: token=%s party=%s', id, contact.token, contact.partyId);
 
       if (!this.isJoinerConsentValid(id, contact)) {
@@ -777,12 +691,24 @@ export interface FormationDialOptions {
   responderAddrs: string[];
   /** Validate the responder's result; a false return aborts the formation. */
   validateResponse(response: FormationResultMessage): Promise<boolean>;
+  /**
+   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
+   * every deadline below takes its default ({@link formationDeadlines}). The default
+   * declaration when omitted.
+   */
+  linkRoundTripMs?: number;
+  /** Whole-session budget; default `sessionMs` of the derived ladder. */
   sessionTimeoutMs?: number;
-  stepTimeoutMs?: number;
   /**
-   * Budget for the `await-response` read only (the responder's provisioning + reply travel
-   * time) — `dial-connect` keeps using `stepTimeoutMs`. Default 15 s; `0`/unset uses the
-   * default. See {@link DEFAULT_PROVISION_TIMEOUT_MS} for the full ordering rationale.
+   * Budget for `dial-connect`: opening the connection, through a relay if need be, and
+   * negotiating the formation protocol. Default `dialMs` of the derived ladder.
+   */
+  dialTimeoutMs?: number;
+  /**
+   * Budget for the `await-response` read only (the responder's provisioning plus the reply's
+   * travel time). Default `initiatorAwaitResponseMs` of the derived ladder; `0`/unset uses
+   * the default; a value that would outlive the session is clamped. See
+   * {@link formationDeadlines} for the ordering.
    */
   provisionTimeoutMs?: number;
   protocolId?: string;
@@ -806,6 +732,32 @@ export interface FormationDialResult {
   strandAddrs: string[];
 }
 
+/**
+ * Open the formation stream under the dial deadline, cancelling the dial when it expires.
+ *
+ * The deadline's signal goes into `dialProtocol`, so an expired dial is abandoned by libp2p
+ * rather than left running. A dial that settles in the same tick the deadline fires loses
+ * the race to the timeout rejection and would leave its stream open with nobody to close
+ * it, so a stream that arrives after the signal aborted is reset here — the same treatment
+ * `exchangeFrame` (`control-stream.ts`) gives a stream dialed past its deadline. A late
+ * rejection is the abort itself, or reaches the caller through the awaited copy, so the
+ * handler below only stops it being reported as unhandled.
+ */
+function openFormationStream(node: Libp2p, addr: Multiaddr, protocolId: string, dialTimeoutMs: number): Promise<ControlStream> {
+  return withDeadline(dialTimeoutMs, 'Formation dial-connect', (signal) => {
+    const pending = node.dialProtocol(addr, protocolId, { signal });
+    void pending.then(
+      (stream) => {
+        if (signal.aborted) {
+          (stream as unknown as ControlStream).abort(new Error('Formation dial-connect resolved after its deadline'));
+        }
+      },
+      () => { /* surfaced through the awaited copy, or the abort itself */ }
+    );
+    return pending as unknown as Promise<ControlStream>;
+  });
+}
+
 /**
  * Initiator side of the native formation protocol. Dials the responder, sends the
  * contact (carrying the real disclosure/token/cadre), validates the responder's
@@ -817,17 +769,17 @@ export async function dialFormation(node: Libp2p, options: FormationDialOptions)
     throw new Error('No responder addresses available for formation');
   }
   const protocolId = options.protocolId ?? FORMATION_PROTOCOL;
-  const sessionTimeoutMs = options.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
-  const stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+  const deadlines = formationDeadlines(options.linkRoundTripMs);
+  const sessionTimeoutMs = options.sessionTimeoutMs ?? deadlines.sessionMs;
+  const dialTimeoutMs = options.dialTimeoutMs ?? deadlines.dialMs;
   const provisionTimeoutMs = resolveProvisionTimeoutMs(
-    options.provisionTimeoutMs, DEFAULT_INITIATOR_PROVISION_TIMEOUT_MS,
-    sessionTimeoutMs, stepTimeoutMs, 'dialFormation'
+    options.provisionTimeoutMs, deadlines.initiatorAwaitResponseMs,
+    sessionTimeoutMs, dialTimeoutMs, 'dialFormation'
   );
   const addr = multiaddr(options.responderAddrs[0]);
 
   return withTimeout(sessionTimeoutMs, 'Formation dial', async () => {
-    const rawStream = await withTimeout(stepTimeoutMs, 'Formation dial-connect', async () => node.dialProtocol(addr, protocolId));
-    const stream = rawStream as unknown as ControlStream;
+    const stream = await openFormationStream(node, addr, protocolId, dialTimeoutMs);
     try {
       const reader = new FrameReader(stream);
       writeFrame(stream, options.contact);

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;
+}