@decentnetwork/lan 0.1.0

package/dist/tun/route-manager.d.ts

@@ -0,0 +1,59 @@
+/**
+ * TUN device + route management.
+ * Linux uses `ip` (iproute2). macOS uses `ifconfig` + `route`.
+ */
+import type { TunDeviceConfig } from "./types.js";
+export declare class RouteManager {
+    private logger;
+    private createdInterface;
+    private platform;
+    constructor();
+    /**
+     * Create and configure TUN interface (Linux only — on macOS the helper
+     * binary creates the utun device implicitly).
+     */
+    createTun(config: TunDeviceConfig): Promise<void>;
+    /**
+     * Configure an existing TUN interface (assign IP, bring up, add route).
+     * `name` here should be the ACTUAL device name (e.g. utun12 on macOS).
+     */
+    configureTun(config: TunDeviceConfig): Promise<void>;
+    private configureTunLinux;
+    private configureTunDarwin;
+    /**
+     * Remove TUN interface (Linux only — on macOS utun goes away when helper exits).
+     */
+    removeTun(name: string): Promise<void>;
+    /**
+     * Cleanup all routes and interface. Pass the daemon's actual TUN
+     * IP so we can also remove the macOS lo0 self-alias we added in
+     * configureTun; without that, the alias persists across daemon
+     * restarts (harmless, but leaks state).
+     */
+    cleanup(name: string, subnet: string, ip?: string): Promise<void>;
+    /**
+     * Enable IP forwarding (Linux only)
+     */
+    enableIpForwarding(): Promise<void>;
+    disableIpForwarding(): Promise<void>;
+    /**
+     * Setup NAT/masquerade — Linux iptables only (gateway mode).
+     * Not implemented on macOS in MVP.
+     */
+    setupMasquerade(subnet: string, outInterface: string, tunInterface: string): Promise<void>;
+    cleanupMasquerade(subnet: string, outInterface: string, tunInterface: string): Promise<void>;
+    private exec;
+    /**
+     * Convert "10.86.0.0/16" -> 16
+     */
+    private subnetToCidr;
+    /**
+     * Convert "10.86.0.0/16" -> "255.255.0.0"
+     */
+    private subnetToNetmask;
+    /**
+     * Convert "10.86.0.0/16" -> "10.86.0.0" (network address)
+     */
+    private subnetBase;
+    getCreatedInterface(): string | null;
+}

package/dist/tun/route-manager.js

