@decentnetwork/lan 0.1.0

package/dist/router/ip-parser.js

@@ -0,0 +1,127 @@
+/**
+ * IPv4 packet parser
+ * Extracts source/dest IP, protocol, and (for TCP/UDP) ports
+ */
+import { IP_PROTO_TCP, IP_PROTO_UDP } from "./types.js";
+export class IpParser {
+    /**
+     * Parse an IPv4 packet.
+     * Returns null if not a valid IPv4 packet.
+     */
+    static parse(packet) {
+        if (packet.length < 20) {
+            return null;
+        }
+        // Version & header length (first byte)
+        const versionAndIhl = packet[0];
+        const version = (versionAndIhl >> 4) & 0x0f;
+        const ihl = versionAndIhl & 0x0f; // Header length in 32-bit words
+        if (version !== 4) {
+            return null; // Only IPv4 supported in MVP
+        }
+        const headerBytes = ihl * 4;
+        if (packet.length < headerBytes) {
+            return null;
+        }
+        // Protocol (byte 9)
+        const protocol = packet[9];
+        // Source IP (bytes 12-15)
+        const srcIp = `${packet[12]}.${packet[13]}.${packet[14]}.${packet[15]}`;
+        // Destination IP (bytes 16-19)
+        const dstIp = `${packet[16]}.${packet[17]}.${packet[18]}.${packet[19]}`;
+        const result = {
+            version,
+            protocol,
+            srcIp,
+            dstIp,
+        };
+        // For TCP/UDP, extract ports
+        if ((protocol === IP_PROTO_TCP || protocol === IP_PROTO_UDP) && packet.length >= headerBytes + 4) {
+            result.srcPort = (packet[headerBytes] << 8) | packet[headerBytes + 1];
+            result.dstPort = (packet[headerBytes + 2] << 8) | packet[headerBytes + 3];
+        }
+        return result;
+    }
+    /**
+     * Get the protocol name for logging.
+     */
+    static protoName(protocol) {
+        switch (protocol) {
+            case IP_PROTO_TCP:
+                return "tcp";
+            case IP_PROTO_UDP:
+                return "udp";
+            case 1:
+                return "icmp";
+            default:
+                return `proto-${protocol}`;
+        }
+    }
+    /**
+     * Check if protocol is TCP.
+     */
+    static isTcp(protocol) {
+        return protocol === IP_PROTO_TCP;
+    }
+    /**
+     * Check if protocol is UDP.
+     */
+    static isUdp(protocol) {
+        return protocol === IP_PROTO_UDP;
+    }
+    /**
+     * Build a minimal IPv4 packet header for testing.
+     * Returns a 20-byte header plus optional payload.
+     */
+    static buildIpv4Header(opts) {
+        const payloadLen = opts.payload?.length || 0;
+        const portsLen = opts.srcPort !== undefined && opts.dstPort !== undefined ? 4 : 0;
+        const totalLen = 20 + portsLen + payloadLen;
+        const packet = new Uint8Array(totalLen);
+        // Version=4, IHL=5
+        packet[0] = 0x45;
+        // DSCP/ECN
+        packet[1] = 0;
+        // Total length
+        packet[2] = (totalLen >> 8) & 0xff;
+        packet[3] = totalLen & 0xff;
+        // Identification
+        packet[4] = 0;
+        packet[5] = 0;
+        // Flags + Fragment offset
+        packet[6] = 0;
+        packet[7] = 0;
+        // TTL
+        packet[8] = 64;
+        // Protocol
+        packet[9] = opts.protocol;
+        // Header checksum (skip for testing)
+        packet[10] = 0;
+        packet[11] = 0;
+        // Source IP
+        const srcParts = opts.srcIp.split(".").map((s) => parseInt(s, 10));
+        packet[12] = srcParts[0];
+        packet[13] = srcParts[1];
+        packet[14] = srcParts[2];
+        packet[15] = srcParts[3];
+        // Destination IP
+        const dstParts = opts.dstIp.split(".").map((s) => parseInt(s, 10));
+        packet[16] = dstParts[0];
+        packet[17] = dstParts[1];
+        packet[18] = dstParts[2];
+        packet[19] = dstParts[3];
+        let offset = 20;
+        // Optional ports (TCP/UDP)
+        if (portsLen > 0) {
+            packet[offset++] = (opts.srcPort >> 8) & 0xff;
+            packet[offset++] = opts.srcPort & 0xff;
+            packet[offset++] = (opts.dstPort >> 8) & 0xff;
+            packet[offset++] = opts.dstPort & 0xff;
+        }
+        // Payload
+        if (opts.payload) {
+            packet.set(opts.payload, offset);
+        }
+        return packet;
+    }
+}

