@decentnetwork/lan 0.1.0

package/dist/acl/audit.js

@@ -0,0 +1,144 @@
+/**
+ * Audit logger for ACL decisions and connection events
+ * Append-only JSONL file format
+ */
+import { appendFileSync, readFileSync, mkdirSync, existsSync } from "fs";
+import { dirname } from "path";
+import { Logger } from "../utils/logger.js";
+export class AuditLog {
+    filePath;
+    logger;
+    buffer = [];
+    bufferLimit = 100; // Keep last N entries in memory for fast reads
+    constructor(filePath) {
+        this.filePath = filePath;
+        this.logger = new Logger({ prefix: "AuditLog" });
+        // Ensure parent dir exists
+        const dir = dirname(filePath);
+        mkdirSync(dir, { recursive: true });
+    }
+    /**
+     * Log an access attempt (allowed or denied)
+     */
+    logAccess(opts) {
+        this.write({
+            timestamp: Date.now(),
+            type: "access",
+            srcPubkey: opts.srcPubkey,
+            srcName: opts.srcName,
+            dstIp: opts.dstIp,
+            dstPort: opts.dstPort,
+            proto: opts.proto,
+            allowed: opts.allowed,
+            reason: opts.reason,
+        });
+    }
+    /**
+     * Log a grant event
+     */
+    logGrant(opts) {
+        this.write({
+            timestamp: Date.now(),
+            type: "grant",
+            srcName: opts.peer,
+            reason: `granted: tcp ${opts.ports.join(",")}${opts.expiresAt ? ` until ${new Date(opts.expiresAt).toISOString()}` : ""}${opts.purpose ? ` (${opts.purpose})` : ""}`,
+        });
+    }
+    /**
+     * Log a revoke event
+     */
+    logRevoke(peer, reason) {
+        this.write({
+            timestamp: Date.now(),
+            type: "revoke",
+            srcName: peer,
+            reason: reason || "revoked",
+        });
+    }
+    /**
+     * Log a connection event
+     */
+    logConnection(opts) {
+        this.write({
+            timestamp: Date.now(),
+            type: opts.type,
+            srcPubkey: opts.srcPubkey,
+        });
+    }
+    /**
+     * Log a CONNECT proxy tunnel opening.
+     */
+    logProxyOpen(opts) {
+        this.write({
+            timestamp: Date.now(),
+            type: "proxy_open",
+            srcName: opts.srcName,
+            dstIp: opts.srcIp,
+            proxyTarget: opts.target,
+        });
+    }
+    /**
+     * Log a CONNECT proxy tunnel closing.
+     */
+    logProxyClose(opts) {
+        this.write({
+            timestamp: Date.now(),
+            type: "proxy_close",
+            srcName: opts.srcName,
+            dstIp: opts.srcIp,
+            proxyTarget: opts.target,
+            bytesTransferred: opts.bytesTransferred,
+        });
+    }
+    /**
+     * Read recent entries (from buffer + tail of file)
+     */
+    readRecent(limit = 50) {
+        if (this.buffer.length >= limit) {
+            return this.buffer.slice(-limit);
+        }
+        // Read full file if buffer is short
+        if (!existsSync(this.filePath)) {
+            return this.buffer.slice();
+        }
+        try {
+            const content = readFileSync(this.filePath, "utf-8");
+            const lines = content.trim().split("\n").filter(Boolean);
+            const entries = [];
+            for (const line of lines.slice(-limit)) {
+                try {
+                    entries.push(JSON.parse(line));
+                }
+                catch {
+                    // Skip malformed lines
+                }
+            }
+            return entries;
+        }
+        catch (error) {
+            this.logger.error(`Failed to read audit log: ${error}`);
+            return this.buffer.slice();
+        }
+    }
+    /**
+     * Get all entries since a timestamp
+     */
+    readSince(timestamp) {
+        const entries = this.readRecent(10000); // Effectively "all recent"
+        return entries.filter((e) => e.timestamp >= timestamp);
+    }
+    write(entry) {
+        // Add to in-memory buffer
+        this.buffer.push(entry);
+        if (this.buffer.length > this.bufferLimit) {
+            this.buffer = this.buffer.slice(-this.bufferLimit);
+        }
+        // Append to file (JSONL)
+        try {
+            appendFileSync(this.filePath, JSON.stringify(entry) + "\n", "utf-8");
+        }
+        catch (error) {
+            this.logger.error(`Failed to write audit entry: ${error}`);
+        }
+    }
+}

