@serfab/cadre-core 0.11.0 → 0.12.0

package/dist/membership-connection-gater.js

@@ -1,5 +1,6 @@
 /**
- * Control-network inbound connection gate (defense-in-depth).
+ * Control-network inbound admission gates (defense-in-depth): the
+ * encrypted-connection checkpoint and the circuit-relay reservation checkpoint.
  *
  * Layer 2 of the membership enforcement chain: the PRIMARY gates are per-stream
  * — every sensitive sereus control protocol rejects a peer that fails the
@@ -10,7 +11,9 @@
  * time. This module adds the opportunistic connection-level layer on top: a
  * peer this node can positively determine is NOT authorized is refused at the
  * encrypted-connection checkpoint, before any protocol negotiation, so a
- * known-nothing outsider is never even in the conversation.
+ * known-nothing outsider is never even in the conversation — EXCEPT on a node
+ * that runs the circuit-relay server, where the refusal moves to the
+ * relay-reservation checkpoint instead (see "The relay-reservation seam").
  *
  * ## The stranger allowlist (the ONE place it is defined)
  *
@@ -45,14 +48,54 @@
  *
  *  - **Announced delegate peers** (`delegate-admission.ts`). A member's strand
  *    node runs as a separate libp2p identity whose peerId no sibling can
- *    recompute, so a relay-running control node would deny its circuit-relay
- *    reservation. Before starting a strand node, a member's control node
+ *    recompute. Before starting a strand node, a member's control node
  *    announces that peerId over the already-authenticated strand-addr RPC, and
  *    the receiver holds a short-lived grant for it
- *    (`CadreNode.grantDelegateAdmission`). The grant admits the CONNECTION and
- *    nothing else — a reservation needs no stream — and is deliberately
- *    invisible to the per-stream gate below, so a delegate still gets refused
- *    on every members-only protocol.
+ *    (`CadreNode.grantDelegateAdmission`). The grant admits the CONNECTION,
+ *    admits the peer's RESERVATION at the seam below (without spending the
+ *    unauthorized budget), and nothing else — it is deliberately invisible to
+ *    the per-stream gate, so a delegate still gets refused on every
+ *    members-only protocol.
+ *
+ * ## The relay-reservation seam
+ *
+ * A circuit-relay reservation is established by the reserving peer DIALING the
+ * relay, so at the relay it is an inbound connection — and killing that
+ * connection kills the reservation. For a genuine member whose `CadrePeer` row
+ * has not yet replicated to this node, a connection-level deny here is NOT
+ * self-healing the way a data connection's is: an outbound reconcile dial
+ * re-establishes a data link, but no outbound dial can grant the REMOTE peer a
+ * reservation, and a relay-only peer has no address of its own to dial back —
+ * the reservation IS its address. Boot ordering makes the window ordinary (a
+ * node's circuit listener runs inside `libp2p.start()`, before its own row
+ * could have replicated anywhere), and a stalled replication makes it
+ * unbounded. So the relay would be answering a RELAY question ("may this peer
+ * use my forwarding capacity?") with a MEMBERSHIP answer, at a checkpoint where
+ * a wrong answer is unrecoverable.
+ *
+ * On a node whose relay server is enabled the two questions are separated:
+ *
+ *  - The policy returns `'admit-for-relay'` instead of `'deny'`, and the
+ *    connection is ADMITTED. The fail-closed per-stream gates still refuse such
+ *    a peer every members-only protocol, so it gains identify/ping and the
+ *    relay hop protocol, nothing else.
+ *  - The reservation itself is decided at libp2p's
+ *    `denyInboundRelayReservation` hook (the circuit-relay server consults it
+ *    per RESERVE request): the policy admits members, delegates and configured
+ *    infra outright, and admits peers it cannot place only within a bounded
+ *    budget ({@link UnauthorizedReservationBudget}) — a member whose row is in
+ *    flight always finds a slot under any sane cap, while outsiders cannot
+ *    annex the party's relay capacity.
+ *  - An `'admit-for-relay'` connection that is NOT reserving is dropped: it has
+ *    {@link RELAY_ADMISSION_RESERVE_DEADLINE_MS} to get a reservation ADMITTED
+ *    at that hook, after which the underlying connection is aborted. The
+ *    guarantee above thus weakens on relay-enabled nodes from "never in the
+ *    conversation" to "in it briefly, and can speak nothing".
+ *
+ * The deadline clears on reservation ADMISSION, not on the reservation's own
+ * success: this gate cannot observe the server-side `reserve()` outcome, so a
+ * peer whose admitted reservation is then refused for server capacity keeps its
+ * connection until either side closes it — bounded and mute, so harmless.
  *
  * Everything else a control node handles — the Optimystic control-DB protocols
  * (`/optimystic/control-<party>/{repo,cluster,sync,block-transfer}/…`), wake
@@ -70,12 +113,45 @@
  * stranger carve-outs — an enrollment window admits a stranger's connection
  * for seed delivery, yet its repo streams are still refused.
  *
+ * ## The bring-up quiet period
+ *
+ * One state is decided BEFORE any of the above, and is not about the remote peer
+ * at all: while this node's control-database bring-up is in flight
+ * (`InboundAdmissionPolicy.bringUpInFlight`), the gate denies BOTH directions —
+ * `denyDialPeer` and `denyInboundEncryptedConnection` — and then opens.
+ *
+ * The invariant it protects is "`ControlDatabase.initialize()` runs while this
+ * node holds ZERO control connections". Building that database is a long chain
+ * of cohort-consulting block probes, and every connected same-party sibling is in
+ * the cohort those probes consult. A sibling that has not yet replicated this
+ * node's `CadrePeer` row correctly refuses them at its own fail-closed per-stream
+ * gate, so ONE connection in this window turns bring-up into
+ * `BlockUnavailableError` and `start()` rejects. Retrying cannot converge: the
+ * condition that would clear the refusal is this node's own row reaching the
+ * sibling, and writing that row needs the database the retry is building. So the
+ * only fix is to not be in the conversation yet — which is what this window is.
+ *
+ * The ordering is arranged so nothing SHOULD open a connection here anyway:
+ * `network.relayAddrs` resolves to a listener that dials nothing and reserves
+ * after bring-up (`relay-addrs.ts`), and the control-cohort reconcile pass is
+ * scheduled post-start. This window is what makes that a property rather than an
+ * accident of ordering — the live case it actually catches is
+ * `controlNetwork.bootstrapNodes`, where `@libp2p/bootstrap` emits its discovery
+ * events ~1 s after `libp2p.start()` and the connection manager auto-dials from
+ * there, which is a race bring-up wins only while raw-storage latency stays low.
+ *
+ * A denial here costs a retry, not a partition: libp2p's connection manager
+ * re-dials on its auto-dial cadence, the reservation supervisor re-drives, and a
+ * denied inbound peer reconnects. The window opens on bring-up FAILURE too (via
+ * `CadreNode.cleanup`), so teardown is never gated.
+ *
  * ## Fail-open, deliberately
  *
- * This layer only ever denies on a POSITIVE determination of "unauthorized
- * outsider while no stranger path is open". Any error, missing dependency, or
- * ambiguous state admits the connection and defers to the fail-closed stream
- * gates — a DB hiccup must not partition a legitimate cadre.
+ * Outside that window this layer only ever denies on a POSITIVE determination of
+ * "unauthorized outsider while no stranger path is open". Any error, missing
+ * dependency, or ambiguous state admits the connection (and the reservation) and
+ * defers to the fail-closed stream gates — a DB hiccup must not partition a
+ * legitimate cadre.
  */
 import debug from 'debug';
 import { SEED_PROTOCOL } from './seed-bootstrap.js';
