@cello-protocol/daemon 0.0.54 → 0.0.56

package/dist/session-node-manager.js

@@ -35,7 +35,8 @@ import { CELLO_CONTENT_PROTOCOL_ID, NodeAutoNatService } from "@cello-protocol/t
 import { verify } from "@cello-protocol/crypto";
 import { encodeSealPayload, MONIKER_RE, validateMoniker } from "@cello-protocol/protocol-types";
 import { decodeParkEnvelope, authenticateParkedEntry, pubkeyMatchesHex } from "./park-envelope.js";
-import { AgentRelayClient, LEAF_KIND_CTRL } from "./session-relay-client.js";
+import { isValidMultiaddr } from "@cello-protocol/transport";
+import { AgentRelayClient, LEAF_KIND_CTRL, extractErrorMessage } from "./session-relay-client.js";
 import { RelayReceiptStore } from "./relay-receipt-store.js";
 import { SessionSealLeafStore } from "./session-seal-leaf-store.js";
 import { PassthroughGatewayClient, GATEWAY_UNAVAILABLE, GOVERNANCE_TIMEOUT, } from "@cello-protocol/gateway";
@@ -87,6 +88,8 @@ export class SessionNodeManager {
     #agentsWantingReceiver = new Set();
     // M8B F14: standing-receiver create retry schedule (see constructor opts).
     #srRetryDelaysMs;
+    /** DOD-NAT-REACHABILITY-1: reservation deadline — see #startReceiverNode. */
+    #srReservationTimeoutMs;
     // Agents whose removeStandingReceiverForAgent ran while an #ensureStandingReceiver for them was
     // in flight (parked on createNode/start, so the map had no entry to delete yet). The in-flight
     // ensure checks this after start() and tears the fresh node down instead of installing an SR for
@@ -200,6 +203,7 @@ export class SessionNodeManager {
         }
         this.#autoNatProbers = opts.autoNatProbers ?? (() => []);
         this.#srRetryDelaysMs = opts.standingReceiverRetryDelaysMs ?? [1_000, 5_000, 15_000];
+        this.#srReservationTimeoutMs = opts.standingReceiverReservationTimeoutMs ?? 8_000;
         this.#securityGateway = opts.securityGateway ?? new PassthroughGatewayClient();
     }
     /**
@@ -2455,6 +2459,15 @@ export class SessionNodeManager {
         if (addrs.length === 0) {
             return { ok: false, reason: "no_counterparty_addrs", error: "the assignment carried no counterparty session addrs to dial" };
         }
+        // DOD-NAT-REACHABILITY-1: a /p2p-circuit counterparty address is dialed
+        // THROUGH its relay, so the gater must admit that relay peer OUTBOUND. The
+        // relay id is embedded in the address, which arrived inside the FROST-signed
+        // assignment — the same authorization rail as the assigned witness relay.
+        for (const addr of addrs) {
+            const viaRelay = addr.match(/\/p2p\/([^/]+)\/p2p-circuit/);
+            if (viaRelay)
+                entry.gater.setAllowedOutboundPeer(viaRelay[1]);
+        }
         let lastError = "";
         for (const addr of addrs) {
             try {
@@ -2467,8 +2480,11 @@ export class SessionNodeManager {
                 return { ok: true };
             }
             catch (err) {
-                // error.message extracted — never [object Object]; try the next addr.
-                lastError = err instanceof Error ? err.message : String(err);
+                // extractErrorMessage handles the transport's structured plain-object
+                // throws (dial() never throws Error instances) — the old
+                // `instanceof Error` idiom logged "[object Object]" on every dial
+                // failure; try the next addr.
+                lastError = extractErrorMessage(err);
             }
         }
         this.#logger.warn("session.transport.connect.failed", {
@@ -3871,6 +3887,197 @@ export class SessionNodeManager {
             this.#standingReceiverCreating.delete(agentName);
         }
     }
+    /**
+     * DOD-NAT-REACHABILITY-1 (Phase 2): relay endpoints the DIRECTORY handed this
+     * agent at signaling-auth time — the freshest, health-filtered view of the
+     * relay pool, and the only source a FRESH agent (no session history) has.
+     */
+    #directoryRelayEndpoints = new Map();
+    /**
+     * DOD-NAT-REACHABILITY-1 (Phase 2): accept the directory's relay-pool endpoints
+     * for an agent (arrives with signaling_auth_ok, i.e. on every connect AND every
+     * reconnect). If the agent's standing receiver is up but holds NO reservation —
+     * the agent-online ensure raced ahead of auth_ok, or every relay was down at
+     * create time — rebuild it now so the agent becomes dialable without waiting
+     * for a session handoff that (being unreachable) would never come.
+     */
+    setDirectoryRelayEndpoints(agentName, endpoints) {
+        this.#directoryRelayEndpoints.set(agentName, endpoints);
+        if (endpoints.length === 0 || this.#shuttingDown)
+            return;
+        const sr = this.#standingReceivers.get(agentName);
+        if (!sr)
+            return; // not ensured yet — the coming ensure reads the map
+        if (sr.node.listenAddresses().some((a) => a.includes("/p2p-circuit")))
+            return; // already reserved
+        this.#logger.info("session.standing_receiver.reservation.rebuild", {
+            agentName,
+            relayPeerIds: endpoints.map((e) => e.relayPeerId),
+        });
+        void this.#rebuildStandingReceiver(agentName);
+    }
+    /**
+     * Replace an agent's reservation-less standing receiver with one that reserves.
+     *
+     * Deliberately NOT removeStandingReceiverForAgent()+ensureStandingReceiverForAgent():
+     * the public remove CLEARS #agentsWantingReceiver, so a cello_stop_agent landing in
+     * the window while node.stop() is awaited would find no map entry and no creating
+     * marker, leave no tombstone, and the re-ensure would then RESURRECT a receiver for
+     * an agent that asked to go dark — accepting inbound sessions for an offline agent.
+     * Here the want-flag is left intact and re-checked after the stop: a concurrent stop
+     * clears it, and the rebuild correctly no-ops.
+     */
+    async #rebuildStandingReceiver(agentName) {
+        try {
+            const sr = this.#standingReceivers.get(agentName);
+            if (sr) {
+                this.#standingReceivers.delete(agentName);
+                try {
+                    sr.autoNat.stop();
+                    await sr.node.stop();
+                }
+                catch (err) {
+                    this.#logger.warn("session.standing_receiver.teardown.failed", {
+                        agentName,
+                        error: extractErrorMessage(err),
+                    });
+                }
+            }
+            // The agent may have gone offline while we were stopping the old node. Its
+            // want-flag is the authority — never resurrect a receiver it disowned.
+            if (!this.#agentsWantingReceiver.has(agentName) || this.#shuttingDown)
+                return;
+            await this.#ensureStandingReceiver(agentName);
+        }
+        catch (err) {
+            this.#logger.warn("session.standing_receiver.reservation.rebuild.failed", {
+                agentName,
+                error: extractErrorMessage(err),
+            });
+        }
+    }
+    /**
+     * DOD-NAT-REACHABILITY-1: circuit-relay listen addresses for an agent's known
+     * relays, so its standing receiver takes reservations and becomes dialable
+     * behind NAT. Sources, merged and deduped by relay peer id: the directory's
+     * auth-time relay pool (freshest — first), then the persisted relay endpoints
+     * of past sessions (getAgentRelayEndpoints — covers a directory that predates
+     * the auth_ok extension).
+     */
+    #reservationCircuitAddrs(agentName) {
+        let persisted;
+        try {
+            persisted = this.getAgentRelayEndpoints(agentName);
+        }
+        catch (err) {
+            // No DB / unknown agent — persisted source unavailable. The directory
+            // source may still serve; reachability degrades only if both are empty.
+            // Logged (not swallowed): a genuine DB failure must be distinguishable
+            // from "fresh agent, no history" in the reachability trail.
+            this.#logger.debug("session.standing_receiver.persisted_relays.unavailable", {
+                agentName,
+                error: extractErrorMessage(err),
+            });
+            persisted = [];
+        }
+        const merged = new Map();
+        for (const ep of [...(this.#directoryRelayEndpoints.get(agentName) ?? []), ...persisted]) {
+            if (!merged.has(ep.relayPeerId))
+                merged.set(ep.relayPeerId, ep);
+        }
+        const addrs = [];
+        const relayPeerIds = [];
+        for (const ep of merged.values()) {
+            const base = ep.relayAddrs[0];
+            if (!base)
+                continue;
+            const candidate = base.includes("/p2p/")
+                ? `${base}/p2p-circuit`
+                : `${base}/p2p/${ep.relayPeerId}/p2p-circuit`;
+            // These addresses are built from DIRECTORY-supplied endpoints — data from off
+            // this machine. A malformed one throws inside libp2p node construction, which
+            // would take the standing receiver down entirely and leave the agent deaf to
+            // ALL inbound (worse than the defect this fixes). A bad endpoint must cost one
+            // relay, never the receiver.
+            if (!isValidMultiaddr(candidate)) {
+                this.#logger.warn("session.standing_receiver.relay_endpoint.invalid", {
+                    agentName,
+                    relayPeerId: ep.relayPeerId,
+                    addr: candidate,
+                });
+                continue;
+            }
+            addrs.push(candidate);
+            relayPeerIds.push(ep.relayPeerId);
+        }
+        return { addrs, relayPeerIds };
+    }
+    /**
+     * Start the standing receiver's libp2p node, with reservations if they can be had
+     * QUICKLY, and without them if they cannot.
+     *
+     * THE INVARIANT — learned the hard way, live: **standing-receiver creation must
+     * NEVER be gated on relay reachability.** libp2p's circuit listener awaits a live
+     * connection to each relay before start() resolves, and it does not time out. Put
+     * three relays in the initial listen set, have one of them not answer from this
+     * network, and start() hangs FOREVER: no created event, no failure, no retry, no
+     * alarm — the agent simply has no receiver and is deaf to ALL inbound, including
+     * the direct path that worked before reservations existed. That is strictly worse
+     * than the NAT defect this whole line exists to fix.
+     *
+     * So the reservation attempt is RACED against a deadline. If it wins, we get a
+     * node that is both directly dialable and reachable through the relays. If it does
+     * not, we fall back to a plain TCP receiver — the agent is reachable on the direct
+     * path immediately — and the standing receiver is rebuilt with reservations later,
+     * when the directory next hands us endpoints (setDirectoryRelayEndpoints → the
+     * rebuild-if-deaf path). Degraded, loud, and never deaf.
+     */
+    async #startReceiverNode(agentName, sessionId, gater, circuitAddrs, correlationId) {
+        if (circuitAddrs.length > 0) {
+            const withReservations = await this.#factory.createNode({
+                sessionId,
+                connectionGater: gater,
+                nodeType: "standing_receiver",
+                circuitRelayListenAddrs: circuitAddrs,
+            });
+            let timer;
+            const timedOut = Symbol("reservation_timeout");
+            try {
+                const outcome = await Promise.race([
+                    withReservations.start().then(() => "started"),
+                    new Promise((resolve) => {
+                        timer = setTimeout(() => resolve(timedOut), this.#srReservationTimeoutMs);
+                    }),
+                ]);
+                if (outcome === "started")
+                    return withReservations;
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+            // The deadline passed with start() still pending — at least one relay is not
+            // answering. Abandon this node (its start may still be parked on a dial; stop()
+            // is best-effort and must not itself block the fallback) and come up TCP-only.
+            this.#logger.warn("session.standing_receiver.reservation.timeout", {
+                agentName,
+                relayCount: circuitAddrs.length,
+                timeoutMs: this.#srReservationTimeoutMs,
+                reason: "at_least_one_relay_did_not_answer_in_time",
+                correlationId,
+            });
+            void Promise.resolve()
+                .then(() => withReservations.stop())
+                .catch(() => { });
+        }
+        const plain = await this.#factory.createNode({
+            sessionId,
+            connectionGater: gater,
+            nodeType: "standing_receiver",
+        });
+        await plain.start();
+        return plain;
+    }
     /** One standing-receiver create attempt (extracted for the M8B F14 retry loop). */
     async #tryCreateStandingReceiver(agentName, correlationId) {
         const sessionId = `standing_receiver_${randomUUID()}`;
