@decentnetwork/lan 0.1.0

package/dist/dns/server.d.ts

@@ -0,0 +1,70 @@
+/**
+ * In-process DNS server — answers A and PTR queries for `<name>.<domain>`
+ * (default `.decent`) out of the daemon's IPAM, forwards everything
+ * else to the system upstream.
+ *
+ * Why bake this into the daemon: every node already pulls dora's
+ * roster every 60s, so the records are in memory. Spinning up a
+ * separate dnsmasq / CoreDNS + a glue script that regenerates a
+ * hosts file is more moving parts than `dgram.createSocket("udp4")`
+ * plus a hundred lines of DNS wire parsing. Same pattern Tailscale
+ * uses for MagicDNS.
+ *
+ * Wire format: stub implementation of RFC 1035 — enough to answer
+ * A / AAAA / PTR for our zone and forward (just the question
+ * section) for everything else. We don't recurse; we proxy the raw
+ * query to the upstream and ferry the reply back. Compression
+ * pointers in incoming queries are handled by the parser; outgoing
+ * answers use literal labels (slightly larger packets, but inside
+ * the 512-byte UDP DNS limit for our short names).
+ */
+import type { Ipam } from "../ipam/ipam.js";
+export interface DnsServerOptions {
+    ipam: Ipam;
+    /** Bare TLD label, e.g. "decent" — queries for `<name>.decent` resolve
+     *  from IPAM. */
+    domain: string;
+    /** UDP port to listen on. 5353 is the conventional unprivileged
+     *  choice (mDNS uses it too but at a different multicast address;
+     *  unicast on 127.0.0.1 doesn't collide). 53 would need root. */
+    port: number;
+    /** Address to bind. Defaults to 127.0.0.1; pass the TUN ip if you
+     *  want other peers on the virtual LAN to query this resolver. */
+    bindAddress?: string;
+    /** Upstream resolver for queries outside our zone. Defaults to
+     *  Node's `dns.lookup` (which uses the system resolver). */
+    upstream?: string;
+}
+export declare class DnsServer {
+    private opts;
+    private logger;
+    private sock?;
+    /** When a forwarded query is in flight, key = txid string,
+     *  value = the original requester. */
+    private pendingForwards;
+    private forwardSock?;
+    /** Actual port we ended up bound to (may differ from opts.port if
+     *  we fell back due to EADDRINUSE). Exposed via getBoundPort() so
+     *  `agentnet dns install` can write the correct port into the
+     *  OS resolver config. */
+    private boundPort;
+    constructor(opts: DnsServerOptions);
+    start(): Promise<void>;
+    /** Actual UDP port the listener bound to (matches opts.port unless
+     *  the fallback sweep had to pick something else). */
+    getBoundPort(): number;
+    stop(): Promise<void>;
+    /**
+     * Parse the incoming DNS query, answer A/PTR records from IPAM for
+     * our zone, forward everything else to the upstream resolver.
+     */
+    private handleQuery;
+    private answerA;
+    private answerPtr;
+    private forwardQuery;
+    private handleForwardReply;
+    private pickUpstream;
+    private replyError;
+    private sendReply;
+    getDomain(): string;
+}

package/dist/dns/server.js