package/dist/router/packet-router.d.ts

@@ -0,0 +1,49 @@
+/**
+ * PacketRouter — main forwarding engine
+ *
+ * Flow:
+ *   TUN read -> parse IP -> IPAM lookup -> ACL check -> Carrier send
+ *   Carrier recv -> ACL check -> TUN write
+ */
+import { EventEmitter } from "events";
+import type { TunDevice } from "../tun/tun-device.js";
+import type { PeerManager } from "../carrier/peer-manager.js";
+import type { Ipam } from "../ipam/ipam.js";
+import type { AclEngine } from "../acl/acl-engine.js";
+import type { ForwardingStats } from "./types.js";
+export interface PacketRouterOptions {
+    tunDevice: TunDevice;
+    peerManager: PeerManager;
+    ipam: Ipam;
+    acl: AclEngine;
+}
+export declare class PacketRouter extends EventEmitter {
+    private tunDevice;
+    private peerManager;
+    private acl;
+    private sessionManager;
+    private logger;
+    private isRunning;
+    private listenedSessions;
+    private keepaliveTimer?;
+    private stats;
+    constructor(opts: PacketRouterOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Periodically send a 1-byte ping through each connected packet session
+     * so the Carrier crypto session doesn't idle out. The receiver's IpParser
+     * will reject the malformed IP packet (length<20) and silently drop it.
+     */
+    private sendKeepalivesToActiveSessions;
+    getStats(): ForwardingStats;
+    /**
+     * Handle outgoing packet (app -> TUN -> Carrier).
+     */
+    private handleOutgoingPacket;
+    /**
+     * Handle incoming packet (Carrier -> peer -> TUN).
+     */
+    private handleIncomingPacket;
+    private setupCarrierHandlers;
+}

package/dist/router/packet-router.js

@@ -0,0 +1,251 @@
+/**
+ * PacketRouter — main forwarding engine
+ *
+ * Flow:
+ *   TUN read -> parse IP -> IPAM lookup -> ACL check -> Carrier send
+ *   Carrier recv -> ACL check -> TUN write
+ */
+import { EventEmitter } from "events";
+import { IpParser } from "./ip-parser.js";
+import { SessionManager } from "./session-manager.js";
+import { Logger } from "../utils/logger.js";
+export class PacketRouter extends EventEmitter {
+    tunDevice;
+    peerManager;
+    acl;
+    sessionManager;
+    logger;
+    isRunning = false;
+    listenedSessions = new WeakSet();
+    keepaliveTimer;
+    stats = {
+        packetsForwarded: 0,
+        packetsReceived: 0,
+        packetsDenied: 0,
+        packetsDropped: 0,
+        activeSessions: 0,
+    };
+    constructor(opts) {
+        super();
+        this.tunDevice = opts.tunDevice;
+        this.peerManager = opts.peerManager;
+        this.acl = opts.acl;
+        this.sessionManager = new SessionManager({
+            peerManager: opts.peerManager,
+            ipam: opts.ipam,
+        });
+        this.logger = new Logger({ prefix: "PacketRouter" });
+        this.setupCarrierHandlers();
+    }
+    async start() {
+        if (this.isRunning)
+            return;
+        this.logger.info("Starting packet router");
+        this.isRunning = true;
+        // Listen for TUN packets
+        this.tunDevice.on("packet", (packet) => {
+            this.handleOutgoingPacket(packet).catch((err) => {
+                // "friend offline" / "no transport" / "Handshake timeout" are all
+                // expected when a peer's daemon isn't up or hasn't completed the
+                // Carrier session yet — they're informational, not errors. Drop
+                // them to debug so the operator's log shows real failures.
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes("offline") ||
+                    msg.includes("no transport") ||
+                    msg.includes("Handshake timeout")) {
+                    this.logger.debug(`Outgoing packet dropped: ${msg}`);
+                }
+                else {
+                    this.logger.error("Outgoing packet error:", err);
+                }
+            });
+        });
+        await this.tunDevice.startReadLoop();
+        // Periodic keepalive: send a tiny zero-byte packet through each active
+        // session every 10s. This keeps the Carrier crypto session alive (which
+        // times out at 32s of no data) so an idle TCP connection like SSH won't
+        // get reaped between user keystrokes.
+        this.keepaliveTimer = setInterval(() => {
+            this.sendKeepalivesToActiveSessions();
+        }, 10000);
+        this.logger.info("Packet router started");
+    }
+    async stop() {
+        if (!this.isRunning)
+            return;
+        this.logger.info("Stopping packet router");
+        this.isRunning = false;
+        if (this.keepaliveTimer) {
+            clearInterval(this.keepaliveTimer);
+            this.keepaliveTimer = undefined;
+        }
+        await this.tunDevice.stopReadLoop();
+        this.sessionManager.closeAll();
+        this.logger.info("Packet router stopped");
+    }
+    /**
+     * Periodically send a 1-byte ping through each connected packet session
+     * so the Carrier crypto session doesn't idle out. The receiver's IpParser
+     * will reject the malformed IP packet (length<20) and silently drop it.
+     */
+    async sendKeepalivesToActiveSessions() {
+        if (!this.isRunning)
+            return;
+        const peerIds = this.sessionManager.getActiveSessions();
+        for (const dstIp of peerIds) {
+            const session = this.sessionManager.getSession(dstIp);
+            if (!session?.isConnected())
+                continue;
+            try {
+                await session.send(new Uint8Array([0])); // 1-byte keepalive, dropped at receiver
+            }
+            catch {
+                // ignore — session may have just gone offline
+            }
+        }
+    }
+    getStats() {
+        return {
+            ...this.stats,
+            activeSessions: this.sessionManager.getActiveCount(),
+        };
+    }
+    /**
+     * Handle outgoing packet (app -> TUN -> Carrier).
+     */
+    async handleOutgoingPacket(packet) {
+        if (!this.isRunning)
+            return;
+        const parsed = IpParser.parse(packet);
+        if (!parsed) {
+            this.stats.packetsDropped++;
+            this.logger.debug("Dropped invalid IP packet");
+            return;
+        }
+        // Get our own pubkey for ACL (we are the source for outbound)
+        const srcPubkey = this.peerManager.getPubkey();
+        const proto = IpParser.protoName(parsed.protocol);
+        // Only forward TCP/UDP packets that have ports
+        if (parsed.dstPort === undefined && proto !== "icmp") {
+            this.stats.packetsDropped++;
+            return;
+        }
+        // ACL check (outbound)
+        if (parsed.dstPort !== undefined && (proto === "tcp" || proto === "udp")) {
+            const result = this.acl.evaluate({
+                srcPubkey,
+                dstIp: parsed.dstIp,
+                dstPort: parsed.dstPort,
+                srcPort: parsed.srcPort,
+                proto,
+                direction: "outbound",
+            });
+            if (!result.allowed) {
+                this.stats.packetsDenied++;
+                this.logger.debug(`Denied outbound: ${parsed.srcIp}:${parsed.srcPort || "-"} -> ${parsed.dstIp}:${parsed.dstPort} (${result.reason})`);
+                return;
+            }
+        }
+        // Get session for destination
+        const session = await this.sessionManager.getOrOpenSession(parsed.dstIp);
+        if (!session) {
+            this.stats.packetsDropped++;
+            this.logger.debug(`No peer for ${parsed.dstIp}, dropping`);
+            return;
+        }
+        // Send packet
+        try {
+            await session.send(packet);
+            this.stats.packetsForwarded++;
+            this.logger.debug(`Forwarded ${proto} ${parsed.srcIp}:${parsed.srcPort || "-"} -> ${parsed.dstIp}:${parsed.dstPort || "-"} (${packet.length} bytes)`);
+        }
+        catch (err) {
+            // Friend going offline mid-send is normal during connection flapping;
+            // log at debug rather than warn to avoid spamming the operator.
+            const msg = err instanceof Error ? err.message : String(err);
+            this.stats.packetsDropped++;
+            if (msg.includes("offline") || msg.includes("no transport")) {
+                this.logger.debug(`Drop ${parsed.dstIp}: ${msg}`);
+            }
+            else {
+                this.logger.warn(`Failed to forward to ${parsed.dstIp}: ${msg}`);
+            }
+        }
+    }
+    /**
+     * Handle incoming packet (Carrier -> peer -> TUN).
+     */
+    async handleIncomingPacket(srcPubkey, packet) {
+        if (!this.isRunning)
+            return;
+        const parsed = IpParser.parse(packet);
+        if (!parsed) {
+            this.stats.packetsDropped++;
+            this.logger.debug("Dropped invalid incoming IP packet");
+            return;
+        }
+        const proto = IpParser.protoName(parsed.protocol);
+        // ACL check (inbound)
+        if (parsed.dstPort !== undefined && (proto === "tcp" || proto === "udp")) {
+            const result = this.acl.evaluate({
+                srcPubkey,
+                dstIp: parsed.dstIp,
+                dstPort: parsed.dstPort,
+                srcPort: parsed.srcPort,
+                proto,
+                direction: "inbound",
+            });
+            if (!result.allowed) {
+                this.stats.packetsDenied++;
+                this.logger.debug(`Denied inbound: ${parsed.srcIp}:${parsed.srcPort || "-"} -> ${parsed.dstIp}:${parsed.dstPort} (${result.reason})`);
+                return;
+            }
+        }
+        // Write to TUN. A second isRunning check handles the shutdown race:
+        // Carrier keeps delivering packets via TCP relay even after we've
+        // closed the TUN device, and our PacketSession listeners are still
+        // attached. Without this guard, every late packet that arrives
+        // between TUN close and full session teardown produces a "TUN device
+        // not open" warning. Treat that case as a silent drop.
+        if (!this.isRunning || !this.tunDevice.isActive()) {
+            this.stats.packetsDropped++;
+            return;
+        }
+        try {
+            await this.tunDevice.write(packet);
+            this.stats.packetsReceived++;
+            this.logger.debug(`Received ${proto} ${parsed.srcIp}:${parsed.srcPort || "-"} -> ${parsed.dstIp}:${parsed.dstPort || "-"} (${packet.length} bytes)`);
+        }
+        catch (err) {
+            this.stats.packetsDropped++;
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes("TUN device not open")) {
+                // Late packet during shutdown — already covered by the guard
+                // above on most paths but the TUN can also close mid-write.
+                this.logger.debug(`Drop late inbound packet: ${msg}`);
+            }
+            else {
+                this.logger.warn(`Failed to write to TUN:`, err);
+            }
+        }
+    }
+    setupCarrierHandlers() {
+        // When PeerManager creates a session (inbound or outbound), register packet handler.
+        // Guard against double-attachment: this event fires from both the responder-side
+        // handshake-req handler and the initiator-side openPacketSession completion. Without
+        // the WeakSet check, each peer-arriving packet would be written to TUN twice, which
+        // shows up as `(DUP!)` ICMP replies on the sender side.
+        this.peerManager.on("session-opened", ({ pubkey }) => {
+            const session = this.peerManager.getSession(pubkey);
+            if (session && !this.listenedSessions.has(session)) {
+                this.listenedSessions.add(session);
+                this.sessionManager.registerInboundSession(pubkey, session);
+                session.on("packet", (packet) => {
+                    this.handleIncomingPacket(pubkey, packet).catch((err) => {
+                        this.logger.error("Incoming packet error:", err);
+                    });
+                });
+            }
+        });
+    }
+}

