@decentnetwork/lan 0.1.0

package/dist/dora/dora-integration.js

@@ -0,0 +1,325 @@
+/**
+ * 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 { DoraClient, AllRegistriesUnavailableError } from "@decentnetwork/dora";
+import { Logger } from "../utils/logger.js";
+export class DoraIntegration {
+    opts;
+    client;
+    logger;
+    refreshTimer;
+    retryBootstrapTimer;
+    /** The IP dora handed us. Falls back to preferredIp on registry failure. */
+    allocatedIp;
+    /** Userids we've already attempted to friend this session — keeps the
+     *  60s roster refresh from spamming sendFriendRequest. */
+    friendRequested = new Set();
+    /** Set once we've successfully registered. The retry-bootstrap loop
+     *  uses this to know when to stop trying. */
+    registered = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.logger = new Logger({ prefix: "Dora" });
+        this.client = new DoraClient({
+            registryUserids: opts.config.userids ?? [],
+            sendText: (toUserid, text) => opts.peerManager.sendText(toUserid, text),
+            onText: (handler) => {
+                opts.peerManager.on("dora-message", (fromUserid, text) => {
+                    handler(fromUserid, text);
+                });
+            },
+            timeoutMs: 10_000,
+        });
+    }
+    /**
+     * Register self with dora and pull the roster. Idempotent; safe to
+     * retry. Returns the IP dora allocated (or preferredIp if all servers
+     * were unreachable).
+     */
+    async bootstrap() {
+        const myUserid = this.opts.peerManager.getPubkey();
+        const userids = this.opts.config.userids ?? [];
+        if (userids.length === 0) {
+            this.logger.warn("dora.userids empty — skipping dora registration");
+            return this.opts.preferredIp ?? "";
+        }
+        // Kick session establishment with each registry so the first call
+        // doesn't fail on cold-start cookie/handshake delay. peer-manager
+        // swallows the "friend offline" error internally.
+        for (const id of userids) {
+            this.opts.peerManager
+                .kickSessionEstablishment(id)
+                .catch(() => undefined);
+        }
+        // Wait up to 30s for ANY configured dora server to come online.
+        // Without this, the first `register` call races the underlying
+        // Carrier session establishment and fails with "friend is offline
+        // and no express node is configured", forcing the daemon onto the
+        // fallback (config) IP. Use Promise.race so the first responder
+        // wins — slow registries don't hold up the bootstrap.
+        const onlineWaits = userids.map((id) => this.opts.peerManager
+            .waitForFriendConnected(id, 30_000)
+            .then((online) => ({ id, online }))
+            .catch(() => ({ id, online: false })));
+        const anyOnline = await Promise.race([
+            Promise.any(onlineWaits.map((p) => p.then((r) => (r.online ? r : Promise.reject(new Error("offline")))))).catch(() => null),
+            new Promise((r) => setTimeout(() => r(null), 30_000)),
+        ]);
+        if (!anyOnline) {
+            this.logger.warn("No dora server became reachable within 30s — falling back to config IP");
+            return this.opts.preferredIp ?? "";
+        }
+        this.logger.debug(`Dora friend online: ${anyOnline.id}`);
+        // Include our address so other peers fetched from list() can call
+        // sendFriendRequest on us. Userid alone is the bare pubkey-derived
+        // id; sendFriendRequest needs the address form (with nospam).
+        const myAddress = this.opts.peerManager.getAddress();
+        // Wrap the entire register-and-roster-fetch flow in ONE try/catch
+        // so any failure (registry unreachable, transient session blip,
+        // unexpected error) cleanly falls back to the config IP. An
+        // earlier version split this into two try blocks, with the result
+        // that a non-IP-collision error from the first register call
+        // re-threw past the AllRegistriesUnavailableError handler and
+        // crashed the daemon on startup.
+        try {
+            let record;
+            try {
+                record = await this.tryRegister(myUserid, myAddress, this.opts.preferredIp);
+            }
+            catch (err) {
+                // Common case: the preferred IP from config.yaml collides
+                // with another peer's reservation (every fresh `agentnet
+                // init` defaults to 10.86.1.10, so the second peer to
+                // register always loses the race). Retry once without
+                // requestedIp so dora picks any free slot. Errors that
+                // aren't IP-collision flavored fall through to the outer
+                // catch and trigger the fallback path.
+                const msg = err instanceof Error ? err.message : String(err);
+                const looksLikeIpCollision = /held by|in use|already taken|already in use/i.test(msg);
+                if (!looksLikeIpCollision)
+                    throw err;
+                this.logger.warn(`Preferred IP ${this.opts.preferredIp} not available (${msg}) — requesting any free IP`);
+                record = await this.tryRegister(myUserid, myAddress);
+            }
+            this.allocatedIp = record.virtualIp;
+            this.registered = true;
+            this.logger.info(`Registered with dora: ${record.name} -> ${record.virtualIp}`);
+            // Add self to the in-memory IPAM so the local DNS server can
+            // answer `<my-name>.<domain>` queries from this very host.
+            // mergeRosterIntoIpam skips own entry (sensible — peers don't
+            // need to "auto-friend themselves"), but the DNS resolver
+            // looks at the same IPAM, so without this entry `dig snoopy.
+            // decent` from snoopy itself NXDOMAINs.
+            this.opts.ipam.assignPeer({
+                name: record.name,
+                carrierId: myUserid,
+                virtualIp: record.virtualIp,
+                services: [],
+            });
+            // Pull the full roster. We don't fail the whole bootstrap if
+            // list() throws — we still have our own address allocated.
+            try {
+                const roster = await this.client.list();
+                this.mergeRosterIntoIpam(roster, myUserid);
+            }
+            catch (err) {
+                this.logger.warn(`Initial roster fetch failed: ${err}`);
+            }
+            // Start periodic refresh.
+            const interval = this.opts.config.refreshIntervalMs ?? 60_000;
+            this.refreshTimer = setInterval(() => {
+                this.refreshRoster(myUserid).catch((err) => {
+                    this.logger.debug(`Roster refresh: ${err}`);
+                });
+            }, interval);
+            return this.allocatedIp;
+        }
+        catch (err) {
+            if (err instanceof AllRegistriesUnavailableError) {
+                this.logger.warn(`All dora servers unreachable — falling back to config IP ${this.opts.preferredIp}: ${err.message}`);
+            }
+            else {
+                // Treat unexpected errors the same as unreachable — the
+                // daemon should still come up. Operator sees the warning
+                // and can fix.
+                this.logger.warn(`Dora register failed — falling back to config IP ${this.opts.preferredIp}: ${err instanceof Error ? err.message : err}`);
+            }
+            // Schedule a background retry. The TUN is already up at the
+            // fallback IP; we don't bring it down on success, so the
+            // daemon keeps running with the fallback even when register
+            // eventually succeeds — but at least subsequent peers
+            // (Ubuntu's daemon doing list()) will see our record with our
+            // address and can auto-friend us.
+            this.scheduleBootstrapRetry();
+            return this.opts.preferredIp ?? "";
+        }
+    }
+    /**
+     * 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.
+     */
+    scheduleBootstrapRetry() {
+        if (this.retryBootstrapTimer || this.registered)
+            return;
+        const tick = () => {
+            if (this.registered)
+                return;
+            this.logger.debug("Retrying dora bootstrap…");
+            // Don't await — let it run async and clear the timer if it
+            // succeeds, otherwise leave the timer running.
+            void this.bootstrap().then(() => {
+                if (this.registered && this.retryBootstrapTimer) {
+                    clearInterval(this.retryBootstrapTimer);
+                    this.retryBootstrapTimer = undefined;
+                }
+            });
+        };
+        this.retryBootstrapTimer = setInterval(tick, 30_000);
+    }
+    /**
+     * 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.
+     */
+    async tryRegister(myUserid, myAddress, requestedIp) {
+        const maxAttempts = 3;
+        let lastErr;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await this.client.register({
+                    userid: myUserid,
+                    name: this.opts.nodeName,
+                    address: myAddress,
+                    requestedIp,
+                    replace: true,
+                });
+            }
+            catch (err) {
+                lastErr = err;
+                const msg = err instanceof Error ? err.message : String(err);
+                // Don't retry on definitive rejections (name/IP collision):
+                // those are protocol-level errors that won't fix themselves.
+                if (/held by|in use|already taken|already in use|out of range|already registered/i.test(msg)) {
+                    throw err;
+                }
+                if (attempt < maxAttempts) {
+                    this.logger.debug(`register attempt ${attempt}/${maxAttempts} failed: ${msg} — retrying in 2s`);
+                    await new Promise((r) => setTimeout(r, 2000));
+                }
+            }
+        }
+        throw lastErr;
+    }
+    stop() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = undefined;
+        }
+        if (this.retryBootstrapTimer) {
+            clearInterval(this.retryBootstrapTimer);
+            this.retryBootstrapTimer = undefined;
+        }
+    }
+    getAllocatedIp() {
+        return this.allocatedIp;
+    }
+    async refreshRoster(myUserid) {
+        const roster = await this.client.list();
+        this.mergeRosterIntoIpam(roster, myUserid);
+    }
+    /**
+     * 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).
+     */
+    mergeRosterIntoIpam(roster, myUserid) {
+        let added = 0;
+        let updated = 0;
+        for (const entry of roster) {
+            if (entry.userid === myUserid)
+                continue; // skip self
+            const existing = this.opts.ipam.resolveCarrierId(entry.userid);
+            if (!existing) {
+                added += 1;
+            }
+            else if (existing.virtualIp !== entry.virtualIp ||
+                existing.name !== entry.name) {
+                updated += 1;
+            }
+            else {
+                // Entry unchanged in IPAM, but still attempt friending — a
+                // roster refresh may pick up a peer that registered earlier
+                // and is already in our IPAM (because we previously fetched
+                // them) but never got friended.
+                this.maybeFriend(entry);
+                continue;
+            }
+            this.opts.ipam.assignPeer({
+                name: entry.name,
+                carrierId: entry.userid,
+                virtualIp: entry.virtualIp,
+                services: existing?.services ?? [],
+            });
+            this.maybeFriend(entry);
+        }
+        if (added > 0 || updated > 0) {
+            this.logger.info(`Roster refreshed: ${added} new, ${updated} updated, ${roster.length} total`);
+        }
+    }
+    /**
+     * 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.
+     */
+    maybeFriend(entry) {
+        if (this.friendRequested.has(entry.userid))
+            return;
+        if (this.opts.peerManager.isFriend(entry.userid)) {
+            this.friendRequested.add(entry.userid);
+            return;
+        }
+        if (!entry.address) {
+            this.logger.warn(`Roster entry ${entry.name} (${entry.userid.slice(0, 12)}...) has no address — can't auto-friend. ` +
+                `Have them re-register against a newer dora server, or run 'agentnet friend-request' manually.`);
+            this.friendRequested.add(entry.userid); // don't keep warning every 60s
+            return;
+        }
+        this.friendRequested.add(entry.userid);
+        this.opts.peerManager
+            .sendFriendRequest(entry.address, `dora roster auto-friend (${this.opts.nodeName})`)
+            .then(() => {
+            this.logger.info(`Auto-friend sent to ${entry.name} (${entry.userid.slice(0, 12)}...)`);
+        })
+            .catch((err) => {
+            this.logger.warn(`Auto-friend ${entry.name}: ${err instanceof Error ? err.message : err}`);
+            // Allow another attempt on the next refresh cycle.
+            this.friendRequested.delete(entry.userid);
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Decent AgentNet — Main entry point
+ * Dispatches to CLI handler.
+ *
+ * NOTE: the EventEmitter.defaultMaxListeners adjustment MUST happen before
+ * the SDK is imported. The Carrier SDK's UdpTransport attaches one listener
+ * per bootstrap node and per relay, easily exceeding Node's default cap of
+ * 10. If we raise the cap after the SDK loads, EventEmitter instances
+ * created during the SDK's module initialization still use the old default
+ * and produce a wall of MaxListenersExceededWarning lines at runtime.
+ */
+import "./cli/index.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * Decent AgentNet — Main entry point
+ * Dispatches to CLI handler.
+ *
+ * NOTE: the EventEmitter.defaultMaxListeners adjustment MUST happen before
+ * the SDK is imported. The Carrier SDK's UdpTransport attaches one listener
+ * per bootstrap node and per relay, easily exceeding Node's default cap of
+ * 10. If we raise the cap after the SDK loads, EventEmitter instances
+ * created during the SDK's module initialization still use the old default
+ * and produce a wall of MaxListenersExceededWarning lines at runtime.
+ */
+import { EventEmitter } from "events";
+EventEmitter.defaultMaxListeners = 100;
+import "./cli/index.js";

package/dist/ipam/index.d.ts

@@ -0,0 +1 @@
+export { Ipam, type IpamConfig } from "./ipam.js";

package/dist/ipam/index.js

@@ -0,0 +1 @@
+export { Ipam } from "./ipam.js";

package/dist/ipam/ipam.d.ts

@@ -0,0 +1,99 @@
+/**
+ * IPAM - IP Address Management
+ * Maps Carrier IDs to virtual IPs, hostnames, and services
+ */
+import type { IpamRecord, Service } from "../types.js";
+export interface IpamConfig {
+    namespace: string;
+    peers: IpamRecord[];
+}
+export declare class Ipam {
+    private config;
+    private filePath;
+    private logger;
+    private ipCache;
+    private idCache;
+    private nameCache;
+    constructor(config: IpamConfig, filePath: string);
+    static load(filePath: string): Promise<Ipam>;
+    static loadOrCreate(filePath: string, namespace?: string): Promise<Ipam>;
+    /**
+     * Resolve hostname to virtual IP
+     */
+    resolveName(name: string): string | null;
+    /**
+     * Resolve virtual IP to IpamRecord
+     */
+    resolveIp(ip: string): IpamRecord | null;
+    /**
+     * Resolve Carrier ID to IpamRecord
+     */
+    resolveCarrierId(carrierId: string): IpamRecord | null;
+    /**
+     * Get all peers
+     */
+    getPeers(): IpamRecord[];
+    /**
+     * Add or update a peer
+     */
+    assignPeer(record: IpamRecord): void;
+    /**
+     * Remove a peer by name or Carrier ID
+     */
+    removePeer(identifier: string): boolean;
+    /**
+     * Check if IP is allocated
+     */
+    isIpAllocated(ip: string): boolean;
+    /**
+     * Find next available IP in subnet
+     * Assumes subnet like "10.86.0.0/16"
+     */
+    findNextAvailableIp(subnet: string, start?: string): string;
+    /**
+     * Get service port for peer
+     */
+    getServicePort(peerName: string, serviceName: string): number | null;
+    /**
+     * Get all services for peer
+     */
+    getServices(peerName: string): Service[];
+    /**
+     * Save IPAM config to file
+     */
+    save(): Promise<void>;
+    /**
+     * Check if peer is expired
+     */
+    isExpired(peerName: string): boolean;
+    /**
+     * Deterministically derive a virtual IP from a Carrier userid, in the
+     * same style as ARP/DHCP-by-MAC: every peer computes the same IP for the
+     * same userid, so the network is consistent without manual coordination.
+     *
+     * Hash(userid)[0..1] → last two octets of 10.86.X.Y. Avoids x.0 and x.255.
+     * Returns the IP regardless of whether it's already in the IPAM.
+     */
+    static deterministicIpForUserid(userid: string): string;
+    /**
+     * Ensure each friend has an IPAM record. Returns the number of new
+     * records added. Existing entries (manual or previously auto-assigned)
+     * are preserved.
+     *
+     * On collision (different userid hashes to an already-taken IP), walks
+     * the 4th octet until a free slot is found.
+     */
+    autoAssignFriends(friends: {
+        pubkey: string;
+        name?: string;
+    }[], selfUserid?: string): number;
+    /**
+     * Get config
+     */
+    getConfig(): IpamConfig;
+    /**
+     * Get namespace
+     */
+    getNamespace(): string;
+    private rebuildCache;
+}