@serfab/cadre-core 1.16.0 → 1.18.0

package/src/delegate-admission.ts

@@ -1,314 +1,351 @@
-/**
- * Delegate-peer admission grants for a party control node that also runs the
- * circuit-relay server.
- *
- * A strand node runs as its own libp2p instance with its own transport peerId,
- * derived from the cadre identity key + strandId (`strand-transport-key.ts`).
- * That derivation uses the member's PRIVATE seed by design, so no third party —
- * including a co-cadre relay — can recompute it: a sibling's relay sees an
- * unknown peerId it has no way to place as a member.
- *
- * The resolution (docs/strands.md → "Relay willingness"): a party control
- * node running a relay is party-private infrastructure — it relays for its own
- * party's nodes, including the extra transport identities its members' strand
- * nodes run as. The mechanism is a **member-announced delegate grant**: before
- * a member's control node starts a strand node, it tells its siblings (over the
- * already-authenticated `/sereus/strand-addr/1.0.0` RPC) the derived peerId
- * that strand node will use, and the receiver holds a short-lived, in-memory
- * admission grant for exactly that peerId. The grant is consulted by the
- * connection-level gate (`CadreNode.admitInboundControlConnection`) and by the
- * relay-reservation admission (`CadreNode.admitControlRelayReservation`) — a
- * granted delegate is admitted outright, never drawing on the small
- * unauthorized-reservation budget that unplaced peers share
- * (`membership-connection-gater.ts` → "The relay-reservation seam") and never
- * put on the provisional connection deadline. The fail-closed per-stream gate
- * (`authorizeInboundControlStream`) never honors a grant, so a delegate gets
- * the connection and its reservation (all a circuit-relay `hop` needs) and
- * nothing more.
- *
- * A grant is a delegation of trust to an already-trusted member: the receiver
- * cannot verify that the announced peerId really is the member's strand node,
- * so an authorized member can hand CONNECTION-level access to a peerId of its
- * choosing for up to {@link DELEGATE_GRANT_TTL_MS}. The caps below bound how
- * far a buggy or compromised member can stretch that.
- *
- * The receiver side is {@link DelegateAdmissionStore}. The announcer side keeps
- * its own throttle state (a "last announced at" map that `CadreNode` owns) and
- * decides from it, per reconcile pass, which relays are due a re-announce —
- * {@link dueRelayAnnounces} and {@link prunePeerStrandKeys} are that
- * decision, pure and testable, kept here beside the TTL they are derived from.
- */
-
-import debug from 'debug';
-import { multiaddr } from '@multiformats/multiaddr';
-import { peerIdFromString } from '@libp2p/peer-id';
-
-const log = debug('sereus:cadre:delegate-admission');
-
-/**
- * How long one announced delegate grant stays valid without a re-announce.
- * Announcers refresh at half this (`CadreNode`'s reconcile pass), so a live
- * strand's grant never lapses while its control node can still reach the relay.
- */
-export const DELEGATE_GRANT_TTL_MS = 30 * 60 * 1000;
-
-/** Cap on live grants per announcing member (soonest-expiry evicted first). */
-export const MAX_DELEGATE_GRANTS_PER_MEMBER = 32;
-
-/** Cap on live grants in total (soonest-expiry evicted first). */
-export const MAX_DELEGATE_GRANTS = 256;
-
-/** One recorded delegate admission grant. */
-interface DelegateGrant {
-  /** The authorized member whose control node announced this delegate. */
-  announcerPeerId: string;
-  /** The strand the delegate serves — diagnostics + per-strand replace semantics. */
-  strandId: string;
-  /** The delegate transport peerId the grant admits. */
-  delegatePeerId: string;
-  /** Epoch ms after which the grant is inert. */
-  expiresAt: number;
-}
-
-/**
- * Composite map key for per-(peer, strand) state: the receiver's
- * replace-per-(announcer, strand) grant, the announcer's per-(target, strand)
- * throttle timestamp, and `CadreNode`'s per-(sibling, strand) strand-addr ask
- * due time.
- */
-export function peerStrandKey(peerId: string, strandId: string): string {
-  return `${peerId}\n${strandId}`;
-}
-
-/** The `peerId` half of a {@link peerStrandKey} (a peer id never contains a newline). */
-function peerIdOfKey(key: string): string {
-  return key.slice(0, key.indexOf('\n'));
-}
-
-/** The `strandId` half of a {@link peerStrandKey}. */
-function strandIdOfKey(key: string): string {
-  return key.slice(key.indexOf('\n') + 1);
-}
-
-/**
- * In-memory store of delegate admission grants, keyed by (announcer, strandId)
- * so a re-announce REPLACES the previous delegate peerId rather than
- * accumulating — a restarted strand cannot leak grants. Expired entries are
- * pruned lazily on every read/write. Injectable `now` keeps expiry testable
- * without fake timers.
- */
-export class DelegateAdmissionStore {
-  private readonly grants = new Map<string, DelegateGrant>();
-  private readonly ttlMs: number;
-
-  constructor(ttlMs: number = DELEGATE_GRANT_TTL_MS) {
-    this.ttlMs = ttlMs;
-  }
-
-  /** Number of live (unexpired at last prune) grants — test/diagnostic surface. */
-  get size(): number {
-    return this.grants.size;
-  }
-
-  /**
-   * Record (or refresh) a grant: `delegatePeerId` acts on behalf of
-   * `announcerPeerId` for `strandId`, valid for the store's TTL from `now`.
-   * Enforces {@link MAX_DELEGATE_GRANTS_PER_MEMBER} and
-   * {@link MAX_DELEGATE_GRANTS}, evicting the soonest-expiry grant first —
-   * biased against the stalest delegation, never against the fresh announce.
-   */
-  grant(announcerPeerId: string, strandId: string, delegatePeerId: string, now: number = Date.now()): void {
-    this.prune(now);
-    const key = peerStrandKey(announcerPeerId, strandId);
-    if (!this.grants.has(key)) {
-      this.evictAtCap(
-        MAX_DELEGATE_GRANTS_PER_MEMBER,
-        (g) => g.announcerPeerId === announcerPeerId
-      );
-      this.evictAtCap(MAX_DELEGATE_GRANTS, () => true);
-    }
-    this.grants.set(key, { announcerPeerId, strandId, delegatePeerId, expiresAt: now + this.ttlMs });
-    log('Delegate grant recorded: %s → %s (strand %s, %d live)', announcerPeerId, delegatePeerId, strandId, this.grants.size);
-  }
-
-  /**
-   * Drop every grant. Called when the owning node stops: grants are scoped to
-   * the session that recorded them, and outliving it would admit delegates
-   * announced against a node that no longer exists.
-   */
-  clear(): void {
-    this.grants.clear();
-  }
-
-  /** Is `remotePeerId` covered by a live grant? Prunes expired entries as it goes. */
-  has(remotePeerId: string, now: number = Date.now()): boolean {
-    this.prune(now);
-    for (const grant of this.grants.values()) {
-      if (grant.delegatePeerId === remotePeerId) {
-        return true;
-      }
-    }
-    return false;
-  }
-
-  /** Drop every grant whose expiry has passed. */
-  private prune(now: number): void {
-    for (const [key, grant] of this.grants) {
-      if (grant.expiresAt <= now) {
-        this.grants.delete(key);
-      }
-    }
-  }
-
-  /**
-   * If the grants matching `filter` are at `cap`, evict the soonest-expiry one
-   * among them to make room for the insert the caller is about to do.
-   */
-  private evictAtCap(cap: number, filter: (grant: DelegateGrant) => boolean): void {
-    let count = 0;
-    let victimKey: string | undefined;
-    let victimExpiry = Number.POSITIVE_INFINITY;
-    for (const [key, grant] of this.grants) {
-      if (!filter(grant)) {
-        continue;
-      }
-      count++;
-      if (grant.expiresAt < victimExpiry) {
-        victimExpiry = grant.expiresAt;
-        victimKey = key;
-      }
-    }
-    if (count >= cap && victimKey !== undefined) {
-      const victim = this.grants.get(victimKey)!;
-      this.grants.delete(victimKey);
-      log('Delegate grant cap %d hit — evicted soonest-expiry grant %s → %s (strand %s)',
-        cap, victim.announcerPeerId, victim.delegatePeerId, victim.strandId);
-    }
-  }
-}
-
-/** A circuit relay named by a multiaddr, as an announce target. */
-export interface CircuitRelayTarget {
-  /** The relay's peerId — the `<relay>` in `…/p2p/<relay>/p2p-circuit…`. */
-  relayPeerId: string;
-  /**
-   * The relay's DIRECT dial multiaddr (the prefix before `/p2p-circuit`),
-   * usable as a dial fallback when no connection to the relay is open yet.
-   */
-  relayAddr: string;
-}
-
-/**
- * Extract the circuit relays named by a multiaddr list — for each
- * `…/p2p/<relay>/p2p-circuit…` entry, the relay's peerId and its direct dial
- * prefix. A bare `/p2p-circuit` (no relay named), a non-circuit addr, an
- * unparsable addr, and an unparsable relay peerId are all skipped. A trailing
- * `/p2p/<dst>` after the circuit component names the DESTINATION, never the
- * relay, and is ignored. Deduplicated by relay peerId (first addr wins).
- */
-export function extractCircuitRelayTargets(addrs: string[]): CircuitRelayTarget[] {
-  const byRelay = new Map<string, CircuitRelayTarget>();
-  for (const addr of addrs) {
-    const target = circuitRelayTarget(addr);
-    if (target && !byRelay.has(target.relayPeerId)) {
-      byRelay.set(target.relayPeerId, target);
-    }
-  }
-  return [...byRelay.values()];
-}
-
-/**
- * Of `relays`, the ones whose grant for `strandId` is due a re-announce: never
- * announced to, or last announced at least half the TTL ago. Half, so a failed
- * refresh has one more attempt before the grant lapses — a lapsed grant means
- * the relay denies the strand node's reservation re-dial.
- *
- * `announceAt` is the announcer-side "last announced at" map, keyed by
- * {@link peerStrandKey} on the peer announced TO.
- */
-export function dueRelayAnnounces(
-  announceAt: ReadonlyMap<string, number>,
-  relays: readonly CircuitRelayTarget[],
-  strandId: string,
-  now: number,
-  ttlMs: number = DELEGATE_GRANT_TTL_MS
-): CircuitRelayTarget[] {
-  return relays.filter(
-    (relay) => now - (announceAt.get(peerStrandKey(relay.relayPeerId, strandId)) ?? 0) >= ttlMs / 2
-  );
-}
-
-/**
- * Drop the entries of a {@link peerStrandKey}-keyed map whose strand is no longer
- * running, and — when `livePeerIds` is given — whose peer is not among them. A
- * stopped strand needs no refresh, a departed peer is owed a fresh start when it
- * returns, and without this the map grows for the node's lifetime. Mutates in
- * place.
- */
-export function prunePeerStrandKeys(
-  byKey: Map<string, number>,
-  runningStrandIds: ReadonlySet<string>,
-  livePeerIds?: ReadonlySet<string>
-): void {
-  for (const key of byKey.keys()) {
-    const peerGone = livePeerIds !== undefined && !livePeerIds.has(peerIdOfKey(key));
-    if (peerGone || !runningStrandIds.has(strandIdOfKey(key))) {
-      byKey.delete(key);
-    }
-  }
-}
-
-/**
- * The circuit relay named by `addr`, throwing when `addr` is unparsable or names
- * no relay. The throwing form exists for CONFIG-facing callers (`relay-addrs.ts`),
- * where a typo must fail loudly rather than cost the node its reachability;
- * {@link extractCircuitRelayTargets} reads runtime-discovered addrs instead and
- * logs-and-skips.
- */
-export function circuitRelayTargetOrThrow(addr: string): CircuitRelayTarget {
-  const target = parseCircuitRelayTarget(addr);
-  if (!target) {
-    throw new Error(`Multiaddr names no circuit relay (expected …/p2p/<relayPeerId>/p2p-circuit): ${addr}`);
-  }
-  return target;
-}
-
-/**
- * The circuit relay named by `addr`; null when `addr` is well-formed but simply
- * names no relay (a direct listen addr, a bare `/p2p-circuit`), and THROWS when
- * `addr` is malformed (unparsable multiaddr, garbage relay peerId). The two
- * callers want opposite things from the first case and the same thing from the
- * second, so the distinction lives here rather than in either of them.
- */
-function parseCircuitRelayTarget(addr: string): CircuitRelayTarget | null {
-  const ma = multiaddr(addr);
-  const components = ma.getComponents();
-  const circuitIdx = components.findIndex((c) => c.name === 'p2p-circuit');
-  if (circuitIdx < 1) {
-    return null;
-  }
-  const relay = components[circuitIdx - 1];
-  if (relay.name !== 'p2p' || !relay.value) {
-    return null;
-  }
-  peerIdFromString(relay.value); // validate; throws on garbage
-  return {
-    relayPeerId: relay.value,
-    relayAddr: ma.decapsulate('/p2p-circuit').toString()
-  };
-}
-
-/**
- * One-addr body of {@link extractCircuitRelayTargets}; null when `addr` names no
- * relay. Only a MALFORMED addr logs — the addr lists this reads (a node's live
- * multiaddrs, its configured listen addrs) are mostly direct addrs, and calling
- * each of those "unparsable" is both wrong and per-announce noise.
- */
-function circuitRelayTarget(addr: string): CircuitRelayTarget | null {
-  try {
-    return parseCircuitRelayTarget(addr);
-  } catch (err) {
-    log('Skipping unparsable relay addr %s: %o', addr, err);
-    return null;
-  }
-}
+/**
+ * Delegate-peer admission grants for a party control node that also runs the
+ * circuit-relay server.
+ *
+ * A strand node runs as its own libp2p instance with its own transport peerId,
+ * derived from the cadre identity key + strandId (`strand-transport-key.ts`).
+ * That derivation uses the member's PRIVATE seed by design, so no third party —
+ * including a co-cadre relay — can recompute it: a sibling's relay sees an
+ * unknown peerId it has no way to place as a member.
+ *
+ * The resolution (docs/strands.md → "Relay willingness"): a party control
+ * node running a relay is party-private infrastructure — it relays for its own
+ * party's nodes, including the extra transport identities its members' strand
+ * nodes run as. The mechanism is a **member-announced delegate grant**: before
+ * a member's control node starts a strand node, it tells its siblings (over the
+ * already-authenticated `/sereus/strand-addr/1.0.0` RPC) the derived peerId
+ * that strand node will use, and the receiver holds a short-lived, in-memory
+ * admission grant for exactly that peerId. The grant is consulted by the
+ * connection-level gate (`CadreNode.admitInboundControlConnection`) and by the
+ * relay-reservation admission (`CadreNode.admitControlRelayReservation`) — a
+ * granted delegate is admitted outright, never drawing on the small
+ * unauthorized-reservation budget that unplaced peers share
+ * (`membership-connection-gater.ts` → "The relay-reservation seam") and never
+ * put on the provisional connection deadline. The fail-closed per-stream gate
+ * (`authorizeInboundControlStream`) never honors a grant, so a delegate gets
+ * the connection and its reservation (all a circuit-relay `hop` needs) and
+ * nothing more.
+ *
+ * A grant is a delegation of trust to an already-trusted member: the receiver
+ * cannot verify that the announced peerId really is the member's strand node,
+ * so an authorized member can hand CONNECTION-level access to a peerId of its
+ * choosing for up to {@link DELEGATE_GRANT_TTL_MS}. The caps below bound how
+ * far a buggy or compromised member can stretch that.
+ *
+ * The receiver side is {@link DelegateAdmissionStore}. The announcer side keeps
+ * its own throttle state (a "last announced at" map that `CadreNode` owns) and
+ * decides from it, per reconcile pass, which relays are due a re-announce —
+ * {@link dueRelayAnnounces} and {@link prunePeerStrandKeys} are that
+ * decision, pure and testable, kept here beside the TTL they are derived from.
+ */
+
+import debug from 'debug';
+import { multiaddr } from '@multiformats/multiaddr';
+import { peerIdFromString } from '@libp2p/peer-id';
+import type { StrandAddrOutcome } from './strand-addr-protocol.js';
+
+const log = debug('sereus:cadre:delegate-admission');
+
+/**
+ * How long one announced delegate grant stays valid without a re-announce.
+ * Announcers refresh at half this (`CadreNode`'s reconcile pass), so a live
+ * strand's grant never lapses while its control node can still reach the relay.
+ */
+export const DELEGATE_GRANT_TTL_MS = 30 * 60 * 1000;
+
+/** Cap on live grants per announcing member (soonest-expiry evicted first). */
+export const MAX_DELEGATE_GRANTS_PER_MEMBER = 32;
+
+/** Cap on live grants in total (soonest-expiry evicted first). */
+export const MAX_DELEGATE_GRANTS = 256;
+
+/** One recorded delegate admission grant. */
+interface DelegateGrant {
+  /** The authorized member whose control node announced this delegate. */
+  announcerPeerId: string;
+  /** The strand the delegate serves — diagnostics + per-strand replace semantics. */
+  strandId: string;
+  /** The delegate transport peerId the grant admits. */
+  delegatePeerId: string;
+  /** Epoch ms after which the grant is inert. */
+  expiresAt: number;
+}
+
+/**
+ * Composite map key for per-(peer, strand) state: the receiver's
+ * replace-per-(announcer, strand) grant, the announcer's per-(target, strand)
+ * throttle timestamp, and `CadreNode`'s per-(sibling, strand) strand-addr ask
+ * due time.
+ */
+export function peerStrandKey(peerId: string, strandId: string): string {
+  return `${peerId}\n${strandId}`;
+}
+
+/** The `peerId` half of a {@link peerStrandKey} (a peer id never contains a newline). */
+function peerIdOfKey(key: string): string {
+  return key.slice(0, key.indexOf('\n'));
+}
+
+/** The `strandId` half of a {@link peerStrandKey}. */
+function strandIdOfKey(key: string): string {
+  return key.slice(key.indexOf('\n') + 1);
+}
+
+/**
+ * In-memory store of delegate admission grants, keyed by (announcer, strandId)
+ * so a re-announce REPLACES the previous delegate peerId rather than
+ * accumulating — a restarted strand cannot leak grants. Expired entries are
+ * pruned lazily on every read/write. Injectable `now` keeps expiry testable
+ * without fake timers.
+ */
+export class DelegateAdmissionStore {
+  private readonly grants = new Map<string, DelegateGrant>();
+  private readonly ttlMs: number;
+
+  constructor(ttlMs: number = DELEGATE_GRANT_TTL_MS) {
+    this.ttlMs = ttlMs;
+  }
+
+  /** Number of live (unexpired at last prune) grants — test/diagnostic surface. */
+  get size(): number {
+    return this.grants.size;
+  }
+
+  /**
+   * Record (or refresh) a grant: `delegatePeerId` acts on behalf of
+   * `announcerPeerId` for `strandId`, valid for the store's TTL from `now`.
+   * Enforces {@link MAX_DELEGATE_GRANTS_PER_MEMBER} and
+   * {@link MAX_DELEGATE_GRANTS}, evicting the soonest-expiry grant first —
+   * biased against the stalest delegation, never against the fresh announce.
+   */
+  grant(announcerPeerId: string, strandId: string, delegatePeerId: string, now: number = Date.now()): void {
+    this.prune(now);
+    const key = peerStrandKey(announcerPeerId, strandId);
+    if (!this.grants.has(key)) {
+      this.evictAtCap(
+        MAX_DELEGATE_GRANTS_PER_MEMBER,
+        (g) => g.announcerPeerId === announcerPeerId
+      );
+      this.evictAtCap(MAX_DELEGATE_GRANTS, () => true);
+    }
+    this.grants.set(key, { announcerPeerId, strandId, delegatePeerId, expiresAt: now + this.ttlMs });
+    log('Delegate grant recorded: %s → %s (strand %s, %d live)', announcerPeerId, delegatePeerId, strandId, this.grants.size);
+  }
+
+  /**
+   * Drop every grant. Called when the owning node stops: grants are scoped to
+   * the session that recorded them, and outliving it would admit delegates
+   * announced against a node that no longer exists.
+   */
+  clear(): void {
+    this.grants.clear();
+  }
+
+  /** Is `remotePeerId` covered by a live grant? Prunes expired entries as it goes. */
+  has(remotePeerId: string, now: number = Date.now()): boolean {
+    this.prune(now);
+    for (const grant of this.grants.values()) {
+      if (grant.delegatePeerId === remotePeerId) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Drop every grant whose expiry has passed. */
+  private prune(now: number): void {
+    for (const [key, grant] of this.grants) {
+      if (grant.expiresAt <= now) {
+        this.grants.delete(key);
+      }
+    }
+  }
+
+  /**
+   * If the grants matching `filter` are at `cap`, evict the soonest-expiry one
+   * among them to make room for the insert the caller is about to do.
+   */
+  private evictAtCap(cap: number, filter: (grant: DelegateGrant) => boolean): void {
+    let count = 0;
+    let victimKey: string | undefined;
+    let victimExpiry = Number.POSITIVE_INFINITY;
+    for (const [key, grant] of this.grants) {
+      if (!filter(grant)) {
+        continue;
+      }
+      count++;
+      if (grant.expiresAt < victimExpiry) {
+        victimExpiry = grant.expiresAt;
+        victimKey = key;
+      }
+    }
+    if (count >= cap && victimKey !== undefined) {
+      const victim = this.grants.get(victimKey)!;
+      this.grants.delete(victimKey);
+      log('Delegate grant cap %d hit — evicted soonest-expiry grant %s → %s (strand %s)',
+        cap, victim.announcerPeerId, victim.delegatePeerId, victim.strandId);
+    }
+  }
+}
+
+/** A circuit relay named by a multiaddr, as an announce target. */
+export interface CircuitRelayTarget {
+  /** The relay's peerId — the `<relay>` in `…/p2p/<relay>/p2p-circuit…`. */
+  relayPeerId: string;
+  /**
+   * The relay's DIRECT dial multiaddr (the prefix before `/p2p-circuit`),
+   * usable as a dial fallback when no connection to the relay is open yet.
+   */
+  relayAddr: string;
+}
+
+/**
+ * Extract the circuit relays named by a multiaddr list — for each
+ * `…/p2p/<relay>/p2p-circuit…` entry, the relay's peerId and its direct dial
+ * prefix. A bare `/p2p-circuit` (no relay named), a non-circuit addr, an
+ * unparsable addr, and an unparsable relay peerId are all skipped. A trailing
+ * `/p2p/<dst>` after the circuit component names the DESTINATION, never the
+ * relay, and is ignored. Deduplicated by relay peerId (first addr wins).
+ */
+export function extractCircuitRelayTargets(addrs: string[]): CircuitRelayTarget[] {
+  const byRelay = new Map<string, CircuitRelayTarget>();
+  for (const addr of addrs) {
+    const target = circuitRelayTarget(addr);
+    if (target && !byRelay.has(target.relayPeerId)) {
+      byRelay.set(target.relayPeerId, target);
+    }
+  }
+  return [...byRelay.values()];
+}
+
+/**
+ * Of `relays`, the ones whose grant for `strandId` is due a re-announce: never
+ * announced to, or last announced at least half the TTL ago. Half, so a failed
+ * refresh has one more attempt before the grant lapses — a lapsed grant means
+ * the relay denies the strand node's reservation re-dial.
+ *
+ * `announceAt` is the announcer-side "last announced at" map, keyed by
+ * {@link peerStrandKey} on the peer announced TO.
+ */
+export function dueRelayAnnounces(
+  announceAt: ReadonlyMap<string, number>,
+  relays: readonly CircuitRelayTarget[],
+  strandId: string,
+  now: number,
+  ttlMs: number = DELEGATE_GRANT_TTL_MS
+): CircuitRelayTarget[] {
+  return relays.filter(
+    (relay) => now - (announceAt.get(peerStrandKey(relay.relayPeerId, strandId)) ?? 0) >= ttlMs / 2
+  );
+}
+
+/**
+ * Fold one announce pass's outcomes into `refusing`, the relay peerIds remembered
+ * as refusing the strand-addr protocol. A relay whose negotiation refused it
+ * (`unsupported`) is added; one that replied with any status is removed, because
+ * it serves the protocol now. A relay that did not reply (`unreachable`) is left
+ * as it was: being down says nothing about what it serves. Only `relayPeerIds`
+ * are read, so a sibling asked in the same pass is never recorded. Mutates in
+ * place.
+ */
+export function recordRelayRefusals(
+  refusing: Set<string>,
+  relayPeerIds: readonly string[],
+  outcomes: ReadonlyMap<string, StrandAddrOutcome>
+): void {
+  for (const relayPeerId of relayPeerIds) {
+    switch (outcomes.get(relayPeerId)) {
+      case 'unsupported':
+        refusing.add(relayPeerId);
+        break;
+      case 'answered':
+      case 'empty':
+      case 'unavailable':
+        refusing.delete(relayPeerId);
+        break;
+    }
+  }
+}
+
+/** Of `relays`, the ones not remembered in `refusing` (see {@link recordRelayRefusals}). */
+export function relaysNotRefusing(
+  relays: readonly CircuitRelayTarget[],
+  refusing: ReadonlySet<string>
+): CircuitRelayTarget[] {
+  return relays.filter((relay) => !refusing.has(relay.relayPeerId));
+}
+
+/**
+ * Drop the entries of a {@link peerStrandKey}-keyed map whose strand is no longer
+ * running, and — when `livePeerIds` is given — whose peer is not among them. A
+ * stopped strand needs no refresh, a departed peer is owed a fresh start when it
+ * returns, and without this the map grows for the node's lifetime. Mutates in
+ * place.
+ */
+export function prunePeerStrandKeys(
+  byKey: Map<string, number>,
+  runningStrandIds: ReadonlySet<string>,
+  livePeerIds?: ReadonlySet<string>
+): void {
+  for (const key of byKey.keys()) {
+    const peerGone = livePeerIds !== undefined && !livePeerIds.has(peerIdOfKey(key));
+    if (peerGone || !runningStrandIds.has(strandIdOfKey(key))) {
+      byKey.delete(key);
+    }
+  }
+}
+
+/**
+ * The circuit relay named by `addr`, throwing when `addr` is unparsable or names
+ * no relay. The throwing form exists for CONFIG-facing callers (`relay-addrs.ts`),
+ * where a typo must fail loudly rather than cost the node its reachability;
+ * {@link extractCircuitRelayTargets} reads runtime-discovered addrs instead and
+ * logs-and-skips.
+ */
+export function circuitRelayTargetOrThrow(addr: string): CircuitRelayTarget {
+  const target = parseCircuitRelayTarget(addr);
+  if (!target) {
+    throw new Error(`Multiaddr names no circuit relay (expected …/p2p/<relayPeerId>/p2p-circuit): ${addr}`);
+  }
+  return target;
+}
+
+/**
+ * The circuit relay named by `addr`; null when `addr` is well-formed but simply
+ * names no relay (a direct listen addr, a bare `/p2p-circuit`), and THROWS when
+ * `addr` is malformed (unparsable multiaddr, garbage relay peerId). The two
+ * callers want opposite things from the first case and the same thing from the
+ * second, so the distinction lives here rather than in either of them.
+ */
+function parseCircuitRelayTarget(addr: string): CircuitRelayTarget | null {
+  const ma = multiaddr(addr);
+  const components = ma.getComponents();
+  const circuitIdx = components.findIndex((c) => c.name === 'p2p-circuit');
+  if (circuitIdx < 1) {
+    return null;
+  }
+  const relay = components[circuitIdx - 1];
+  if (relay.name !== 'p2p' || !relay.value) {
+    return null;
+  }
+  peerIdFromString(relay.value); // validate; throws on garbage
+  return {
+    relayPeerId: relay.value,
+    relayAddr: ma.decapsulate('/p2p-circuit').toString()
+  };
+}
+
+/**
+ * One-addr body of {@link extractCircuitRelayTargets}; null when `addr` names no
+ * relay. Only a MALFORMED addr logs — the addr lists this reads (a node's live
+ * multiaddrs, its configured listen addrs) are mostly direct addrs, and calling
+ * each of those "unparsable" is both wrong and per-announce noise.
+ */
+function circuitRelayTarget(addr: string): CircuitRelayTarget | null {
+  try {
+    return parseCircuitRelayTarget(addr);
+  } catch (err) {
+    log('Skipping unparsable relay addr %s: %o', addr, err);
+    return null;
+  }
+}