@aria-cli/wireguard 1.0.37 → 1.0.38

package/dist/peer-discovery.js

@@ -1,486 +0,0 @@
-"use strict";
-/**
- * PeerDiscoveryService — periodic peer discovery via coordination server.
- *
- * Polls the coordination server every 60s, diffs against local PeerRegistry,
- * refreshes remote endpoints for known peers, and auto-starts/stops tunnels for
- * new/disappeared peers. Emits events for peer join/leave so higher-level systems
- * can react.
- *
- * Architecture:
- *   PeerDiscoveryService → POST /api/v1/network/peers → diff local →
- *   applyPeerRepair/startTunnel/stopTunnel
- *   STUN refreshes OUR endpoint. Peer discovery refreshes REMOTE peer endpoints.
- *
- * Limitation: The coordination server is a peer's ARIA HTTP server, NOT an
- * independent highly-available service. If the coordination server peer goes
- * offline, discovery stops for the entire mesh. For production meshes (>10 peers),
- * deploy a dedicated coordination service at the coordinationUrl.
- *
- * Discovery only auto-connects peers that have completed the invite flow (PSK
- * exchange). Unknown peers emit "peerDiscoveredUnknown" for the daemon to handle.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PeerDiscoveryService = void 0;
-const node_events_1 = require("node:events");
-const tools_1 = require("@aria-cli/tools");
-const bootstrap_tls_js_1 = require("./bootstrap-tls.js");
-/**
- * Periodic peer discovery service.
- *
- * Polls coordination server, diffs against local state, auto-manages tunnels.
- * Emits: "peerJoined" (displayNameSnapshot|nodeId, nodeId), "peerLeft" (displayNameSnapshot|nodeId, nodeId), "error" (Error)
- */
-class PeerDiscoveryService extends node_events_1.EventEmitter {
-    interval = null;
-    networkManager;
-    nodeId;
-    coordinationUrl;
-    displayNameSnapshot;
-    signal;
-    pollIntervalMs;
-    maxPeers;
-    signingPublicKey;
-    signingPrivateKey;
-    envelopeSigner;
-    coordinationCaCert;
-    coordinationTlsIdentity;
-    getLocalRegistrationState;
-    /** Track known remote peers by durable peer principal for diff */
-    knownRemotePeers = new Map();
-    pollInFlight = null;
-    initialSyncPromise;
-    resolveInitialSync = null;
-    initialSyncSettled = false;
-    stopped = false;
-    constructor(options) {
-        super();
-        this.networkManager = options.networkManager;
-        this.nodeId = options.nodeId;
-        this.coordinationUrl = options.coordinationUrl.replace(/\/$/, "");
-        this.displayNameSnapshot = options.displayNameSnapshot;
-        this.signal = options.signal;
-        this.pollIntervalMs = options.pollIntervalMs ?? 60_000;
-        this.maxPeers = options.maxPeers ?? 128;
-        this.signingPublicKey = options.signingPublicKey;
-        this.signingPrivateKey = options.signingPrivateKey;
-        this.envelopeSigner = options.envelopeSigner;
-        this.coordinationCaCert = options.coordinationCaCert?.trim() || undefined;
-        this.coordinationTlsIdentity = options.coordinationTlsIdentity?.trim() || undefined;
-        this.getLocalRegistrationState = options.getLocalRegistrationState;
-        if (!this.envelopeSigner) {
-            throw new Error("Peer discovery requires an envelope signer");
-        }
-        this.initialSyncPromise = new Promise((resolve) => {
-            this.resolveInitialSync = () => {
-                if (this.initialSyncSettled)
-                    return;
-                this.initialSyncSettled = true;
-                resolve();
-            };
-        });
-        if (!this.signingPublicKey || !this.signingPrivateKey) {
-            throw new Error("Peer discovery requires Ed25519 signing keys (signingPublicKey + signingPrivateKey)");
-        }
-        if ((this.coordinationCaCert && !this.coordinationTlsIdentity) ||
-            (!this.coordinationCaCert && this.coordinationTlsIdentity)) {
-            throw new Error("Peer discovery HTTPS pinning requires both coordinationCaCert and coordinationTlsIdentity");
-        }
-        // Wire abort signal for clean shutdown
-        if (this.signal) {
-            this.signal.addEventListener("abort", () => this.stop(), { once: true });
-        }
-    }
-    /** Start periodic peer discovery */
-    start() {
-        if (this.interval || this.stopped)
-            return;
-        // Initial discovery + heartbeat
-        this.schedulePoll();
-        this.interval = setInterval(() => {
-            if (this.stopped || this.signal?.aborted) {
-                this.stop();
-                return;
-            }
-            this.schedulePoll();
-        }, this.pollIntervalMs);
-    }
-    /** Resolve once the first discovery poll attempt finishes (success or failure). */
-    waitForInitialSync() {
-        return this.initialSyncPromise;
-    }
-    /** Stop periodic discovery */
-    stop() {
-        this.stopped = true;
-        if (this.interval) {
-            clearInterval(this.interval);
-            this.interval = null;
-        }
-        this.resolveInitialSync?.();
-    }
-    schedulePoll() {
-        if (this.pollInFlight)
-            return;
-        this.pollInFlight = this.poll()
-            .catch((err) => this.reportError(err instanceof Error ? err : new Error(String(err))))
-            .finally(() => {
-            this.pollInFlight = null;
-            this.resolveInitialSync?.();
-        });
-    }
-    reportError(err) {
-        if (this.listenerCount("error") > 0) {
-            this.emit("error", err);
-        }
-    }
-    peerEndpointRevision(peer) {
-        if (typeof peer.endpointRevision === "number" && Number.isInteger(peer.endpointRevision)) {
-            return peer.endpointRevision;
-        }
-        return null;
-    }
-    peerFreshness(peer) {
-        const candidates = [
-            typeof peer.updatedAt === "number" && Number.isFinite(peer.updatedAt) ? peer.updatedAt : null,
-            typeof peer.lastHandshake === "number" && Number.isFinite(peer.lastHandshake)
-                ? peer.lastHandshake
-                : null,
-            typeof peer.createdAt === "number" && Number.isFinite(peer.createdAt) ? peer.createdAt : null,
-        ].filter((value) => value !== null);
-        return candidates.length > 0 ? Math.max(...candidates) : null;
-    }
-    classifyRepairOutcome(peer) {
-        const repairInput = this.repairInputForPeer(peer);
-        if (repairInput === null) {
-            return "ok";
-        }
-        if (repairInput === false) {
-            return "blocked";
-        }
-        const repair = this.networkManager.applyPeerRepair(repairInput);
-        if (repair.repaired) {
-            return "ok";
-        }
-        if ("errorCode" in repair && repair.errorCode === "not_found") {
-            return "unknown";
-        }
-        return "blocked";
-    }
-    repairInputForPeer(peer) {
-        if (peer.endpointHost === null && peer.endpointPort === null) {
-            return null;
-        }
-        if (typeof peer.endpointHost !== "string" ||
-            typeof peer.endpointPort !== "number" ||
-            !Number.isInteger(peer.endpointPort) ||
-            peer.endpointPort < 1 ||
-            peer.endpointPort > 65_535 ||
-            typeof peer.endpointRevision !== "number" ||
-            !Number.isInteger(peer.endpointRevision) ||
-            peer.endpointRevision < 0) {
-            return false;
-        }
-        return {
-            nodeId: peer.nodeId,
-            endpointHost: peer.endpointHost,
-            endpointPort: peer.endpointPort,
-            endpointRevision: peer.endpointRevision,
-        };
-    }
-    async postControlPlane(path, payload) {
-        const url = `${this.coordinationUrl}${path}`;
-        const body = JSON.stringify(payload);
-        if (url.startsWith("https://") && this.coordinationCaCert && this.coordinationTlsIdentity) {
-            return (0, bootstrap_tls_js_1.bootstrapTlsRequest)(url, {
-                method: "POST",
-                body,
-                caCert: this.coordinationCaCert,
-                expectedTlsIdentity: this.coordinationTlsIdentity,
-                timeoutMs: 10_000,
-                headers: {
-                    "Content-Type": "application/json",
-                    "Content-Length": Buffer.byteLength(body).toString(),
-                },
-            });
-        }
-        const response = await fetch(url, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body,
-            signal: AbortSignal.timeout(10_000),
-        });
-        let responseBody = "";
-        if (typeof response.text === "function") {
-            responseBody = await response.text();
-        }
-        else if (typeof response.json === "function") {
-            responseBody = JSON.stringify(await response.json());
-        }
-        return {
-            status: response.status,
-            body: responseBody,
-        };
-    }
-    /** Force an immediate heartbeat to the coordination server */
-    async heartbeat() {
-        const localRegistration = this.getLocalRegistrationState?.() ?? undefined;
-        const body = {
-            nodeId: this.nodeId,
-            displayNameSnapshot: this.displayNameSnapshot,
-        };
-        const envelopePayload = {
-            nodeId: this.nodeId,
-            displayNameSnapshot: this.displayNameSnapshot,
-        };
-        if (localRegistration?.endpointHost &&
-            typeof localRegistration.endpointPort === "number" &&
-            Number.isInteger(localRegistration.endpointPort)) {
-            body.endpointHost = localRegistration.endpointHost;
-            body.endpointPort = localRegistration.endpointPort;
-            envelopePayload.endpointHost = localRegistration.endpointHost;
-            envelopePayload.endpointPort = localRegistration.endpointPort;
-            body.endpointRevision = localRegistration.endpointRevision ?? 0;
-            envelopePayload.endpointRevision = localRegistration.endpointRevision ?? 0;
-        }
-        body.envelope = this.envelopeSigner("network.register", envelopePayload);
-        const response = await this.postControlPlane("/api/v1/network/register", body);
-        if (response.status < 200 || response.status >= 300) {
-            throw new Error(`Peer discovery heartbeat failed: HTTP ${response.status}`);
-        }
-    }
-    parseDiscoveredPeer(value) {
-        if (!value || typeof value !== "object")
-            return null;
-        const peer = value;
-        const parsedNodeId = tools_1.NodeIdSchema.safeParse(peer.nodeId);
-        const parsedStatus = tools_1.LegacyPeerRegistryStatusSchema.safeParse(peer.status);
-        const transportPublicKey = typeof peer.transportPublicKey === "string" && peer.transportPublicKey.length > 0
-            ? tools_1.PeerTransportIdSchema.parse(peer.transportPublicKey)
-            : null;
-        const displayNameSnapshot = typeof peer.displayNameSnapshot === "string" ? peer.displayNameSnapshot : undefined;
-        const endpointHost = peer.endpointHost === null ? null : peer.endpointHost;
-        const endpointPort = peer.endpointPort === null ? null : peer.endpointPort;
-        const endpointRevision = typeof peer.endpointRevision === "number" ? peer.endpointRevision : undefined;
-        const updatedAt = typeof peer.updatedAt === "number" ? peer.updatedAt : undefined;
-        const lastHandshake = peer.lastHandshake === null || typeof peer.lastHandshake === "number"
-            ? peer.lastHandshake
-            : undefined;
-        const createdAt = typeof peer.createdAt === "number" ? peer.createdAt : undefined;
-        const displayNameOk = displayNameSnapshot === undefined || displayNameSnapshot.length > 0;
-        const endpointHostOk = endpointHost === null ||
-            (typeof endpointHost === "string" &&
-                endpointHost.length > 0 &&
-                endpointHost.length <= 253 &&
-                /^[a-zA-Z0-9._:-]+$/.test(endpointHost));
-        const endpointPortOk = endpointPort === null ||
-            (typeof endpointPort === "number" &&
-                Number.isInteger(endpointPort) &&
-                endpointPort >= 1 &&
-                endpointPort <= 65535);
-        const endpointRevisionRequired = endpointHost !== null &&
-            endpointPort !== null &&
-            parsedStatus.success &&
-            parsedStatus.data !== "revoked";
-        const endpointRevisionOk = (!endpointRevisionRequired && endpointRevision === undefined) ||
-            (typeof endpointRevision === "number" &&
-                Number.isInteger(endpointRevision) &&
-                endpointRevision >= 0);
-        const endpointMutationComplete = (endpointHost === null && endpointPort === null && endpointRevision === undefined) ||
-            (typeof endpointHost === "string" &&
-                typeof endpointPort === "number" &&
-                typeof endpointRevision === "number");
-        const lastHandshakeOk = peer.lastHandshake === undefined ||
-            lastHandshake === null ||
-            (typeof lastHandshake === "number" && Number.isFinite(lastHandshake));
-        const updatedAtOk = peer.updatedAt === undefined || (typeof updatedAt === "number" && Number.isFinite(updatedAt));
-        const createdAtOk = peer.createdAt === undefined || (typeof createdAt === "number" && Number.isFinite(createdAt));
-        if (!parsedNodeId.success ||
-            !transportPublicKey ||
-            !parsedStatus.success ||
-            !displayNameOk ||
-            !endpointHostOk ||
-            !endpointPortOk ||
-            !endpointRevisionOk ||
-            !updatedAtOk ||
-            !endpointMutationComplete ||
-            !lastHandshakeOk ||
-            !createdAtOk) {
-            return null;
-        }
-        return {
-            nodeId: parsedNodeId.data,
-            transportPublicKey,
-            ...(displayNameSnapshot ? { displayNameSnapshot } : {}),
-            status: parsedStatus.data,
-            endpointHost,
-            endpointPort,
-            ...(endpointRevision !== undefined ? { endpointRevision } : {}),
-            ...(updatedAt !== undefined ? { updatedAt } : {}),
-            ...(lastHandshake !== undefined ? { lastHandshake } : {}),
-            ...(createdAt !== undefined ? { createdAt } : {}),
-        };
-    }
-    /** Single poll cycle: heartbeat + discover + diff + act */
-    async poll() {
-        if (this.stopped || this.signal?.aborted)
-            return;
-        // 1. Send heartbeat (register ourselves)
-        await this.heartbeat();
-        // 2. Fetch peer list from coordination server
-        const remotePeers = await this.fetchPeers();
-        if (!remotePeers)
-            return;
-        // 3. Diff and act
-        await this.reconcile(remotePeers);
-    }
-    /** Fetch peers from coordination server using envelope-authenticated POST only. */
-    async fetchPeers() {
-        const envelope = this.envelopeSigner("network.list_peers", {
-            nodeId: this.nodeId,
-            displayNameSnapshot: this.displayNameSnapshot,
-        });
-        const response = await this.postControlPlane("/api/v1/network/peers", { envelope });
-        if (response.status < 200 || response.status >= 300) {
-            throw new Error(`Peer discovery fetch failed: HTTP ${response.status}`);
-        }
-        const data = JSON.parse(response.body);
-        if (!Array.isArray(data.peers)) {
-            throw new Error("Peer discovery fetch returned invalid payload: peers must be an array");
-        }
-        const MAX_REMOTE_PEERS = 5000;
-        if (data.peers.length > MAX_REMOTE_PEERS) {
-            throw new Error(`Peer discovery fetch returned too many peers (${data.peers.length})`);
-        }
-        const parsedPeers = [];
-        for (const peer of data.peers) {
-            const parsedPeer = this.parseDiscoveredPeer(peer);
-            if (!parsedPeer) {
-                throw new Error("Peer discovery fetch returned malformed peer record");
-            }
-            parsedPeers.push(parsedPeer);
-        }
-        return parsedPeers;
-    }
-    /** Reconcile remote peers with local state */
-    async reconcile(remotePeers) {
-        const myNodeId = this.nodeId;
-        const remoteMap = new Map();
-        // Build map of remote active peers (excluding self and revoked)
-        for (const peer of remotePeers) {
-            if (peer.nodeId === myNodeId)
-                continue; // Skip self
-            const { identityState } = (0, tools_1.derivePeerStateFromLegacyStatus)(peer);
-            if (!(0, tools_1.canRefreshEndpoint)(identityState))
-                continue;
-            remoteMap.set(peer.nodeId, peer);
-        }
-        // Detect known peers whose endpoint changed on the coordination server.
-        // Reboots/NAT rebinding can invalidate the persisted endpoint even when the
-        // peer identity is unchanged. Refresh the live tunnel first, then persist.
-        for (const [nodeId, peer] of remoteMap) {
-            const known = this.knownRemotePeers.get(nodeId);
-            if (!known)
-                continue;
-            const endpointChanged = known.endpointHost !== peer.endpointHost || known.endpointPort !== peer.endpointPort;
-            const endpointRevisionChanged = (known.endpointRevision ?? 0) !== (peer.endpointRevision ?? 0);
-            const transportChanged = known.transportPublicKey !== peer.transportPublicKey;
-            const knownEndpointRevision = this.peerEndpointRevision(known);
-            const remoteEndpointRevision = this.peerEndpointRevision(peer);
-            const knownFreshness = this.peerFreshness(known);
-            const remoteFreshness = this.peerFreshness(peer);
-            const staleEndpointRegression = endpointChanged &&
-                knownEndpointRevision !== null &&
-                remoteEndpointRevision !== null &&
-                remoteEndpointRevision <= knownEndpointRevision;
-            const staleEndpointFallback = endpointChanged &&
-                knownEndpointRevision === null &&
-                remoteEndpointRevision === null &&
-                knownFreshness !== null &&
-                remoteFreshness !== null &&
-                remoteFreshness <= knownFreshness;
-            const staleTransportRevision = transportChanged &&
-                knownEndpointRevision !== null &&
-                remoteEndpointRevision !== null &&
-                remoteEndpointRevision <= knownEndpointRevision;
-            const staleTransportRegression = transportChanged &&
-                knownFreshness !== null &&
-                remoteFreshness !== null &&
-                remoteFreshness <= knownFreshness;
-            if (staleEndpointRegression ||
-                staleEndpointFallback ||
-                staleTransportRevision ||
-                staleTransportRegression) {
-                continue;
-            }
-            if (endpointChanged && peer.endpointHost && peer.endpointPort) {
-                const repairOutcome = this.classifyRepairOutcome(peer);
-                if (repairOutcome === "unknown") {
-                    this.reportError(new Error(`Peer discovery lost authoritative repair binding for ${peer.displayNameSnapshot ?? peer.nodeId} (${peer.nodeId})`));
-                    continue;
-                }
-                if (repairOutcome === "blocked") {
-                    continue;
-                }
-            }
-            // Continuity rebinding can rotate transport identity while the durable
-            // node identity stays stable, but discovery is read-only and may not
-            // rebind transport identity. Only the explicit continuity transaction may
-            // authorize a replacement transport key for an existing node binding.
-            if (transportChanged) {
-                this.reportError(new Error(`Peer discovery observed transport rotation for ${peer.displayNameSnapshot ?? peer.nodeId} (${peer.nodeId}); explicit continuity required`));
-                continue;
-            }
-            if (endpointRevisionChanged) {
-                this.knownRemotePeers.set(nodeId, peer);
-                continue;
-            }
-            this.knownRemotePeers.set(nodeId, peer);
-        }
-        // Detect new peers (in remote, not in local known set)
-        for (const [nodeId, peer] of remoteMap) {
-            if (this.knownRemotePeers.has(nodeId))
-                continue;
-            // Check tunnel limit
-            if (this.networkManager.activeTunnelCount >= this.maxPeers)
-                break;
-            try {
-                const repairOutcome = this.classifyRepairOutcome(peer);
-                if (repairOutcome === "unknown") {
-                    this.emit("peerDiscoveredUnknown", peer.displayNameSnapshot ?? peer.nodeId, peer.nodeId, peer);
-                    continue;
-                }
-                if (repairOutcome === "blocked") {
-                    continue;
-                }
-                await this.networkManager.startTunnel(peer.nodeId);
-                this.knownRemotePeers.set(nodeId, peer);
-                this.emit("peerJoined", peer.displayNameSnapshot ?? peer.nodeId, peer.nodeId);
-            }
-            catch (err) {
-                // Peer exists on coordination server but not in local registry —
-                // they haven't gone through the invite flow with us.
-                // Emit distinct event so the daemon can decide whether to auto-invite.
-                const message = err instanceof Error ? err.message : String(err);
-                const code = err?.code;
-                if (code === "PEER_NOT_IN_REGISTRY" || message.includes("not found in registry")) {
-                    this.emit("peerDiscoveredUnknown", peer.displayNameSnapshot ?? peer.nodeId, peer.nodeId, peer);
-                }
-                else {
-                    this.reportError(new Error(`Peer discovery failed to start tunnel for ${peer.displayNameSnapshot ?? peer.nodeId} (${peer.nodeId}): ${message}`));
-                }
-            }
-        }
-        // Detect disappeared/revoked peers (in local known set, not in remote active set)
-        for (const [nodeId, peer] of this.knownRemotePeers) {
-            if (remoteMap.has(nodeId))
-                continue;
-            // Peer disappeared or was revoked
-            this.networkManager.stopTunnel(nodeId);
-            this.knownRemotePeers.delete(nodeId);
-            this.emit("peerLeft", peer.displayNameSnapshot ?? peer.nodeId, peer.nodeId);
-        }
-        // Keep knownRemotePeers as connected peers only.
-    }
-}
-exports.PeerDiscoveryService = PeerDiscoveryService;
-//# sourceMappingURL=peer-discovery.js.map