@@ -3879,13 +4086,23 @@ export class SessionNodeManager {
             allowedPeerId: null, // open — counterparty unknown at creation time
             logger: this.#logger,
         });
+        // DOD-NAT-REACHABILITY-1: reserve with the agent's known relays. The relay
+        // peers are allowed OUTBOUND on the gater up front, so reservation refreshes
+        // keep working after the receiver is claimed and setAllowedPeer() narrows
+        // the inbound gate to the session counterparty.
+        const reservations = this.#reservationCircuitAddrs(agentName);
+        for (const relayPeerId of reservations.relayPeerIds) {
+            gater.setAllowedOutboundPeer(relayPeerId);
+        }
         let node;
         try {
-            node = await this.#factory.createNode({ sessionId, connectionGater: gater, nodeType: "standing_receiver" });
-            await node.start();
+            node = await this.#startReceiverNode(agentName, sessionId, gater, reservations.addrs, correlationId);
         }
         catch (err) {
-            const error = err instanceof Error ? err.message : String(err);
+            // extractErrorMessage, NOT String(err): the transport throws structured
+            // plain objects ({ reason, message }), and String() destroys both into
+            // "[object Object]" — the loud failure must carry its cause.
+            const error = extractErrorMessage(err);
             this.#logger.error("session.node.create.failed", {
                 sessionId,
                 agentName: `${STANDING_RECEIVER_AGENT_NAME}:${agentName}`,
@@ -3931,6 +4148,25 @@ export class SessionNodeManager {
             sessionPeerId: node.getPeerId(),
             correlationId,
         });
