@aria-cli/wireguard 1.0.38 → 1.0.40

package/dist/resilient-tunnel.js

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * ResilientTunnel — wraps SecureTunnel with dead peer detection, auto-reconnection,
+ * and outbound message queuing.
+ *
+ * State machine:
+ *   CONNECTING → HANDSHAKING → CONNECTED → DISCONNECTED → RECONNECTING → HANDSHAKING → CONNECTED
+ *                                  ↓
+ *                               DEAD (max retries exhausted)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResilientTunnel = void 0;
+const node_events_1 = require("node:events");
+const tunnel_js_1 = require("./tunnel.js");
+class ResilientTunnel extends node_events_1.EventEmitter {
+    options;
+    tunnel = null;
+    _state = "connecting";
+    queue = [];
+    queueBytes = 0;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    deadPeerTimer = null;
+    lastPacketAt = 0;
+    reconnections = 0;
+    awaitingReplayReadiness = false;
+    stopped = false;
+    static MAX_QUEUE_SIZE = 1000;
+    static MAX_QUEUE_BYTES = 1_048_576; // 1MB
+    static MAX_RECONNECT_ATTEMPTS = 10;
+    // Safety-net timeout: fires only if neither peerActivity events nor the
+    // WG state machine's own REJECT_AFTER_TIME (180s) detect the dead peer.
+    // Must be longer than REJECT_AFTER_TIME to avoid premature disconnection
+    // when keepalives can't reach us (e.g. stale endpoint from STUN/WAN IP).
+    static DEAD_PEER_TIMEOUT_MS = 300_000; // 5 minutes
+    static MAX_BACKOFF_MS = 60_000;
+    static BASE_BACKOFF_MS = 1_000;
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    /** Start the resilient tunnel — creates underlying SecureTunnel and waits for remote proof before CONNECTED */
+    async start() {
+        if (this.stopped)
+            throw new Error("Tunnel has been stopped");
+        this.setState("connecting");
+        const port = await this.createAndStartTunnel();
+        if (this._state === "connecting") {
+            this.setState("handshaking");
+            this.requestSessionProof();
+        }
+        return port;
+    }
+    /** Send plaintext through the tunnel. Queues if not yet connected or reconnecting, throws if dead. */
+    sendPlaintext(data) {
+        if (this._state === "dead") {
+            throw new Error("Tunnel is dead — max reconnection attempts exhausted");
+        }
+        if (this._state === "connecting" ||
+            this._state === "handshaking" ||
+            this._state === "reconnecting" ||
+            this._state === "disconnected") {
+            this.enqueue(data);
+            // Don't call requestSessionProof() here — the initial handshake was
+            // already triggered by start(). Re-probing while a handshake is in
+            // progress risks calling encrypt() after the native tunnel processed
+            // a peer's init (state=None), which starts a NEW handshake that
+            // overwrites the pending initiator state in Handshake::previous.
+            // boringtun internally queues data sent via encrypt() during handshake.
+            return;
+        }
+        if (this._state !== "connected" || !this.tunnel) {
+            throw new Error(`Cannot send in state: ${this._state}`);
+        }
+        const activeTunnel = this.tunnel;
+        try {
+            activeTunnel.sendPlaintext(data);
+        }
+        catch (error) {
+            if (!this.stopped) {
+                this.enqueue(data);
+            }
+            throw error;
+        }
+        // If the send synchronously triggered a disconnect, preserve the payload
+        // for replay on the next reconnect instead of dropping the in-flight frame.
+        if (!this.stopped && this._state !== "connected") {
+            this.enqueue(data);
+            return;
+        }
+        if (!this.stopped && this.tunnel !== activeTunnel) {
+            this.enqueue(data);
+        }
+    }
+    /** Stop the tunnel permanently */
+    stop() {
+        this.stopped = true;
+        this.clearTimers();
+        if (this.tunnel) {
+            this.tunnel.removeAllListeners();
+            this.tunnel.stop();
+            this.tunnel = null;
+        }
+        this.queue = [];
+        this.queueBytes = 0;
+    }
+    /** Whether the tunnel is actively connected */
+    get isActive() {
+        return this._state === "connected";
+    }
+    /** Current tunnel state */
+    getState() {
+        return this._state;
+    }
+    /** Stats including reconnection count and queue depth */
+    getStats() {
+        return {
+            state: this._state,
+            reconnections: this.reconnections,
+            reconnectAttempts: this.reconnectAttempts,
+            queueDepth: this.queue.length,
+            queueBytes: this.queueBytes,
+        };
+    }
+    /** Get the underlying SecureTunnel (for event wiring, e.g. "plaintext") */
+    getInnerTunnel() {
+        return this.tunnel;
+    }
+    // ── Internal ─────────────────────────────────────────────────────
+    setState(newState) {
+        const prev = this._state;
+        if (prev === newState)
+            return;
+        this._state = newState;
+        this.emit("stateChange", newState, prev);
+    }
+    requestSessionProof() {
+        if (this.stopped || !this.tunnel) {
+            return;
+        }
+        if (this._state !== "handshaking" &&
+            !(this._state === "reconnecting" && this.awaitingReplayReadiness)) {
+            return;
+        }
+        try {
+            // Empty payload is a no-op at the application layer but still forces
+            // WireGuard to emit handshake traffic. This primes the route without
+            // falsely promoting the tunnel to CONNECTED.
+            this.tunnel.sendPlaintext(Buffer.alloc(0));
+        }
+        catch {
+            // Best-effort only: later outbound queueing or reconnect backoff can retry.
+        }
+    }
+    async createAndStartTunnel() {
+        if (this.tunnel) {
+            this.tunnel.removeAllListeners();
+            this.tunnel.stop();
+            this.tunnel = null;
+        }
+        const tunnel = new tunnel_js_1.SecureTunnel(this.options);
+        this.tunnel = tunnel;
+        // Wire events from inner tunnel
+        tunnel.on("plaintext", (data) => {
+            this.lastPacketAt = Date.now();
+            this.resetDeadPeerTimer();
+            this.promoteReconnectReady();
+            this.emit("plaintext", data);
+        });
+        tunnel.on("handshake", () => {
+            this.lastPacketAt = Date.now();
+            this.resetDeadPeerTimer();
+            this.promoteInitialReady();
+            this.promoteReconnectReady();
+            this.emit("handshake");
+        });
+        // WG keepalive responses produce write_to_tunnel with empty data.
+        // Without this, the dead-peer timer fires after 75s of no real
+        // plaintext, even though the peer is alive and exchanging keepalives.
+        tunnel.on("peerActivity", () => {
+            this.lastPacketAt = Date.now();
+            this.resetDeadPeerTimer();
+        });
+        tunnel.on("error", (err) => {
+            this.emit("error", err);
+            if (!this.stopped &&
+                (this._state === "handshaking" ||
+                    this._state === "connected" ||
+                    this._state === "reconnecting")) {
+                this.handleDisconnect();
+            }
+        });
+        tunnel.on("close", () => {
+            if (!this.stopped &&
+                (this._state === "handshaking" ||
+                    this._state === "connected" ||
+                    this._state === "reconnecting")) {
+                this.handleDisconnect();
+            }
+        });
+        try {
+            const port = await tunnel.start();
+            return port;
+        }
+        catch (err) {
+            // CRITICAL: Clean up listeners on failure to prevent accumulation
+            // after N failed reconnections (N×4 orphaned listeners → OOM)
+            tunnel.removeAllListeners();
+            tunnel.stop();
+            this.tunnel = null;
+            throw err;
+        }
+    }
+    disposeCurrentTunnel() {
+        if (!this.tunnel) {
+            return;
+        }
+        this.tunnel.removeAllListeners();
+        this.tunnel.stop();
+        this.tunnel = null;
+    }
+    handleDisconnect() {
+        this.awaitingReplayReadiness = false;
+        this.clearDeadPeerTimer();
+        this.disposeCurrentTunnel();
+        this.setState("disconnected");
+        this.attemptReconnect();
+    }
+    promoteInitialReady() {
+        if (this.stopped)
+            return;
+        if (this._state !== "connecting" && this._state !== "handshaking") {
+            return;
+        }
+        this.setState("connected");
+        this.resetDeadPeerTimer();
+        this.flushQueue();
+    }
+    promoteReconnectReady() {
+        if (!this.awaitingReplayReadiness || this.stopped) {
+            return;
+        }
+        this.finalizeReconnect();
+    }
+    finalizeReconnect() {
+        this.awaitingReplayReadiness = false;
+        this.reconnectAttempts = 0;
+        this.reconnections++;
+        this.setState("connected");
+        this.resetDeadPeerTimer();
+        this.flushQueue();
+        this.emit("reconnected");
+    }
+    attemptReconnect() {
+        if (this.stopped)
+            return;
+        if (this.reconnectTimer)
+            return;
+        if (this.reconnectAttempts >= ResilientTunnel.MAX_RECONNECT_ATTEMPTS) {
+            this.setState("dead");
+            this.emit("dead");
+            return;
+        }
+        this.setState("reconnecting");
+        const backoff = Math.min(ResilientTunnel.BASE_BACKOFF_MS * Math.pow(2, this.reconnectAttempts), ResilientTunnel.MAX_BACKOFF_MS);
+        this.reconnectAttempts++;
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = null;
+            if (this.stopped)
+                return;
+            try {
+                this.awaitingReplayReadiness = true;
+                await this.createAndStartTunnel();
+                // NOTE: Do NOT reset reconnectAttempts here. createAndStartTunnel()
+                // succeeding only means the UDP socket bound — the handshake has NOT
+                // completed yet. Reset happens in finalizeReconnect() when the peer
+                // proves liveness. Without this, an unreachable peer causes an infinite
+                // reconnect loop: start succeeds → error fires → counter resets → repeat.
+                if (this._state === "connected") {
+                    return;
+                }
+                this.requestSessionProof();
+            }
+            catch {
+                this.awaitingReplayReadiness = false;
+                // Reconnect failed — try again
+                this.attemptReconnect();
+            }
+        }, backoff);
+    }
+    resetDeadPeerTimer() {
+        this.clearDeadPeerTimer();
+        if (this.stopped || this._state !== "connected")
+            return;
+        this.deadPeerTimer = setTimeout(() => {
+            if (this._state === "connected" && !this.stopped) {
+                this.handleDisconnect();
+            }
+        }, ResilientTunnel.DEAD_PEER_TIMEOUT_MS);
+    }
+    clearDeadPeerTimer() {
+        if (this.deadPeerTimer) {
+            clearTimeout(this.deadPeerTimer);
+            this.deadPeerTimer = null;
+        }
+    }
+    clearTimers() {
+        this.clearDeadPeerTimer();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    enqueue(data) {
+        // Drop expired messages first
+        this.purgeExpired();
+        // Check capacity
+        if (this.queue.length >= ResilientTunnel.MAX_QUEUE_SIZE) {
+            process.stderr.write(`[ResilientTunnel] dropping message, queue overflow (maxSize: ${this.queue.length}/${ResilientTunnel.MAX_QUEUE_SIZE})\n`);
+            this.emit("queueOverflow", { reason: "maxSize", dropped: 1 });
+            return;
+        }
+        if (this.queueBytes + data.length > ResilientTunnel.MAX_QUEUE_BYTES) {
+            process.stderr.write(`[ResilientTunnel] dropping message, queue overflow (maxBytes: ${this.queueBytes + data.length}/${ResilientTunnel.MAX_QUEUE_BYTES})\n`);
+            this.emit("queueOverflow", { reason: "maxBytes", dropped: 1 });
+            return;
+        }
+        this.queue.push({ data, enqueuedAt: Date.now(), sendAttempts: 0 });
+        this.queueBytes += data.length;
+    }
+    purgeExpired() {
+        const now = Date.now();
+        const before = this.queue.length;
+        this.queue = this.queue.filter((msg) => {
+            if (msg.ttl !== undefined && now - msg.enqueuedAt > msg.ttl) {
+                this.queueBytes -= msg.data.length;
+                return false;
+            }
+            return true;
+        });
+        const expired = before - this.queue.length;
+        if (expired > 0) {
+            this.emit("messagesExpired", { count: expired });
+        }
+    }
+    flushQueue() {
+        if (!this.tunnel || this._state !== "connected")
+            return;
+        // Purge expired before flushing
+        this.purgeExpired();
+        const toSend = this.queue.splice(0);
+        this.queueBytes = 0;
+        const MAX_SEND_ATTEMPTS = 3;
+        const requeueFrom = (startIndex, currentMessage) => {
+            const replayQueue = [];
+            if (currentMessage) {
+                currentMessage.sendAttempts++;
+                if (currentMessage.sendAttempts < MAX_SEND_ATTEMPTS) {
+                    replayQueue.push(currentMessage);
+                }
+            }
+            replayQueue.push(...toSend.slice(startIndex + (currentMessage ? 1 : 0)));
+            if (replayQueue.length > 0) {
+                this.queue.unshift(...replayQueue);
+                this.queueBytes = replayQueue.reduce((sum, message) => sum + message.data.length, this.queueBytes);
+                this.emit("queueFlushPartialFailure", {
+                    failed: replayQueue.length,
+                    total: toSend.length,
+                });
+            }
+        };
+        for (let index = 0; index < toSend.length; index += 1) {
+            const msg = toSend[index];
+            try {
+                this.tunnel.sendPlaintext(msg.data);
+            }
+            catch {
+                requeueFrom(index, msg);
+                return;
+            }
+            if (this._state !== "connected") {
+                requeueFrom(index, msg);
+                return;
+            }
+        }
+    }
+}
+exports.ResilientTunnel = ResilientTunnel;
+//# sourceMappingURL=resilient-tunnel.js.map