@@ -0,0 +1,353 @@
+/**
+ * TUN device + route management.
+ * Linux uses `ip` (iproute2). macOS uses `ifconfig` + `route`.
+ */
+import { execSync } from "child_process";
+import { Logger } from "../utils/logger.js";
+export class RouteManager {
+    logger;
+    createdInterface = null;
+    platform;
+    constructor() {
+        this.logger = new Logger({ prefix: "RouteManager" });
+        if (process.platform === "darwin") {
+            this.platform = "darwin";
+        }
+        else {
+            this.platform = "linux";
+        }
+    }
+    /**
+     * Create and configure TUN interface (Linux only — on macOS the helper
+     * binary creates the utun device implicitly).
+     */
+    async createTun(config) {
+        if (this.platform === "darwin") {
+            // utun is auto-created by the helper; just configure
+            await this.configureTun(config);
+            return;
+        }
+        const { name } = config;
+        try {
+            this.logger.info(`Creating TUN interface: ${name}`);
+            this.exec(`ip tuntap add dev ${name} mode tun`);
+            this.createdInterface = name;
+            this.logger.info(`TUN device created: ${name}`);
+            await this.configureTun(config);
+        }
+        catch (error) {
+            this.logger.error(`Failed to create TUN: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Configure an existing TUN interface (assign IP, bring up, add route).
+     * `name` here should be the ACTUAL device name (e.g. utun12 on macOS).
+     */
+    async configureTun(config) {
+        if (this.platform === "darwin") {
+            return this.configureTunDarwin(config);
+        }
+        return this.configureTunLinux(config);
+    }
+    async configureTunLinux(config) {
+        const { name, ip, subnet } = config;
+        const mtu = config.mtu ?? 900;
+        this.exec(`ip link set ${name} mtu ${mtu}`);
+        this.exec(`ip link set ${name} up`);
+        this.logger.info(`Interface ${name} brought up (mtu=${mtu})`);
+        const cidr = this.subnetToCidr(subnet);
+        try {
+            this.exec(`ip addr add ${ip}/${cidr} dev ${name}`);
+            this.logger.info(`Assigned IP ${ip}/${cidr} to ${name}`);
+        }
+        catch (error) {
+            const msg = String(error);
+            if (msg.includes("File exists")) {
+                this.logger.debug(`IP ${ip}/${cidr} already assigned`);
+            }
+            else {
+                throw error;
+            }
+        }
+        try {
+            this.exec(`ip route add ${subnet} dev ${name}`);
+            this.logger.info(`Added route ${subnet} -> ${name}`);
+        }
+        catch (error) {
+            const msg = String(error);
+            if (msg.includes("File exists") || msg.includes("RTNETLINK answers: File exists")) {
+                this.logger.debug(`Route ${subnet} already exists`);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    async configureTunDarwin(config) {
+        const { name, ip, subnet } = config;
+        const netmask = this.subnetToNetmask(subnet);
+        const subnetBase = this.subnetBase(subnet);
+        const mtu = config.mtu ?? 900;
+        // utun on macOS is point-to-point. Standard pattern (WireGuard/Tailscale):
+        // assign IP as /32 host address, then add an explicit subnet route.
+        this.exec(`ifconfig ${name} inet ${ip} ${ip} netmask 255.255.255.255 up`);
+        // macOS ifconfig doesn't accept `mtu` as part of the inet assignment;
+        // it must be a separate invocation.
+        this.exec(`ifconfig ${name} mtu ${mtu}`);
+        this.logger.info(`Assigned IP ${ip}/32 to ${name} (point-to-point, mtu=${mtu})`);
+        // Add subnet route via the TUN interface
+        try {
+            this.exec(`route -n add -net ${subnetBase} -netmask ${netmask} -interface ${name}`);
+            this.logger.info(`Added route ${subnet} -> ${name}`);
+        }
+        catch (error) {
+            const msg = String(error);
+            if (msg.includes("File exists") || msg.includes("route already in table")) {
+                this.logger.debug(`Route ${subnet} already exists`);
+            }
+            else {
+                throw error;
+            }
+        }
+        // macOS doesn't auto-insert a host route for the TUN's own IP
+        // through lo0 the way Linux does, so a self-issued packet to
+        // <my-tun-ip> goes OUT through the utun device, arrives at our
+        // packet-router, and gets dropped (the daemon doesn't friend
+        // itself).
+        //
+        // Two pieces are needed to actually fix self-ping on macOS:
+        //   1) Add the IP as a /32 alias on lo0 (so the kernel CAN
+        //      deliver a packet for that IP locally).
+        //   2) Replace the auto-added utun host route with a lo0 host
+        //      route — `ifconfig <utun> inet <ip> <ip> netmask
+        //      255.255.255.255 up` implicitly inserts `<ip>/32 -> utun`
+        //      which beats the lo0 alias on specificity.
+        // Without (2), `route get <ip>` still says utun and self-pings
+        // time out. Same trick as Tailscale.
+        try {
+            this.exec(`ifconfig lo0 alias ${ip}/32`);
+            this.logger.debug(`Added lo0 alias for ${ip}`);
+        }
+        catch (error) {
+            const msg = String(error);
+            if (!msg.includes("File exists") && !msg.includes("already in list")) {
+                this.logger.warn(`lo0 alias ${ip} failed (self-ping won't work): ${msg}`);
+            }
+        }
+        try {
+            // macOS `route -n change -host <ip> -interface lo0` is misleading:
+            // it sets the GATEWAY column to "lo0" but leaves the Netif column
+            // pointing at utun10 — packets still get sent out the utun. The
+            // pattern that actually flips Netif is to specify a gateway IP
+            // that already lives on lo0 (127.0.0.1). The kernel then picks
+            // lo0 as the egress interface from the gateway's address.
+            // Delete-then-add is more reliable than `change` for this since
+            // an existing route with the wrong Netif can't be rewritten in
+            // one shot on all macOS versions.
+            try {
+                this.exec(`route -n delete -host ${ip}`);
+            }
+            catch {
+                // route wasn't there, fine
+            }
+            this.exec(`route -n add -host ${ip} 127.0.0.1`);
+            this.logger.info(`Routed self-IP ${ip} via lo0 (self-traffic shortcut)`);
+        }
+        catch (error) {
+            this.logger.warn(`Could not redirect self-IP ${ip} to lo0 — self-pings will time out: ${error}`);
+        }
+    }
+    /**
+     * Remove TUN interface (Linux only — on macOS utun goes away when helper exits).
+     */
+    async removeTun(name) {
+        if (this.platform === "darwin") {
+            // utun is auto-destroyed when the helper subprocess exits
+            this.logger.debug(`macOS utun ${name} cleaned up by helper exit`);
+            return;
+        }
+        try {
+            this.logger.info(`Removing TUN interface: ${name}`);
+            try {
+                this.exec(`ip link set ${name} down`);
+            }
+            catch {
+                // already down
+            }
+            this.exec(`ip tuntap del dev ${name} mode tun`);
+            this.createdInterface = null;
+            this.logger.info(`TUN device removed: ${name}`);
+        }
+        catch (error) {
+            this.logger.error(`Failed to remove TUN: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Cleanup all routes and interface. Pass the daemon's actual TUN
+     * IP so we can also remove the macOS lo0 self-alias we added in
+     * configureTun; without that, the alias persists across daemon
+     * restarts (harmless, but leaks state).
+     */
+    async cleanup(name, subnet, ip) {
+        try {
+            this.logger.info(`Cleaning up TUN and routes`);
+            if (this.platform === "darwin") {
+                const subnetBase = this.subnetBase(subnet);
+                const netmask = this.subnetToNetmask(subnet);
+                try {
+                    this.exec(`route -n delete -net ${subnetBase} -netmask ${netmask}`);
+                }
+                catch {
+                    // route might not exist
+                }
+                if (ip) {
+                    try {
+                        this.exec(`route -n delete -host ${ip}`);
+                        this.logger.debug(`Removed host route ${ip}`);
+                    }
+                    catch {
+                        // route wasn't there
+                    }
+                    try {
+                        this.exec(`ifconfig lo0 -alias ${ip}`);
+                        this.logger.debug(`Removed lo0 alias ${ip}`);
+                    }
+                    catch {
+                        // alias wasn't there
+                    }
+                }
+                // utun device cleanup is handled when helper exits
+                return;
+            }
+            try {
+                this.exec(`ip route del ${subnet} dev ${name}`);
+            }
+            catch {
+                // Route might not exist
+            }
+            try {
+                await this.removeTun(name);
+            }
+            catch {
+                // Interface might not exist
+            }
+        }
+        catch (error) {
+            this.logger.error(`Cleanup error: ${error}`);
+        }
+    }
+    /**
+     * Enable IP forwarding (Linux only)
+     */
+    async enableIpForwarding() {
+        if (this.platform === "darwin") {
+            try {
+                this.exec("sysctl -w net.inet.ip.forwarding=1");
+                this.logger.info("IP forwarding enabled (macOS)");
+            }
+            catch (error) {
+                this.logger.error(`Failed to enable IP forwarding: ${error}`);
+                throw error;
+            }
+            return;
+        }
+        try {
+            this.exec("sysctl -w net.ipv4.ip_forward=1");
+            this.logger.info("IP forwarding enabled");
+        }
+        catch (error) {
+            this.logger.error(`Failed to enable IP forwarding: ${error}`);
+            throw error;
+        }
+    }
+    async disableIpForwarding() {
+        try {
+            if (this.platform === "darwin") {
+                this.exec("sysctl -w net.inet.ip.forwarding=0");
+            }
+            else {
+                this.exec("sysctl -w net.ipv4.ip_forward=0");
+            }
+            this.logger.info("IP forwarding disabled");
+        }
+        catch (error) {
+            this.logger.warn(`Failed to disable IP forwarding: ${error}`);
+        }
+    }
+    /**
+     * Setup NAT/masquerade — Linux iptables only (gateway mode).
+     * Not implemented on macOS in MVP.
+     */
+    async setupMasquerade(subnet, outInterface, tunInterface) {
+        if (this.platform === "darwin") {
+            this.logger.warn("Masquerade not implemented on macOS in MVP");
+            return;
+        }
+        this.exec(`iptables -t nat -A POSTROUTING -o ${outInterface} -j MASQUERADE`);
+        this.exec(`iptables -A FORWARD -i ${tunInterface} -o ${outInterface} -j ACCEPT`);
+        this.exec(`iptables -A FORWARD -i ${outInterface} -o ${tunInterface} -m state --state RELATED,ESTABLISHED -j ACCEPT`);
+        this.logger.info(`Masquerade setup for ${subnet} (${tunInterface} -> ${outInterface})`);
+    }
+    async cleanupMasquerade(subnet, outInterface, tunInterface) {
+        if (this.platform === "darwin")
+            return;
+        for (const cmd of [
+            `iptables -t nat -D POSTROUTING -o ${outInterface} -j MASQUERADE`,
+            `iptables -D FORWARD -i ${tunInterface} -o ${outInterface} -j ACCEPT`,
+            `iptables -D FORWARD -i ${outInterface} -o ${tunInterface} -m state --state RELATED,ESTABLISHED -j ACCEPT`,
+        ]) {
+            try {
+                this.exec(cmd);
+            }
+            catch {
+                // best effort
+            }
+        }
+        this.logger.info(`Masquerade cleanup for ${subnet}`);
+    }
+    exec(command) {
+        this.logger.debug(`Executing: ${command}`);
+        try {
+            return execSync(command, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Command failed: ${command}\n${message}`);
+        }
+    }
+    /**
+     * Convert "10.86.0.0/16" -> 16
+     */
+    subnetToCidr(subnet) {
+        const parts = subnet.split("/");
+        if (parts.length === 2) {
+            return parseInt(parts[1], 10);
+        }
+        return 24;
+    }
+    /**
+     * Convert "10.86.0.0/16" -> "255.255.0.0"
+     */
+    subnetToNetmask(subnet) {
+        const cidr = this.subnetToCidr(subnet);
+        const mask = (0xffffffff << (32 - cidr)) >>> 0;
+        return [
+            (mask >>> 24) & 0xff,
+            (mask >>> 16) & 0xff,
+            (mask >>> 8) & 0xff,
+            mask & 0xff,
+        ].join(".");
+    }
+    /**
+     * Convert "10.86.0.0/16" -> "10.86.0.0" (network address)
+     */
+    subnetBase(subnet) {
+        const parts = subnet.split("/");
+        return parts[0];
+    }
+    getCreatedInterface() {
+        return this.createdInterface;
+    }
+}

package/dist/tun/tun-device.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TUN device abstraction for reading/writing IP packets
+ *
+ * Two modes:
+ *  - mockMode (default): in-memory packet queue, used for tests
+ *  - real mode: spawns a Go helper subprocess (bin/tun-helper-{platform})
+ *    that owns the TUN device and pipes packets via stdin/stdout with
+ *    4-byte big-endian length-prefix framing.
+ */
+import { EventEmitter } from "events";
+import type { TunDeviceConfig } from "./types.js";
+export interface TunDeviceOptions {
+    config: TunDeviceConfig;
+    mockMode?: boolean;
+    helperPath?: string;
+}
+export declare class TunDevice extends EventEmitter {
+    private config;
+    private logger;
+    private mockMode;
+    private helperPath?;
+    private isOpen;
+    private packetQueue;
+    private readLoopActive;
+    private helper?;
+    private stdinBuffer;
+    private actualDeviceName?;
+    constructor(opts: TunDeviceOptions);
+    open(): Promise<void>;
+    close(): Promise<void>;
+    write(packet: Uint8Array): Promise<void>;
+    read(timeoutMs?: number): Promise<Uint8Array>;
+    queuePacket(packet: Uint8Array): void;
+    startReadLoop(): Promise<void>;
+    stopReadLoop(): Promise<void>;
+    getConfig(): TunDeviceConfig;
+    isActive(): boolean;
+    getInterface(): string;
+    getVirtualIp(): string;
+    getSubnet(): string;
+    private openReal;
+    private waitForReady;
+    private handleStdoutData;
+    private findHelperBinary;
+}