package/dist/router/session-manager.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Session Manager
+ * Manages packet sessions keyed by destination IP
+ */
+import type { PacketSession } from "../carrier/packet-session.js";
+import type { PeerManager } from "../carrier/peer-manager.js";
+import type { Ipam } from "../ipam/ipam.js";
+export declare class SessionManager {
+    private peerManager;
+    private ipam;
+    private sessions;
+    private opening;
+    private logger;
+    constructor(opts: {
+        peerManager: PeerManager;
+        ipam: Ipam;
+    });
+    /**
+     * Get or open a session to the peer responsible for dstIp.
+     * Coalesces concurrent calls to avoid multiple handshakes.
+     * Returns null if peer is unknown or offline.
+     */
+    getOrOpenSession(dstIp: string): Promise<PacketSession | null>;
+    /**
+     * Get session by destination IP (no handshake)
+     */
+    getSession(dstIp: string): PacketSession | null;
+    /**
+     * Register a session that was opened by remote peer (responder side).
+     * Called when PeerManager auto-creates session for inbound HANDSHAKE_REQ.
+     */
+    registerInboundSession(srcPubkey: string, session: PacketSession): void;
+    /**
+     * Close session for a specific destination IP
+     */
+    closeSession(dstIp: string): void;
+    /**
+     * Close all sessions
+     */
+    closeAll(): void;
+    /**
+     * Get number of active sessions
+     */
+    getActiveCount(): number;
+    /**
+     * Get all active session destinations
+     */
+    getActiveSessions(): string[];
+    private openSession;
+}