package/dist/route-ownership.d.ts

@@ -0,0 +1,23 @@
+export type DirectRouteClaimStatus = "active" | "pending" | "pending_tunnel" | "pending_verification" | "revoked";
+export interface DirectRouteClaim {
+    publicKey: string;
+    nodeId?: string | null;
+    status: DirectRouteClaimStatus;
+    endpointHost?: string | null;
+    endpointPort?: number | null;
+    endpointRevision?: number | null;
+    createdAt: number;
+    updatedAt?: number | null;
+}
+export interface DirectRouteOwnershipDecision {
+    routeKey: string | null;
+    ownership: "current" | "superseded";
+    ownerPublicKey: string;
+    supersededByPublicKey?: string;
+}
+export declare function getDirectRouteKey(input: {
+    endpointHost?: string | null;
+    endpointPort?: number | null;
+}): string | null;
+export declare function resolveDirectRouteOwnership(claims: readonly DirectRouteClaim[]): Map<string, DirectRouteOwnershipDecision>;
+//# sourceMappingURL=route-ownership.d.ts.map

package/dist/route-ownership.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDirectRouteKey = getDirectRouteKey;
+exports.resolveDirectRouteOwnership = resolveDirectRouteOwnership;
+const network_runtime_1 = require("@aria-cli/tools/network-runtime");
+const STATUS_PRECEDENCE = {
+    pending_verification: 5,
+    pending_tunnel: 4,
+    active: 3,
+    pending: 2,
+    revoked: 1,
+};
+function getDirectRouteKey(input) {
+    const { endpointHost: host, endpointPort: port } = (0, network_runtime_1.canonicalizeAuthoritativeDirectEndpoint)(input);
+    if (!host || typeof port !== "number" || !Number.isFinite(port)) {
+        return null;
+    }
+    return `${host}:${port}`;
+}
+function compareRouteClaims(a, b) {
+    const precedenceDelta = STATUS_PRECEDENCE[b.status] - STATUS_PRECEDENCE[a.status];
+    if (precedenceDelta !== 0) {
+        return precedenceDelta;
+    }
+    const aEndpointRevision = a.endpointRevision ?? 0;
+    const bEndpointRevision = b.endpointRevision ?? 0;
+    if (aEndpointRevision !== bEndpointRevision) {
+        return bEndpointRevision - aEndpointRevision;
+    }
+    const aUpdatedAt = a.updatedAt ?? a.createdAt;
+    const bUpdatedAt = b.updatedAt ?? b.createdAt;
+    if (aUpdatedAt !== bUpdatedAt) {
+        return bUpdatedAt - aUpdatedAt;
+    }
+    if (a.createdAt !== b.createdAt) {
+        return b.createdAt - a.createdAt;
+    }
+    return a.publicKey.localeCompare(b.publicKey);
+}
+function resolveDirectRouteOwnership(claims) {
+    const decisions = new Map();
+    const byRouteKey = new Map();
+    for (const claim of claims) {
+        const routeKey = getDirectRouteKey(claim);
+        if (!routeKey) {
+            decisions.set(claim.publicKey, {
+                routeKey: null,
+                ownership: "current",
+                ownerPublicKey: claim.publicKey,
+            });
+            continue;
+        }
+        const bucket = byRouteKey.get(routeKey) ?? [];
+        bucket.push(claim);
+        byRouteKey.set(routeKey, bucket);
+    }
+    for (const [routeKey, bucket] of byRouteKey) {
+        const sorted = [...bucket].sort(compareRouteClaims);
+        const owner = sorted[0];
+        if (!owner) {
+            continue;
+        }
+        decisions.set(owner.publicKey, {
+            routeKey,
+            ownership: "current",
+            ownerPublicKey: owner.publicKey,
+        });
+        for (const superseded of sorted.slice(1)) {
+            decisions.set(superseded.publicKey, {
+                routeKey,
+                ownership: "superseded",
+                ownerPublicKey: owner.publicKey,
+                supersededByPublicKey: owner.publicKey,
+            });
+        }
+    }
+    return decisions;
+}
+//# sourceMappingURL=route-ownership.js.map