package/dist/acl/index.d.ts

@@ -0,0 +1,4 @@
+export { AclEngine, type AclEngineOptions } from "./acl-engine.js";
+export { Policy } from "./policy.js";
+export { AuditLog } from "./audit.js";
+export type { AccessRequest, AccessResult } from "./types.js";

package/dist/acl/index.js

@@ -0,0 +1,3 @@
+export { AclEngine } from "./acl-engine.js";
+export { Policy } from "./policy.js";
+export { AuditLog } from "./audit.js";

package/dist/acl/policy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Policy file loader and manager
+ * Handles loading/saving ACL rules from YAML
+ */
+import type { PolicyConfig, AclRule } from "../types.js";
+export declare class Policy {
+    private config;
+    private filePath;
+    private logger;
+    constructor(config: PolicyConfig, filePath: string);
+    static load(filePath: string): Promise<Policy>;
+    static loadOrCreate(filePath: string): Promise<Policy>;
+    save(): Promise<void>;
+    getRules(): AclRule[];
+    getDefaultAction(): "allow" | "deny";
+    getRulesForPeer(peerIdentifier: string): AclRule[];
+    /**
+     * Add or replace a rule for a peer.
+     * If existing rule for same peer + direction, replaces it.
+     */
+    addRule(rule: AclRule): void;
+    /**
+     * Remove all rules for a peer.
+     */
+    removePeer(peerIdentifier: string): boolean;
+    /**
+     * Remove expired rules.
+     */
+    cleanupExpired(): number;
+    getConfig(): PolicyConfig;
+}

package/dist/acl/policy.js

@@ -0,0 +1,102 @@
+/**
+ * Policy file loader and manager
+ * Handles loading/saving ACL rules from YAML
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import yaml from "js-yaml";
+import { Logger } from "../utils/logger.js";
+export class Policy {
+    config;
+    filePath;
+    logger;
+    constructor(config, filePath) {
+        this.config = config;
+        this.filePath = filePath;
+        this.logger = new Logger({ prefix: "Policy" });
+    }
+    static async load(filePath) {
+        try {
+            const content = readFileSync(filePath, "utf-8");
+            const config = yaml.load(content);
+            return new Policy(config, filePath);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("ENOENT")) {
+                throw new Error(`Policy file not found: ${filePath}`);
+            }
+            throw error;
+        }
+    }
+    static async loadOrCreate(filePath) {
+        try {
+            return await Policy.load(filePath);
+        }
+        catch {
+            // Default to "allow" rather than "deny". Friends in the IPAM are
+            // already vetted (you accepted their friend request and assigned
+            // them a virtual IP), so further per-port gatekeeping mirrors what
+            // Tailscale does for tailnet members: trust the relationship, let
+            // the OS firewall + service-binding decide what's actually exposed.
+            // Operators who want strict per-port control can flip this to
+            // "deny" in policy.yaml and add explicit grants.
+            const config = {
+                defaultAction: "allow",
+                rules: [],
+            };
+            const policy = new Policy(config, filePath);
+            await policy.save();
+            return policy;
+        }
+    }
+    async save() {
+        const dir = dirname(this.filePath);
+        mkdirSync(dir, { recursive: true });
+        const content = yaml.dump(this.config, { lineWidth: -1 });
+        writeFileSync(this.filePath, content, "utf-8");
+        this.logger.info(`Policy saved to ${this.filePath}`);
+    }
+    getRules() {
+        return this.config.rules;
+    }
+    getDefaultAction() {
+        return this.config.defaultAction;
+    }
+    getRulesForPeer(peerIdentifier) {
+        return this.config.rules.filter((r) => r.peer === peerIdentifier);
+    }
+    /**
+     * Add or replace a rule for a peer.
+     * If existing rule for same peer + direction, replaces it.
+     */
+    addRule(rule) {
+        const direction = rule.direction || "inbound";
+        this.config.rules = this.config.rules.filter((r) => !(r.peer === rule.peer && (r.direction || "inbound") === direction));
+        this.config.rules.push(rule);
+        this.logger.info(`Added rule for peer ${rule.peer} (${direction})`);
+    }
+    /**
+     * Remove all rules for a peer.
+     */
+    removePeer(peerIdentifier) {
+        const initialLength = this.config.rules.length;
+        this.config.rules = this.config.rules.filter((r) => r.peer !== peerIdentifier);
+        const removed = this.config.rules.length < initialLength;
+        if (removed) {
+            this.logger.info(`Removed rules for peer ${peerIdentifier}`);
+        }
+        return removed;
+    }
+    /**
+     * Remove expired rules.
+     */
+    cleanupExpired() {
+        const now = Date.now();
+        const initialLength = this.config.rules.length;
+        this.config.rules = this.config.rules.filter((r) => !r.expiresAt || r.expiresAt > now);
+        return initialLength - this.config.rules.length;
+    }
+    getConfig() {
+        return this.config;
+    }
+}