@@ -0,0 +1,393 @@
+/**
+ * In-process DNS server — answers A and PTR queries for `<name>.<domain>`
+ * (default `.decent`) out of the daemon's IPAM, forwards everything
+ * else to the system upstream.
+ *
+ * Why bake this into the daemon: every node already pulls dora's
+ * roster every 60s, so the records are in memory. Spinning up a
+ * separate dnsmasq / CoreDNS + a glue script that regenerates a
+ * hosts file is more moving parts than `dgram.createSocket("udp4")`
+ * plus a hundred lines of DNS wire parsing. Same pattern Tailscale
+ * uses for MagicDNS.
+ *
+ * Wire format: stub implementation of RFC 1035 — enough to answer
+ * A / AAAA / PTR for our zone and forward (just the question
+ * section) for everything else. We don't recurse; we proxy the raw
+ * query to the upstream and ferry the reply back. Compression
+ * pointers in incoming queries are handled by the parser; outgoing
+ * answers use literal labels (slightly larger packets, but inside
+ * the 512-byte UDP DNS limit for our short names).
+ */
+import { createSocket } from "dgram";
+import { lookup } from "dns/promises";
+import { Logger } from "../utils/logger.js";
+const QTYPE_A = 1;
+const QTYPE_PTR = 12;
+const QTYPE_AAAA = 28;
+const QCLASS_IN = 1;
+const RCODE_NOERROR = 0;
+const RCODE_NXDOMAIN = 3;
+const RCODE_SERVFAIL = 2;
+const RCODE_NOTIMPL = 4;
+export class DnsServer {
+    opts;
+    logger;
+    sock;
+    /** When a forwarded query is in flight, key = txid string,
+     *  value = the original requester. */
+    pendingForwards = new Map();
+    forwardSock;
+    /** Actual port we ended up bound to (may differ from opts.port if
+     *  we fell back due to EADDRINUSE). Exposed via getBoundPort() so
+     *  `agentnet dns install` can write the correct port into the
+     *  OS resolver config. */
+    boundPort = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.logger = new Logger({ prefix: "DNS" });
+    }
+    async start() {
+        // Outbound socket for forwarded queries. Bind ephemerally; we
+        // multiplex by txid -> requester.
+        this.forwardSock = createSocket("udp4");
+        this.forwardSock.on("message", (msg) => this.handleForwardReply(msg));
+        // Try the configured port first; if it's taken (macOS
+        // mDNSResponder holds :5353 system-wide on every interface,
+        // openclaw-gateway sometimes too) sweep upward until we find
+        // a free slot. Anything up to +9 is fair game — operator can
+        // see the actual port in the daemon log and `agentnet diag`
+        // reads the live socket so `dns install` writes the right
+        // value into the OS resolver config.
+        const startPort = this.opts.port;
+        const bindAddr = this.opts.bindAddress ?? "127.0.0.1";
+        let lastErr;
+        for (let attempt = 0; attempt < 10; attempt++) {
+            const port = startPort + attempt;
+            const sock = createSocket("udp4");
+            try {
+                await new Promise((resolve, reject) => {
+                    const onErr = (err) => {
+                        sock.off("listening", onListening);
+                        reject(err);
+                    };
+                    const onListening = () => {
+                        sock.off("error", onErr);
+                        resolve();
+                    };
+                    sock.once("error", onErr);
+                    sock.once("listening", onListening);
+                    sock.bind(port, bindAddr);
+                });
+                // Success
+                sock.on("error", (err) => this.logger.warn(`socket error: ${err.message}`));
+                sock.on("message", (msg, rinfo) => {
+                    this.handleQuery(msg, rinfo.address, rinfo.port).catch((err) => {
+                        this.logger.debug(`handleQuery: ${err}`);
+                    });
+                });
+                this.sock = sock;
+                this.boundPort = port;
+                if (port !== startPort) {
+                    this.logger.warn(`Port ${startPort} was busy on ${bindAddr}; fell back to ${port}. ` +
+                        `Update OS resolver config via 'agentnet dns install' to pick up the new port.`);
+                }
+                this.logger.info(`Listening on ${bindAddr}:${port} for *.${this.opts.domain}`);
+                return;
+            }
+            catch (err) {
+                lastErr = err instanceof Error ? err : new Error(String(err));
+                sock.close();
+                if (!/EADDRINUSE/i.test(lastErr.message))
+                    break;
+            }
+        }
+        throw lastErr ?? new Error("DnsServer.start: could not bind any port");
+    }
+    /** Actual UDP port the listener bound to (matches opts.port unless
+     *  the fallback sweep had to pick something else). */
+    getBoundPort() {
+        return this.boundPort;
+    }
+    async stop() {
+        if (this.sock) {
+            await new Promise((r) => this.sock.close(() => r()));
+            this.sock = undefined;
+        }
+        if (this.forwardSock) {
+            await new Promise((r) => this.forwardSock.close(() => r()));
+            this.forwardSock = undefined;
+        }
+    }
+    /**
+     * Parse the incoming DNS query, answer A/PTR records from IPAM for
+     * our zone, forward everything else to the upstream resolver.
+     */
+    async handleQuery(msg, clientAddr, clientPort) {
+        if (msg.length < 12)
+            return;
+        const txid = msg.readUInt16BE(0);
+        const flags = msg.readUInt16BE(2);
+        const qdcount = msg.readUInt16BE(4);
+        if (qdcount !== 1) {
+            // Multi-question queries are rare and we don't support them.
+            this.replyError(txid, msg, clientAddr, clientPort, RCODE_NOTIMPL);
+            return;
+        }
+        // Skip the header (12 bytes), parse the QNAME.
+        const parsed = parseName(msg, 12);
+        if (!parsed) {
+            this.replyError(txid, msg, clientAddr, clientPort, RCODE_SERVFAIL);
+            return;
+        }
+        const { name, nextOffset } = parsed;
+        if (nextOffset + 4 > msg.length) {
+            this.replyError(txid, msg, clientAddr, clientPort, RCODE_SERVFAIL);
+            return;
+        }
+        const qtype = msg.readUInt16BE(nextOffset);
+        const qclass = msg.readUInt16BE(nextOffset + 2);
+        if (qclass !== QCLASS_IN) {
+            this.replyError(txid, msg, clientAddr, clientPort, RCODE_NOTIMPL);
+            return;
+        }
+        const lower = name.toLowerCase();
+        const dotDomain = "." + this.opts.domain.toLowerCase();
+        const inZone = lower === this.opts.domain.toLowerCase() || lower.endsWith(dotDomain);
+        if (inZone && (qtype === QTYPE_A || qtype === QTYPE_AAAA)) {
+            this.answerA(msg, txid, flags, name, qtype, nextOffset + 4, clientAddr, clientPort);
+            return;
+        }
+        if (qtype === QTYPE_PTR && lower.endsWith(".in-addr.arpa")) {
+            this.answerPtr(msg, txid, flags, name, lower, nextOffset + 4, clientAddr, clientPort);
+            return;
+        }
+        // Not ours — proxy to the upstream. We DON'T use Node's
+        // dns.lookup() because that returns a single result, no SOA, no
+        // TTL — instead we forward the raw wire query to a real DNS
+        // server and ferry the reply back. The upstream is whatever the
+        // host's /etc/resolv.conf says, accessed via the dns module's
+        // getServers() so we always honor the OS config.
+        await this.forwardQuery(msg, txid, clientAddr, clientPort);
+    }
+    answerA(query, txid, qflags, name, qtype, questionEnd, clientAddr, clientPort) {
+        const shortName = name
+            .slice(0, name.length - this.opts.domain.length - (name.endsWith("." + this.opts.domain) ? 1 : 0));
+        const record = this.opts.ipam.resolveName(shortName);
+        if (!record) {
+            this.sendReply(buildHeader(txid, qflags, RCODE_NXDOMAIN, 0), query, questionEnd, [], clientAddr, clientPort);
+            return;
+        }
+        // For AAAA we return NOERROR with no answers — clients will fall
+        // back to A. Returning NXDOMAIN here would cause some resolvers
+        // to give up on the name entirely.
+        if (qtype === QTYPE_AAAA) {
+            this.sendReply(buildHeader(txid, qflags, RCODE_NOERROR, 0), query, questionEnd, [], clientAddr, clientPort);
+            return;
+        }
+        const rdata = ipv4ToBytes(record);
+        if (!rdata) {
+            this.sendReply(buildHeader(txid, qflags, RCODE_SERVFAIL, 0), query, questionEnd, [], clientAddr, clientPort);
+            return;
+        }
+        const answer = encodeAnswer(name, QTYPE_A, QCLASS_IN, 60, rdata);
+        this.sendReply(buildHeader(txid, qflags, RCODE_NOERROR, 1), query, questionEnd, [answer], clientAddr, clientPort);
+    }
+    answerPtr(query, txid, qflags, name, lower, questionEnd, clientAddr, clientPort) {
+        // X.Y.Z.W.in-addr.arpa -> W.Z.Y.X
+        const ipReversed = lower.slice(0, lower.length - ".in-addr.arpa".length);
+        const parts = ipReversed.split(".");
+        if (parts.length !== 4) {
+            this.sendReply(buildHeader(txid, qflags, RCODE_NXDOMAIN, 0), query, questionEnd, [], clientAddr, clientPort);
+            return;
+        }
+        const ip = [parts[3], parts[2], parts[1], parts[0]].join(".");
+        const record = this.opts.ipam.resolveIp(ip);
+        if (!record) {
+            this.sendReply(buildHeader(txid, qflags, RCODE_NXDOMAIN, 0), query, questionEnd, [], clientAddr, clientPort);
+            return;
+        }
+        const fqdn = `${record.name}.${this.opts.domain}`;
+        const rdata = encodeName(fqdn);
+        const answer = encodeAnswer(name, QTYPE_PTR, QCLASS_IN, 60, rdata);
+        this.sendReply(buildHeader(txid, qflags, RCODE_NOERROR, 1), query, questionEnd, [answer], clientAddr, clientPort);
+    }
+    async forwardQuery(msg, txid, clientAddr, clientPort) {
+        const upstream = await this.pickUpstream();
+        if (!upstream) {
+            this.replyError(txid, msg, clientAddr, clientPort, RCODE_SERVFAIL);
+            return;
+        }
+        const key = `${txid}|${clientAddr}|${clientPort}`;
+        this.pendingForwards.set(key, { addr: clientAddr, port: clientPort, originalId: txid });
+        // Use the txid as-is — the upstream echoes it back, we match on it.
+        this.forwardSock.send(msg, upstream.port, upstream.host, (err) => {
+            if (err) {
+                this.pendingForwards.delete(key);
+                this.logger.debug(`forward send: ${err.message}`);
+                this.replyError(txid, msg, clientAddr, clientPort, RCODE_SERVFAIL);
+            }
+        });
+        // Expire stale entries after 5s.
+        setTimeout(() => this.pendingForwards.delete(key), 5000).unref();
+    }
+    handleForwardReply(msg) {
+        if (msg.length < 2)
+            return;
+        const txid = msg.readUInt16BE(0);
+        // Find any matching pending entry (txid is the only key the
+        // upstream preserves; with two simultaneous clients using the
+        // same id we'd collide — rare for our scale).
+        for (const [key, pending] of this.pendingForwards) {
+            if (pending.originalId === txid) {
+                this.pendingForwards.delete(key);
+                this.sock?.send(msg, pending.port, pending.addr, () => undefined);
+                return;
+            }
+        }
+    }
+    async pickUpstream() {
+        if (this.opts.upstream) {
+            return { host: this.opts.upstream, port: 53 };
+        }
+        // Fallback: ask Node's resolver for its servers. We don't pin
+        // these on startup so changes to /etc/resolv.conf propagate.
+        try {
+            const { Resolver } = await import("dns/promises");
+            const resolver = new Resolver();
+            const servers = resolver.getServers();
+            // Skip 127.0.0.x — would loop right back to us via systemd-
+            // resolved on Linux setups.
+            const external = servers.find((s) => !s.startsWith("127."));
+            if (external)
+                return { host: external, port: 53 };
+        }
+        catch {
+            // ignore
+        }
+        return { host: "1.1.1.1", port: 53 };
+    }
+    replyError(txid, query, clientAddr, clientPort, rcode) {
+        if (!this.sock)
+            return;
+        const flags = query.length >= 4 ? query.readUInt16BE(2) : 0;
+        const header = buildHeader(txid, flags, rcode, 0);
+        this.sock.send(header, clientPort, clientAddr, () => undefined);
+    }
+    sendReply(header, query, questionEnd, answers, clientAddr, clientPort) {
+        if (!this.sock)
+            return;
+        // Echo the question section so the client knows which query
+        // this answers (per RFC 1035).
+        const question = query.slice(12, questionEnd);
+        const reply = Buffer.concat([header, question, ...answers]);
+        this.sock.send(reply, clientPort, clientAddr, () => undefined);
+    }
+    // For test/debug — make sure the IPAM bound at construction time
+    // is still the one being used (it's a reference, but explicit
+    // is safer if the daemon ever needs to swap it).
+    getDomain() {
+        return this.opts.domain;
+    }
+}
+/**
+ * Parse a DNS-encoded name starting at `offset`. Supports compression
+ * pointers (RFC 1035 §4.1.4). Returns the dot-joined ASCII name and
+ * the byte offset just past the terminator (or the pointer-back
+ * label, whichever ends the name).
+ */
+function parseName(buf, offset) {
+    const labels = [];
+    let cursor = offset;
+    let jumped = false;
+    let nextAfter = -1;
+    let safety = 0;
+    while (true) {
+        if (safety++ > 64)
+            return null;
+        if (cursor >= buf.length)
+            return null;
+        const len = buf[cursor];
+        if (len === 0) {
+            cursor += 1;
+            if (!jumped)
+                nextAfter = cursor;
+            break;
+        }
+        if ((len & 0xc0) === 0xc0) {
+            if (cursor + 1 >= buf.length)
+                return null;
+            const pointer = ((len & 0x3f) << 8) | buf[cursor + 1];
+            if (!jumped)
+                nextAfter = cursor + 2;
+            cursor = pointer;
+            jumped = true;
+            continue;
+        }
+        cursor += 1;
+        if (cursor + len > buf.length)
+            return null;
+        labels.push(buf.slice(cursor, cursor + len).toString("ascii"));
+        cursor += len;
+    }
+    return { name: labels.join("."), nextOffset: nextAfter };
+}
+function encodeName(name) {
+    const parts = name.split(".").filter((p) => p.length > 0);
+    let total = 1; // trailing zero
+    for (const p of parts)
+        total += 1 + p.length;
+    const buf = Buffer.alloc(total);
+    let off = 0;
+    for (const p of parts) {
+        buf[off++] = p.length;
+        buf.write(p, off, "ascii");
+        off += p.length;
+    }
+    buf[off] = 0;
+    return buf;
+}
+function buildHeader(txid, qflagsRaw, rcode, ancount) {
+    const buf = Buffer.alloc(12);
+    buf.writeUInt16BE(txid, 0);
+    // QR=1 (response), Opcode from query, AA=1, RD echoed, RA=1, RCODE.
+    const opcode = (qflagsRaw >> 11) & 0x0f;
+    const rd = (qflagsRaw >> 8) & 1;
+    const flags = (1 << 15) | (opcode << 11) | (1 << 10) | (rd << 8) | (1 << 7) | (rcode & 0x0f);
+    buf.writeUInt16BE(flags, 2);
+    buf.writeUInt16BE(1, 4); // qdcount
+    buf.writeUInt16BE(ancount, 6);
+    return buf;
+}
+function encodeAnswer(name, type, klass, ttl, rdata) {
+    const nameBuf = encodeName(name);
+    const buf = Buffer.alloc(nameBuf.length + 10 + rdata.length);
+    nameBuf.copy(buf, 0);
+    let off = nameBuf.length;
+    buf.writeUInt16BE(type, off);
+    off += 2;
+    buf.writeUInt16BE(klass, off);
+    off += 2;
+    buf.writeUInt32BE(ttl, off);
+    off += 4;
+    buf.writeUInt16BE(rdata.length, off);
+    off += 2;
+    rdata.copy(buf, off);
+    return buf;
+}
+function ipv4ToBytes(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4)
+        return null;
+    const buf = Buffer.alloc(4);
+    for (let i = 0; i < 4; i++) {
+        const n = parseInt(parts[i], 10);
+        if (Number.isNaN(n) || n < 0 || n > 255)
+            return null;
+        buf[i] = n;
+    }
+    return buf;
+}
+// Silence the unused-import warning while preserving the import as
+// a hint that we *could* drop to Node's high-level resolver if the
+// raw-forward path ever proves too fragile.
+void lookup;