@@ -97,7 +173,8 @@ export const STRANGER_OPEN_PROTOCOLS = [SEED_PROTOCOL, FORMATION_PROTOCOL];
  */
 export const DEFAULT_ENROLLMENT_WINDOW_MS = 30 * 60 * 1000;
 /**
- * Deadline for one admission decision, after which the connection is ADMITTED.
+ * Deadline for one admission decision, after which the fail-open outcome is
+ * used (connection admitted / reservation admitted).
  *
  * libp2p awaits `denyInboundEncryptedConnection` inside the inbound upgrade
  * WITHOUT racing its inbound-upgrade timeout signal (unlike the pre-encryption
@@ -110,16 +187,118 @@ export const DEFAULT_ENROLLMENT_WINDOW_MS = 30 * 60 * 1000;
  * failing closed (or not at all).
  */
 export const ADMISSION_DECISION_TIMEOUT_MS = 2000;
+/**
+ * How long an `'admit-for-relay'` connection may exist without a relay
+ * reservation being ADMITTED at the `denyInboundRelayReservation` hook, after
+ * which the gate aborts the underlying connection. A reserving client asks for
+ * its slot immediately after the connection upgrades (`relay-reservation.ts`
+ * dials and requests in one drive; a strand node's configured circuit listener
+ * does the same from inside its own `listen()`), so a connection idle past this
+ * deadline is not reserving.
+ */
+export const RELAY_ADMISSION_RESERVE_DEADLINE_MS = 5000;
+/**
+ * Default cap on concurrent relay reservations held by peers the membership
+ * check could not place (see {@link UnauthorizedReservationBudget}). Small on
+ * purpose: it exists for the handful of genuine members whose rows are still
+ * in flight, not as public relay capacity. Overridable per node via
+ * `network.unauthorizedRelayReservationCap` (0 refuses every unauthorized
+ * reservation — the strict pre-seam posture).
+ *
+ * NOTE: this cap shares the relay server's own reservation store, whose default
+ * size is 15 (`@libp2p/circuit-relay-v2`'s `DEFAULT_MAX_RESERVATION_STORE_SIZE`);
+ * unplaced peers may therefore occupy up to this many of those slots, and the
+ * rest are what members and delegates compete for. This module cannot read the
+ * server's size, so the two are kept apart by hand — if either is raised, keep
+ * this one well under the store's, or a fleet of unplaceable peers can crowd
+ * genuine members out of the server's own store (which the gate cannot override).
+ */
+export const MAX_UNAUTHORIZED_RELAY_RESERVATIONS = 8;
+/**
+ * How long one {@link UnauthorizedReservationBudget} entry occupies a slot
+ * without a refresh. Mirrors the relay server's own default reservation TTL
+ * (`@libp2p/circuit-relay-v2`'s `DEFAULT_MAX_RESERVATION_TTL`, 2 h): the server
+ * holds an unrefreshed reservation exactly that long, and a live reserver
+ * re-requests (re-hitting the admission hook, refreshing its entry) well before
+ * expiry — so the live entry count tracks the server's own occupancy without
+ * this module reaching into the server's reservation store.
+ *
+ * NOTE: a mirror, not a live coupling — if the relay server is ever configured
+ * with a non-default `reservationTtl` (db-p2p's `relayServerInit`), update this
+ * constant alongside it or the budget's occupancy drifts from the server's.
+ */
+export const UNAUTHORIZED_RESERVATION_TTL_MS = 2 * 60 * 60 * 1000;
+/**
+ * Bounded budget of concurrent relay reservations for peers the membership
+ * check could not place. `tryAdmit` is the whole surface: an already-admitted
+ * peer refreshes its entry (a reservation refresh never double-counts), a new
+ * peer takes a free slot or is refused. Entries expire after `ttlMs` (see
+ * {@link UNAUTHORIZED_RESERVATION_TTL_MS} for why that mirrors the relay
+ * server's own hold). Injectable `now` keeps expiry testable without fake
+ * timers. Authorized members and delegates are never run through this — the
+ * policy admits them before consulting the budget, and `release`s the slot such
+ * a peer took while it was still unplaceable, so the boot-ordering window a
+ * member passes through costs the budget nothing once its row lands.
+ */
+export class UnauthorizedReservationBudget {
+    constructor(cap = MAX_UNAUTHORIZED_RELAY_RESERVATIONS, ttlMs = UNAUTHORIZED_RESERVATION_TTL_MS) {
+        this.cap = cap;
+        this.ttlMs = ttlMs;
+        this.admitted = new Map();
+    }
+    /** Number of live (unexpired at last prune) entries — test/diagnostic surface. */
+    get size() {
+        return this.admitted.size;
+    }
+    /** Admit (or refresh) `remotePeerId` if a slot is free; false when the cap is spent. */
+    tryAdmit(remotePeerId, now = Date.now()) {
+        this.prune(now);
+        if (!this.admitted.has(remotePeerId) && this.admitted.size >= this.cap) {
+            log('Unauthorized-reservation budget spent (%d/%d) — refusing %s', this.admitted.size, this.cap, remotePeerId);
+            return false;
+        }
+        this.admitted.set(remotePeerId, now + this.ttlMs);
+        return true;
+    }
+    /**
+     * Give back the slot `remotePeerId` holds, if any — called when the peer has
+     * become admissible on its own merits (its membership row replicated, or a
+     * delegate grant landed), so the slot it took during the boot-ordering window
+     * does not stay spent for the remaining TTL on a peer that no longer needs it.
+     */
+    release(remotePeerId) {
+        this.admitted.delete(remotePeerId);
+    }
+    prune(now) {
+        for (const [peerId, expiresAt] of this.admitted) {
+            if (expiresAt <= now) {
+                this.admitted.delete(peerId);
+            }
+        }
+    }
+}
 /**
  * Build the control node's connection gater: the caller-supplied gater (if any)
  * with membership admission composed onto `denyInboundEncryptedConnection` —
- * the earliest checkpoint where the remote's authenticated PeerId is known.
+ * the earliest checkpoint where the remote's authenticated PeerId is known —
+ * and reservation admission composed onto `denyInboundRelayReservation` — the
+ * hook the circuit-relay server consults per RESERVE request (inert on a node
+ * whose relay server is off; libp2p never calls it there).
+ *
+ * `denyDialPeer` is composed too, but ONLY for the bring-up quiet period (see
+ * the module doc): outside that window outbound dials are never gated by
+ * membership — this node decides for itself who to talk to.
+ *
+ * Composition semantics: every hook of `base` is preserved as-is; on the three
+ * composed hooks a deny from EITHER the base gater or the admission policy
+ * denies. A policy error — or a decision slower than `decisionTimeoutMs` —
+ * takes the fail-open outcome (connection admitted / reservation admitted, see
+ * module doc); the base gater's verdict is still honored first.
  *
- * Composition semantics: every hook of `base` is preserved as-is; on the
- * inbound-encrypted hook a deny from EITHER the base gater or the admission
- * policy denies. A policy error — or a decision slower than
- * `decisionTimeoutMs` — admits (fail-open, see module doc); the base gater's
- * verdict is still honored first.
+ * An `'admit-for-relay'` verdict admits the connection and arms a
+ * `reserveDeadlineMs` timer against it; the timer is disarmed when a
+ * reservation for that peer is ADMITTED at the reservation hook, and aborts the
+ * underlying `MultiaddrConnection` when it fires first.
  *
  * NOTE: `base` is spread, so a gater passed as a CLASS INSTANCE would lose its
  * prototype methods; every caller in this repo (and libp2p's own default)
@@ -136,39 +315,80 @@ export const ADMISSION_DECISION_TIMEOUT_MS = 2000;
  * Control node only: strand cohort nodes legitimately connect cross-party
  * peers, so `CadreNode` threads the raw configured gater to them unchanged.
  */