package/dist/router/session-manager.js

@@ -0,0 +1,138 @@
+/**
+ * Session Manager
+ * Manages packet sessions keyed by destination IP
+ */
+import { Logger } from "../utils/logger.js";
+export class SessionManager {
+    peerManager;
+    ipam;
+    sessions = new Map(); // dstIp -> session
+    opening = new Map(); // dstIp -> in-flight handshake
+    logger;
+    constructor(opts) {
+        this.peerManager = opts.peerManager;
+        this.ipam = opts.ipam;
+        this.logger = new Logger({ prefix: "SessionManager" });
+        // Drop our IP→session cache when a friend's Carrier-level
+        // connection flips. PeerManager already closes the underlying
+        // PacketSession, but our map still holds the (now-closed)
+        // reference — and an isConnected() check during the brief
+        // window between the close() call and our re-keying race
+        // could return stale data. Belt-and-braces.
+        this.peerManager.on("friend-connection", (evt) => {
+            const record = this.ipam.resolveCarrierId(evt.pubkey);
+            if (record && this.sessions.has(record.virtualIp)) {
+                this.logger.debug(`Dropping ${record.name} (${record.virtualIp}) session on friend-${evt.status}`);
+                this.sessions.delete(record.virtualIp);
+            }
+        });
+    }
+    /**
+     * Get or open a session to the peer responsible for dstIp.
+     * Coalesces concurrent calls to avoid multiple handshakes.
+     * Returns null if peer is unknown or offline.
+     */
+    async getOrOpenSession(dstIp) {
+        // Already have session
+        const existing = this.sessions.get(dstIp);
+        if (existing && existing.isConnected()) {
+            return existing;
+        }
+        // In-flight handshake
+        const inFlight = this.opening.get(dstIp);
+        if (inFlight) {
+            return inFlight;
+        }
+        // Look up peer in IPAM
+        const record = this.ipam.resolveIp(dstIp);
+        if (!record) {
+            this.logger.debug(`No IPAM record for ${dstIp}`);
+            return null;
+        }
+        // Skip if friend isn't online — sendText() would otherwise queue
+        // packets via the slow express HTTP relay, which can't keep up with
+        // packet rates and produces error spam.
+        if (!this.peerManager.isFriendOnline(record.carrierId)) {
+            this.logger.debug(`Friend ${record.name} (${dstIp}) not online — dropping`);
+            return null;
+        }
+        // Open new session
+        const promise = this.openSession(dstIp, record.carrierId);
+        this.opening.set(dstIp, promise);
+        try {
+            const session = await promise;
+            this.sessions.set(dstIp, session);
+            return session;
+        }
+        finally {
+            this.opening.delete(dstIp);
+        }
+    }
+    /**
+     * Get session by destination IP (no handshake)
+     */
+    getSession(dstIp) {
+        return this.sessions.get(dstIp) || null;
+    }
+    /**
+     * Register a session that was opened by remote peer (responder side).
+     * Called when PeerManager auto-creates session for inbound HANDSHAKE_REQ.
+     */
+    registerInboundSession(srcPubkey, session) {
+        const record = this.ipam.resolveCarrierId(srcPubkey);
+        if (record) {
+            this.sessions.set(record.virtualIp, session);
+            this.logger.info(`Registered inbound session from ${record.name} (${record.virtualIp})`);
+        }
+        else {
+            this.logger.warn(`Inbound session from unknown peer ${srcPubkey}`);
+        }
+    }
+    /**
+     * Close session for a specific destination IP
+     */
+    closeSession(dstIp) {
+        const session = this.sessions.get(dstIp);
+        if (session) {
+            session.close();
+            this.sessions.delete(dstIp);
+        }
+    }
+    /**
+     * Close all sessions
+     */
+    closeAll() {
+        for (const session of this.sessions.values()) {
+            session.close();
+        }
+        this.sessions.clear();
+        this.opening.clear();
+    }
+    /**
+     * Get number of active sessions
+     */
+    getActiveCount() {
+        let count = 0;
+        for (const session of this.sessions.values()) {
+            if (session.isConnected())
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Get all active session destinations
+     */
+    getActiveSessions() {
+        const result = [];
+        for (const [dstIp, session] of this.sessions) {
+            if (session.isConnected()) {
+                result.push(dstIp);
+            }
+        }
+        return result;
+    }
+    async openSession(dstIp, carrierId) {
+        this.logger.info(`Opening session to ${dstIp} (carrier: ${carrierId.slice(0, 16)}...)`);
+        return await this.peerManager.openPacketSession(carrierId);
+    }
+}

package/dist/router/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Router types
+ */
+export interface ParsedPacket {
+    version: number;
+    protocol: number;
+    srcIp: string;
+    dstIp: string;
+    srcPort?: number;
+    dstPort?: number;
+}
+export declare const IP_PROTO_TCP = 6;
+export declare const IP_PROTO_UDP = 17;
+export declare const IP_PROTO_ICMP = 1;
+export interface ForwardingStats {
+    packetsForwarded: number;
+    packetsReceived: number;
+    packetsDenied: number;
+    packetsDropped: number;
+    activeSessions: number;
+}

package/dist/router/types.js

@@ -0,0 +1,6 @@
+/**
+ * Router types
+ */
+export const IP_PROTO_TCP = 6;
+export const IP_PROTO_UDP = 17;
+export const IP_PROTO_ICMP = 1;

package/dist/tun/index.d.ts

@@ -0,0 +1,3 @@
+export { TunDevice, type TunDeviceOptions } from "./tun-device.js";
+export { RouteManager } from "./route-manager.js";
+export type { TunDeviceConfig, RouteConfig, IpHeader } from "./types.js";

package/dist/tun/index.js

@@ -0,0 +1,2 @@
+export { TunDevice } from "./tun-device.js";
+export { RouteManager } from "./route-manager.js";