+        // DOD-NAT-REACHABILITY-1 observability: how reachable did this receiver come
+        // up? circuitAddrs === 0 with reservations requested means every relay
+        // refused/was unreachable — the agent is deaf to NAT'd initiators (public
+        // ones can still connect directly). That must be LOUD, not a quiet shrug.
+        const circuitAddrs = node.listenAddresses().filter((a) => a.includes("/p2p-circuit")).length;
+        this.#logger.info("session.standing_receiver.reachability", {
+            agentName,
+            circuitAddrs,
+            reservationsRequested: reservations.addrs.length,
+            correlationId,
+        });
+        if (reservations.addrs.length > 0 && circuitAddrs === 0) {
+            this.#logger.warn("session.standing_receiver.reservation.none", {
+                agentName,
+                reservationsRequested: reservations.addrs.length,
+                relayPeerIds: reservations.relayPeerIds,
+                correlationId,
+            });
+        }
         return { outcome: "installed" };
     }
     /**
@@ -3946,6 +4182,10 @@ export class SessionNodeManager {
     async removeStandingReceiverForAgent(agentName) {
         // M8B F14: the agent no longer wants a receiver — disarm the teardown re-arm.
         this.#agentsWantingReceiver.delete(agentName);
+        // The directory hands these out at signaling-auth time, so a re-started agent
+        // gets a fresh set on its next connect — holding the old ones would keep a
+        // retired agent's relay list alive for the daemon's lifetime.
+        this.#directoryRelayEndpoints.delete(agentName);
         const sr = this.#standingReceivers.get(agentName);
         if (!sr) {
             // L1: an #ensureStandingReceiver for this agent may be in flight (parked on start(), so no