-export function createMembershipConnectionGater(policy, base, decisionTimeoutMs = ADMISSION_DECISION_TIMEOUT_MS) {
+export function createMembershipConnectionGater(policy, base, decisionTimeoutMs = ADMISSION_DECISION_TIMEOUT_MS, reserveDeadlineMs = RELAY_ADMISSION_RESERVE_DEADLINE_MS) {
+    const pendingReservations = new PendingReserveDeadlines(reserveDeadlineMs);
+    const quiet = () => policy.bringUpInFlight?.() ?? false;
     return {
         ...base,
+        denyDialPeer: async (peerId) => {
+            if (await base?.denyDialPeer?.(peerId)) {
+                return true;
+            }
+            if (quiet()) {
+                log('Control-database bring-up in flight — refusing the outbound dial to %s', peerId.toString());
+                return true;
+            }
+            return false;
+        },
         denyInboundEncryptedConnection: async (peerId, maConn) => {
             if (await base?.denyInboundEncryptedConnection?.(peerId, maConn)) {
                 return true;
             }
+            if (quiet()) {
+                log('Control-database bring-up in flight — refusing the inbound connection from %s', peerId.toString());
+                return true;
+            }
             const remotePeerId = peerId.toString();
+            let verdict;
             try {
-                return !(await admitWithinDeadline(policy, remotePeerId, decisionTimeoutMs));
+                verdict = await decideWithinDeadline(() => policy.admitInbound(remotePeerId), 'admit', decisionTimeoutMs, `admitInbound(${remotePeerId})`);
             }
             catch (error) {
                 log('admitInbound threw for %s — admitting (fail-open; stream gates decide): %o', remotePeerId, error);
                 return false;
             }
+            if (verdict === 'admit-for-relay') {
+                pendingReservations.arm(remotePeerId, maConn);
+                return false;
+            }
+            return verdict === 'deny';
+        },
+        denyInboundRelayReservation: async (peerId) => {
+            if (await base?.denyInboundRelayReservation?.(peerId)) {
+                return true;
+            }
+            const remotePeerId = peerId.toString();
+            let admitted;
+            try {
+                admitted = await decideWithinDeadline(() => policy.admitRelayReservation(remotePeerId), true, decisionTimeoutMs, `admitRelayReservation(${remotePeerId})`);
+            }
+            catch (error) {
+                log('admitRelayReservation threw for %s — admitting (fail-open): %o', remotePeerId, error);
+                admitted = true;
+            }
+            if (admitted) {
+                pendingReservations.disarm(remotePeerId);
+            }
+            return !admitted;
         }
     };
 }
 /**
- * Run the admission decision under {@link ADMISSION_DECISION_TIMEOUT_MS},
- * resolving to "admit" if it has not settled in time (see that constant for why
- * an unbounded await is not safe here). The timer is always cleared so a decided
- * connection never holds the event loop open.
+ * Run one admission decision under `timeoutMs`, resolving to `fallback` (the
+ * fail-open outcome) if it has not settled in time — see
+ * {@link ADMISSION_DECISION_TIMEOUT_MS} for why an unbounded await is not safe
+ * on the connection hook. The timer is always cleared so a decided call never
+ * holds the event loop open.
  */
-async function admitWithinDeadline(policy, remotePeerId, timeoutMs) {
+async function decideWithinDeadline(decide, fallback, timeoutMs, what) {
     let timer;
     try {
         return await Promise.race([
-            Promise.resolve(policy.admitInbound(remotePeerId)),
+            Promise.resolve().then(decide),
             new Promise((resolve) => {
                 timer = setTimeout(() => {
-                    log('admitInbound exceeded %dms for %s — admitting (fail-open; stream gates decide)', timeoutMs, remotePeerId);
-                    resolve(true);
+                    log('%s exceeded %dms — taking the fail-open outcome (stream gates decide)', what, timeoutMs);
+                    resolve(fallback);
                 }, timeoutMs);
             })
         ]);
@@ -177,4 +397,64 @@ async function admitWithinDeadline(policy, remotePeerId, timeoutMs) {
         clearTimeout(timer);
     }
 }
+/**
+ * The not-reserving deadlines for `'admit-for-relay'` connections, keyed by
+ * remote peerId (a Set per peer — one peer can hold several in-flight
+ * connections). `arm` starts a timer that aborts the connection; `disarm`
+ * (called when a reservation for that peer is admitted) cancels every pending
+ * timer for the peer. Timers are unref'd so an armed deadline never holds a
+ * process open, and a timer that fires against an already-closed connection is
+ * a swallowed no-op.
+ *
+ * Disarming is final for the connections it cancelled: a peer that reserved
+ * once and then lets its reservation lapse keeps a mute connection (the
+ * fail-closed stream gates refuse it every members-only protocol) until either
+ * side closes it. Bounded — only a peer the reservation policy already admitted
+ * can reach that state, so unplaceable peers are bounded by the budget cap.
+ */
+class PendingReserveDeadlines {
+    constructor(deadlineMs) {
+        this.deadlineMs = deadlineMs;
+        this.byPeer = new Map();
+    }
+    arm(remotePeerId, maConn) {
+        const entry = {
+            maConn,
+            timer: setTimeout(() => this.expire(remotePeerId, entry), this.deadlineMs)
+        };
+        entry.timer.unref?.();
+        let entries = this.byPeer.get(remotePeerId);
+        if (!entries) {
+            entries = new Set();
+            this.byPeer.set(remotePeerId, entries);
+        }
+        entries.add(entry);
+        log('Admitted %s for relay only — dropping the connection unless a reservation is admitted within %dms', remotePeerId, this.deadlineMs);
+    }
+    disarm(remotePeerId) {
+        const entries = this.byPeer.get(remotePeerId);
+        if (!entries) {
+            return;
+        }
+        this.byPeer.delete(remotePeerId);
+        for (const entry of entries) {
+            clearTimeout(entry.timer);
+        }
+    }
+    expire(remotePeerId, entry) {
+        const entries = this.byPeer.get(remotePeerId);
+        entries?.delete(entry);
+        if (entries?.size === 0) {
+            this.byPeer.delete(remotePeerId);
+        }
+        log('Relay-only admission expired for %s — no reservation admitted within %dms, aborting the connection', remotePeerId, this.deadlineMs);
+        try {
+            entry.maConn.abort(new Error(`relay-only admission expired: no relay reservation admitted within ${this.deadlineMs}ms`));
+        }
+        catch (error) {
+            // Aborting a connection that already closed on its own is not a failure.
+            log('Aborting the expired relay-only connection from %s threw: %o', remotePeerId, error);
+        }
+    }
+}
 //# sourceMappingURL=membership-connection-gater.js.map

package/dist/membership-connection-gater.js.map

@@ -1 +1 @@
-{"version":3,"file":"membership-connection-gater.js","sourceRoot":"","sources":["../src/membership-connection-gater.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEpE,MAAM,GAAG,GAAG,KAAK,CAAC,+BAA+B,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAE9F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAK,CAAC;AAanD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,+BAA+B,CAC7C,MAA8B,EAC9B,IAAsB,EACtB,oBAA4B,6BAA6B;IAEzD,OAAO;QACL,GAAG,IAAI;QACP,8BAA8B,EAAE,KAAK,EAAE,MAAc,EAAE,MAA2B,EAAoB,EAAE;YACtG,IAAI,MAAM,IAAI,EAAE,8BAA8B,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;gBACjE,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YACvC,IAAI,CAAC;gBACH,OAAO,CAAC,CAAC,MAAM,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC;YAC/E,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,GAAG,CAAC,4EAA4E,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;gBACvG,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,mBAAmB,CAChC,MAA8B,EAC9B,YAAoB,EACpB,SAAiB;IAEjB,IAAI,KAAgD,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC;YACxB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;YAClD,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;gBAC/B,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBACtB,GAAG,CAAC,gFAAgF,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;oBAC/G,OAAO,CAAC,IAAI,CAAC,CAAC;gBAChB,CAAC,EAAE,SAAS,CAAC,CAAC;YAChB,CAAC,CAAC;SACH,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}
+{"version":3,"file":"membership-connection-gater.js","sourceRoot":"","sources":["../src/membership-connection-gater.ts"],"names":[],"mappings":"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"}

package/dist/peer-record.d.ts

@@ -84,6 +84,32 @@ export declare function isSignalingAddr(addr: string): boolean;
  * cannot express that distinction.
  */
 export declare function trailingPeerId(addr: Multiaddr): string | null;
+/**
+ * `addr` guaranteed to terminate in `/p2p/<peerId>` — the shape every dial path
+ * needs — or `null` when it cannot, because the address already terminates in a
+ * DIFFERENT peer id and therefore does not reach `peerId` at all.
+ *
+ * Three input shapes, matching what a `CadrePeer` record can legitimately carry:
+ *
+ * - no `/p2p/` component (`/ip4/1.2.3.4/tcp/4001`) — the suffix is appended;
+ * - a relay hop with the destination missing (`…/p2p/<relay>/p2p-circuit`) — the
+ *   last component is the circuit, not a peer id, so the suffix is appended and
+ *   the address becomes the full `…/p2p/<relay>/p2p-circuit/p2p/<peerId>`;
+ * - already terminating in `/p2p/<X>` — returned untouched when `X` is `peerId`,
+ *   dropped otherwise.
+ *
+ * This is deliberately the same rule libp2p applies internally in
+ * `calculateMultiaddrs` (append when the LAST component is not `p2p`) followed by
+ * its wrong-peer-id filter, so a normalized list matches what libp2p would have
+ * built anyway. Normalizing before the dial is what keeps a list from mixing
+ * suffixed and unsuffixed entries, which `getPeerAddress` rejects outright
+ * ("Multiaddrs must all have the same peer id or have no peer id") — taking the
+ * whole peer down with it, not just the odd address.
+ *
+ * Never use before signature verification: verification runs against the
+ * original on-record strings.
+ */
+export declare function withTrailingPeerId(addr: Multiaddr, peerId: string): Multiaddr | null;
 /**
  * Return `addrs` with signaling (`/p2p-circuit`) addrs first, otherwise stable.
  * Used to present the WebRTC dial input ahead of direct addrs. Does NOT mutate

package/dist/peer-record.js

@@ -104,6 +104,38 @@ export function trailingPeerId(addr) {
     const p2p = addr.getComponents().filter((c) => c.name === 'p2p');
     return p2p.length > 0 ? (p2p[p2p.length - 1].value ?? null) : null;
 }
+/**
+ * `addr` guaranteed to terminate in `/p2p/<peerId>` — the shape every dial path
+ * needs — or `null` when it cannot, because the address already terminates in a
+ * DIFFERENT peer id and therefore does not reach `peerId` at all.
+ *
+ * Three input shapes, matching what a `CadrePeer` record can legitimately carry:
+ *
+ * - no `/p2p/` component (`/ip4/1.2.3.4/tcp/4001`) — the suffix is appended;
+ * - a relay hop with the destination missing (`…/p2p/<relay>/p2p-circuit`) — the
+ *   last component is the circuit, not a peer id, so the suffix is appended and
+ *   the address becomes the full `…/p2p/<relay>/p2p-circuit/p2p/<peerId>`;
+ * - already terminating in `/p2p/<X>` — returned untouched when `X` is `peerId`,
+ *   dropped otherwise.
+ *
+ * This is deliberately the same rule libp2p applies internally in
+ * `calculateMultiaddrs` (append when the LAST component is not `p2p`) followed by
+ * its wrong-peer-id filter, so a normalized list matches what libp2p would have
+ * built anyway. Normalizing before the dial is what keeps a list from mixing
+ * suffixed and unsuffixed entries, which `getPeerAddress` rejects outright
+ * ("Multiaddrs must all have the same peer id or have no peer id") — taking the
+ * whole peer down with it, not just the odd address.
+ *
+ * Never use before signature verification: verification runs against the
+ * original on-record strings.
+ */
+export function withTrailingPeerId(addr, peerId) {
+    const components = addr.getComponents();
+    if (components[components.length - 1]?.name !== 'p2p') {
+        return addr.encapsulate(`/p2p/${peerId}`);
+    }
+    return trailingPeerId(addr) === peerId ? addr : null;
+}
 /**
  * Return `addrs` with signaling (`/p2p-circuit`) addrs first, otherwise stable.
  * Used to present the WebRTC dial input ahead of direct addrs. Does NOT mutate

package/dist/peer-record.js.map

@@ -1 +1 @@
-{"version":3,"file":"peer-record.js","sourceRoot":"","sources":["../src/peer-record.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"peer-record.js","sourceRoot":"","sources":["../src/peer-record.ts"],"names":[],"mappings":"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"}

package/dist/relay-addrs.d.ts

@@ -1,29 +1,59 @@
 /**
  * Translate `network.relayAddrs` — the operator-facing "use these relay servers"
- * setting — into the mechanism this repo already has for reserving a circuit-relay
- * slot: a `…/p2p/<relayPeerId>/p2p-circuit` entry in the node's listen addrs.
- *
- * `@libp2p/circuit-relay-v2`'s transport is always present on the Node path
- * (`../optimystic/packages/db-p2p/src/libp2p-node.ts` pushes `circuitRelayTransport()`
- * unconditionally), and listening on a relay's circuit addr is what makes libp2p dial
- * that relay and hold a reservation. Everything downstream of the listen list —
- * the reservation itself, `CadreNode.circuitRelayTargets()` picking delegate-announce
- * targets, strand nodes inheriting the listen addrs, the `/p2p-circuit`-first address
- * publishing in `registerSelf` — then works unchanged.
- *
- * So `relayAddrs` is a second, friendlier door onto an existing mechanism:
- *
- *   effective listen addrs = listenAddrs ++ relayAddrs.map(a => a + '/p2p-circuit')
- *
- * NOTE: this is the FAIL-FAST route to a reservation — libp2p's transport manager
- * throws when a configured circuit listener cannot listen, so naming a relay that
- * is down means the node does not start. The fail-soft route is the bare
- * `/p2p-circuit` search listener driven by `relay-reservation.ts`. The two are
- * ALTERNATIVES, not layers: configuring `relayAddrs` on a node that already
- * reserves via the search listener adds the fatal listener back and the node
- * stops booting when its relay is down.
+ * setting — into the listen entry a node needs before it can hold a circuit-relay
+ * slot, and validate the operator's entries while doing it.
+ *
+ * `@libp2p/circuit-relay-v2`'s listener branches on the SHAPE of the listen addr,
+ * and the same `relayAddrs` list resolves to either shape depending on WHO is
+ * listening ({@link RelayListenRoute}):
+ *
+ * | route          | listen entry                                | libp2p behaviour                                          |
+ * | -------------- | ------------------------------------------- | --------------------------------------------------------- |
+ * | `'configured'` | `<relayAddr>/p2p-circuit`, one per relay      | dial that relay from inside `listen()` and reserve, or throw |
+ * | `'search'`     | a single bare `/p2p-circuit`                  | register a pending reservation; open no connection          |
+ *
+ * The CONTROL node takes the `'search'` route, and `CadreNode.start()` drives the
+ * reservation explicitly (`relay-reservation.ts`) once the control database is up.
+ * That ordering is the point: a configured circuit listener dials the relay from
+ * inside `libp2p.start()`, so the control database was being built while a sibling
+ * relay was already in this node's cohort — and a sibling that has not yet
+ * replicated this node's `CadrePeer` row correctly refuses its control-DB streams,
+ * which killed `start()` outright. See `cadre-node.ts` → `start()`.
+ *
+ * STRAND nodes keep the `'configured'` route (`strand-instance-manager.ts`): they
+ * inherit the control node's `NetworkConfig`, nothing drives an explicit
+ * reservation for them, and their relay connection cannot disturb a control-DB
+ * bring-up (a strand node's protocol ids are namespaced `/optimystic/strand-<id>/…`,
+ * so the relay is never in its cohort).
+ *
+ * `network.relayAddrs` is FAIL-FAST for the operator on both routes, just from
+ * different places: a malformed entry throws here at config resolution, and on the
+ * control node a first reservation attempt that does not land throws out of
+ * `start()` (`RelayReservationFailedError`). Naming a relay that is down still
+ * means the node does not come up.
+ *
+ * The bare `/p2p-circuit` search listener cannot open a connection on its own:
+ * libp2p fills a pending reservation from `RelayDiscovery`, which nominates a peer
+ * only once the relay-hop protocol id is in that peer's peer-store protocol list,
+ * and that list is written exclusively by IDENTIFY — which `@optimystic/db-p2p`
+ * namespaces per network, so a cadre node and a stock relay never identify each
+ * other. See `relay-reservation.ts`'s module doc and `docs/architecture.md`.
  */
 import type { NetworkConfig } from './types.js';
+import type { RelayReservationState } from './relay-reservation.js';
+/**
+ * libp2p's relay SEARCH listener: registers one pending reservation and dials
+ * nothing. One entry covers every configured relay — the pending reservation is
+ * per-listener, not per-relay, and `relay-reservation.ts` fills it with whichever
+ * relay answers first.
+ */
+export declare const RELAY_SEARCH_LISTEN_ADDR = "/p2p-circuit";
+/**
+ * Which listener shape `network.relayAddrs` resolves to for this caller — see the
+ * table in the module doc. Defaults to `'configured'` everywhere except the
+ * control node's own libp2p options.
+ */
+export type RelayListenRoute = 'configured' | 'search';
 /**
  * The circuit-listen multiaddr for each configured relay: `<relayAddr>/p2p-circuit`.
  * An entry that already carries `/p2p-circuit` is passed through unchanged.
@@ -38,8 +68,28 @@ import type { NetworkConfig } from './types.js';
 export declare function relayCircuitAddrs(relayAddrs: readonly string[]): string[];
 /**
  * The listen multiaddrs a node actually binds: configured `listenAddrs` plus the
- * circuit-listen addr of every configured relay, deduplicated, order-stable
- * (configured entries first). Returns `undefined` when neither field is set, so
- * callers keep omitting `listenAddrs` and inherit db-p2p's default.
+ * relay listen entry `route` calls for, deduplicated, order-stable (configured
+ * entries first). Returns `undefined` when neither field is set, so callers keep
+ * omitting `listenAddrs` and inherit db-p2p's default.
+ *
+ * Every `relayAddrs` entry is validated on BOTH routes — the `'search'` route
+ * discards the resolved circuit addrs, but an operator typo must fail at config
+ * resolution either way.
+ */
+export declare function resolveListenAddrs(network: NetworkConfig | undefined, route?: RelayListenRoute): string[] | undefined;
+/**
+ * Thrown out of `CadreNode.start()` when the boot-path reservation drive for
+ * `network.relayAddrs` produces no `/p2p-circuit` address on its FIRST attempt.
+ *
+ * This is what keeps `network.relayAddrs` fail-fast now that the control node
+ * takes the `'search'` route: libp2p's own `UnsupportedListenAddressesError` used
+ * to abort start from inside `listen()`, and an operator who names a relay is
+ * telling the node it has no other reachability — coming up undialable is worse
+ * than not coming up. Names the relays and the reservation's own reason, both of
+ * which the libp2p error omitted.
  */
-export declare function resolveListenAddrs(network: NetworkConfig | undefined): string[] | undefined;
+export declare class RelayReservationFailedError extends Error {
+    readonly relayAddrs: readonly string[];
+    readonly state: RelayReservationState;
+    constructor(relayAddrs: readonly string[], state: RelayReservationState);
+}