package/dist/acl/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ACL & Policy types — re-exported from main types.ts
+ */
+export type { ProtocolType, AclRule, AclPermission, PolicyConfig, AuditEntry, } from "../types.js";
+export interface AccessRequest {
+    srcPubkey: string;
+    dstIp: string;
+    dstPort: number;
+    srcPort?: number;
+    proto: "tcp" | "udp";
+    direction: "inbound" | "outbound";
+    now?: Date;
+}
+export interface AccessResult {
+    allowed: boolean;
+    matchedRule?: string;
+    reason: string;
+}

package/dist/acl/types.js

@@ -0,0 +1,4 @@
+/**
+ * ACL & Policy types — re-exported from main types.ts
+ */
+export {};

package/dist/carrier/frame.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Packet framing for Carrier transport
+ *
+ * Frame format:
+ * [1 byte: magic 0xAA]
+ * [2 bytes: length (big-endian, includes payload only)]
+ * [2 bytes: session ID (big-endian)]
+ * [1 byte: opcode]
+ * [N bytes: payload]
+ */
+import type { PacketFrame } from "./types.js";
+export declare class FrameCodec {
+    static encode(packet: Uint8Array, sessionId: number, opcode?: number): Uint8Array;
+    static decode(data: Uint8Array): PacketFrame | null;
+    static isHandshakeRequest(opcode: number): boolean;
+    static isHandshakeAck(opcode: number): boolean;
+    static isData(opcode: number): boolean;
+}

package/dist/carrier/frame.js

@@ -0,0 +1,66 @@
+/**
+ * Packet framing for Carrier transport
+ *
+ * Frame format:
+ * [1 byte: magic 0xAA]
+ * [2 bytes: length (big-endian, includes payload only)]
+ * [2 bytes: session ID (big-endian)]
+ * [1 byte: opcode]
+ * [N bytes: payload]
+ */
+import { FRAME_MAGIC, FRAME_HEADER_SIZE, FRAME_OPCODE_DATA, } from "./types.js";
+export class FrameCodec {
+    static encode(packet, sessionId, opcode = FRAME_OPCODE_DATA) {
+        const payloadLength = packet.length;
+        const frameSize = FRAME_HEADER_SIZE + payloadLength;
+        const frame = new Uint8Array(frameSize);
+        let offset = 0;
+        // Magic byte
+        frame[offset++] = FRAME_MAGIC;
+        // Length (2 bytes, big-endian)
+        frame[offset++] = (payloadLength >> 8) & 0xff;
+        frame[offset++] = payloadLength & 0xff;
+        // Session ID (2 bytes, big-endian)
+        frame[offset++] = (sessionId >> 8) & 0xff;
+        frame[offset++] = sessionId & 0xff;
+        // Opcode
+        frame[offset++] = opcode;
+        // Payload
+        frame.set(packet, offset);
+        return frame;
+    }
+    static decode(data) {
+        if (data.length < FRAME_HEADER_SIZE) {
+            return null;
+        }
+        let offset = 0;
+        // Check magic
+        if (data[offset++] !== FRAME_MAGIC) {
+            return null;
+        }
+        // Length
+        const length = (data[offset] << 8) | data[offset + 1];
+        offset += 2;
+        // Session ID
+        const sessionId = (data[offset] << 8) | data[offset + 1];
+        offset += 2;
+        // Opcode
+        const opcode = data[offset++];
+        // Validate frame size
+        if (data.length < FRAME_HEADER_SIZE + length) {
+            return null;
+        }
+        // Extract payload
+        const payload = data.slice(offset, offset + length);
+        return { sessionId, opcode, payload };
+    }
+    static isHandshakeRequest(opcode) {
+        return opcode === 0x01;
+    }
+    static isHandshakeAck(opcode) {
+        return opcode === 0x02;
+    }
+    static isData(opcode) {
+        return opcode === FRAME_OPCODE_DATA;
+    }
+}