package/dist/tunnel.d.ts

@@ -0,0 +1,141 @@
+/**
+ * SecureTunnel — TypeScript transport layer wrapping the boringtun native addon.
+ *
+ * Manages the UDP socket, port forwarding (plaintext ↔ encrypted), and the
+ * 250ms timer loop that drives WireGuard's internal state machine. The native
+ * addon handles all cryptographic operations; this module handles I/O.
+ *
+ * Usage:
+ *   const tunnel = new SecureTunnel({ privateKey, peerPublicKey, listenPort });
+ *   await tunnel.start();
+ *   tunnel.sendPlaintext(Buffer.from("hello"));
+ *   tunnel.on("plaintext", (data) => console.log("received:", data));
+ *   tunnel.stop();
+ */
+import * as dgram from "node:dgram";
+import { EventEmitter } from "node:events";
+export interface PacketHandlingDisposition {
+    handled: boolean;
+    peerPublicKey: string;
+    outcome: "no_tunnel" | "done" | "write_to_network" | "write_to_tunnel" | "decrypt_error" | "decrypt_exception";
+    errorDetail?: string;
+}
+/**
+ * External shared UDP socket interface.
+ * When provided, SecureTunnel uses this socket instead of creating its own.
+ * This enables the single-port WireGuard architecture where NetworkManager
+ * owns ONE socket for ALL peers (like the real WireGuard kernel module).
+ */
+export interface ExternalSocket {
+    /** Send encrypted data to a peer through the shared socket */
+    send(data: Buffer, port: number, host: string, cb?: (err?: Error) => void): void;
+    /** The bound port of the shared socket (returned from start()) */
+    port: number;
+    /**
+     * Subscribe to incoming packets on the shared socket.
+     * The handler receives ALL packets — the tunnel must check if each packet
+     * belongs to it (via decrypt) and report whether it consumed the packet.
+     * Returns an unsubscribe function.
+     */
+    onPacket(handler: (msg: Buffer, rinfo: dgram.RemoteInfo) => PacketHandlingDisposition): () => void;
+}
+export interface SecureTunnelOptions {
+    /** Base64-encoded X25519 private key */
+    privateKey: string;
+    /** Base64-encoded X25519 peer public key */
+    peerPublicKey: string;
+    /** Optional preshared key (base64) */
+    presharedKey?: string;
+    /** Persistent keepalive interval in seconds (0 = disabled, default: 25) */
+    keepalive?: number;
+    /** Local UDP port for WireGuard protocol (default: random high port) */
+    listenPort?: number;
+    /** Peer's endpoint host */
+    peerHost?: string;
+    /** Peer's endpoint port */
+    peerPort?: number;
+    /** Tunnel-internal source IPv4 address as 32-bit integer (default: 10.0.0.1 = 0x0a000001) */
+    tunnelSrcIp?: number;
+    /** Tunnel-internal destination IPv4 address as 32-bit integer (default: 10.0.0.2 = 0x0a000002) */
+    tunnelDstIp?: number;
+    /**
+     * External shared UDP socket. When provided, the tunnel uses this socket
+     * instead of creating its own. This is the single-port WireGuard model
+     * where NetworkManager owns ONE socket for ALL peers.
+     */
+    externalSocket?: ExternalSocket;
+}
+export interface TunnelStats {
+    /** Bytes sent through the tunnel */
+    bytesSent: number;
+    /** Bytes received through the tunnel */
+    bytesReceived: number;
+    /** Number of successful handshakes */
+    handshakes: number;
+    /** Timestamp of last handshake (epoch ms) */
+    lastHandshake: number | null;
+    /** Whether the tunnel is currently active */
+    active: boolean;
+}
+/**
+ * Encrypted UDP tunnel backed by boringtun.
+ *
+ * Events:
+ *   - "plaintext": decrypted data received from peer
+ *   - "handshake": WireGuard handshake completed
+ *   - "error": tunnel or socket error
+ *   - "close": tunnel stopped
+ */
+/**
+ * Wrap arbitrary data in a minimal valid IPv4 packet for boringtun layer-3 tunnel.
+ *
+ * WireGuard is a layer-3 VPN — boringtun validates that decrypted plaintext is a
+ * valid IPv4 or IPv6 packet before returning it. Raw bytes are rejected with
+ * "InvalidPacket". This helper constructs a minimal 20-byte IPv4 header wrapping
+ * the given payload.
+ */
+declare function wrapIpv4(payload: Buffer, srcIp?: number, dstIp?: number): Buffer;
+/**
+ * Extract payload from an IPv4 packet by reading the IHL field.
+ * Optionally validates that the source IP matches the expected peer IP.
+ */
+declare function unwrapIpv4(packet: Buffer, expectedSourceIp?: number): Buffer;
+export { wrapIpv4, unwrapIpv4 };
+export declare class SecureTunnel extends EventEmitter {
+    private options;
+    private socket;
+    private tickTimer;
+    private tunnel;
+    private stats;
+    /** Tracks whether the first successful decrypt has occurred (handshake completed) */
+    private handshakeCompleted;
+    private peerHost;
+    private peerPort;
+    /** Unsubscribe function for external socket mode */
+    private externalSocketUnsub;
+    constructor(options: SecureTunnelOptions);
+    /** Start the tunnel — binds UDP socket, creates WireGuard tunnel, starts timer */
+    start(): Promise<number>;
+    /**
+     * Handle an incoming encrypted packet. Called either by our own socket
+     * or by the shared socket dispatcher (in shared socket mode).
+     *
+     * Returns true if this tunnel consumed the packet, false otherwise.
+     */
+    handleIncomingPacket(msg: Buffer, rinfo: dgram.RemoteInfo): boolean;
+    private classifyIncomingPacket;
+    /** Whether the tunnel is currently active */
+    get isActive(): boolean;
+    /** Send plaintext data through the encrypted tunnel */
+    sendPlaintext(data: Buffer): void;
+    /** Set or update the peer endpoint */
+    setPeerEndpoint(host: string, port: number): void;
+    /** Get tunnel statistics */
+    getStats(): TunnelStats;
+    private markAuthenticatedSessionProof;
+    /** Stop the tunnel — closes socket (or unsubscribes from shared), stops timer */
+    stop(): void;
+    /** Handle a WireGuard tunnel result */
+    private handleResult;
+}
+//# sourceMappingURL=tunnel.d.ts.map