package/dist/dora/dora-integration.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Dora integration — registers this node with a dora (DHCP-style) server
+ * and pulls the roster of known peers into the in-memory IPAM.
+ *
+ * Replaces the manual ipam.yaml dance once an operator points the config
+ * at a dora server's userid. The yaml file is still loaded first as a
+ * fallback; whatever the dora server says wins on conflict.
+ *
+ * Failure mode: if no configured dora server answers within the timeout,
+ * we log a warning and fall through to whatever IP/IPAM was loaded from
+ * disk. Decentlan is fully functional without dora — it's just that
+ * peers need to manually share ipam.yaml entries.
+ */
+import type { PeerManager } from "../carrier/peer-manager.js";
+import type { Ipam } from "../ipam/ipam.js";
+import type { DoraConfig } from "../types.js";
+export interface DoraIntegrationOptions {
+    config: DoraConfig;
+    peerManager: PeerManager;
+    ipam: Ipam;
+    /** Our own user-facing node name (becomes the `name` field in dora). */
+    nodeName: string;
+    /** Preferred virtual IP from local config — sent as `requestedIp` so a
+     *  restart keeps the same address when possible. */
+    preferredIp?: string;
+}
+export declare class DoraIntegration {
+    private opts;
+    private client;
+    private logger;
+    private refreshTimer?;
+    private retryBootstrapTimer?;
+    /** The IP dora handed us. Falls back to preferredIp on registry failure. */
+    private allocatedIp;
+    /** Userids we've already attempted to friend this session — keeps the
+     *  60s roster refresh from spamming sendFriendRequest. */
+    private friendRequested;
+    /** Set once we've successfully registered. The retry-bootstrap loop
+     *  uses this to know when to stop trying. */
+    private registered;
+    constructor(opts: DoraIntegrationOptions);
+    /**
+     * Register self with dora and pull the roster. Idempotent; safe to
+     * retry. Returns the IP dora allocated (or preferredIp if all servers
+     * were unreachable).
+     */
+    bootstrap(): Promise<string>;
+    /**
+     * Re-attempt the register flow every 30 seconds until it succeeds.
+     * Without this, a daemon that started before its dora server came
+     * online never makes it into the roster — peers can't auto-friend
+     * us, and auto-IP allocation is lost. bootstrap() re-derives its
+     * own myUserid so we don't need to thread it through.
+     */
+    private scheduleBootstrapRetry;
+    /**
+     * Wrap a single register call with up to 3 retries spaced 2s apart.
+     * The first call often races the underlying Carrier session even
+     * after waitForFriendConnected resolves — the SDK has a transient
+     * gap between the "online" event and the in-session crypto channel
+     * being ready for the next outgoing sendText. A short retry burst
+     * hides that without needing express fallback.
+     */
+    private tryRegister;
+    stop(): void;
+    getAllocatedIp(): string | undefined;
+    private refreshRoster;
+    /**
+     * Stamp dora records into the in-memory IPAM. We DON'T persist to
+     * ipam.yaml — that file remains operator-managed. Dora is treated as
+     * a live overlay that's refreshed on every restart.
+     *
+     * Conflict policy: dora wins. If ipam.yaml had a peer with a stale IP,
+     * the dora record overwrites it (assignPeer dedupes by name + carrierId).
+     */
+    private mergeRosterIntoIpam;
+    /**
+     * Send an outbound friend request to a roster entry if we haven't
+     * already (and aren't already friends). Idempotent at multiple
+     * levels: in-process guard via `friendRequested`, SDK-level
+     * short-circuit on `acceptedAt`, and recipient-side auto-accept.
+     *
+     * Address is optional in the protocol for backward-compat with
+     * older dora records; without it, we can't initiate the request
+     * (the SDK needs the nospam token embedded in the address). The
+     * caller logs a one-time warning so the operator knows to either
+     * re-register the peer or fall back to a manual friend-request.
+     */
+    private maybeFriend;
+}