package/dist/carrier/index.d.ts

@@ -0,0 +1,5 @@
+export { PeerManager, type PeerManagerOptions } from "./peer-manager.js";
+export { PacketSession, type PacketSessionOptions } from "./packet-session.js";
+export { FrameCodec } from "./frame.js";
+export type { PeerIdentity, RemotePeer, FriendConnectionEvent, PacketFrame, } from "./types.js";
+export { FRAME_OPCODE_HANDSHAKE_REQ, FRAME_OPCODE_HANDSHAKE_ACK, FRAME_OPCODE_DATA, FRAME_MAGIC, FRAME_HEADER_SIZE, } from "./types.js";

package/dist/carrier/index.js

@@ -0,0 +1,4 @@
+export { PeerManager } from "./peer-manager.js";
+export { PacketSession } from "./packet-session.js";
+export { FrameCodec } from "./frame.js";
+export { FRAME_OPCODE_HANDSHAKE_REQ, FRAME_OPCODE_HANDSHAKE_ACK, FRAME_OPCODE_DATA, FRAME_MAGIC, FRAME_HEADER_SIZE, } from "./types.js";

package/dist/carrier/packet-session.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bidirectional packet session over Carrier friend connection
+ */
+import { EventEmitter } from "events";
+import type { PacketFrame } from "./types.js";
+export interface PacketSessionOptions {
+    peerId: string;
+    sessionId: number;
+    sendText: (text: string) => Promise<void>;
+    onClose?: () => void;
+}
+export declare class PacketSession extends EventEmitter {
+    private peerId;
+    private sessionId;
+    private sendText;
+    private isActive;
+    private handshakeTimeout;
+    private handshakePromise;
+    constructor(opts: PacketSessionOptions);
+    /**
+     * Mark session as active (responder side, after sending HANDSHAKE_ACK).
+     * Used by PeerManager when accepting incoming connections.
+     */
+    acceptIncoming(): void;
+    handshake(): Promise<void>;
+    send(packet: Uint8Array): Promise<void>;
+    handleIncomingFrame(frame: PacketFrame): void;
+    close(): void;
+    getPeerId(): string;
+    getSessionId(): number;
+    isConnected(): boolean;
+}

package/dist/carrier/packet-session.js

