@aria-cli/wireguard 1.0.38 → 1.0.39

package/dist/network.js

@@ -0,0 +1,3391 @@
+"use strict";
+/**
+ * Network manager — auto-setup, peer management, and invite flow for ARIA.
+ *
+ * Creates a secure WireGuard network on first run with zero user configuration.
+ * Manages peer lifecycle (invite, revoke, list) through the manage_network tool.
+ * Persists peer registry in Memoria DB (network_peers table).
+ *
+ * Architecture:
+ *   NetworkManager owns a SecureTunnel per peer. On startup it loads peers from
+ *   the DB, creates tunnels, and starts them. New peers join via invite tokens
+ *   that encode the leader's public key + endpoint + PSK.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkManager = exports.PeerRegistry = void 0;
+exports.generateSigningKeypair = generateSigningKeypair;
+exports.generateKeyPair = generateKeyPair;
+exports.createInviteToken = createInviteToken;
+exports.decodeInviteToken = decodeInviteToken;
+exports.ensureSecureNetwork = ensureSecureNetwork;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const tools_1 = require("@aria-cli/tools");
+const bootstrap_authority_js_1 = require("./bootstrap-authority.js");
+const bootstrap_tls_js_1 = require("./bootstrap-tls.js");
+const route_ownership_js_1 = require("./route-ownership.js");
+const tunnel_js_1 = require("./tunnel.js");
+const resilient_tunnel_js_1 = require("./resilient-tunnel.js");
+const DEFAULT_WIREGUARD_LISTEN_PORT = 58291;
+const WIREGUARD_TEST_LISTEN_PORT_ENV = "ARIA_WIREGUARD_TEST_LISTEN_PORT";
+function resolveDefaultWireguardListenPort() {
+    const override = process.env[WIREGUARD_TEST_LISTEN_PORT_ENV]?.trim();
+    if (!override) {
+        return DEFAULT_WIREGUARD_LISTEN_PORT;
+    }
+    const parsed = Number(override);
+    if (Number.isInteger(parsed) && parsed >= 0 && parsed <= 65_535) {
+        return parsed;
+    }
+    return DEFAULT_WIREGUARD_LISTEN_PORT;
+}
+/** Write to stderr only when ARIA_LOG_LEVEL=debug. Tunnel state noise is invisible by default. */
+function wireguardDebug(msg) {
+    if (typeof process !== "undefined" && process.env.ARIA_LOG_LEVEL === "debug" && process.stderr) {
+        process.stderr.write(msg);
+    }
+}
+function appendWireguardDiagnostic(ariaDir, entry) {
+    try {
+        const logDir = path.join(ariaDir, "audit");
+        fs.mkdirSync(logDir, { recursive: true });
+        fs.appendFileSync(path.join(logDir, "wireguard-diagnostics.jsonl"), JSON.stringify(entry) + "\n");
+    }
+    catch {
+        // Diagnostics are best-effort only.
+    }
+}
+const PEER_INFO_SELECT = `SELECT public_key AS publicKey, node_id AS nodeId, name, endpoint_host AS endpointHost,
+        endpoint_port AS endpointPort, endpoint_revision AS endpointRevision,
+        control_endpoint_host AS controlEndpointHost,
+        control_endpoint_port AS controlEndpointPort,
+        control_tls_ca_fingerprint AS controlTlsCaFingerprint,
+        status, last_handshake AS lastHandshake,
+        created_at AS createdAt, updated_at AS updatedAt, signing_public_key AS signingPublicKey
+       FROM network_peers`;
+function normalizeEndpointRevision(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 0;
+}
+function deriveLocalDisplayNameSnapshot(arionName) {
+    const normalized = arionName
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (normalized.length === 0) {
+        return "node";
+    }
+    return normalized.endsWith("-node") ? normalized : `${normalized}-node`;
+}
+const PENDING_INVITE_PLACEHOLDER_PREFIX = "pending-invite:";
+function normalizeInviteLabel(inviteLabel) {
+    if (inviteLabel === undefined) {
+        return undefined;
+    }
+    const trimmed = inviteLabel?.trim();
+    if (trimmed.length === 0) {
+        throw new Error("Invite peer name must not be empty");
+    }
+    return trimmed;
+}
+function buildPendingInvitePlaceholderName(tokenNonce) {
+    return `${PENDING_INVITE_PLACEHOLDER_PREFIX}${tokenNonce}`;
+}
+function extractPendingInviteLabel(name) {
+    return name.startsWith(PENDING_INVITE_PLACEHOLDER_PREFIX) ? undefined : name;
+}
+function matchesLegacyDerivedLocalPeerName(candidate, arionName) {
+    const trimmedArionName = arionName.trim();
+    if (trimmedArionName.length === 0) {
+        return false;
+    }
+    const escapedArionName = trimmedArionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`^${escapedArionName}-[0-9a-f]{8}$`, "i").test(candidate.trim());
+}
+function signingKeyFingerprintFromPublicKey(signingPublicKey) {
+    return tools_1.PrincipalFingerprintSchema.parse(crypto.createHash("sha256").update(Buffer.from(signingPublicKey, "base64")).digest("hex"));
+}
+function trySigningKeyFingerprintFromPublicKey(signingPublicKey) {
+    try {
+        assertValidSigningPublicKeyB64(signingPublicKey, "Peer signing key");
+        return signingKeyFingerprintFromPublicKey(signingPublicKey);
+    }
+    catch {
+        return null;
+    }
+}
+function hasLegacyRemoteActorKey(record) {
+    const legacyRemoteActorKey = "peer" + "Id";
+    return Object.prototype.hasOwnProperty.call(record, legacyRemoteActorKey);
+}
+function buildPeerInfo(row) {
+    const hasControlEndpoint = row.controlEndpointHost !== null ||
+        row.controlEndpointPort !== null ||
+        row.controlTlsCaFingerprint !== null;
+    const brandedCaFingerprint = row.controlTlsCaFingerprint !== null
+        ? tools_1.TlsCaFingerprintSchema.parse(row.controlTlsCaFingerprint)
+        : null;
+    const derivedControlTlsIdentity = typeof row.signingPublicKey === "string" && row.signingPublicKey.length > 0
+        ? trySigningKeyFingerprintFromPublicKey(row.signingPublicKey)
+        : null;
+    return {
+        ...row,
+        endpointRevision: normalizeEndpointRevision(row.endpointRevision),
+        nodeId: row.nodeId,
+        updatedAt: row.updatedAt ?? row.createdAt,
+        controlTlsCaFingerprint: brandedCaFingerprint,
+        controlEndpoint: hasControlEndpoint
+            ? {
+                host: row.controlEndpointHost,
+                port: row.controlEndpointPort,
+                tlsCaFingerprint: brandedCaFingerprint,
+                tlsServerIdentity: derivedControlTlsIdentity,
+                protocolVersion: 1,
+                endpointRevision: normalizeEndpointRevision(row.endpointRevision),
+            }
+            : null,
+    };
+}
+function parseOptionalNodeId(value) {
+    return typeof value === "string" && value.trim().length > 0 ? tools_1.NodeIdSchema.parse(value) : null;
+}
+function parsePeerInfoRow(row) {
+    return {
+        publicKey: tools_1.PeerTransportIdSchema.parse(row.publicKey),
+        nodeId: parseOptionalNodeId(row.nodeId),
+        name: row.name,
+        endpointHost: row.endpointHost ?? null,
+        endpointPort: row.endpointPort ?? null,
+        endpointRevision: row.endpointRevision ?? null,
+        controlEndpointHost: row.controlEndpointHost ?? null,
+        controlEndpointPort: row.controlEndpointPort ?? null,
+        controlTlsCaFingerprint: row.controlTlsCaFingerprint ?? null,
+        status: row.status,
+        lastHandshake: row.lastHandshake ?? null,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt ?? null,
+        signingPublicKey: row.signingPublicKey ?? null,
+    };
+}
+function assertNoUnexpectedActorKeys(input, allowedKeys, context) {
+    const unexpectedKeys = Object.keys(input).filter((key) => !allowedKeys.includes(key));
+    if (unexpectedKeys.length > 0) {
+        throw new Error(`${context} received unsupported fields: ${unexpectedKeys.join(", ")}`);
+    }
+}
+function hasAdvertisedEndpointChange(previous, next) {
+    if (!previous) {
+        return (next.endpointHost !== undefined ||
+            next.endpointPort !== undefined ||
+            next.controlEndpointHost !== undefined ||
+            next.controlEndpointPort !== undefined ||
+            next.controlTlsCaFingerprint !== undefined);
+    }
+    return ((next.endpointHost !== undefined && next.endpointHost !== previous.endpointHost) ||
+        (next.endpointPort !== undefined && next.endpointPort !== previous.endpointPort) ||
+        (next.controlEndpointHost !== undefined &&
+            next.controlEndpointHost !== previous.controlEndpointHost) ||
+        (next.controlEndpointPort !== undefined &&
+            next.controlEndpointPort !== previous.controlEndpointPort) ||
+        (next.controlTlsCaFingerprint !== undefined &&
+            next.controlTlsCaFingerprint !== previous.controlTlsCaFingerprint));
+}
+function resolveAdvertisedEndpointState(previous, next) {
+    const storedEndpointRevision = normalizeEndpointRevision(previous?.endpointRevision);
+    const hasStoredAdvertisedEndpoint = previous !== null &&
+        (previous.endpointHost !== null ||
+            previous.endpointPort !== null ||
+            previous.controlEndpointHost !== null ||
+            previous.controlEndpointPort !== null ||
+            previous.controlTlsCaFingerprint !== null);
+    const endpointChanged = hasAdvertisedEndpointChange(previous, next);
+    const hasExplicitEndpointRevision = typeof next.endpointRevision === "number" &&
+        Number.isInteger(next.endpointRevision) &&
+        next.endpointRevision >= 0;
+    const requestedEndpointRevision = hasExplicitEndpointRevision && typeof next.endpointRevision === "number"
+        ? next.endpointRevision
+        : endpointChanged
+            ? storedEndpointRevision + 1
+            : storedEndpointRevision;
+    const baselineEndpointAdvertisement = previous !== null &&
+        !hasStoredAdvertisedEndpoint &&
+        endpointChanged &&
+        requestedEndpointRevision === storedEndpointRevision;
+    const staleRevision = previous !== null &&
+        !baselineEndpointAdvertisement &&
+        (requestedEndpointRevision < storedEndpointRevision ||
+            (endpointChanged && requestedEndpointRevision === storedEndpointRevision));
+    const commitEndpointMutation = previous === null
+        ? endpointChanged || requestedEndpointRevision > 0
+        : baselineEndpointAdvertisement ||
+            (!staleRevision && requestedEndpointRevision > storedEndpointRevision);
+    return {
+        endpointHost: commitEndpointMutation
+            ? (next.endpointHost ?? previous?.endpointHost ?? null)
+            : (previous?.endpointHost ?? null),
+        endpointPort: commitEndpointMutation
+            ? (next.endpointPort ?? previous?.endpointPort ?? null)
+            : (previous?.endpointPort ?? null),
+        endpointRevision: previous !== null && staleRevision ? storedEndpointRevision : requestedEndpointRevision,
+        controlEndpointHost: commitEndpointMutation
+            ? (next.controlEndpointHost ?? previous?.controlEndpointHost ?? null)
+            : (previous?.controlEndpointHost ?? null),
+        controlEndpointPort: commitEndpointMutation
+            ? (next.controlEndpointPort ?? previous?.controlEndpointPort ?? null)
+            : (previous?.controlEndpointPort ?? null),
+        controlTlsCaFingerprint: commitEndpointMutation
+            ? (next.controlTlsCaFingerprint ?? previous?.controlTlsCaFingerprint ?? null)
+            : (previous?.controlTlsCaFingerprint ?? null),
+    };
+}
+/**
+ * Peer registry — wraps the network_peers table.
+ */
+class PeerRegistry {
+    db;
+    constructor(db) {
+        this.db = db;
+        // Schema is managed by Memoria migrations (V31 creates network_peers + token_claims).
+        // PeerRegistry does NO schema creation — it only reads/writes data.
+        this.reconcileSchema();
+    }
+    reconcileSchema() {
+        const columns = this.db.prepare("PRAGMA table_info(network_peers)").all();
+        const columnNames = new Set(columns.map((column) => column.name));
+        if (columnNames.has("peer_id")) {
+            throw new Error("Legacy network_peers schema requires hard reset: legacy peer_id alias");
+        }
+        const missingColumns = ["node_id", "endpoint_revision", "updated_at"].filter((column) => !columnNames.has(column));
+        if (missingColumns.length > 0) {
+            throw new Error(`Legacy network_peers schema requires hard reset: missing columns: ${missingColumns.join(", ")}`);
+        }
+        const rowsMissingUpdatedAt = this.db
+            .prepare(`SELECT public_key AS publicKey
+           FROM network_peers
+          WHERE updated_at IS NULL`)
+            .all();
+        if (rowsMissingUpdatedAt.length > 0) {
+            throw new Error("Legacy network_peers rows require hard reset: missing updated_at");
+        }
+        const rowsMissingDurablePeerIds = this.db
+            .prepare(`SELECT public_key AS publicKey
+           FROM network_peers
+          WHERE signing_public_key IS NOT NULL AND (node_id IS NULL OR LENGTH(TRIM(node_id)) = 0)`)
+            .all();
+        if (rowsMissingDurablePeerIds.length > 0) {
+            throw new Error("Legacy network_peers rows require hard reset: missing durable peer ids");
+        }
+        const duplicateDurableNodeIds = this.db
+            .prepare(`SELECT TRIM(node_id) AS nodeId, COUNT(*) AS count
+           FROM network_peers
+          WHERE node_id IS NOT NULL AND LENGTH(TRIM(node_id)) > 0
+          GROUP BY TRIM(node_id)
+         HAVING COUNT(*) > 1`)
+            .all()
+            .map((row) => {
+            const nodeId = parseOptionalNodeId(row.nodeId);
+            if (!nodeId) {
+                throw new Error("Duplicate durable nodeId query returned an invalid nodeId");
+            }
+            return {
+                nodeId,
+                count: row.count,
+            };
+        });
+        if (duplicateDurableNodeIds.length > 0) {
+            throw new Error(`Legacy network_peers rows require hard reset: duplicate durable node ids: ${duplicateDurableNodeIds
+                .map((row) => `${row.nodeId} (${row.count})`)
+                .join(", ")}`);
+        }
+    }
+    /** Add or update a peer */
+    upsert(peer) {
+        if (peer.signingPublicKey) {
+            assertValidSigningPublicKeyB64(peer.signingPublicKey, "Peer signing key");
+        }
+        const existingByPublicKey = this.getByPublicKey(peer.publicKey);
+        const explicitNodeId = peer.nodeId;
+        const existingByNodeId = explicitNodeId ? this.getByNodeId(explicitNodeId) : undefined;
+        if (existingByPublicKey?.nodeId && !explicitNodeId) {
+            throw new Error(`Peer "${peer.publicKey}" requires an explicit durable nodeId before mutating a bound peer row`);
+        }
+        const nodeId = explicitNodeId ?? existingByPublicKey?.nodeId ?? null;
+        if (peer.signingPublicKey && !nodeId) {
+            throw new Error(`Peer "${peer.publicKey}" requires an explicit durable nodeId before binding a signing key`);
+        }
+        const endpointMutation = {
+            endpointHost: peer.endpointHost,
+            endpointPort: peer.endpointPort,
+            endpointRevision: peer.endpointRevision,
+            controlEndpointHost: peer.controlEndpointHost,
+            controlEndpointPort: peer.controlEndpointPort,
+            controlTlsCaFingerprint: peer.controlTlsCaFingerprint,
+        };
+        const now = Date.now();
+        if (existingByNodeId) {
+            // A durable principal owns exactly one canonical transport binding. When
+            // the transport key rotates, rebind the existing row instead of creating
+            // a second row keyed by the stale transport identity.
+            if (existingByNodeId.publicKey !== peer.publicKey && nodeId) {
+                this.db
+                    .prepare(`DELETE FROM network_peers WHERE public_key = ? AND node_id != ?`)
+                    .run(peer.publicKey, nodeId);
+            }
+            const resolvedEndpointState = resolveAdvertisedEndpointState(existingByNodeId, endpointMutation);
+            this.db
+                .prepare(`UPDATE network_peers
+              SET node_id = ?,
+                  public_key = ?,
+                  name = ?,
+                  endpoint_host = ?,
+                  endpoint_port = ?,
+                  endpoint_revision = ?,
+                  control_endpoint_host = ?,
+                  control_endpoint_port = ?,
+                  control_tls_ca_fingerprint = ?,
+                  preshared_key = COALESCE(?, preshared_key),
+                  allowed_ips = COALESCE(?, allowed_ips),
+                  invite_token = COALESCE(?, invite_token),
+                  status = COALESCE(?, status),
+                  updated_at = ?,
+                  signing_public_key = COALESCE(?, signing_public_key)
+            WHERE node_id = ?`)
+                .run(nodeId, peer.publicKey, peer.name, resolvedEndpointState.endpointHost, resolvedEndpointState.endpointPort, resolvedEndpointState.endpointRevision, resolvedEndpointState.controlEndpointHost, resolvedEndpointState.controlEndpointPort, resolvedEndpointState.controlTlsCaFingerprint, peer.presharedKey ?? null, peer.allowedIps ?? null, peer.inviteToken ?? null, peer.status ?? "active", now, peer.signingPublicKey ?? null, nodeId);
+            return;
+        }
+        if (existingByPublicKey) {
+            const resolvedEndpointState = resolveAdvertisedEndpointState(existingByPublicKey, endpointMutation);
+            this.db
+                .prepare(`UPDATE network_peers
+              SET public_key = ?,
+                  node_id = ?,
+                  name = ?,
+                  endpoint_host = ?,
+                  endpoint_port = ?,
+                  endpoint_revision = ?,
+                  control_endpoint_host = ?,
+                  control_endpoint_port = ?,
+                  control_tls_ca_fingerprint = ?,
+                  preshared_key = COALESCE(?, preshared_key),
+                  allowed_ips = COALESCE(?, allowed_ips),
+                  invite_token = COALESCE(?, invite_token),
+                  status = COALESCE(?, status),
+                  updated_at = ?,
+                  signing_public_key = COALESCE(?, signing_public_key)
+            WHERE public_key = ?`)
+                .run(peer.publicKey, nodeId, peer.name, resolvedEndpointState.endpointHost, resolvedEndpointState.endpointPort, resolvedEndpointState.endpointRevision, resolvedEndpointState.controlEndpointHost, resolvedEndpointState.controlEndpointPort, resolvedEndpointState.controlTlsCaFingerprint, peer.presharedKey ?? null, peer.allowedIps ?? null, peer.inviteToken ?? null, peer.status ?? "active", now, peer.signingPublicKey ?? null, peer.publicKey);
+            return;
+        }
+        const resolvedEndpointState = resolveAdvertisedEndpointState(null, endpointMutation);
+        this.db
+            .prepare(`INSERT INTO network_peers (node_id, public_key, name, endpoint_host, endpoint_port, endpoint_revision,
+        control_endpoint_host, control_endpoint_port, control_tls_ca_fingerprint,
+        preshared_key, allowed_ips, invite_token, status, created_at, updated_at, signing_public_key)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(nodeId, peer.publicKey, peer.name, resolvedEndpointState.endpointHost, resolvedEndpointState.endpointPort, resolvedEndpointState.endpointRevision, resolvedEndpointState.controlEndpointHost, resolvedEndpointState.controlEndpointPort, resolvedEndpointState.controlTlsCaFingerprint, peer.presharedKey ?? null, peer.allowedIps ?? null, peer.inviteToken ?? null, peer.status ?? "active", now, now, peer.signingPublicKey ?? null);
+    }
+    /** Get all active peers */
+    listActive() {
+        const rows = this.db
+            .prepare(`${PEER_INFO_SELECT} WHERE status = 'active' ORDER BY name`)
+            .all();
+        return rows.map((row) => buildPeerInfo(parsePeerInfoRow(row)));
+    }
+    /** Get all peers (any status) */
+    listAll() {
+        const rows = this.db.prepare(`${PEER_INFO_SELECT} ORDER BY name`).all();
+        return rows.map((row) => buildPeerInfo(parsePeerInfoRow(row)));
+    }
+    /** List peers by display name. Display names are not unique principals. */
+    listByName(name) {
+        const rows = this.db
+            .prepare(`${PEER_INFO_SELECT} WHERE name = ? ORDER BY publicKey`)
+            .all(name);
+        return rows.map((row) => buildPeerInfo(parsePeerInfoRow(row)));
+    }
+    /** Get a peer by name */
+    getByName(name) {
+        const matches = this.listByName(name);
+        if (matches.length !== 1)
+            return undefined;
+        return matches[0];
+    }
+    /** Get a peer by durable node identity */
+    getByNodeId(nodeId) {
+        const row = this.db
+            .prepare(`${PEER_INFO_SELECT}
+         WHERE node_id = ?
+         ORDER BY CASE WHEN status = 'revoked' THEN 1 ELSE 0 END, created_at DESC`)
+            .get(nodeId);
+        return row ? buildPeerInfo(parsePeerInfoRow(row)) : undefined;
+    }
+    /** Get a peer by durable transport identity */
+    getByPublicKey(publicKey) {
+        const row = this.db.prepare(`${PEER_INFO_SELECT} WHERE public_key = ?`).get(publicKey);
+        return row ? buildPeerInfo(parsePeerInfoRow(row)) : undefined;
+    }
+    /** Update peer signing key by durable peer identity */
+    setSigningKeyByPublicKey(publicKey, signingPublicKey) {
+        assertValidSigningPublicKeyB64(signingPublicKey, "Peer signing key");
+        const existingRow = this.db
+            .prepare(`SELECT node_id AS nodeId FROM network_peers WHERE public_key = ?`)
+            .get(publicKey);
+        if (!existingRow) {
+            throw new Error(`No peer row found for public key "${publicKey}"`);
+        }
+        const existingNodeId = parseOptionalNodeId(existingRow.nodeId);
+        if (!existingNodeId || existingNodeId === publicKey) {
+            throw new Error(`Peer "${publicKey}" requires a durable nodeId before persisting a signing key`);
+        }
+        this.db
+            .prepare(`UPDATE network_peers SET signing_public_key = ? WHERE public_key = ?`)
+            .run(signingPublicKey, publicKey);
+    }
+    /** Revoke a peer by durable node identity. */
+    revokeByNodeId(nodeId) {
+        this.db
+            .prepare(`UPDATE network_peers SET status = 'revoked', updated_at = ? WHERE node_id = ?`)
+            .run(Date.now(), nodeId);
+    }
+    /** Revoke a peer's access while preserving durable audit state for restart and introspection. */
+    revoke(publicKey) {
+        this.db
+            .prepare(`UPDATE network_peers SET status = 'revoked', updated_at = ? WHERE public_key = ?`)
+            .run(Date.now(), publicKey);
+    }
+    /** Delete a superseded transport binding by its public key. */
+    delete(publicKey) {
+        this.db.prepare(`DELETE FROM network_peers WHERE public_key = ?`).run(publicKey);
+    }
+    /** Check if a token nonce was already consumed */
+    isTokenConsumed(nonce) {
+        const row = this.db.prepare(`SELECT 1 FROM network_peers WHERE invite_token = ?`).get(nonce);
+        return row !== undefined;
+    }
+    /**
+     * P0-3: Atomically claim a token nonce. Returns true if this call claimed it
+     * (first use), false if already claimed. Uses a SQLite transaction to eliminate
+     * the race window between check and mark in acceptInvite.
+     */
+    claimToken(nonce) {
+        return this.db.transaction(() => {
+            // Check both the legacy peer table and the claims table
+            const inPeers = this.db
+                .prepare(`SELECT 1 FROM network_peers WHERE invite_token = ?`)
+                .get(nonce);
+            if (inPeers)
+                return false;
+            const inClaims = this.db.prepare(`SELECT 1 FROM token_claims WHERE nonce = ?`).get(nonce);
+            if (inClaims)
+                return false;
+            this.db
+                .prepare(`INSERT INTO token_claims (nonce, claimed_at) VALUES (?, ?)`)
+                .run(nonce, Date.now());
+            return true;
+        })();
+    }
+    /** Release a previously claimed token (on error rollback). */
+    releaseToken(nonce) {
+        this.db.prepare(`DELETE FROM token_claims WHERE nonce = ?`).run(nonce);
+    }
+    /** Remove stale token claims older than maxAge (default 24h). Returns count of removed claims. */
+    cleanupStaleClaims(maxAgeMs = 24 * 60 * 60 * 1000) {
+        const cutoff = Date.now() - maxAgeMs;
+        const result = this.db.prepare("DELETE FROM token_claims WHERE claimed_at < ?").run(cutoff);
+        return result.changes;
+    }
+    /**
+     * Delete disposable invite stubs that can never become active again.
+     * Revoked peers stay durable so restart reconciliation, audits, and operator
+     * surfaces can still explain why a peer disappeared from active routing.
+     * Returns count of removed rows.
+     */
+    pruneTerminalPeers() {
+        const result = this.db.prepare(`DELETE FROM network_peers WHERE status = 'pending'`).run();
+        return result.changes;
+    }
+    /** Update last handshake timestamp */
+    updateHandshake(publicKey) {
+        this.db
+            .prepare(`UPDATE network_peers SET last_handshake = ? WHERE public_key = ?`)
+            .run(Date.now(), publicKey);
+    }
+    /** Update last handshake timestamp by durable node identity. */
+    updateHandshakeByNodeId(nodeId) {
+        this.db
+            .prepare(`UPDATE network_peers SET last_handshake = ? WHERE node_id = ?`)
+            .run(Date.now(), nodeId);
+    }
+    /** Get peers by status */
+    listByStatus(status) {
+        const rows = this.db
+            .prepare(`${PEER_INFO_SELECT} WHERE status = ? ORDER BY name`)
+            .all(status);
+        return rows.map((row) => buildPeerInfo(parsePeerInfoRow(row)));
+    }
+    /** Get a pending peer by invite token nonce */
+    getPendingByInviteToken(inviteTokenNonce) {
+        const row = this.db
+            .prepare(`${PEER_INFO_SELECT} WHERE status = 'pending' AND invite_token = ? LIMIT 1`)
+            .get(inviteTokenNonce);
+        return row ? buildPeerInfo(parsePeerInfoRow(row)) : undefined;
+    }
+    /** Count active peers */
+    activeCount() {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) as count FROM network_peers WHERE status = 'active'`)
+            .get();
+        return row.count;
+    }
+    /** Get a peer by public key with PSK for tunnel reconstruction */
+    getWithPsk(publicKey) {
+        const row = this.db
+            .prepare(`SELECT public_key, name, preshared_key, invite_token, endpoint_host, endpoint_port, status,
+                node_id, signing_public_key, endpoint_revision
+       FROM network_peers WHERE public_key = ?`)
+            .get(publicKey);
+        if (!row)
+            return undefined;
+        return {
+            publicKey: row.public_key,
+            nodeId: row.node_id ? tools_1.NodeIdSchema.parse(row.node_id) : null,
+            name: row.name,
+            presharedKey: row.preshared_key,
+            inviteToken: row.invite_token,
+            endpointHost: row.endpoint_host,
+            endpointPort: row.endpoint_port,
+            endpointRevision: row.endpoint_revision ?? 0,
+            status: row.status,
+            signingPublicKey: row.signing_public_key,
+        };
+    }
+}
+exports.PeerRegistry = PeerRegistry;
+/**
+ * Generate an Ed25519 keypair for message signing.
+ * Returns base64-encoded SPKI DER (public) and PKCS#8 DER (private).
+ */
+function generateSigningKeypair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519", {
+        publicKeyEncoding: { type: "spki", format: "der" },
+        privateKeyEncoding: { type: "pkcs8", format: "der" },
+    });
+    return {
+        publicKey: publicKey.toString("base64"),
+        privateKey: privateKey.toString("base64"),
+    };
+}
+/**
+ * Generate a new X25519 keypair using node:crypto.
+ */
+function generateKeyPair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("x25519", {
+        publicKeyEncoding: { type: "spki", format: "der" },
+        privateKeyEncoding: { type: "pkcs8", format: "der" },
+    });
+    // Extract raw 32-byte keys from DER encoding
+    // X25519 SPKI DER: 12-byte header + 32-byte key
+    // X25519 PKCS8 DER: 16-byte header + 32-byte key
+    const rawPublic = publicKey.subarray(publicKey.length - 32);
+    const rawPrivate = privateKey.subarray(privateKey.length - 32);
+    return {
+        publicKey: rawPublic.toString("base64"),
+        privateKey: rawPrivate.toString("base64"),
+    };
+}
+function assertValidEndpointHost(host, label) {
+    if (host.length < 1 || host.length > 253) {
+        throw new Error(`${label} must be 1-253 characters`);
+    }
+    if (!/^[a-zA-Z0-9._:-]+$/.test(host)) {
+        throw new Error(`${label} contains invalid characters`);
+    }
+    if (host.includes("..")) {
+        throw new Error(`${label} cannot contain consecutive dots`);
+    }
+}
+function assertValidPort(port, label) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`${label} must be an integer between 1 and 65535`);
+    }
+}
+function assertValidPeerPublicKeyB64(peerPublicKey, label) {
+    const keyBytes = Buffer.from(peerPublicKey, "base64");
+    if (keyBytes.length !== 32) {
+        throw new Error(`${label} must be a base64-encoded 32-byte X25519 public key`);
+    }
+}
+function assertValidSigningPublicKeyB64(signingPublicKey, label) {
+    try {
+        const key = crypto.createPublicKey({
+            key: Buffer.from(signingPublicKey, "base64"),
+            format: "der",
+            type: "spki",
+        });
+        if (key.asymmetricKeyType !== "ed25519") {
+            throw new Error("wrong key type");
+        }
+    }
+    catch {
+        throw new Error(`${label} must be a valid base64 SPKI Ed25519 public key`);
+    }
+}
+function evaluateEndpointRevision(params) {
+    const currentRevision = params.currentRevision ?? 0;
+    if (params.nextRevision < currentRevision) {
+        return { kind: "stale", currentRevision };
+    }
+    if (params.nextRevision === currentRevision) {
+        const sameEndpoint = params.currentHost === params.nextHost && params.currentPort === params.nextPort;
+        return sameEndpoint
+            ? { kind: "idempotent", revision: currentRevision }
+            : { kind: "conflict", currentRevision };
+    }
+    return { kind: "apply", revision: params.nextRevision };
+}
+/**
+ * Validate that a decoded invite token has all required fields with correct types.
+ */
+function validateInviteToken(data) {
+    const parsed = tools_1.TransportInviteTokenSchema.safeParse(data);
+    if (!parsed.success) {
+        throw new Error(`Invalid token: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`);
+    }
+    return parsed.data;
+}
+function canonicalizeInviteTokenPayload(invite) {
+    return JSON.stringify({
+        nodeId: invite.nodeId,
+        audienceNodeId: invite.audienceNodeId,
+        publicKey: invite.publicKey,
+        leaderDisplayNameSnapshot: invite.leaderDisplayNameSnapshot,
+        host: invite.host,
+        port: invite.port,
+        controlEndpoint: invite.controlEndpoint,
+        psk: invite.psk,
+        displayNameSnapshot: invite.displayNameSnapshot,
+        signingPublicKey: invite.signingPublicKey,
+        caCert: invite.caCert,
+        createdAt: invite.createdAt,
+        expiresAt: invite.expiresAt,
+        tokenNonce: invite.tokenNonce,
+        coordinationUrl: invite.coordinationUrl,
+        networkId: invite.networkId,
+    });
+}
+/**
+ * Create an invite token for a new peer.
+ * Encodes: leader's public key + endpoint + PSK + display snapshots.
+ *
+ * Token format: aria-net-v4-<base64url(JSON{payload,signature})>
+ * The payload is always signed with Ed25519.
+ */
+function createInviteToken(params) {
+    if (!params.signingPrivateKey || !params.signingPublicKey) {
+        throw new Error("Signed invite tokens require signingPrivateKey and signingPublicKey (v3 tokens are removed)");
+    }
+    assertNoUnexpectedActorKeys(params, [
+        "leaderPublicKey",
+        "nodeId",
+        "audienceNodeId",
+        "leaderDisplayNameSnapshot",
+        "host",
+        "port",
+        "controlEndpoint",
+        "displayNameSnapshot",
+        "durationMs",
+        "signingPublicKey",
+        "caCert",
+        "coordinationUrl",
+        "networkId",
+        "signingPrivateKey",
+    ], "Signed invite token");
+    const rawNodeId = params.nodeId?.trim();
+    if (!rawNodeId) {
+        throw new Error("Signed invite tokens require an explicit durable nodeId");
+    }
+    const nodeId = tools_1.NodeIdSchema.parse(rawNodeId);
+    const audienceNodeId = params.audienceNodeId
+        ? tools_1.NodeIdSchema.parse(params.audienceNodeId)
+        : undefined;
+    const leaderPublicKey = tools_1.PeerTransportIdSchema.parse(params.leaderPublicKey);
+    const signingPublicKey = tools_1.SigningPublicKeySchema.parse(params.signingPublicKey);
+    const DEFAULT_INVITE_EXPIRY_MS = 24 * 60 * 60 * 1000;
+    const psk = crypto.randomBytes(32).toString("base64");
+    const tokenNonce = crypto.randomBytes(16).toString("hex");
+    const hasCustomDuration = typeof params.durationMs === "number";
+    const durationMs = params.durationMs ?? DEFAULT_INVITE_EXPIRY_MS;
+    const createdAt = Date.now();
+    const expiresAt = hasCustomDuration
+        ? durationMs === 0
+            ? 0
+            : Math.min(createdAt + durationMs, Number.MAX_SAFE_INTEGER)
+        : Math.min(createdAt + DEFAULT_INVITE_EXPIRY_MS, Number.MAX_SAFE_INTEGER);
+    const payload = {
+        nodeId,
+        audienceNodeId,
+        publicKey: leaderPublicKey,
+        leaderDisplayNameSnapshot: params.leaderDisplayNameSnapshot,
+        host: params.host,
+        port: params.port,
+        controlEndpoint: params.controlEndpoint,
+        psk,
+        displayNameSnapshot: params.displayNameSnapshot,
+        signingPublicKey,
+        caCert: params.caCert,
+        createdAt,
+        expiresAt,
+        tokenNonce,
+        coordinationUrl: params.coordinationUrl,
+        networkId: params.networkId,
+    };
+    const json = canonicalizeInviteTokenPayload(payload);
+    const keyDer = Buffer.from(params.signingPrivateKey, "base64");
+    const privateKey = crypto.createPrivateKey({ key: keyDer, format: "der", type: "pkcs8" });
+    const signature = crypto.sign(null, Buffer.from(json), privateKey).toString("base64");
+    const signedPayload = JSON.stringify({ payload, signature });
+    const data = Buffer.from(signedPayload).toString("base64url");
+    return { token: `aria-net-v4-${data}`, psk };
+}
+/**
+ * Decode an invite token.
+ *
+ * Accepts v4 (aria-net-v4-, Ed25519 signed) format only.
+ */
+function decodeInviteToken(token) {
+    if (!token.startsWith("aria-net-")) {
+        throw new Error("Invalid invite token format — must start with aria-net-");
+    }
+    // v4: signed token — verify signature against included public key
+    if (token.startsWith("aria-net-v4-")) {
+        const dataB64 = token.slice("aria-net-v4-".length);
+        const json = Buffer.from(dataB64, "base64url").toString("utf-8");
+        const parsed = JSON.parse(json);
+        if (!parsed.payload || !parsed.signature) {
+            throw new Error("Invalid v4 token: missing payload or signature");
+        }
+        const rawPayload = parsed.payload;
+        const signingPublicKey = typeof rawPayload.signingPublicKey === "string" ? rawPayload.signingPublicKey : undefined;
+        if (!signingPublicKey) {
+            throw new Error("Invalid v4 token: missing signingPublicKey for signature verification");
+        }
+        const payloadJson = JSON.stringify(parsed.payload);
+        const pubKeyDer = Buffer.from(signingPublicKey, "base64");
+        const publicKey = crypto.createPublicKey({ key: pubKeyDer, format: "der", type: "spki" });
+        const valid = crypto.verify(null, Buffer.from(payloadJson), publicKey, Buffer.from(parsed.signature, "base64"));
+        if (!valid) {
+            throw new Error("Invalid v4 token: signature verification failed");
+        }
+        return validateInviteToken(parsed.payload);
+    }
+    // Explicitly reject all legacy formats.
+    if (token.startsWith("aria-net-v2-")) {
+        throw new Error("v2 tokens are no longer accepted — the HMAC key was included in the token (forgeable). Generate a new signed v4 invite token.");
+    }
+    if (token.startsWith("aria-net-") && token.split(".").length === 4) {
+        throw new Error("v1 encrypted tokens are no longer accepted — the AES key was included in the token. Generate a new signed v4 invite token.");
+    }
+    throw new Error("Legacy invite tokens are no longer accepted. Generate a new signed v4 invite token.");
+}
+function normalizeTrustedCaId(fingerprint) {
+    const normalized = fingerprint.trim().toLowerCase();
+    if (!/^[a-f0-9]{16,128}$/.test(normalized)) {
+        throw new Error("Invalid trusted CA fingerprint");
+    }
+    return normalized;
+}
+function trustedCaPathForFingerprint(ariaDir, fingerprint) {
+    const trustedDir = path.resolve(path.join(ariaDir, "network", "trusted-cas"));
+    const targetPath = path.resolve(path.join(trustedDir, `${normalizeTrustedCaId(fingerprint)}.pem`));
+    if (!targetPath.startsWith(`${trustedDir}${path.sep}`)) {
+        throw new Error("Trusted CA path escapes trusted-cas directory");
+    }
+    return targetPath;
+}
+function persistTrustedPeerCa(ariaDir, caCert) {
+    const trimmedCert = caCert?.trim();
+    if (!trimmedCert)
+        return;
+    const fingerprint = tools_1.TlsCaFingerprintSchema.parse(crypto
+        .createHash("sha256")
+        .update(Buffer.from(trimmedCert
+        .replace(/-----BEGIN CERTIFICATE-----/, "")
+        .replace(/-----END CERTIFICATE-----/, "")
+        .replace(/\s/g, ""), "base64"))
+        .digest("hex"));
+    const targetPath = trustedCaPathForFingerprint(ariaDir, fingerprint);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, trimmedCert, "utf8");
+}
+function solveJoinProofOfWork(challengeString, difficulty) {
+    const [challengeId, challenge] = challengeString.split(":");
+    if (!challengeId || !challenge) {
+        throw new Error("Join challenge payload is malformed");
+    }
+    const targetPrefix = "0".repeat(Math.max(0, difficulty));
+    const MAX_NONCE_ATTEMPTS = 5_000_000;
+    for (let nonce = 0; nonce < MAX_NONCE_ATTEMPTS; nonce++) {
+        const hash = crypto
+            .createHash("sha256")
+            .update(challenge + nonce.toString())
+            .digest("hex");
+        if (hash.startsWith(targetPrefix)) {
+            return `${challengeId}:${nonce}`;
+        }
+    }
+    throw new Error("Failed to solve join proof-of-work within attempt budget");
+}
+/**
+ * Ensure a secure network exists — auto-creates on first run.
+ *
+ * This is the zero-configuration entry point. Called during ARIA startup.
+ * If no network config exists, generates keypair, picks a random port,
+ * discovers external endpoint via STUN, and saves the config.
+ */
+async function ensureSecureNetwork(ariaDir, arionName = "ARIA", options = {}) {
+    const networkDir = path.join(ariaDir, "network");
+    const configPath = path.join(networkDir, "config.json");
+    const authoritativeNodeId = options.nodeId ? tools_1.NodeIdSchema.parse(options.nodeId) : undefined;
+    // Check for existing config
+    if (fs.existsSync(configPath)) {
+        // Verify file permissions haven't been weakened (private key protection)
+        const stat = fs.statSync(configPath);
+        const mode = stat.mode & 0o777;
+        if (mode !== 0o600) {
+            // Attempt to fix permissions
+            try {
+                fs.chmodSync(configPath, 0o600);
+            }
+            catch {
+                // Can't fix — log warning but continue
+                wireguardDebug(`[wireguard] WARNING: config.json has permissions ${mode.toString(8)} (expected 600). Contains private key.\n`);
+            }
+        }
+        const data = fs.readFileSync(configPath, "utf-8");
+        const config = JSON.parse(data);
+        if (config.nodeId) {
+            config.nodeId = tools_1.NodeIdSchema.parse(config.nodeId);
+        }
+        if (typeof config.publicKey === "string" && config.publicKey.length > 0) {
+            config.publicKey = tools_1.PeerTransportIdSchema.parse(config.publicKey);
+        }
+        // Migration: generate missing keys for configs with partial fields.
+        // The config may have been created with only signing keys (e.g., test harness
+        // or manual setup) — we need WireGuard X25519 keys for tunnel operations.
+        let needsPersist = false;
+        if (!config.publicKey || !config.privateKey) {
+            const keyPair = generateKeyPair();
+            config.publicKey = tools_1.PeerTransportIdSchema.parse(keyPair.publicKey);
+            config.privateKey = keyPair.privateKey;
+            needsPersist = true;
+        }
+        if (typeof config.listenPort !== "number" || Number.isNaN(config.listenPort)) {
+            config.listenPort = resolveDefaultWireguardListenPort();
+            needsPersist = true;
+        }
+        if (typeof config.createdAt !== "number" ||
+            !Number.isFinite(config.createdAt) ||
+            config.createdAt <= 0) {
+            config.createdAt = Date.now();
+            needsPersist = true;
+        }
+        if (typeof config.endpointRevision !== "number" ||
+            !Number.isInteger(config.endpointRevision) ||
+            config.endpointRevision < 0) {
+            config.endpointRevision = 0;
+            needsPersist = true;
+        }
+        if (!config.signingPublicKey || !config.signingPrivateKey) {
+            const signingKeypair = generateSigningKeypair();
+            config.signingPublicKey = signingKeypair.publicKey;
+            config.signingPrivateKey = signingKeypair.privateKey;
+            needsPersist = true;
+        }
+        if (!config.nodeId) {
+            if (!authoritativeNodeId) {
+                throw new Error("Network config missing nodeId — runtime bootstrap authority must provide nodeId before network initialization");
+            }
+            config.nodeId = authoritativeNodeId;
+            needsPersist = true;
+        }
+        if (authoritativeNodeId && config.nodeId !== authoritativeNodeId) {
+            throw new Error(`Network config nodeId mismatch: expected ${authoritativeNodeId}, found ${config.nodeId}`);
+        }
+        if (typeof config.endpointRevision !== "number" || config.endpointRevision < 0) {
+            config.endpointRevision = config.externalEndpoint ? 1 : 0;
+            needsPersist = true;
+        }
+        const expectedDisplaySnapshot = deriveLocalDisplayNameSnapshot(arionName);
+        const legacyLocalPeerName = typeof config.localPeerName === "string" ? config.localPeerName.trim() : "";
+        const currentDisplaySnapshot = config.localDisplayNameSnapshot?.trim() ?? "";
+        const preferredDisplaySnapshot = currentDisplaySnapshot.length > 0 ? currentDisplaySnapshot : legacyLocalPeerName;
+        if (preferredDisplaySnapshot.length === 0) {
+            config.localDisplayNameSnapshot = expectedDisplaySnapshot;
+            needsPersist = true;
+        }
+        else if (preferredDisplaySnapshot === arionName ||
+            matchesLegacyDerivedLocalPeerName(preferredDisplaySnapshot, arionName)) {
+            config.localDisplayNameSnapshot = expectedDisplaySnapshot;
+            needsPersist = true;
+        }
+        else if (config.localDisplayNameSnapshot !== preferredDisplaySnapshot) {
+            config.localDisplayNameSnapshot = preferredDisplaySnapshot;
+            needsPersist = true;
+        }
+        if ("localPeerName" in config) {
+            delete config.localPeerName;
+            needsPersist = true;
+        }
+        if (needsPersist) {
+            try {
+                fs.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+            }
+            catch {
+                // Non-fatal: keys are in memory even if we can't persist them
+            }
+        }
+        return config;
+    }
+    // Generate new network
+    if (!authoritativeNodeId) {
+        throw new Error("Network bootstrap requires an explicit runtime-owned nodeId before WireGuard initialization");
+    }
+    const keyPair = generateKeyPair();
+    const signingKeypair = generateSigningKeypair();
+    // Default UDP listen port for ARIA secure networking. Fixed (not
+    // random) so firewall rules and NAT port forwarding work across
+    // restarts. High port (49151+) avoids port scanning and IANA conflicts.
+    const listenPort = resolveDefaultWireguardListenPort();
+    const localDisplayNameSnapshot = deriveLocalDisplayNameSnapshot(arionName);
+    const config = {
+        nodeId: authoritativeNodeId,
+        publicKey: tools_1.PeerTransportIdSchema.parse(keyPair.publicKey),
+        privateKey: keyPair.privateKey,
+        signingPublicKey: signingKeypair.publicKey,
+        signingPrivateKey: signingKeypair.privateKey,
+        listenPort,
+        endpointRevision: 0,
+        createdAt: Date.now(),
+        localDisplayNameSnapshot,
+    };
+    // Save config — atomic create-or-fail to avoid TOCTOU race
+    fs.mkdirSync(networkDir, { recursive: true, mode: 0o700 });
+    try {
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600, flag: "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            // Another process created the config — read and use theirs
+            const data = fs.readFileSync(configPath, "utf-8");
+            const existing = JSON.parse(data);
+            if (existing.nodeId) {
+                existing.nodeId = tools_1.NodeIdSchema.parse(existing.nodeId);
+            }
+            if (!existing.nodeId) {
+                throw new Error("Concurrent network bootstrap produced config without nodeId — refusing bootstrap");
+            }
+            if (existing.nodeId !== authoritativeNodeId) {
+                throw new Error(`Concurrent network bootstrap nodeId mismatch: expected ${authoritativeNodeId}, found ${existing.nodeId}`);
+            }
+            return existing;
+        }
+        throw err;
+    }
+    return config;
+}
+/**
+ * NetworkManager — manages the lifecycle of all peer tunnels.
+ *
+ * Loads peers from DB on start, creates/destroys tunnels on demand,
+ * handles invite acceptance, and provides status queries.
+ */
+class NetworkManager {
+    static MAX_PEERS = 128;
+    /** Interval for attempting direct connection upgrade when using relay */
+    static RELAY_UPGRADE_INTERVAL_MS = 5 * 60_000; // 5 min
+    config = null;
+    tunnels = new Map();
+    /** In-flight tunnel startups keyed by peer public key. */
+    pendingTunnelStarts = new Map();
+    /** Pending starts that must self-cancel before publishing an active tunnel. */
+    canceledTunnelStarts = new Set();
+    /** Relay transports for peers behind symmetric NAT (publicKey -> relay) */
+    relayTransports = new Map();
+    /** Periodic timers for attempting direct connection upgrade from relay */
+    relayUpgradeTimers = new Map();
+    /** Known peer Ed25519 signing public keys keyed by display-name snapshot. */
+    _peerSigningKeys = new Map();
+    /** Public display snapshot surfaced through runtime/publication boundaries. */
+    _localDisplayNameSnapshot;
+    /** Our durable local node identity projected from the runtime authority. */
+    _localNodeId;
+    /** Runtime-published local control endpoint advertisement for invite/join flows. */
+    _localControlEndpoint;
+    /** Cached bootstrap CA authority used to mint pinned invite tokens. */
+    _localBootstrapCaCert;
+    /** Consecutive failed upgrade attempts per relay (for exponential backoff) */
+    relayUpgradeAttempts = new Map();
+    appendDiagnostic(entry) {
+        appendWireguardDiagnostic(this.ariaDir, entry);
+    }
+    /** Callback for relay data received through DERP relay.
+     *  Set by daemon to wire relay-received messages into the EventQueue. */
+    onRelayDataReceived;
+    // ── Listener-based event system (replaces singleton callbacks) ──────────
+    _transportListeners = [];
+    _messageListeners = [];
+    _deliveryAckListeners = [];
+    _peerActivationListeners = [];
+    /** Subscribe to transport events (tunnel/relay up/down). Returns unsubscribe fn. */
+    addTransportListener(listener) {
+        this._transportListeners.push(listener);
+        return () => {
+            const idx = this._transportListeners.indexOf(listener);
+            if (idx >= 0)
+                this._transportListeners.splice(idx, 1);
+        };
+    }
+    /** Subscribe to incoming messages. Returns unsubscribe fn. */
+    addMessageListener(listener) {
+        this._messageListeners.push(listener);
+        return () => {
+            const idx = this._messageListeners.indexOf(listener);
+            if (idx >= 0)
+                this._messageListeners.splice(idx, 1);
+        };
+    }
+    /** Subscribe to delivery acknowledgements. Returns unsubscribe fn. */
+    addDeliveryAckListener(listener) {
+        this._deliveryAckListeners.push(listener);
+        return () => {
+            const idx = this._deliveryAckListeners.indexOf(listener);
+            if (idx >= 0)
+                this._deliveryAckListeners.splice(idx, 1);
+        };
+    }
+    /** Subscribe to verified peer activation events. Returns unsubscribe fn. */
+    addPeerActivationListener(listener) {
+        this._peerActivationListeners.push(listener);
+        return () => {
+            const idx = this._peerActivationListeners.indexOf(listener);
+            if (idx >= 0)
+                this._peerActivationListeners.splice(idx, 1);
+        };
+    }
+    /** Get a snapshot of currently active transports (for late-bind mailbox scenarios). */
+    getActiveTransports() {
+        const result = [];
+        const includedPubKeys = new Set();
+        for (const [pubKey, tunnel] of this.tunnels) {
+            const routeOwnership = this.getDirectRouteOwnershipForPublicKey(pubKey);
+            if (routeOwnership?.ownership === "superseded") {
+                continue;
+            }
+            const tunnelState = typeof tunnel.getState === "function" ? tunnel.getState() : "connected";
+            if (tunnelState !== "connected" && tunnelState !== "handshaking") {
+                continue;
+            }
+            const peerInfo = this.peerRegistry?.getWithPsk(pubKey);
+            if (peerInfo) {
+                const nodeId = this.resolvePeerPrincipalId(peerInfo);
+                if (!nodeId)
+                    continue;
+                result.push({
+                    type: "tunnel",
+                    nodeId,
+                    displayNameSnapshot: peerInfo.name,
+                    transport: tunnelState === "connected"
+                        ? tunnel
+                        : {
+                            sendPlaintext: (data) => tunnel.sendPlaintext(data),
+                            routeBootstrapOnly: true,
+                        },
+                });
+                includedPubKeys.add(pubKey);
+            }
+        }
+        for (const [pubKey, relay] of this.relayTransports) {
+            if (includedPubKeys.has(pubKey))
+                continue;
+            const routeOwnership = this.getDirectRouteOwnershipForPublicKey(pubKey);
+            if (routeOwnership?.ownership === "superseded") {
+                continue;
+            }
+            const peerInfo = this.peerRegistry?.getWithPsk(pubKey);
+            if (peerInfo) {
+                const nodeId = this.resolvePeerPrincipalId(peerInfo);
+                if (!nodeId)
+                    continue;
+                result.push({
+                    type: "relay",
+                    nodeId,
+                    displayNameSnapshot: peerInfo.name,
+                    transport: { sendPlaintext: (data) => relay.send(data) },
+                });
+            }
+        }
+        return result;
+    }
+    /** Shared UDP socket for all WG tunnels (single-port model like real WireGuard).
+     *  Created in initialize(), bound to config.listenPort. All tunnels send/receive
+     *  through this one socket. Incoming packets are offered to registered tunnel
+     *  handlers until one claims ownership. */
+    sharedSocket = null;
+    /** Packet handlers registered by tunnels using the shared socket.
+     *  Each handler returns a disposition object indicating whether it handled the packet. */
+    sharedSocketHandlers = new Set();
+    /** ExternalSocket interface exposed to SecureTunnels */
+    get externalSocketInterface() {
+        if (!this.sharedSocket)
+            return undefined;
+        const socket = this.sharedSocket;
+        const handlers = this.sharedSocketHandlers;
+        return {
+            send: (data, port, host, cb) => {
+                socket.send(data, 0, data.length, port, host, cb);
+            },
+            port: this.config?.listenPort ?? 0,
+            onPacket: (handler) => {
+                handlers.add(handler);
+                return () => {
+                    handlers.delete(handler);
+                };
+            },
+        };
+    }
+    ariaDir;
+    arionName;
+    peerRegistry;
+    constructor(ariaDir, arionNameOrPeerRegistry, peerRegistry) {
+        this.ariaDir = ariaDir;
+        if (typeof arionNameOrPeerRegistry === "string") {
+            this.arionName = arionNameOrPeerRegistry;
+            this.peerRegistry = peerRegistry;
+        }
+        else {
+            this.arionName = "ARIA";
+            this.peerRegistry = arionNameOrPeerRegistry;
+        }
+    }
+    isLocalIdentityCandidate(candidate) {
+        if (!this.config)
+            return false;
+        if (candidate.publicKey && candidate.publicKey === this.config.publicKey)
+            return true;
+        if (candidate.signingPublicKey &&
+            this.config.signingPublicKey &&
+            candidate.signingPublicKey === this.config.signingPublicKey) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Remote peers and the local machine identity must never share the same registry.
+     * This guard makes the invalid state unrepresentable for all peer-registration paths.
+     */
+    assertRemotePeerIdentity(candidate, context = "Peer") {
+        if (this.isLocalIdentityCandidate(candidate)) {
+            const candidateName = candidate.name ? ` "${candidate.name}"` : "";
+            throw new Error(`${context}${candidateName} matches the local machine identity`);
+        }
+    }
+    quarantineCorruptedLocalPeerRows() {
+        if (!this.peerRegistry || !this.config)
+            return;
+        for (const peer of this.peerRegistry.listAll()) {
+            if (!this.isLocalIdentityCandidate(peer))
+                continue;
+            this.peerRegistry.delete(peer.publicKey);
+            this._peerSigningKeys.delete(peer.publicKey);
+            wireguardDebug(`[wireguard] Quarantined corrupted local identity row "${peer.name}" (${peer.publicKey.slice(0, 8)}...)\n`);
+        }
+    }
+    resolveUniqueLivePeerPublicKeyByNodeId(nodeId) {
+        const peer = this.resolvePeerByNodeId(nodeId, { includeRevoked: false });
+        return peer?.publicKey ?? null;
+    }
+    getDirectRouteOwnershipSnapshot() {
+        if (!this.peerRegistry) {
+            return new Map();
+        }
+        return (0, route_ownership_js_1.resolveDirectRouteOwnership)(this.peerRegistry
+            .listAll()
+            .filter((peer) => !this.isLocalIdentityCandidate(peer))
+            .filter((peer) => peer.status !== "revoked")
+            .map((peer) => ({
+            publicKey: peer.publicKey,
+            nodeId: peer.nodeId,
+            status: peer.status,
+            endpointHost: peer.endpointHost,
+            endpointPort: peer.endpointPort,
+            endpointRevision: peer.endpointRevision,
+            createdAt: peer.createdAt,
+            updatedAt: peer.updatedAt,
+        })));
+    }
+    getDirectRouteOwnershipForPublicKey(peerPublicKey) {
+        return this.getDirectRouteOwnershipSnapshot().get(peerPublicKey) ?? null;
+    }
+    resolveCurrentDirectRoutePeerPublicKeyByNodeId(nodeId) {
+        const peer = this.resolvePeerByNodeId(nodeId, { includeRevoked: false });
+        if (!peer) {
+            return null;
+        }
+        const ownership = this.getDirectRouteOwnershipForPublicKey(peer.publicKey);
+        if (ownership?.ownership === "superseded") {
+            return null;
+        }
+        return peer.publicKey;
+    }
+    ensureCurrentDirectRouteOwner(peerPublicKey) {
+        const ownership = this.getDirectRouteOwnershipForPublicKey(peerPublicKey);
+        if (ownership?.ownership === "superseded") {
+            throw new Error(`Peer ${peerPublicKey} has a superseded route claim`);
+        }
+    }
+    reconcileDirectRouteOwnership() {
+        if (!this.peerRegistry) {
+            return;
+        }
+        for (const [peerPublicKey, ownership] of this.getDirectRouteOwnershipSnapshot()) {
+            if (ownership.ownership !== "superseded") {
+                continue;
+            }
+            const peerInfo = this.peerRegistry.getWithPsk(peerPublicKey);
+            const ownerPeer = this.peerRegistry.getWithPsk(ownership.ownerPublicKey);
+            this.appendDiagnostic({
+                timestamp: Date.now(),
+                event: "route_superseded",
+                peerPublicKey,
+                peerNodeId: peerInfo?.nodeId ?? null,
+                peerName: peerInfo?.name,
+                detail: {
+                    ownerPublicKey: ownership.ownerPublicKey,
+                    ownerNodeId: ownerPeer?.nodeId ?? null,
+                    routeKey: ownership.routeKey,
+                },
+            });
+            this.tearDownRelay(peerPublicKey);
+            this.stopTunnelByTransportKey(peerPublicKey);
+        }
+    }
+    resolvePeerByNodeId(nodeId, options) {
+        if (!this.peerRegistry) {
+            return null;
+        }
+        const peer = this.peerRegistry.getByNodeId(nodeId);
+        if (!peer) {
+            return null;
+        }
+        if (!options.includeRevoked && peer.status === "revoked") {
+            return null;
+        }
+        return peer;
+    }
+    listSupersededPrincipalRows(signingPublicKey, retainingPublicKey, retainingNodeId) {
+        if (!this.peerRegistry) {
+            return [];
+        }
+        const principalFingerprint = crypto
+            .createHash("sha256")
+            .update(Buffer.from(signingPublicKey, "base64"))
+            .digest("hex");
+        return this.peerRegistry
+            .listAll()
+            .filter((peer) => peer.status !== "revoked")
+            .filter((peer) => peer.publicKey !== retainingPublicKey)
+            .filter((peer) => !retainingNodeId || !peer.nodeId || peer.nodeId === retainingNodeId)
+            .filter((peer) => this.getPeerSigningFingerprintByPublicKey(peer.publicKey) === principalFingerprint);
+    }
+    cleanupSupersededPrincipalRows(rows) {
+        for (const peer of rows) {
+            this.tearDownRelay(peer.publicKey);
+            this.stopTunnelByTransportKey(peer.publicKey);
+            this._peerSigningKeys.delete(peer.publicKey);
+        }
+    }
+    getCachedOrDurablePeerSigningKey(peerPublicKey) {
+        return (this._peerSigningKeys.get(peerPublicKey) ??
+            this.getDurablePeerSigningKey(peerPublicKey) ??
+            undefined);
+    }
+    async ensureNativeRuntimeAvailable() {
+        const wireguard = (await import("./index.js"));
+        wireguard.assertNativeAddonAvailable?.();
+    }
+    refreshExternalEndpointFromSharedSocket() {
+        const activeSocket = this.sharedSocket;
+        if (!activeSocket) {
+            return;
+        }
+        void import("./nat.js")
+            .then(({ discoverEndpoint }) => discoverEndpoint(undefined, 5000, activeSocket))
+            .then((stunResult) => {
+            if (!this.config || this.sharedSocket !== activeSocket) {
+                return;
+            }
+            this.updateExternalEndpoint(stunResult.address, stunResult.port);
+        })
+            .catch(() => {
+            // STUN failed — keep the current endpoint state. Runtime startup must
+            // not block on external endpoint discovery.
+        });
+    }
+    /**
+     * Resolve a unique peer name — disambiguates if the proposed name collides
+     * with our own identity or an existing peer with a different signing key.
+     * Returns the original name if no collision, or "name-<8hex>" if collision.
+     */
+    resolveUniquePeerName(proposedName, signingPublicKey) {
+        // Check collision with our own identity
+        const ourName = this.getLocalDisplayNameSnapshot();
+        if (ourName && proposedName === ourName) {
+            return this._disambiguateName(proposedName, signingPublicKey);
+        }
+        // Display names are non-authoritative. If any existing row with the same
+        // name belongs to a different principal, the new peer must be disambiguated.
+        if (this.peerRegistry) {
+            const existingPeers = this.peerRegistry.listByName(proposedName);
+            const collidesWithDifferentPrincipal = existingPeers.some((existing) => existing.signingPublicKey !== null && existing.signingPublicKey !== signingPublicKey);
+            if (collidesWithDifferentPrincipal) {
+                return this._disambiguateName(proposedName, signingPublicKey);
+            }
+        }
+        return proposedName;
+    }
+    _disambiguateName(name, signingPublicKey) {
+        const fp = crypto
+            .createHash("sha256")
+            .update(Buffer.from(signingPublicKey, "base64"))
+            .digest("hex")
+            .slice(0, 8);
+        return `${name}-${fp}`;
+    }
+    matchesPeerNodeIdClaim(claimedNodeId, peer) {
+        if (!claimedNodeId) {
+            return false;
+        }
+        const resolvedNodeId = this.resolvePeerPrincipalId(peer);
+        if (!resolvedNodeId) {
+            return false;
+        }
+        return claimedNodeId === resolvedNodeId;
+    }
+    matchesDeliveryAckNodeId(senderNodeId, peer) {
+        if (!senderNodeId) {
+            return false;
+        }
+        const resolvedNodeId = this.resolvePeerPrincipalId(peer);
+        if (!resolvedNodeId) {
+            return false;
+        }
+        return senderNodeId === resolvedNodeId;
+    }
+    /** Stage signing-key material through the runtime-owned peer identity boundary. */
+    stagePendingPeerSigningKey(input) {
+        const peer = this.peerRegistry?.getWithPsk(input.peerPublicKey);
+        if (!peer) {
+            throw new Error(`No peer row found for public key "${input.peerPublicKey}"`);
+        }
+        if (!peer.nodeId || peer.nodeId !== input.nodeId) {
+            throw new Error(`stagePendingPeerSigningKey nodeId mismatch for public key "${input.peerPublicKey}"`);
+        }
+        this._peerSigningKeys.set(input.peerPublicKey, input.signingPublicKey);
+        this.peerRegistry?.setSigningKeyByPublicKey(input.peerPublicKey, input.signingPublicKey);
+    }
+    /** Stage a direct-pair peer through the runtime-owned pending_verification transition. */
+    async applyDirectPairActivation(input) {
+        if (!this.peerRegistry) {
+            throw new Error("No peer registry");
+        }
+        this.peerRegistry.upsert({
+            publicKey: input.peerPublicKey,
+            nodeId: input.nodeId,
+            name: input.displayNameSnapshot,
+            endpointHost: input.transportEndpoint.host,
+            endpointPort: input.transportEndpoint.port,
+            endpointRevision: input.controlEndpoint.endpointRevision,
+            controlEndpointHost: input.controlEndpoint.host,
+            controlEndpointPort: input.controlEndpoint.port,
+            controlTlsCaFingerprint: input.controlEndpoint.tlsCaFingerprint,
+            presharedKey: input.presharedKey,
+            status: "pending_verification",
+            signingPublicKey: input.signingPublicKey,
+        });
+        this.stagePendingPeerSigningKey({
+            nodeId: input.nodeId,
+            peerPublicKey: input.peerPublicKey,
+            displayNameSnapshot: input.displayNameSnapshot,
+            signingPublicKey: input.signingPublicKey,
+        });
+        this.reconcileDirectRouteOwnership();
+        this.stopTunnel(input.nodeId);
+        await this.startTunnel(input.nodeId);
+    }
+    /** Get all known peer signing keys keyed by durable peer principal id. */
+    getAllPeerSigningKeysByPrincipal() {
+        const byPrincipal = new Map();
+        if (!this.peerRegistry) {
+            return byPrincipal;
+        }
+        for (const peer of this.peerRegistry.listAll()) {
+            if (this.isLocalIdentityCandidate(peer))
+                continue;
+            const { identityState } = (0, tools_1.derivePeerStateFromLegacyStatus)(peer);
+            if (identityState === "revoked")
+                continue;
+            const signingPublicKey = this.getDurablePeerSigningKey(peer.publicKey);
+            if (!signingPublicKey)
+                continue;
+            if (!peer.nodeId)
+                continue;
+            byPrincipal.set(peer.nodeId, signingPublicKey);
+        }
+        return byPrincipal;
+    }
+    /**
+     * Activate a peer that is in pending_verification status.
+     *
+     * Called after the first successfully verified signed message from the peer.
+     * Updates the peer's status to "active" in PeerRegistry and invokes the
+     * onPeerActivated callback so the runtime can durably persist the peer's
+     * verified signing identity.
+     *
+     * Idempotent: no-op if the peer is already active.
+     */
+    activatePendingPeer(nodeId) {
+        if (!this.peerRegistry)
+            return;
+        const peer = this.peerRegistry
+            .listAll()
+            .find((candidate) => this.resolvePeerPrincipalId(candidate) === nodeId);
+        if (!peer)
+            return;
+        const { identityState } = (0, tools_1.derivePeerStateFromLegacyStatus)(peer);
+        if (!(0, tools_1.canCommitVerifiedPair)(identityState, { proofValid: true }))
+            return;
+        // Promote to active
+        this.peerRegistry.upsert({
+            nodeId,
+            publicKey: peer.publicKey,
+            name: peer.name,
+            status: "active",
+        });
+        this.reconcileDirectRouteOwnership();
+        // Notify the server to register the signing key for message auth
+        const signingKey = this.getDurablePeerSigningKey(peer.publicKey);
+        if (signingKey) {
+            const activation = {
+                nodeId,
+                displayNameSnapshot: peer.name,
+                signingPublicKey: signingKey,
+            };
+            for (const listener of this._peerActivationListeners) {
+                listener(activation);
+            }
+        }
+    }
+    /** Initialize the network — ensure config exists, load peers */
+    async initialize() {
+        const authoritativeNodeId = this._localNodeId;
+        if (!authoritativeNodeId) {
+            throw new Error("NetworkManager requires an explicit runtime-owned local nodeId before initialize()");
+        }
+        this.config = await ensureSecureNetwork(this.ariaDir, this.arionName, {
+            nodeId: authoritativeNodeId,
+        });
+        await this.ensureNativeRuntimeAvailable();
+        this._localBootstrapCaCert = (0, bootstrap_authority_js_1.loadStoredBootstrapCaCert)(this.ariaDir);
+        // Create the shared UDP socket — single port for ALL WG tunnels,
+        // like the real WireGuard kernel module. `listenPort > 0` is durable
+        // transport identity and must bind exactly or fail closed. `listenPort = 0`
+        // is an explicit bootstrap sentinel that requests an OS-assigned port.
+        if (!this.sharedSocket) {
+            const dgram = await import("node:dgram");
+            this.sharedSocket = dgram.createSocket("udp4");
+            try {
+                await new Promise((resolve, reject) => {
+                    const socket = this.sharedSocket;
+                    const handleError = (error) => {
+                        socket.off("error", handleError);
+                        reject(error);
+                    };
+                    socket.once("error", handleError);
+                    socket.bind(this.config.listenPort, () => {
+                        socket.off("error", handleError);
+                        resolve();
+                    });
+                });
+            }
+            catch (bindErr) {
+                const socket = this.sharedSocket;
+                this.sharedSocket = null;
+                this.sharedSocketHandlers.clear();
+                if (socket) {
+                    await new Promise((resolve) => {
+                        try {
+                            socket.close(() => resolve());
+                        }
+                        catch {
+                            resolve();
+                        }
+                    });
+                }
+                if (bindErr.code === "EADDRINUSE" &&
+                    this.config.listenPort > 0) {
+                    throw new Error(`WireGuard listen port ${this.config.listenPort} is already in use; ` +
+                        "refusing to bind a different port. Stop the conflicting process or " +
+                        "set listenPort: 0 for explicit ephemeral bootstrap.");
+                }
+                throw bindErr;
+            }
+            if (this.config.listenPort === 0) {
+                const addr = this.sharedSocket.address();
+                if (typeof addr !== "string" && addr.port > 0) {
+                    this.config.listenPort = addr.port;
+                    this.persistConfig();
+                }
+            }
+            // Route incoming packets to the first tunnel that claims them.
+            this.sharedSocket.on("message", (msg, rinfo) => {
+                const rejections = [];
+                for (const handler of this.sharedSocketHandlers) {
+                    const disposition = handler(msg, rinfo);
+                    if (disposition.handled) {
+                        return;
+                    }
+                    if (disposition.outcome === "decrypt_error" ||
+                        disposition.outcome === "decrypt_exception") {
+                        rejections.push({
+                            peerPublicKey: disposition.peerPublicKey,
+                            outcome: disposition.outcome,
+                            errorDetail: disposition.errorDetail,
+                        });
+                    }
+                }
+                if (rejections.length > 0) {
+                    this.appendDiagnostic({
+                        timestamp: Date.now(),
+                        event: "shared_socket_packet_unhandled",
+                        detail: {
+                            sourceAddress: rinfo.address,
+                            sourcePort: rinfo.port,
+                            packetBytes: msg.length,
+                            messageType: msg.length > 0 ? msg[0] : null,
+                            rejections,
+                        },
+                    });
+                }
+            });
+            // Re-discover external endpoint using the SHARED socket so the
+            // NAT mapping matches the actual WG listening port. The initial
+            // STUN in ensureSecureNetwork() used an ephemeral socket — its
+            // mapping is useless after that socket was closed.
+            this.refreshExternalEndpointFromSharedSocket();
+        }
+        // Clean up stale token claims and terminal peers from previous sessions
+        this.peerRegistry?.cleanupStaleClaims();
+        this.peerRegistry?.pruneTerminalPeers();
+        // Restore known peer signing keys from registry
+        if (this.peerRegistry) {
+            this.quarantineCorruptedLocalPeerRows();
+            for (const peer of this.peerRegistry.listAll()) {
+                if (this.isLocalIdentityCandidate(peer))
+                    continue;
+                const signingPublicKey = this.getDurablePeerSigningKey(peer.publicKey);
+                if (!signingPublicKey)
+                    continue;
+                this._peerSigningKeys.set(peer.publicKey, signingPublicKey);
+            }
+            this.reconcileDirectRouteOwnership();
+            const restoreDirectPeer = async (peer) => {
+                const ownership = this.getDirectRouteOwnershipForPublicKey(peer.publicKey);
+                if (ownership?.ownership === "superseded") {
+                    this.appendDiagnostic({
+                        timestamp: Date.now(),
+                        event: "route_restore_skipped",
+                        peerPublicKey: peer.publicKey,
+                        peerNodeId: peer.nodeId,
+                        peerName: peer.name,
+                        detail: {
+                            ownerPublicKey: ownership.ownerPublicKey,
+                            routeKey: ownership.routeKey,
+                        },
+                    });
+                    return;
+                }
+                try {
+                    await this.startTunnelByTransportKey(peer.publicKey);
+                }
+                catch {
+                    // Best-effort restore; individual peers may be offline
+                }
+            };
+            // Rehydrate active tunnels on startup
+            for (const peer of this.peerRegistry.listActive()) {
+                if (this.isLocalIdentityCandidate(peer))
+                    continue;
+                await restoreDirectPeer(peer);
+            }
+            // Rehydrate tunnels for pending_verification peers.
+            // These peers were paired via /pair/direct but haven't yet sent their first
+            // signed message to prove identity. They need the tunnel to send that message.
+            // Without this, pending_verification peers lose connectivity after restart
+            // and can never activate (catch-22).
+            for (const peer of this.peerRegistry.listByStatus("pending_verification")) {
+                if (this.isLocalIdentityCandidate(peer))
+                    continue;
+                await restoreDirectPeer(peer);
+            }
+            // Recover peers stuck in pending_tunnel (crash before durable join
+            // completion or before the runtime could observe proof). Rehydrate the
+            // tunnel only; never heuristically promote to active on restart.
+            for (const peer of this.peerRegistry.listByStatus("pending_tunnel")) {
+                if (this.isLocalIdentityCandidate(peer))
+                    continue;
+                try {
+                    const ownership = this.getDirectRouteOwnershipForPublicKey(peer.publicKey);
+                    if (ownership?.ownership === "superseded") {
+                        this.appendDiagnostic({
+                            timestamp: Date.now(),
+                            event: "route_restore_skipped",
+                            peerPublicKey: peer.publicKey,
+                            peerNodeId: peer.nodeId,
+                            peerName: peer.name,
+                            detail: {
+                                ownerPublicKey: ownership.ownerPublicKey,
+                                routeKey: ownership.routeKey,
+                            },
+                        });
+                        continue;
+                    }
+                    await this.startTunnelByTransportKey(peer.publicKey);
+                }
+                catch {
+                    wireguardDebug(`[wireguard] WARNING: Failed to recover pending_tunnel peer "${peer.name}" — manual intervention may be required.\n`);
+                }
+            }
+        }
+        return this.config;
+    }
+    /** Get the current network config */
+    getConfig() {
+        return this.config;
+    }
+    get localNodeId() {
+        if (this._localNodeId) {
+            return this._localNodeId;
+        }
+        return this.config?.nodeId ? tools_1.NodeIdSchema.parse(this.config.nodeId) : undefined;
+    }
+    get localControlEndpoint() {
+        return this._localControlEndpoint;
+    }
+    /** Get our own local display snapshot through the runtime boundary. */
+    getLocalDisplayNameSnapshot() {
+        return (this._localDisplayNameSnapshot ??
+            this.config?.localDisplayNameSnapshot ??
+            deriveLocalDisplayNameSnapshot(this.arionName));
+    }
+    setLocalDisplayNameSnapshot(name) {
+        this._localDisplayNameSnapshot = name;
+        if (this.config) {
+            this.config.localDisplayNameSnapshot = name;
+            this.persistConfig();
+        }
+    }
+    setLocalNodeId(nodeId) {
+        this._localNodeId = nodeId;
+        if (this.config) {
+            this.config.nodeId = nodeId;
+            this.persistConfig();
+        }
+    }
+    setLocalControlEndpoint(controlEndpoint) {
+        this._localControlEndpoint = controlEndpoint;
+    }
+    /**
+     * Update the external endpoint (called when STUN refresh detects a change).
+     * Persists to disk so the new endpoint survives restarts.
+     */
+    updateExternalEndpoint(address, port) {
+        if (!this.config)
+            return;
+        const changed = this.config.externalEndpoint?.address !== address ||
+            this.config.externalEndpoint?.port !== port;
+        this.config.externalEndpoint = { address, port };
+        if (changed) {
+            this.config.endpointRevision = normalizeEndpointRevision(this.config.endpointRevision) + 1;
+        }
+        this.persistConfig();
+    }
+    /**
+     * Set the coordination server URL (persisted to disk).
+     */
+    setCoordinationUrl(url) {
+        if (!this.config)
+            return;
+        this.config.coordinationUrl = url;
+        this.persistConfig();
+    }
+    /**
+     * Set the DERP relay server URL (persisted to disk).
+     */
+    setRelayUrl(url) {
+        if (!this.config)
+            return;
+        this.config.relayUrl = url;
+        this.persistConfig();
+    }
+    /** Persist current config to disk */
+    persistConfig() {
+        if (!this.config)
+            return;
+        const networkDir = path.join(this.ariaDir, "network");
+        const configPath = path.join(networkDir, "config.json");
+        try {
+            fs.writeFileSync(configPath, JSON.stringify(this.config, null, 2), { mode: 0o600 });
+        }
+        catch {
+            // Non-fatal: config is in memory even if persist fails
+        }
+    }
+    /**
+     * Compute deterministic complementary tunnel IPs from key ordering.
+     *
+     * Both peers must agree on who is .1 and who is .2. We use lexicographic
+     * ordering of public keys: the smaller key gets 10.0.0.1, the larger gets
+     * 10.0.0.2. This ensures Alice.selfIp === Bob.peerIp and vice versa,
+     * making the tunnel functional in both directions.
+     */
+    computePeerIps(peerPublicKey) {
+        if (!this.config)
+            throw new Error("Network not initialized");
+        const selfIsSmaller = this.config.publicKey < peerPublicKey;
+        return {
+            selfIp: selfIsSmaller ? 0x0a000001 : 0x0a000002,
+            peerIp: selfIsSmaller ? 0x0a000002 : 0x0a000001,
+        };
+    }
+    /** Start a SecureTunnel for a registered peer by durable node identity. */
+    async startTunnel(nodeId) {
+        const peerPublicKey = this.resolveCurrentDirectRoutePeerPublicKeyByNodeId(nodeId);
+        if (!peerPublicKey) {
+            throw new Error(`Peer ${nodeId} not found in registry or has a superseded route`);
+        }
+        await this.startTunnelByTransportKey(peerPublicKey);
+    }
+    /** Transport-internal tunnel startup by transport key. */
+    async startTunnelByTransportKey(peerPublicKey) {
+        this.reconcileDirectRouteOwnership();
+        this.ensureCurrentDirectRouteOwner(peerPublicKey);
+        if (this.tunnels.has(peerPublicKey))
+            return; // Already running — idempotent
+        const pendingStart = this.pendingTunnelStarts.get(peerPublicKey);
+        if (pendingStart) {
+            await pendingStart;
+            return;
+        }
+        if (!this.config)
+            throw new Error("Network not initialized");
+        this.assertRemotePeerIdentity({ publicKey: peerPublicKey }, "Tunnel peer");
+        if (this.tunnels.size + this.pendingTunnelStarts.size >= NetworkManager.MAX_PEERS) {
+            throw new Error(`Tunnel limit reached (${NetworkManager.MAX_PEERS})`);
+        }
+        const peerInfo = this.peerRegistry?.getWithPsk(peerPublicKey);
+        if (!peerInfo)
+            throw new Error(`Peer ${peerPublicKey} not found in registry`);
+        this.assertRemotePeerIdentity({
+            publicKey: peerPublicKey,
+            signingPublicKey: peerInfo.signingPublicKey ?? null,
+            name: peerInfo.name,
+        }, "Tunnel peer");
+        const startPromise = (async () => {
+            this.appendDiagnostic({
+                timestamp: Date.now(),
+                event: "tunnel_start_requested",
+                peerPublicKey,
+                peerNodeId: peerInfo.nodeId,
+                peerName: peerInfo.name,
+                detail: {
+                    endpointHost: peerInfo.endpointHost,
+                    endpointPort: peerInfo.endpointPort,
+                },
+            });
+            const ips = this.computePeerIps(peerPublicKey);
+            const tunnel = new resilient_tunnel_js_1.ResilientTunnel({
+                privateKey: this.config.privateKey,
+                peerPublicKey: peerPublicKey,
+                presharedKey: peerInfo.presharedKey ?? undefined,
+                keepalive: 25,
+                // Use shared socket (single-port model) when available, else random port
+                listenPort: this.sharedSocket ? undefined : 0,
+                externalSocket: this.externalSocketInterface,
+                peerHost: peerInfo.endpointHost ?? undefined,
+                peerPort: peerInfo.endpointPort ?? undefined,
+                tunnelSrcIp: ips.selfIp,
+                tunnelDstIp: ips.peerIp,
+            });
+            tunnel.on("handshake", () => {
+                if (this.peerRegistry) {
+                    this.peerRegistry.updateHandshake(peerPublicKey);
+                    this.appendDiagnostic({
+                        timestamp: Date.now(),
+                        event: "handshake_db_updated",
+                        peerPublicKey,
+                        peerNodeId: peerInfo.nodeId,
+                        peerName: peerInfo.name,
+                        detail: {
+                            reason: "secure_tunnel_handshake",
+                        },
+                    });
+                }
+            });
+            await tunnel.start();
+            this.appendDiagnostic({
+                timestamp: Date.now(),
+                event: "tunnel_start_completed",
+                peerPublicKey,
+                peerNodeId: peerInfo.nodeId,
+                peerName: peerInfo.name,
+                detail: {
+                    resilientState: tunnel.getState(),
+                    isActive: tunnel.isActive,
+                },
+            });
+            if (this.canceledTunnelStarts.delete(peerPublicKey)) {
+                tunnel.stop();
+                return;
+            }
+            this.tunnels.set(peerPublicKey, tunnel);
+            this.appendDiagnostic({
+                timestamp: Date.now(),
+                event: "tunnel_registered",
+                peerPublicKey,
+                peerNodeId: peerInfo.nodeId,
+                peerName: peerInfo.name,
+                detail: {
+                    resilientState: tunnel.getState(),
+                    isActive: tunnel.isActive,
+                },
+            });
+            {
+                const nodeId = this.resolvePeerPrincipalId(peerInfo);
+                if (nodeId) {
+                    const bootstrapTransport = {
+                        sendPlaintext: (data) => tunnel.sendPlaintext(data),
+                        routeBootstrapOnly: true,
+                    };
+                    for (const listener of this._transportListeners) {
+                        listener.onRouteBootstrapAvailable?.(peerInfo.name, bootstrapTransport, nodeId);
+                    }
+                }
+            }
+            // Handle tunnel errors — without this listener, ResilientTunnel's error
+            // re-emit causes an uncaught exception that crashes the process.
+            // The ResilientTunnel internally handles reconnection on error.
+            tunnel.on("error", (err) => {
+                this.appendDiagnostic({
+                    timestamp: Date.now(),
+                    event: "resilient_tunnel_error",
+                    peerPublicKey,
+                    peerNodeId: peerInfo.nodeId,
+                    peerName: peerInfo.name,
+                    detail: { error: err.message },
+                });
+            });
+            // Monitor tunnel health — log state transitions and notify listeners only
+            // after proven remote activity promotes the tunnel to CONNECTED.
+            tunnel.on("stateChange", (newState, prevState) => {
+                this.appendDiagnostic({
+                    timestamp: Date.now(),
+                    event: "resilient_state_change",
+                    peerPublicKey,
+                    peerNodeId: peerInfo.nodeId,
+                    peerName: peerInfo.name,
+                    detail: {
+                        prevState,
+                        newState,
+                    },
+                });
+                // State transitions captured by appendDiagnostic above.
+                if (newState === "connected" &&
+                    (prevState === "reconnecting" ||
+                        prevState === "handshaking" ||
+                        prevState === "connecting")) {
+                    const nodeId = this.resolvePeerPrincipalId(peerInfo);
+                    if (nodeId) {
+                        for (const listener of this._transportListeners) {
+                            listener.onTransportUp?.(peerInfo.name, tunnel, nodeId);
+                        }
+                        this.appendDiagnostic({
+                            timestamp: Date.now(),
+                            event: "transport_up_emitted",
+                            peerPublicKey,
+                            peerNodeId: nodeId,
+                            peerName: peerInfo.name,
+                            detail: {
+                                reason: `${prevState}_to_connected`,
+                            },
+                        });
+                    }
+                }
+            });
+            // When a tunnel reports dead (max reconnection attempts exhausted),
+            // attempt DERP relay fallback if configured, otherwise clean up.
+            tunnel.on("dead", () => {
+                wireguardDebug(`[wireguard] Tunnel ${peerPublicKey.slice(0, 8)}... is DEAD`);
+                this.tunnels.delete(peerPublicKey);
+                // Notify listeners that the direct tunnel is torn down
+                const nodeId = this.resolvePeerPrincipalId(peerInfo);
+                if (nodeId) {
+                    for (const listener of this._transportListeners) {
+                        listener.onTransportDown?.(peerInfo.name, nodeId);
+                    }
+                }
+                // Attempt DERP relay fallback if relay URL is configured
+                const localDisplayNameSnapshot = this.getLocalDisplayNameSnapshot();
+                if (this.config?.relayUrl && this.config.signingPrivateKey && localDisplayNameSnapshot) {
+                    const peerInfo = this.peerRegistry?.getWithPsk(peerPublicKey);
+                    const identityState = peerInfo
+                        ? (0, tools_1.derivePeerStateFromLegacyStatus)(peerInfo).identityState
+                        : undefined;
+                    if (peerInfo && identityState && (0, tools_1.canHeartbeat)(identityState)) {
+                        wireguardDebug(` — falling back to DERP relay for ${peerInfo.name}\n`);
+                        // Lazy-import DerpRelay to avoid circular dependency at module level
+                        void import("./derp-relay.js")
+                            .then(({ DerpRelay }) => {
+                            const localNodeId = this.resolvePeerPrincipalId({
+                                name: localDisplayNameSnapshot,
+                                publicKey: this.config.publicKey,
+                            });
+                            const targetNodeId = this.resolvePeerPrincipalId(peerInfo);
+                            if (!localNodeId || !targetNodeId) {
+                                wireguardDebug(`[wireguard] DERP relay requires durable node identities for ${peerPublicKey.slice(0, 8)}...\n`);
+                                return;
+                            }
+                            const relay = new DerpRelay({
+                                relayUrl: this.config.relayUrl,
+                                nodeId: localNodeId,
+                                displayNameSnapshot: localDisplayNameSnapshot,
+                                signingPrivateKey: this.config.signingPrivateKey,
+                                signingPublicKey: this.config.signingPublicKey,
+                                targetNodeId,
+                            });
+                            relay.on("plaintext", (data, from, fromNodeId) => {
+                                const parsedFromNodeId = tools_1.NodeIdSchema.safeParse(fromNodeId);
+                                if (!parsedFromNodeId.success ||
+                                    !this.matchesPeerNodeIdClaim(parsedFromNodeId.data, peerInfo)) {
+                                    wireguardDebug(`[wireguard] Relay sender principal mismatch for ${peerPublicKey.slice(0, 8)}... expected "${this.resolvePeerPrincipalId(peerInfo) ?? peerInfo.name}", got "${String(fromNodeId)}"\n`);
+                                    return;
+                                }
+                                // Route relay-received data through the same handler as tunnel data
+                                try {
+                                    const parsed = JSON.parse(data.toString());
+                                    const envelope = tools_1.RuntimeIngressEnvelopeSchema.safeParse(parsed);
+                                    if (envelope.success && "deliveryAck" in envelope.data) {
+                                        const ack = envelope.data.deliveryAck;
+                                        // Delivery acks are now keyed by durable node ids, not display names.
+                                        // The authenticated relay/tunnel channel proves the remote transport
+                                        // peer, and the runtime outbox/mailbox layer validates sender/recipient
+                                        // node ids against pending durable receipts before settling them.
+                                        for (const listener of this._deliveryAckListeners) {
+                                            listener(ack);
+                                        }
+                                        return;
+                                    }
+                                    if (parsed.ariaMessage) {
+                                        const claimedSenderNodeId = parsed.ariaMessage?.sender?.id;
+                                        const parsedSenderNodeId = tools_1.NodeIdSchema.safeParse(claimedSenderNodeId);
+                                        if (!parsedSenderNodeId.success ||
+                                            !this.matchesPeerNodeIdClaim(parsedSenderNodeId.data, peerInfo)) {
+                                            wireguardDebug(`[wireguard] Dropped relay message with sender principal mismatch for ${peerPublicKey.slice(0, 8)}... expected "${this.resolvePeerPrincipalId(peerInfo) ?? peerInfo.name}", got "${String(claimedSenderNodeId)}"\n`);
+                                            return;
+                                        }
+                                        for (const ml of this._messageListeners) {
+                                            ml(parsed.ariaMessage);
+                                        }
+                                    }
+                                }
+                                catch {
+                                    // Not JSON — forward raw data via relay handler
+                                    this.onRelayDataReceived?.(data, from);
+                                }
+                            });
+                            void relay
+                                .connect()
+                                .then(() => {
+                                void this.setupRelayFallback(peerPublicKey, {
+                                    send: (data) => relay.send(data),
+                                    disconnect: () => relay.disconnect(),
+                                });
+                            })
+                                .catch(() => {
+                                // Relay connection failed — peer is truly unreachable
+                                wireguardDebug(`[wireguard] DERP relay fallback also failed for ${peerPublicKey.slice(0, 8)}...\n`);
+                            });
+                        })
+                            .catch(() => {
+                            // DerpRelay import failed (ws not available)
+                        });
+                        return;
+                    }
+                }
+                wireguardDebug(` — removing from active tunnels\n`);
+            });
+            tunnel.on("queueFlushPartialFailure", (info) => {
+                wireguardDebug(`[wireguard] Tunnel ${peerPublicKey.slice(0, 8)}... flush: ${info.failed}/${info.total} messages failed\n`);
+            });
+            tunnel.on("queueOverflow", (info) => {
+                wireguardDebug(`[wireguard] Tunnel ${peerPublicKey.slice(0, 8)}... queue overflow (${info.reason}), dropped=${info.dropped}\n`);
+            });
+            tunnel.on("messagesExpired", (info) => {
+                wireguardDebug(`[wireguard] Tunnel ${peerPublicKey.slice(0, 8)}... ${info.count} queued messages expired (TTL)\n`);
+            });
+            // Listen for messages received through the tunnel.
+            // Two message types are handled:
+            //   1. { ariaMessage: ... } — peer-to-peer AriaMessage (Transport 3)
+            //   2. { joinRequest: ... } — peer join-back credentials (sent via tunnel, not HTTP)
+            tunnel.on("plaintext", (data) => {
+                try {
+                    const parsed = JSON.parse(data.toString());
+                    const envelope = tools_1.RuntimeIngressEnvelopeSchema.safeParse(parsed);
+                    if (envelope.success) {
+                        if ("deliveryAck" in envelope.data) {
+                            const ack = envelope.data.deliveryAck;
+                            // Delivery ack sender/recipient identity is validated at the durable
+                            // mailbox/outbox boundary using NodeIds. The transport layer no
+                            // longer enforces stale display-name checks here.
+                            for (const listener of this._deliveryAckListeners) {
+                                listener(ack);
+                            }
+                            return;
+                        }
+                        if ("ariaMessage" in envelope.data) {
+                            const msg = envelope.data.ariaMessage;
+                            const claimedSenderNodeId = typeof msg === "object" && msg !== null
+                                ? msg.sender?.id
+                                : undefined;
+                            const parsedSenderNodeId = tools_1.NodeIdSchema.safeParse(claimedSenderNodeId);
+                            if (!parsedSenderNodeId.success ||
+                                !this.matchesPeerNodeIdClaim(parsedSenderNodeId.data, peerInfo)) {
+                                wireguardDebug(`[wireguard] Dropped tunnel message with sender principal mismatch for ${peerPublicKey.slice(0, 8)}... expected "${this.resolvePeerPrincipalId(peerInfo) ?? peerInfo.name}", got "${String(claimedSenderNodeId)}"\n`);
+                                return;
+                            }
+                            // Validate required AriaMessage fields before dispatch
+                            if (msg &&
+                                typeof msg === "object" &&
+                                "id" in msg &&
+                                typeof msg.id === "string" &&
+                                "sender" in msg &&
+                                "recipient" in msg &&
+                                "type" in msg &&
+                                typeof msg.type === "string" &&
+                                "content" in msg &&
+                                typeof msg.content === "string") {
+                                for (const ml of this._messageListeners) {
+                                    ml(msg);
+                                }
+                            }
+                            return;
+                        }
+                        if ("joinRequest" in envelope.data) {
+                            const jr = envelope.data.joinRequest;
+                            if (!jr.controlEndpoint) {
+                                return;
+                            }
+                            // Peer is sending join-back credentials through the tunnel.
+                            // Process asynchronously — tunnel event handlers are synchronous.
+                            void this.completeJoin({
+                                nodeId: jr.nodeId,
+                                principalFingerprint: signingKeyFingerprintFromPublicKey(jr.signingPublicKey),
+                                peerPublicKey: jr.peerPublicKey,
+                                peerSigningKey: jr.signingPublicKey,
+                                peerTransportEndpoint: jr.transportEndpoint,
+                                peerControlEndpoint: jr.controlEndpoint,
+                                displayNameSnapshot: jr.displayNameSnapshot,
+                                inviteTokenNonce: jr.inviteTokenNonce,
+                            }).catch(() => {
+                                // Non-fatal: join-back failed but tunnel is already active
+                            });
+                            return;
+                        }
+                    }
+                    if (parsed.controlRequest) {
+                        // WG Tunnel Control Protocol — peer-to-peer control operations
+                        // through the encrypted tunnel (no HTTPS needed post-pairing).
+                        void this.handleControlRequest(parsed.controlRequest, peerPublicKey, peerInfo, tunnel);
+                    }
+                    else if (parsed.controlResponse) {
+                        // Response to a control request we sent
+                        this.handleControlResponse(parsed.controlResponse, peerInfo);
+                    }
+                }
+                catch {
+                    // Not valid JSON — ignore (non-message tunnel traffic)
+                }
+            });
+        })();
+        this.pendingTunnelStarts.set(peerPublicKey, startPromise);
+        try {
+            await startPromise;
+        }
+        finally {
+            if (this.pendingTunnelStarts.get(peerPublicKey) === startPromise) {
+                this.pendingTunnelStarts.delete(peerPublicKey);
+            }
+        }
+        // NOTE: We do NOT overwrite endpointPort here. The WireGuard tunnel port
+        // is NOT the pinned mutating control endpoint. Transport and control
+        // endpoints are persisted independently to avoid restart-time drift.
+    }
+    /** Stop and remove a tunnel for a peer by durable node identity. */
+    stopTunnel(nodeId) {
+        const peer = this.resolvePeerByNodeId(nodeId, { includeRevoked: true });
+        if (!peer) {
+            return;
+        }
+        this.stopTunnelByTransportKey(peer.publicKey);
+    }
+    /** Transport-internal tunnel shutdown by transport key. */
+    stopTunnelByTransportKey(peerPublicKey) {
+        const tunnel = this.tunnels.get(peerPublicKey);
+        if (!tunnel) {
+            if (this.pendingTunnelStarts.has(peerPublicKey)) {
+                this.canceledTunnelStarts.add(peerPublicKey);
+            }
+            return;
+        }
+        const peerInfo = this.peerRegistry?.getWithPsk(peerPublicKey);
+        tunnel.stop();
+        this.tunnels.delete(peerPublicKey);
+        if (peerInfo) {
+            const nodeId = this.resolvePeerPrincipalId(peerInfo);
+            if (nodeId) {
+                for (const listener of this._transportListeners) {
+                    listener.onTransportDown?.(peerInfo.name, nodeId);
+                }
+            }
+        }
+    }
+    /** Compatibility surface for the typed network manager ref: revoke by durable peer principal. */
+    revokePeer(nodeId) {
+        return this.revoke(nodeId);
+    }
+    /** Get a tunnel by durable peer identity (for testing/inspection). */
+    getTunnel(nodeId) {
+        const peerPublicKey = this.resolveCurrentDirectRoutePeerPublicKeyByNodeId(nodeId);
+        return peerPublicKey ? this.tunnels.get(peerPublicKey) : undefined;
+    }
+    /** Get the number of active tunnels */
+    get activeTunnelCount() {
+        return this.tunnels.size;
+    }
+    /** Generate an invite token for a new peer */
+    resolveLocalInviteEndpoint() {
+        if (!this.config)
+            return null;
+        const nets = require("node:os").networkInterfaces();
+        for (const addrs of Object.values(nets)) {
+            for (const addr of addrs ?? []) {
+                if (!addr.internal && addr.family === "IPv4") {
+                    return { address: addr.address, port: this.config.listenPort };
+                }
+            }
+        }
+        return null;
+    }
+    invite(displayNameSnapshot, options) {
+        if (!this.config)
+            throw new Error("Network not initialized");
+        let endpoint = this.config.externalEndpoint;
+        if (!endpoint) {
+            // STUN failed (symmetric NAT, no internet, etc.) — fall back to local network address.
+            // This enables LAN pairing even without STUN. WAN peers need a coordination relay.
+            endpoint = this.resolveLocalInviteEndpoint() ?? undefined;
+            if (!endpoint) {
+                throw new Error("Cannot create invite — no reachable network address. STUN failed and no local network interface found.");
+            }
+        }
+        if (this.peerRegistry) {
+            const activeCount = this.peerRegistry.activeCount();
+            if (activeCount >= NetworkManager.MAX_PEERS) {
+                throw new Error(`Peer limit reached (${NetworkManager.MAX_PEERS}). Revoke inactive peers first.`);
+            }
+        }
+        // Also check tunnel count — prevents zombie peers with no tunnel
+        if (this.tunnels.size >= NetworkManager.MAX_PEERS) {
+            throw new Error(`Tunnel limit reached (${NetworkManager.MAX_PEERS}).`);
+        }
+        const inviteLabel = normalizeInviteLabel(displayNameSnapshot);
+        const inviteOptions = typeof options === "number"
+            ? { durationMs: options }
+            : {
+                durationMs: options?.durationMs,
+                controlEndpoint: options?.controlEndpoint,
+                transportHostOverride: options?.transportHostOverride,
+                nodeId: options?.nodeId ? tools_1.NodeIdSchema.parse(options.nodeId) : undefined,
+                caCert: options?.caCert,
+            };
+        if (typeof options === "object" && options !== null) {
+            assertNoUnexpectedActorKeys(options, ["durationMs", "controlEndpoint", "transportHostOverride", "nodeId", "caCert"], "invite");
+        }
+        const inviterControlEndpoint = inviteOptions.controlEndpoint ?? this._localControlEndpoint;
+        if (!inviterControlEndpoint) {
+            throw new Error("invite requires the local control endpoint advertisement");
+        }
+        const bootstrapCaCert = inviteOptions.caCert ?? this._localBootstrapCaCert;
+        if (!bootstrapCaCert?.trim()) {
+            throw new Error("invite requires bootstrap CA authority");
+        }
+        const localNodeId = this.localNodeId;
+        if (!localNodeId) {
+            throw new Error("invite requires an explicit runtime-owned local nodeId");
+        }
+        const localPrincipalFingerprint = trySigningKeyFingerprintFromPublicKey(this.config.signingPublicKey?.trim() ?? "");
+        if (!localPrincipalFingerprint) {
+            throw new Error("invite requires an explicit runtime-owned local signing principal");
+        }
+        if (inviterControlEndpoint.tlsServerIdentity?.trim() !== localPrincipalFingerprint) {
+            throw new Error("invite requires control endpoint tlsServerIdentity to match the signing principal fingerprint");
+        }
+        // Use config.listenPort (the shared socket's bound port) as the advertised
+        // WG endpoint port. The STUN-discovered externalEndpoint.port is from an
+        // ephemeral socket and may not match the shared socket's NAT mapping.
+        // For public IPs (no NAT), listenPort IS the correct port directly.
+        // For NAT, the STUN fix (Phase 1 nat.ts) will make externalEndpoint.port
+        // reflect the shared socket's mapping.
+        const { token, psk } = createInviteToken({
+            leaderPublicKey: this.config.publicKey,
+            nodeId: localNodeId,
+            audienceNodeId: inviteOptions.nodeId,
+            leaderDisplayNameSnapshot: this.getLocalDisplayNameSnapshot() ?? this.arionName,
+            host: inviteOptions.transportHostOverride?.trim() || endpoint.address,
+            port: this.config.listenPort,
+            controlEndpoint: inviterControlEndpoint,
+            displayNameSnapshot: inviteLabel,
+            durationMs: inviteOptions.durationMs,
+            signingPublicKey: this.config.signingPublicKey,
+            caCert: bootstrapCaCert,
+            coordinationUrl: this.config.coordinationUrl,
+            signingPrivateKey: this.config.signingPrivateKey,
+        });
+        const invite = decodeInviteToken(token);
+        // Register peer as pending in DB
+        if (this.peerRegistry) {
+            const pendingAudienceNodeId = inviteOptions.nodeId;
+            this.peerRegistry.upsert({
+                ...(pendingAudienceNodeId ? { nodeId: pendingAudienceNodeId } : {}),
+                publicKey: `pending-${crypto.randomBytes(8).toString("hex")}`,
+                name: inviteLabel ?? buildPendingInvitePlaceholderName(invite.tokenNonce),
+                presharedKey: psk,
+                inviteToken: invite.tokenNonce,
+                status: "pending",
+            });
+        }
+        return { token, psk };
+    }
+    /** Accept an invite from another ARIA instance */
+    async acceptInvite(token, options) {
+        // MAX_PEERS guard — prevent exceeding peer limit via invite acceptance
+        const activeCount = this.peerRegistry?.listActive().length ?? 0;
+        if (activeCount >= NetworkManager.MAX_PEERS) {
+            throw new Error(`Peer limit reached (${NetworkManager.MAX_PEERS}). Revoke inactive peers first.`);
+        }
+        const invite = decodeInviteToken(token);
+        const displayNameSnapshot = typeof options === "string" ? options : options?.displayNameSnapshot;
+        const localControlEndpoint = typeof options === "string" ? undefined : options?.controlEndpoint;
+        const expectedLeaderNodeId = typeof options === "string"
+            ? undefined
+            : options?.nodeId
+                ? tools_1.NodeIdSchema.parse(options.nodeId)
+                : undefined;
+        // Check expiry
+        if (invite.expiresAt > 0 && Date.now() > invite.expiresAt) {
+            throw new Error("Invite token has expired");
+        }
+        // P0-3: Atomic single-use enforcement — claim token in a SQLite transaction
+        // before any async operations. Eliminates the race window where two concurrent
+        // acceptInvite calls could both pass the check before either marks it consumed.
+        if (this.peerRegistry) {
+            if (!this.peerRegistry.claimToken(invite.tokenNonce)) {
+                throw new Error("Invite token has already been used");
+            }
+        }
+        try {
+            if (!this.config) {
+                await this.initialize();
+            }
+            const localConfig = this.config;
+            if (!localConfig) {
+                throw new Error("Network not initialized");
+            }
+            const localNodeId = localConfig.nodeId
+                ? tools_1.NodeIdSchema.parse(localConfig.nodeId)
+                : this.localNodeId;
+            if (!localNodeId) {
+                throw new Error("acceptInvite requires an explicit runtime-owned local nodeId");
+            }
+            if (invite.audienceNodeId && invite.audienceNodeId !== localNodeId) {
+                throw new Error("Invite token is not addressed to this peer");
+            }
+            if (expectedLeaderNodeId && invite.nodeId !== expectedLeaderNodeId) {
+                throw new Error("Invite token nodeId does not match expected leader nodeId");
+            }
+            const inviterNodeId = invite.nodeId?.trim();
+            if (!inviterNodeId) {
+                throw new Error("Invite token missing inviter durable nodeId");
+            }
+            const inviterLeaderNodeId = tools_1.NodeIdSchema.parse(inviterNodeId);
+            const resolvedDisplayNameSnapshot = invite.leaderDisplayNameSnapshot?.trim() || displayNameSnapshot?.trim() || "leader";
+            this.assertRemotePeerIdentity({
+                publicKey: invite.publicKey,
+                signingPublicKey: invite.signingPublicKey ?? null,
+                name: resolvedDisplayNameSnapshot,
+            }, "Invite peer");
+            const advertisedInviterControl = invite.controlEndpoint;
+            if (!advertisedInviterControl) {
+                throw new Error("Invite token missing inviter control endpoint advertisement");
+            }
+            if (!localControlEndpoint) {
+                throw new Error("acceptInvite requires the local control endpoint advertisement");
+            }
+            (0, tools_1.assertSupportedNetworkRuntimeProtocolVersion)(advertisedInviterControl.protocolVersion, "invite control endpoint");
+            (0, tools_1.assertSupportedNetworkRuntimeProtocolVersion)(localControlEndpoint.protocolVersion, "join control endpoint");
+            const peerInfo = {
+                publicKey: invite.publicKey,
+                nodeId: inviterLeaderNodeId,
+                name: resolvedDisplayNameSnapshot,
+                endpointHost: invite.host,
+                endpointPort: invite.port,
+                endpointRevision: advertisedInviterControl.endpointRevision ?? 0,
+                controlEndpointHost: advertisedInviterControl.host,
+                controlEndpointPort: advertisedInviterControl.port,
+                controlTlsCaFingerprint: advertisedInviterControl.tlsCaFingerprint,
+                controlEndpoint: {
+                    host: advertisedInviterControl.host,
+                    port: advertisedInviterControl.port,
+                    tlsCaFingerprint: advertisedInviterControl.tlsCaFingerprint,
+                    tlsServerIdentity: advertisedInviterControl.tlsServerIdentity,
+                    protocolVersion: advertisedInviterControl.protocolVersion,
+                    endpointRevision: advertisedInviterControl.endpointRevision ?? 0,
+                },
+                status: "pending_tunnel",
+                lastHandshake: null,
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+                signingPublicKey: invite.signingPublicKey ?? null,
+            };
+            const supersededPrincipalRows = invite.signingPublicKey
+                ? this.listSupersededPrincipalRows(invite.signingPublicKey, invite.publicKey, inviterLeaderNodeId)
+                : [];
+            if (this.peerRegistry) {
+                const db = this.peerRegistry["db"];
+                db.transaction(() => {
+                    for (const superseded of supersededPrincipalRows) {
+                        this.peerRegistry.delete(superseded.publicKey);
+                    }
+                    if (!this.peerRegistry) {
+                        throw new Error("Peer registry unavailable during invite acceptance");
+                    }
+                    this.peerRegistry.upsert({
+                        nodeId: inviterLeaderNodeId,
+                        publicKey: invite.publicKey,
+                        name: resolvedDisplayNameSnapshot,
+                        status: "pending_tunnel",
+                        endpointHost: invite.host,
+                        endpointPort: invite.port,
+                        endpointRevision: advertisedInviterControl.endpointRevision ?? 0,
+                        controlEndpointHost: advertisedInviterControl.host,
+                        controlEndpointPort: advertisedInviterControl.port,
+                        controlTlsCaFingerprint: advertisedInviterControl.tlsCaFingerprint,
+                        presharedKey: invite.psk,
+                        inviteToken: invite.tokenNonce,
+                        signingPublicKey: invite.signingPublicKey,
+                    });
+                })();
+            }
+            this.cleanupSupersededPrincipalRows(supersededPrincipalRows);
+            // Register leader's signing key if present in the invite token.
+            // This lets us verify signatures on messages from the leader.
+            if (invite.signingPublicKey) {
+                this.stagePendingPeerSigningKey({
+                    nodeId: inviterLeaderNodeId,
+                    peerPublicKey: invite.publicKey,
+                    displayNameSnapshot: resolvedDisplayNameSnapshot,
+                    signingPublicKey: invite.signingPublicKey,
+                });
+            }
+            this.reconcileDirectRouteOwnership();
+            // Store coordination URL from invite for peer discovery.
+            // This enables the accepting peer to discover other peers in the network.
+            if (invite.coordinationUrl && this.config && !this.config.coordinationUrl) {
+                this.config.coordinationUrl = invite.coordinationUrl;
+                this.persistConfig();
+            }
+            // Start tunnel for the newly accepted peer.
+            await this.startTunnelByTransportKey(invite.publicKey);
+            // Send our credentials back to the leader through the WireGuard tunnel.
+            // This avoids sending credentials over plaintext HTTP to the leader's public IP.
+            // The tunnel is already established at this point (startTunnel above).
+            if (this.config) {
+                const tunnel = this.tunnels.get(invite.publicKey);
+                let joinConfirmed = false;
+                const localControlTlsIdentity = localControlEndpoint.tlsServerIdentity?.trim() || undefined;
+                if (!localControlTlsIdentity) {
+                    throw new Error("acceptInvite join propagation requires an explicit tlsServerIdentity on the local control endpoint");
+                }
+                const localPrincipalFingerprint = typeof this.config.signingPublicKey === "string" &&
+                    this.config.signingPublicKey.trim().length > 0
+                    ? crypto
+                        .createHash("sha256")
+                        .update(Buffer.from(this.config.signingPublicKey, "base64"))
+                        .digest("hex")
+                    : undefined;
+                if (!localPrincipalFingerprint) {
+                    throw new Error("acceptInvite join propagation requires an explicit runtime-owned local signing principal");
+                }
+                // Bootstrap join mutates durable peer state, so it is addressed by the
+                // runtime-owned node principal while TLS still pins to the signing fingerprint.
+                if (localControlTlsIdentity !== localPrincipalFingerprint) {
+                    throw new Error("acceptInvite join propagation requires control endpoint tlsServerIdentity to match the signing principal fingerprint");
+                }
+                const joinTransportEndpoint = this.config.externalEndpoint ?? this.resolveLocalInviteEndpoint();
+                if (!joinTransportEndpoint) {
+                    throw new Error("acceptInvite join propagation requires a reachable transport endpoint");
+                }
+                const joinRequest = tools_1.JoinRequestSchema.parse({
+                    nodeId: localNodeId,
+                    principalFingerprint: tools_1.PrincipalFingerprintSchema.parse(localPrincipalFingerprint),
+                    protocolVersion: localControlEndpoint.protocolVersion,
+                    peerPublicKey: this.config.publicKey,
+                    signingPublicKey: this.config.signingPublicKey,
+                    transportEndpoint: {
+                        host: joinTransportEndpoint.address,
+                        port: this.config.listenPort,
+                    },
+                    controlEndpoint: localControlEndpoint,
+                    displayNameSnapshot: invite.displayNameSnapshot,
+                    inviteTokenNonce: invite.tokenNonce,
+                });
+                // Try tunnel first as a transport optimization only.
+                // Queueing plaintext locally is not proof that the remote peer received
+                // or durably committed our join credentials.
+                if (tunnel) {
+                    try {
+                        tunnel.sendPlaintext(Buffer.from(JSON.stringify({
+                            joinRequest,
+                        })));
+                    }
+                    catch {
+                        // Tunnel send failed — fall back to HTTP
+                    }
+                }
+                // Always require a confirmed bootstrap join response before treating the
+                // invite accept as successful. The tunnel send above may help delivery,
+                // but it is only a best-effort optimization until there is an explicit
+                // tunnel-level acknowledgement protocol.
+                const bootstrapCaCert = invite.caCert?.trim();
+                if (bootstrapCaCert) {
+                    const expectedTlsIdentity = advertisedInviterControl.tlsServerIdentity?.trim();
+                    if (!expectedTlsIdentity) {
+                        throw new Error("Invite control endpoint missing tlsServerIdentity for bootstrap TLS verification");
+                    }
+                    try {
+                        const challengeUrl = `https://${advertisedInviterControl.host}:${advertisedInviterControl.port}/api/v1/join/challenge`;
+                        const challengeRes = await (0, bootstrap_tls_js_1.bootstrapTlsRequest)(challengeUrl, {
+                            caCert: bootstrapCaCert,
+                            expectedTlsIdentity,
+                        });
+                        if (challengeRes.status !== 200) {
+                            throw new Error(`Join challenge failed: ${challengeRes.status}`);
+                        }
+                        const challengePayload = JSON.parse(challengeRes.body);
+                        if (!challengePayload.challenge || typeof challengePayload.challenge !== "string") {
+                            throw new Error("Join challenge missing challenge payload");
+                        }
+                        const proofOfWork = solveJoinProofOfWork(challengePayload.challenge, challengePayload.difficulty ?? 4);
+                        const joinUrl = `https://${advertisedInviterControl.host}:${advertisedInviterControl.port}/api/v1/join`;
+                        const joinBody = JSON.stringify({
+                            ...joinRequest,
+                            proofOfWork,
+                        });
+                        const joinRes = await (0, bootstrap_tls_js_1.bootstrapTlsRequest)(joinUrl, {
+                            method: "POST",
+                            body: joinBody,
+                            caCert: bootstrapCaCert,
+                            expectedTlsIdentity,
+                            headers: {
+                                "Content-Type": "application/json",
+                                "Content-Length": Buffer.byteLength(joinBody).toString(),
+                            },
+                        });
+                        if (joinRes.status !== 200) {
+                            throw new Error(`Join HTTP fallback failed: ${joinRes.status}`);
+                        }
+                        persistTrustedPeerCa(this.ariaDir, bootstrapCaCert);
+                        joinConfirmed = true;
+                    }
+                    catch (httpErr) {
+                        // Without a confirmed join response, the accept path must fail
+                        // closed. A queued tunnel write is not a completion signal.
+                        wireguardDebug(`[wireguard] HTTP join confirmation failed: ${httpErr instanceof Error ? httpErr.message : String(httpErr)}\n`);
+                    }
+                }
+                if (!joinConfirmed && invite.coordinationUrl?.trim()) {
+                    try {
+                        const relayUrl = new URL("/api/v1/invite-relay/join", invite.coordinationUrl).toString();
+                        const relayResponse = await fetch(relayUrl, {
+                            method: "POST",
+                            headers: {
+                                "Content-Type": "application/json",
+                            },
+                            body: JSON.stringify({
+                                inviteToken: token,
+                                joinRequest,
+                            }),
+                        });
+                        const relayPayload = (await relayResponse.json());
+                        if (!relayResponse.ok || relayPayload.joined !== true) {
+                            throw new Error(relayPayload.error ??
+                                `Invite relay fallback failed with status ${relayResponse.status}`);
+                        }
+                        if (bootstrapCaCert) {
+                            persistTrustedPeerCa(this.ariaDir, bootstrapCaCert);
+                        }
+                        joinConfirmed = true;
+                    }
+                    catch (relayErr) {
+                        wireguardDebug(`[wireguard] Invite relay fallback failed: ${relayErr instanceof Error ? relayErr.message : String(relayErr)}\n`);
+                    }
+                }
+                if (!joinConfirmed) {
+                    if (!this.revoke(invite.nodeId)) {
+                        this.stopTunnelByTransportKey(invite.publicKey);
+                        this._peerSigningKeys.delete(invite.publicKey);
+                        this.peerRegistry?.revoke(invite.publicKey);
+                    }
+                    throw new Error("Failed to confirm join credentials with leader via bootstrap HTTP join");
+                }
+            }
+            // Accepting an invite only proves that we validated the inviter's signed
+            // token and attempted to propagate our join credentials back. It does not
+            // prove that the round-trip join completed or that a verified signed
+            // message has been observed. Keep the accepter-side peer pending_tunnel
+            // until proof-driven activation occurs through verified ingress.
+            if (this.peerRegistry) {
+                this.peerRegistry.upsert({
+                    nodeId: inviterLeaderNodeId,
+                    publicKey: invite.publicKey,
+                    name: resolvedDisplayNameSnapshot,
+                    status: "pending_tunnel",
+                });
+            }
+            peerInfo.status = "pending_tunnel";
+            return peerInfo;
+        }
+        catch (err) {
+            // P0-3: Release the atomic token claim so the token can be retried
+            this.peerRegistry?.releaseToken(invite.tokenNonce);
+            throw err;
+        }
+    }
+    /**
+     * Complete the join process — upgrade a pending peer to active with real credentials.
+     *
+     * Called by the leader when a peer POSTs its credentials back after accepting an invite.
+     * Removes the pending placeholder entry and registers the real peer with its actual
+     * WireGuard public key, signing key, and endpoint.
+     */
+    async completeJoin(params) {
+        if (!this.peerRegistry)
+            throw new Error("No peer registry");
+        if (!params.inviteTokenNonce || typeof params.inviteTokenNonce !== "string") {
+            throw new Error("Join request missing invite token nonce");
+        }
+        // Resolve pending invite by token nonce first (immutable identity anchor).
+        let pending = this.peerRegistry.getPendingByInviteToken(params.inviteTokenNonce);
+        if (!pending || pending.status !== "pending" || !pending.publicKey.startsWith("pending-")) {
+            throw new Error(`No pending invite found for token nonce "${params.inviteTokenNonce}"`);
+        }
+        const pendingWithPsk = this.peerRegistry.getWithPsk(pending.publicKey);
+        const pendingToken = pendingWithPsk?.inviteToken;
+        if (!pendingToken || pendingToken !== params.inviteTokenNonce) {
+            throw new Error("Join request token nonce does not match pending invite");
+        }
+        if (pending.nodeId && params.nodeId !== pending.nodeId) {
+            throw new Error("Join request nodeId mismatch for pending invite");
+        }
+        // THEN check peer limit (only for valid invites)
+        const activeCount = this.peerRegistry.activeCount();
+        if (activeCount >= NetworkManager.MAX_PEERS) {
+            throw new Error(`Peer limit reached (${NetworkManager.MAX_PEERS}). Revoke inactive peers first.`);
+        }
+        assertValidPeerPublicKeyB64(params.peerPublicKey, "Join peer public key");
+        assertValidSigningPublicKeyB64(params.peerSigningKey, "Join peer signing key");
+        const transportEndpointResult = tools_1.TransportEndpointAdvertisementSchema.safeParse(params.peerTransportEndpoint);
+        if (!transportEndpointResult.success) {
+            throw new Error("Join peer transport endpoint is invalid");
+        }
+        const controlEndpointResult = tools_1.ControlEndpointAdvertisementSchema.safeParse(params.peerControlEndpoint);
+        if (!controlEndpointResult.success) {
+            throw new Error("Join peer control endpoint is invalid");
+        }
+        const authoritativeDisplayName = params.displayNameSnapshot?.trim() || pending.nodeId || params.nodeId;
+        if (!/^[a-zA-Z0-9_-]{1,64}$/.test(authoritativeDisplayName)) {
+            throw new Error("Join peer name must match ^[a-zA-Z0-9_-]{1,64}$");
+        }
+        const peerTransportEndpoint = transportEndpointResult.data;
+        const peerControlEndpoint = controlEndpointResult.data;
+        const peerPrincipalFingerprint = trySigningKeyFingerprintFromPublicKey(params.peerSigningKey);
+        if (!peerPrincipalFingerprint) {
+            throw new Error("Join peer signing key could not derive a principal fingerprint");
+        }
+        if (peerPrincipalFingerprint !== params.principalFingerprint) {
+            throw new Error("Join peer principal fingerprint does not match the signing key");
+        }
+        if (peerControlEndpoint.tlsServerIdentity !== peerPrincipalFingerprint) {
+            throw new Error("Join peer control endpoint tlsServerIdentity must match the signing principal fingerprint");
+        }
+        // Use the invite-bound display snapshot as the single authority here.
+        // The join request may carry a snapshot for diagnostics, but it must never
+        // decide which pending invite row is completed or rename the invite target.
+        const effectiveName = this.resolveUniquePeerName(authoritativeDisplayName, params.peerSigningKey);
+        this.assertRemotePeerIdentity({
+            publicKey: params.peerPublicKey,
+            signingPublicKey: params.peerSigningKey,
+            name: effectiveName,
+        }, "Join peer");
+        // Atomically remove the pending placeholder and register the real peer as
+        // pending_verification. Join completion transports credentials and endpoint
+        // advertisements, but it is not identity proof. Activation only happens
+        // after the first successfully verified signed message.
+        const psk = pendingWithPsk?.presharedKey ?? undefined;
+        const db = this.peerRegistry["db"];
+        const supersededPrincipalRows = this.listSupersededPrincipalRows(params.peerSigningKey, params.peerPublicKey, params.nodeId);
+        db.transaction(() => {
+            for (const superseded of supersededPrincipalRows) {
+                this.peerRegistry.delete(superseded.publicKey);
+            }
+            this.peerRegistry.delete(pending.publicKey);
+            this.peerRegistry.upsert({
+                nodeId: params.nodeId,
+                publicKey: params.peerPublicKey,
+                name: effectiveName,
+                endpointHost: peerTransportEndpoint.host,
+                endpointPort: peerTransportEndpoint.port,
+                endpointRevision: peerControlEndpoint?.endpointRevision ?? 0,
+                controlEndpointHost: peerControlEndpoint?.host,
+                controlEndpointPort: peerControlEndpoint?.port,
+                controlTlsCaFingerprint: peerControlEndpoint?.tlsCaFingerprint,
+                presharedKey: psk,
+                status: "pending_verification",
+                signingPublicKey: params.peerSigningKey,
+                inviteToken: params.inviteTokenNonce,
+            });
+        })();
+        this.cleanupSupersededPrincipalRows(supersededPrincipalRows);
+        // Keep in-memory map and DB row synchronized for verification on restart
+        this.stagePendingPeerSigningKey({
+            nodeId: params.nodeId,
+            peerPublicKey: params.peerPublicKey,
+            displayNameSnapshot: effectiveName,
+            signingPublicKey: params.peerSigningKey,
+        });
+        this.reconcileDirectRouteOwnership();
+        // Start a tunnel to the peer so the first signed message can arrive.
+        // Do not promote to active here — activation is proof-driven.
+        await this.startTunnelByTransportKey(params.peerPublicKey);
+        return { effectiveName };
+    }
+    /** Record a heartbeat from a peer principal (updates last_handshake timestamp) */
+    heartbeat(nodeId) {
+        if (!this.peerRegistry)
+            return false;
+        const peerPublicKey = this.resolveUniqueLivePeerPublicKeyByNodeId(nodeId);
+        const peer = peerPublicKey ? this.peerRegistry.getWithPsk(peerPublicKey) : undefined;
+        if (!peer)
+            return false;
+        const { identityState } = (0, tools_1.derivePeerStateFromLegacyStatus)(peer);
+        if (!(0, tools_1.canHeartbeat)(identityState))
+            return false;
+        this.peerRegistry.updateHandshakeByNodeId(nodeId);
+        return true;
+    }
+    /**
+     * Apply a register/reconcile mutation by durable peer identity.
+     *
+     * This centralizes the peer-state checks that used to be reimplemented
+     * route-by-route using mutable display names.
+     */
+    applyPeerRegistration(input) {
+        if (!this.peerRegistry) {
+            return { registered: false, errorCode: "not_found" };
+        }
+        const peer = this.resolvePeerByNodeId(input.nodeId, { includeRevoked: true }) ?? undefined;
+        if (!peer) {
+            return { registered: false, errorCode: "not_found" };
+        }
+        const peerNodeId = input.nodeId;
+        const { identityState } = (0, tools_1.derivePeerStateFromLegacyStatus)(peer);
+        if (!(0, tools_1.canRefreshEndpoint)(identityState) && !(0, tools_1.canHeartbeat)(identityState)) {
+            if (peer.status === "active" || peer.status === "pending_verification") {
+                throw new Error(`Invariant violation: applyPeerRegistration blocked registerable peer state ${peer.status}`);
+            }
+            return { registered: false, errorCode: peer.status };
+        }
+        let endpointUpdated = false;
+        let endpointRevision = peer.endpointRevision ?? 0;
+        if (input.endpointHost && input.endpointPort) {
+            const requestedEndpointRevision = input.endpointRevision;
+            if (typeof requestedEndpointRevision !== "number" ||
+                !Number.isInteger(requestedEndpointRevision) ||
+                requestedEndpointRevision < 0) {
+                return { registered: false, errorCode: "missing_endpoint_revision" };
+            }
+            const endpointMutation = this.applyEndpointProjectionByTransportKey(peer.publicKey, input.endpointHost, input.endpointPort, requestedEndpointRevision);
+            if (endpointMutation.errorCode &&
+                endpointMutation.errorCode !== "stale_revision" &&
+                endpointMutation.errorCode !== "conflicting_revision") {
+                return { registered: false, errorCode: endpointMutation.errorCode };
+            }
+            endpointUpdated = endpointMutation.updated;
+            endpointRevision = endpointMutation.endpointRevision;
+        }
+        if (endpointUpdated) {
+            this.reconcileDirectRouteOwnership();
+        }
+        const heartbeatUpdated = this.heartbeat(peerNodeId);
+        return {
+            registered: true,
+            nodeId: peerNodeId,
+            ...(peer.name ? { displayNameSnapshot: peer.name } : {}),
+            peerStatus: peer.status,
+            lastSeen: Date.now(),
+            heartbeatUpdated,
+            endpointUpdated,
+            endpointRevision,
+        };
+    }
+    /** Revoke a peer's access */
+    revoke(nodeId) {
+        if (!this.peerRegistry)
+            return false;
+        const peer = this.peerRegistry.getByNodeId(nodeId);
+        if (!peer)
+            return false;
+        // Clean up relay fallback if active (prevents WebSocket + timer leak)
+        this.tearDownRelay(peer.publicKey);
+        // Stop the direct tunnel
+        this.stopTunnelByTransportKey(peer.publicKey);
+        // Evict signing key (prevents memory leak from historical peers)
+        this._peerSigningKeys.delete(peer.publicKey);
+        this.peerRegistry.revokeByNodeId(nodeId);
+        return true;
+    }
+    applyPeerRevocation(input) {
+        if (!this.peerRegistry) {
+            return { revoked: false, errorCode: "not_found" };
+        }
+        const peer = this.peerRegistry.getByNodeId(input.nodeId);
+        if (!peer) {
+            return { revoked: false, errorCode: "not_found" };
+        }
+        if (!peer.nodeId) {
+            return { revoked: false, errorCode: "not_found" };
+        }
+        const peerNodeId = peer.nodeId;
+        const signingPublicKey = peer.signingPublicKey ?? this.getDurablePeerSigningKey(peer.publicKey);
+        const fingerprint = input.fingerprint
+            ? input.fingerprint
+            : signingPublicKey
+                ? signingKeyFingerprintFromPublicKey(signingPublicKey)
+                : undefined;
+        if (!fingerprint) {
+            return { revoked: false, errorCode: "principal_unresolved" };
+        }
+        const revokedAt = Date.now();
+        this.revoke(input.nodeId);
+        return {
+            revoked: true,
+            nodeId: peerNodeId,
+            displayNameSnapshot: peer.name,
+            fingerprint: tools_1.PrincipalFingerprintSchema.parse(fingerprint),
+            revokedAt,
+        };
+    }
+    /** List all peers */
+    listPeers() {
+        if (!this.peerRegistry)
+            return [];
+        const routeOwnership = this.getDirectRouteOwnershipSnapshot();
+        return this.peerRegistry
+            .listAll()
+            .filter((peer) => !this.isLocalIdentityCandidate(peer))
+            .map((peer) => {
+            const routeDecision = routeOwnership.get(peer.publicKey);
+            const ownerPeer = routeDecision && routeDecision.ownerPublicKey !== peer.publicKey
+                ? this.peerRegistry?.getWithPsk(routeDecision.ownerPublicKey)
+                : undefined;
+            const routeOwnerNodeId = ownerPeer ? this.resolvePeerPrincipalId(ownerPeer) : null;
+            const tunnel = routeDecision?.ownership === "superseded" ? undefined : this.tunnels.get(peer.publicKey);
+            const sessionState = routeDecision?.ownership === "superseded"
+                ? "none"
+                : tunnel
+                    ? tunnel.getState()
+                    : "none";
+            const membershipStatus = peer.status;
+            const deliveryReadiness = membershipStatus === "revoked" || routeDecision?.ownership === "superseded"
+                ? "cannot_address"
+                : sessionState === "connected"
+                    ? "can_send_now"
+                    : peer.nodeId
+                        ? "can_queue_only"
+                        : "cannot_address";
+            return {
+                ...peer,
+                membershipStatus,
+                routeOwnership: routeDecision?.ownership ?? "current",
+                routeOwnerNodeId,
+                sessionState,
+                deliveryReadiness,
+            };
+        });
+    }
+    listPendingInvites() {
+        if (!this.peerRegistry)
+            return [];
+        return this.peerRegistry
+            .listByStatus("pending")
+            .map((peer) => {
+            const peerWithPsk = this.peerRegistry?.getWithPsk(peer.publicKey);
+            const inviteId = peerWithPsk?.inviteToken ?? undefined;
+            if (!inviteId) {
+                return null;
+            }
+            return {
+                inviteId,
+                inviteLabel: extractPendingInviteLabel(peer.name),
+                createdAt: peer.createdAt,
+                expiresAt: null,
+            };
+        })
+            .filter((invite) => invite !== null);
+    }
+    cancelInvite(inviteId) {
+        if (!this.peerRegistry)
+            return false;
+        const pendingInvite = this.peerRegistry.getPendingByInviteToken(inviteId);
+        if (!pendingInvite) {
+            return false;
+        }
+        this.peerRegistry.revoke(pendingInvite.publicKey);
+        return true;
+    }
+    /**
+     * Update a peer's endpoint in the registry by durable peer identity.
+     *
+     * Called when a peer's STUN-discovered IP changes and is reported via
+     * the coordination server's POST /register endpoint.
+     */
+    updatePeerEndpoint(nodeId, host, port, endpointRevision) {
+        this.applyPeerRepair({
+            nodeId,
+            endpointHost: host,
+            endpointPort: port,
+            endpointRevision,
+        });
+    }
+    /**
+     * Apply a transport-only repair mutation by durable peer identity.
+     *
+     * This is the authoritative mutation boundary for operator-driven endpoint
+     * repair. It shares the same identity-state gate as register/discovery but
+     * does not manufacture a heartbeat side effect.
+     */
+    applyPeerRepair(input) {
+        if (!this.peerRegistry) {
+            return { repaired: false, errorCode: "not_found" };
+        }
+        const peer = this.resolvePeerByNodeId(input.nodeId, { includeRevoked: true }) ?? undefined;
+        if (!peer) {
+            return { repaired: false, errorCode: "not_found" };
+        }
+        if (!peer.nodeId) {
+            return { repaired: false, errorCode: "not_found" };
+        }
+        const peerNodeId = peer.nodeId;
+        const { identityState } = (0, tools_1.derivePeerStateFromLegacyStatus)(peer);
+        if (!(0, tools_1.canRefreshEndpoint)(identityState)) {
+            if (peer.status === "active" || peer.status === "pending_verification") {
+                throw new Error(`Invariant violation: applyPeerRepair blocked repairable peer state ${peer.status}`);
+            }
+            return { repaired: false, errorCode: peer.status };
+        }
+        if (!Number.isInteger(input.endpointRevision) || (input.endpointRevision ?? -1) < 0) {
+            return { repaired: false, errorCode: "missing_endpoint_revision" };
+        }
+        const endpointMutation = this.applyEndpointProjectionByTransportKey(peer.publicKey, input.endpointHost, input.endpointPort, input.endpointRevision);
+        if (endpointMutation.errorCode) {
+            return { repaired: false, errorCode: endpointMutation.errorCode };
+        }
+        if (endpointMutation.updated) {
+            this.reconcileDirectRouteOwnership();
+        }
+        return {
+            repaired: true,
+            nodeId: peerNodeId,
+            ...(peer.name ? { displayNameSnapshot: peer.name } : {}),
+            peerStatus: peer.status,
+            endpointUpdated: endpointMutation.updated,
+            endpointHost: input.endpointHost,
+            endpointPort: input.endpointPort,
+            endpointRevision: endpointMutation.endpointRevision,
+        };
+    }
+    /**
+     * Apply a transport endpoint projection after a NodeId-owned caller has already
+     * resolved the authoritative remote actor. Transport keys stay internal here.
+     */
+    applyEndpointProjectionByTransportKey(peerPublicKey, host, port, endpointRevision) {
+        if (!this.peerRegistry) {
+            return { updated: false, endpointRevision: 0 };
+        }
+        assertValidEndpointHost(host, "Peer endpoint host");
+        assertValidPort(port, "Peer endpoint port");
+        const peer = this.peerRegistry.getByPublicKey(peerPublicKey);
+        if (!peer) {
+            return { updated: false, endpointRevision: 0 };
+        }
+        const { identityState } = (0, tools_1.derivePeerStateFromLegacyStatus)(peer);
+        if (!(0, tools_1.canRefreshEndpoint)(identityState)) {
+            return {
+                updated: false,
+                endpointRevision: normalizeEndpointRevision(peer.endpointRevision),
+            };
+        }
+        if (!peer.nodeId) {
+            return {
+                updated: false,
+                endpointRevision: normalizeEndpointRevision(peer.endpointRevision),
+            };
+        }
+        if (!Number.isInteger(endpointRevision) || endpointRevision < 0) {
+            throw new Error("Peer endpoint revision must be a non-negative integer");
+        }
+        const revisionDecision = evaluateEndpointRevision({
+            currentHost: peer.endpointHost,
+            currentPort: peer.endpointPort,
+            currentRevision: peer.endpointRevision,
+            nextHost: host,
+            nextPort: port,
+            nextRevision: endpointRevision,
+        });
+        if (revisionDecision.kind === "stale") {
+            return {
+                updated: false,
+                endpointRevision: revisionDecision.currentRevision,
+                errorCode: "stale_revision",
+            };
+        }
+        if (revisionDecision.kind === "conflict") {
+            return {
+                updated: false,
+                endpointRevision: revisionDecision.currentRevision,
+                errorCode: "conflicting_revision",
+            };
+        }
+        const endpointChanged = peer.endpointHost !== host || peer.endpointPort !== port;
+        // Update live tunnel endpoint first. Persisting a DB endpoint that the
+        // live tunnel rejected creates split-brain state across restart boundaries.
+        // Applies to active and pending_verification peers: the latter still need
+        // fresh endpoints to deliver their first signed proof and recover after restart.
+        const tunnel = this.tunnels.get(peer.publicKey);
+        if (tunnel) {
+            const inner = tunnel.getInnerTunnel();
+            if (inner) {
+                inner.setPeerEndpoint(host, port);
+            }
+        }
+        // Persist only after live transport accepts the endpoint update.
+        this.peerRegistry.upsert({
+            nodeId: peer.nodeId,
+            publicKey: peer.publicKey,
+            name: peer.name,
+            endpointHost: host,
+            endpointPort: port,
+            endpointRevision: revisionDecision.revision,
+        });
+        return {
+            updated: revisionDecision.kind === "apply" ? endpointChanged : false,
+            endpointRevision: revisionDecision.revision,
+        };
+    }
+    /**
+     * Get the relay transport for a peer (if using DERP relay fallback).
+     * Returns the same { send } interface as tunnel transports for Mailbox compatibility.
+     */
+    getRelayTransport(peerPublicKey) {
+        return this.relayTransports.get(peerPublicKey);
+    }
+    /**
+     * Set up a DERP relay fallback for a peer.
+     *
+     * Called when a direct tunnel dies (MAX_RECONNECT_ATTEMPTS exhausted).
+     * Creates a DerpRelay connection and registers it as a transport.
+     * Periodically attempts to re-establish the direct tunnel via lightweight probe.
+     */
+    async setupRelayFallback(peerPublicKey, relay) {
+        this.relayTransports.set(peerPublicKey, relay);
+        this.relayUpgradeAttempts.set(peerPublicKey, 0);
+        // Notify listeners (Mailbox registration)
+        const peerInfo = this.peerRegistry?.getWithPsk(peerPublicKey);
+        if (peerInfo) {
+            const relayTransport = { sendPlaintext: (data) => relay.send(data) };
+            const nodeId = this.resolvePeerPrincipalId(peerInfo);
+            if (nodeId) {
+                for (const listener of this._transportListeners) {
+                    listener.onTransportUp?.(peerInfo.name, relayTransport, nodeId);
+                }
+            }
+        }
+        // Schedule first upgrade attempt
+        this.scheduleUpgradeProbe(peerPublicKey);
+    }
+    /**
+     * Schedule a lightweight probe to check if direct tunnel is possible.
+     * Uses exponential backoff: 5min → 10min → 20min → cap at 30min.
+     * On success, tears down relay and restores direct tunnel.
+     */
+    scheduleUpgradeProbe(peerPublicKey) {
+        const attempts = this.relayUpgradeAttempts.get(peerPublicKey) ?? 0;
+        const baseInterval = NetworkManager.RELAY_UPGRADE_INTERVAL_MS; // 5 min
+        const maxInterval = 30 * 60_000; // 30 min cap
+        const interval = Math.min(baseInterval * Math.pow(2, attempts), maxInterval);
+        const timer = setTimeout(async () => {
+            this.relayUpgradeTimers.delete(peerPublicKey);
+            // Skip if relay was already torn down
+            if (!this.relayTransports.has(peerPublicKey))
+                return;
+            if (this.getDirectRouteOwnershipForPublicKey(peerPublicKey)?.ownership === "superseded") {
+                this.tearDownRelay(peerPublicKey);
+                return;
+            }
+            const probeSuccess = await this.probeDirectConnection(peerPublicKey);
+            if (probeSuccess) {
+                // Direct path is alive — restore full tunnel
+                try {
+                    await this.startTunnelByTransportKey(peerPublicKey);
+                    const tunnel = this.tunnels.get(peerPublicKey);
+                    if (tunnel && tunnel.getState() === "connected") {
+                        this.tearDownRelay(peerPublicKey);
+                        wireguardDebug(`[wireguard] Direct tunnel restored for ${peerPublicKey.slice(0, 8)}... — relay disconnected\n`);
+                        return;
+                    }
+                }
+                catch {
+                    // startTunnel failed despite probe success — unusual, keep relay
+                }
+            }
+            // Probe failed — increment backoff and schedule next attempt
+            this.relayUpgradeAttempts.set(peerPublicKey, attempts + 1);
+            this.scheduleUpgradeProbe(peerPublicKey);
+        }, interval);
+        this.relayUpgradeTimers.set(peerPublicKey, timer);
+    }
+    /**
+     * Lightweight probe: create a temporary SecureTunnel, wait 5s for handshake.
+     * Returns true if peer is directly reachable, false otherwise.
+     * Does NOT create a persistent tunnel — just checks connectivity.
+     */
+    async probeDirectConnection(peerPublicKey) {
+        if (!this.config)
+            return false;
+        if (this.getDirectRouteOwnershipForPublicKey(peerPublicKey)?.ownership === "superseded") {
+            return false;
+        }
+        const peerInfo = this.peerRegistry?.getWithPsk(peerPublicKey);
+        if (!peerInfo || !peerInfo.endpointHost || !peerInfo.endpointPort)
+            return false;
+        const ips = this.computePeerIps(peerPublicKey);
+        const probe = new tunnel_js_1.SecureTunnel({
+            privateKey: this.config.privateKey,
+            peerPublicKey,
+            presharedKey: peerInfo.presharedKey ?? undefined,
+            keepalive: 25,
+            listenPort: 0,
+            peerHost: peerInfo.endpointHost ?? undefined,
+            peerPort: peerInfo.endpointPort ?? undefined,
+            tunnelSrcIp: ips.selfIp,
+            tunnelDstIp: ips.peerIp,
+        });
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                probe.stop();
+                resolve(false);
+            }, 5_000);
+            probe.on("handshake", () => {
+                clearTimeout(timeout);
+                probe.stop();
+                resolve(true);
+            });
+            probe.on("error", () => {
+                clearTimeout(timeout);
+                probe.stop();
+                resolve(false);
+            });
+            probe.start().catch(() => {
+                clearTimeout(timeout);
+                resolve(false);
+            });
+        });
+    }
+    /** Tear down relay for a peer and notify listeners */
+    tearDownRelay(peerPublicKey) {
+        const relay = this.relayTransports.get(peerPublicKey);
+        if (!relay)
+            return;
+        relay.disconnect();
+        this.relayTransports.delete(peerPublicKey);
+        this.relayUpgradeAttempts.delete(peerPublicKey);
+        const timer = this.relayUpgradeTimers.get(peerPublicKey);
+        if (timer) {
+            clearTimeout(timer);
+            this.relayUpgradeTimers.delete(peerPublicKey);
+        }
+        // Notify listeners (Mailbox unregistration)
+        const peerInfo = this.peerRegistry?.getWithPsk(peerPublicKey);
+        if (peerInfo) {
+            const nodeId = this.resolvePeerPrincipalId(peerInfo);
+            if (nodeId) {
+                for (const listener of this._transportListeners) {
+                    listener.onTransportDown?.(peerInfo.name, nodeId);
+                }
+            }
+        }
+    }
+    /** Reset relay upgrade backoff (call when STUN detects endpoint change) */
+    resetRelayUpgradeBackoff() {
+        for (const [peerPublicKey] of this.relayTransports) {
+            this.relayUpgradeAttempts.set(peerPublicKey, 0);
+            // Re-schedule with reset backoff
+            const timer = this.relayUpgradeTimers.get(peerPublicKey);
+            if (timer) {
+                clearTimeout(timer);
+                this.relayUpgradeTimers.delete(peerPublicKey);
+            }
+            this.scheduleUpgradeProbe(peerPublicKey);
+        }
+    }
+    /** Shut down all tunnels, relays, and clean up resources */
+    async shutdown() {
+        for (const key of this.pendingTunnelStarts.keys()) {
+            this.canceledTunnelStarts.add(key);
+        }
+        for (const [key, tunnel] of this.tunnels) {
+            tunnel.stop();
+        }
+        this.tunnels.clear();
+        // Close the shared UDP socket and WAIT for the OS to release the port.
+        // dgram.Socket.close() is async — without awaiting the callback, the port
+        // stays bound and the next daemon start fails with EADDRINUSE.
+        if (this.sharedSocket) {
+            const socket = this.sharedSocket;
+            this.sharedSocket = null;
+            this.sharedSocketHandlers.clear();
+            await new Promise((resolve) => {
+                try {
+                    socket.close(() => resolve());
+                }
+                catch {
+                    resolve(); // Socket already closed
+                }
+                // Safety timeout — don't hang shutdown if close callback never fires
+                setTimeout(resolve, 2000);
+            });
+        }
+        // Clean up relay connections and notify listeners
+        for (const [key] of this.relayTransports) {
+            this.tearDownRelay(key);
+        }
+        this.relayTransports.clear();
+        this.relayUpgradeAttempts.clear();
+        // Clear any remaining upgrade timers
+        for (const [key, timer] of this.relayUpgradeTimers) {
+            clearTimeout(timer);
+        }
+        this.relayUpgradeTimers.clear();
+    }
+    /** Get network status */
+    status() {
+        const peers = this.listPeers();
+        return {
+            configured: this.config !== null,
+            nodeId: this.config?.nodeId ?? null,
+            publicKey: this.config?.publicKey ?? null,
+            signingPublicKey: this.config?.signingPublicKey ?? null,
+            listenPort: this.config?.listenPort ?? null,
+            externalEndpoint: this.config?.externalEndpoint ?? null,
+            activePeers: peers.filter((p) => p.membershipStatus === "active" && p.routeOwnership !== "superseded").length,
+            totalPeers: peers.length,
+            activeTunnels: peers.filter((p) => p.sessionState !== "none").length,
+            connectedPeers: peers.filter((p) => p.sessionState === "connected").length,
+            handshakingPeers: peers.filter((p) => p.sessionState === "handshaking").length,
+            queueOnlyPeers: peers.filter((p) => p.deliveryReadiness === "can_queue_only").length,
+            supersededPeers: peers.filter((p) => p.routeOwnership === "superseded").length,
+        };
+    }
+    // =========================================================================
+    // WG Tunnel Control Protocol
+    //
+    // After pairing, ALL peer-to-peer control operations flow through the
+    // encrypted WG tunnel — no HTTPS needed. Two message types:
+    //
+    //   1. { controlRequest: { type, ... } }  — request from peer
+    //   2. { controlResponse: { type, ... } } — response to a request
+    //
+    // Supported control request types:
+    //   - "peerList"  → returns list of active peers
+    //   - "heartbeat" → updates last-seen timestamp
+    // =========================================================================
+    /** Handle an incoming control request from a peer through the WG tunnel. */
+    async handleControlRequest(request, _peerPublicKey, peerInfo, tunnel) {
+        if (!request || typeof request.type !== "string")
+            return;
+        switch (request.type) {
+            case "peerList": {
+                // Respond with the peer list through the same tunnel
+                const peers = this.listPeers().map((p) => ({
+                    nodeId: p.nodeId,
+                    displayNameSnapshot: p.name,
+                    name: p.name,
+                    publicKey: p.publicKey,
+                    status: p.status,
+                    endpointHost: p.endpointHost,
+                    endpointPort: p.endpointPort,
+                    lastHandshake: p.lastHandshake,
+                    createdAt: p.createdAt,
+                }));
+                tunnel.sendPlaintext(Buffer.from(JSON.stringify({ controlResponse: { type: "peerList", peers } })));
+                break;
+            }
+            case "heartbeat": {
+                const requesterNodeId = this.resolvePeerPrincipalId(peerInfo);
+                if (requesterNodeId) {
+                    this.heartbeat(requesterNodeId);
+                }
+                break;
+            }
+            default:
+                // Unknown control request type — ignore (forward compatibility)
+                break;
+        }
+    }
+    /** Pending peer list responses from control requests we sent, keyed by peer transport identity. */
+    pendingPeerListCallbacks = new Map();
+    /** Handle a control response from a peer (response to our request). */
+    handleControlResponse(response, peerInfo) {
+        if (!response || typeof response.type !== "string")
+            return;
+        if (response.type === "peerList" && Array.isArray(response.peers)) {
+            const callback = this.pendingPeerListCallbacks.get(peerInfo.publicKey);
+            if (callback) {
+                this.pendingPeerListCallbacks.delete(peerInfo.publicKey);
+                callback(response.peers);
+            }
+        }
+    }
+    resolvePeerPrincipalId(peer) {
+        if (peer.nodeId) {
+            return peer.nodeId;
+        }
+        if (this.config?.publicKey === peer.publicKey) {
+            return this.localNodeId ?? null;
+        }
+        return null;
+    }
+    getDurablePeerSigningKey(peerPublicKey) {
+        const signingPublicKey = this.peerRegistry?.getWithPsk(peerPublicKey)?.signingPublicKey ?? null;
+        if (!signingPublicKey) {
+            return null;
+        }
+        return trySigningKeyFingerprintFromPublicKey(signingPublicKey) ? signingPublicKey : null;
+    }
+    getPeerSigningFingerprintByPublicKey(peerPublicKey) {
+        const signingPublicKey = this.getDurablePeerSigningKey(peerPublicKey);
+        if (!signingPublicKey) {
+            return null;
+        }
+        return trySigningKeyFingerprintFromPublicKey(signingPublicKey);
+    }
+    /**
+     * Request the peer list from a remote peer through the WG tunnel.
+     * Returns a promise that resolves with the peer list or rejects on timeout.
+     */
+    requestPeerListViaTunnel(peerPublicKey, timeoutMs = 10_000) {
+        const tunnel = this.tunnels.get(peerPublicKey);
+        if (!tunnel)
+            return Promise.reject(new Error("No tunnel to peer"));
+        const peerInfo = this.peerRegistry?.getWithPsk(peerPublicKey);
+        if (!peerInfo)
+            return Promise.reject(new Error("Peer not found in registry"));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingPeerListCallbacks.delete(peerPublicKey);
+                reject(new Error("Peer list request timed out"));
+            }, timeoutMs);
+            this.pendingPeerListCallbacks.set(peerPublicKey, (peers) => {
+                clearTimeout(timer);
+                resolve(peers);
+            });
+            tunnel.sendPlaintext(Buffer.from(JSON.stringify({ controlRequest: { type: "peerList" } })));
+        });
+    }
+    /**
+     * Send a heartbeat through the WG tunnel to a peer.
+     * This is usually unnecessary — WG handshake timestamps track liveness —
+     * but can be used for application-layer keepalive.
+     */
+    sendHeartbeatViaTunnel(peerPublicKey) {
+        const tunnel = this.tunnels.get(peerPublicKey);
+        if (!tunnel)
+            return;
+        tunnel.sendPlaintext(Buffer.from(JSON.stringify({ controlRequest: { type: "heartbeat" } })));
+    }
+}
+exports.NetworkManager = NetworkManager;
+//# sourceMappingURL=network.js.map