@@ -0,0 +1,151 @@
+/**
+ * Bidirectional packet session over Carrier friend connection
+ */
+import { EventEmitter } from "events";
+import { FrameCodec } from "./frame.js";
+import { FRAME_OPCODE_HANDSHAKE_REQ, FRAME_OPCODE_DATA, } from "./types.js";
+export class PacketSession extends EventEmitter {
+    peerId;
+    sessionId;
+    sendText;
+    isActive = false;
+    handshakeTimeout = null;
+    handshakePromise = null;
+    constructor(opts) {
+        super();
+        this.peerId = opts.peerId;
+        this.sessionId = opts.sessionId;
+        this.sendText = opts.sendText;
+        this.on("close", () => {
+            if (opts.onClose) {
+                opts.onClose();
+            }
+        });
+    }
+    /**
+     * Mark session as active (responder side, after sending HANDSHAKE_ACK).
+     * Used by PeerManager when accepting incoming connections.
+     */
+    acceptIncoming() {
+        this.isActive = true;
+        this.emit("session-active");
+    }
+    async handshake() {
+        if (this.isActive) {
+            return;
+        }
+        if (this.handshakePromise) {
+            return this.handshakePromise;
+        }
+        this.handshakePromise = new Promise((resolve, reject) => {
+            // Send handshake request
+            const frame = FrameCodec.encode(new Uint8Array(0), this.sessionId, FRAME_OPCODE_HANDSHAKE_REQ);
+            const frameBase64 = Buffer.from(frame).toString("base64");
+            // 30s default — Carrier express relay can add several seconds of latency
+            // for cross-region peers. Configurable via AGENTNET_HANDSHAKE_TIMEOUT_MS.
+            const timeoutMs = parseInt(process.env.AGENTNET_HANDSHAKE_TIMEOUT_MS || "30000", 10);
+            this.handshakeTimeout = setTimeout(() => {
+                reject(new Error(`Handshake timeout (${timeoutMs}ms) for peer ${this.peerId}`));
+            }, timeoutMs);
+            this.once("handshake-ack", () => {
+                if (this.handshakeTimeout) {
+                    clearTimeout(this.handshakeTimeout);
+                }
+                this.isActive = true;
+                this.handshakePromise = null;
+                resolve();
+            });
+            // If the session is closed mid-handshake (typical cause: the
+            // peer-manager re-issues a session cleanup on a friend-status
+            // flip), reject the in-flight promise so callers like
+            // sessionManager.openSession don't hang waiting on a session
+            // whose listeners are about to be removed.
+            this.once("handshake-aborted", () => {
+                if (this.handshakeTimeout) {
+                    clearTimeout(this.handshakeTimeout);
+                }
+                this.handshakePromise = null;
+                reject(new Error(`Handshake aborted for peer ${this.peerId}`));
+            });
+            this.sendText(frameBase64).catch((error) => {
+                if (this.handshakeTimeout) {
+                    clearTimeout(this.handshakeTimeout);
+                }
+                this.handshakePromise = null;
+                reject(error);
+            });
+        });
+        return this.handshakePromise;
+    }
+    async send(packet) {
+        if (!this.isActive) {
+            throw new Error("Packet session not active. Call handshake() first.");
+        }
+        const frame = FrameCodec.encode(packet, this.sessionId, FRAME_OPCODE_DATA);
+        const frameBase64 = Buffer.from(frame).toString("base64");
+        try {
+            await this.sendText(frameBase64);
+        }
+        catch (error) {
+            // Don't tear down the whole session for a single failed sendText —
+            // doing so triggers SessionManager to open a fresh session on the
+            // next packet, which sends another HANDSHAKE_REQ, which makes the
+            // peer churn through new sessionIds (old=N→new=N+1 in their logs).
+            // TCP retransmit covers per-packet loss; only kill the session on
+            // events that prove the underlying friend session is gone.
+            throw error;
+        }
+    }
+    handleIncomingFrame(frame) {
+        // Adopt the peer's sessionId rather than rejecting on mismatch.
+        //
+        // Background: each side picks its own sessionId when it first opens a
+        // PacketSession. After a Carrier re-pair the two sides can end up with
+        // different sessionIds for what is "morally" the same connection, and
+        // a strict equality check silently drops every DATA frame — exactly
+        // what we observed when SSH packets reached the peer's onText callback
+        // but never made it to the TUN. SessionManager keeps at most one
+        // PacketSession per peer (keyed by dstIp / pubkey), so the sessionId
+        // here is purely advisory; treat the peer's id as authoritative.
+        if (frame.sessionId !== this.sessionId) {
+            this.sessionId = frame.sessionId;
+        }
+        if (FrameCodec.isHandshakeRequest(frame.opcode)) {
+            this.emit("handshake-req");
+        }
+        else if (FrameCodec.isHandshakeAck(frame.opcode)) {
+            this.emit("handshake-ack");
+        }
+        else if (FrameCodec.isData(frame.opcode)) {
+            this.emit("packet", frame.payload);
+        }
+    }
+    close() {
+        if (this.handshakeTimeout) {
+            clearTimeout(this.handshakeTimeout);
+            this.handshakeTimeout = null;
+        }
+        // If a handshake is in flight, we MUST reject its promise — once
+        // we removeAllListeners() below, the `once("handshake-ack")`
+        // wiring is gone and no incoming ACK can resolve it. Without
+        // this, callers awaiting handshake() (sessionManager.openSession)
+        // hang forever; symptom is "activeSessions=0, packetsForwarded=0"
+        // and pings silently time out even though the friend is online.
+        if (this.handshakePromise) {
+            this.emit("handshake-aborted");
+            this.handshakePromise = null;
+        }
+        this.isActive = false;
+        this.emit("close");
+        this.removeAllListeners();
+    }
+    getPeerId() {
+        return this.peerId;
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    isConnected() {
+        return this.isActive;
+    }
+}