@decentnetwork/lan 0.1.10 → 0.1.12

package/dist/carrier/peer-manager.d.ts

@@ -65,6 +65,13 @@ export declare class PeerManager extends EventEmitter {
     /**
      * Check if a specific friend is currently online (direct UDP path established).
      * Returns false for unknown pubkeys.
+     *
+     * Matches on BOTH `pubkey` and `userid` because the SDK's FriendRecord
+     * is inconsistent across code paths: outbound friend requests set
+     * `pubkey: friendId` (the base58 userid), inbound friend requests do
+     * the same, but older persisted entries (pre-1.7.x) only had `pubkey`
+     * and the comparison failed silently when callers pass a userid.
+     * Same belt-and-braces as `isFriend()` above.
      */
     isFriendOnline(pubkey: string): boolean;
     /**

package/dist/carrier/peer-manager.js

@@ -169,11 +169,20 @@ export class PeerManager extends EventEmitter {
     /**
      * Check if a specific friend is currently online (direct UDP path established).
      * Returns false for unknown pubkeys.
+     *
+     * Matches on BOTH `pubkey` and `userid` because the SDK's FriendRecord
+     * is inconsistent across code paths: outbound friend requests set
+     * `pubkey: friendId` (the base58 userid), inbound friend requests do
+     * the same, but older persisted entries (pre-1.7.x) only had `pubkey`
+     * and the comparison failed silently when callers pass a userid.
+     * Same belt-and-braces as `isFriend()` above.
      */
     isFriendOnline(pubkey) {
         if (!this.peer)
             return false;
-        const friend = this.peer.friends().find((f) => f.pubkey === pubkey);
+        const friend = this.peer
+            .friends()
+            .find((f) => f.pubkey === pubkey || f.userid === pubkey);
         return friend?.status === "online";
     }
     /**
@@ -312,25 +321,30 @@ export class PeerManager extends EventEmitter {
             };
             this.emit("friend-connection", evt);
             this.logger.info(`Friend ${event.pubkey} ${event.status}`);
-            // If a friend goes offline (or, more importantly, comes BACK
-            // online after we already had a session — e.g. they restarted
-            // their daemon), the Carrier crypto session under us has
-            // rotated. Our cached PacketSession is bound to the previous
-            // session's frame-sequence state. Sending DATA frames through
-            // it produces ciphertext the new peer can't decrypt; the
-            // packets land in their PeerManager.onText but no session
-            // matches and they're dropped silently. Result: 100% loss
-            // that looks like "the link is up but pings time out."
+            // Drop our cached PacketSession ONLY on disconnect.
             //
-            // Fix: drop our PacketSession on every friend-status change.
-            // The next outbound packet triggers a fresh handshake (or the
-            // remote auto-creates from our HANDSHAKE_REQ); fast, clean,
-            // no stale-session lingering.
-            const existing = this.sessions.get(event.pubkey);
-            if (existing) {
-                this.logger.debug(`Closing stale packet session to ${event.pubkey} on friend-${event.status}`);
-                existing.close();
-                this.sessions.delete(event.pubkey);
+            // History: we used to also close on `connected` events under the
+            // theory that the Carrier crypto session had "rotated" and our
+            // session was bound to old state. That theory was wrong —
+            // PacketSession holds only `sessionId` (decentlan-layer demux ID)
+            // and `isActive`; all crypto state lives inside the SDK and is
+            // read fresh on every sendText. Worse, the SDK fires `connected`
+            // multiple times during initial session-up (once when a TCP relay
+            // route appears, again when UDP holepunching lands). Each one
+            // destroyed our just-created PacketSession mid-handshake,
+            // killing the HANDSHAKE_ACK before it could fire — symptom:
+            // activeSessions=0 forever, even though friend status shows
+            // "online". The restart-case the old code worried about is
+            // already covered: a fresh HANDSHAKE_REQ from the remote enters
+            // the onText path below and triggers session replacement when
+            // the sessionId differs.
+            if (event.status !== "connected") {
+                const existing = this.sessions.get(event.pubkey);
+                if (existing) {
+                    this.logger.debug(`Closing packet session to ${event.pubkey} on friend-disconnect`);
+                    existing.close();
+                    this.sessions.delete(event.pubkey);
+                }
             }
         });
         // Text messages contain our framed packets

package/dist/daemon/server.js

@@ -90,21 +90,26 @@ export class DaemonServer {
             // optional dora registration can decide our IP.
             const keyFile = resolve(this.config.carrier.dataDir, "keypair.json");
             this.peerManager = new PeerManager();
-            // Use express nodes. Previously the daemon passed an empty array
-            // here on the theory that "express is for offline messages, not
-            // live packet forwarding". But asymmetric Carrier sessions (peer
-            // A thinks B is online, B thinks A is offline — common across
-            // China-WAN paths) make dora's sendText reply fail direct and
-            // fall back to express; if we don't subscribe to express we
-            // never see the response. dora -> cn for register-ok / list-ok
-            // hits this exact case. The cost of enabling express here is
-            // that idle text messages may take an extra hop through the
-            // HTTPS relay — packet-router doesn't use sendText, so its
-            // hot path is unaffected.
+            // Daemon does NOT use express nodes. decentlan is a virtual
+            // LAN — peers must be ONLINE for IP packets to flow. Express
+            // is an offline-message store-and-forward relay for chat-style
+            // apps; if we enable it, sendText silently falls back to a
+            // queue when a friend is offline. That creates the illusion of
+            // connectivity ("the daemon says X is reachable") while
+            // packets actually pile up in HTTPS storage and never get
+            // forwarded in real time. For a VPN-like data plane, that's
+            // wrong — better to fail fast and let the operator see the
+            // peer as offline.
+            //
+            // Friend-request bootstrap is the only thing that benefits
+            // from express; for that case use the standalone CLI
+            // `agentnet friend-request` (which DOES use express via its
+            // own short-lived Peer instance) and accept the request on
+            // both ends before bringing the daemon up.
             await this.peerManager.create({
                 keyFile,
                 bootstrapNodes: this.config.carrier.bootstrapNodes,
-                expressNodes: this.config.carrier.expressNodes ?? [],
+                expressNodes: [],
             });
             await this.peerManager.start();
             this.logger.info(`Identity: ${this.peerManager.getAddress()}`);

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

@@ -27,6 +27,13 @@ export declare class PacketRouter extends EventEmitter {
     private listenedSessions;
     private keepaliveTimer?;
     private stats;
+    /** Per-destination drop reasons. Exposed via getStats() for `agentnet diag`. */
+    private dropsByDst;
+    /** (dstIp,reason) tuples we've already logged at info level — avoids
+     *  spamming the journal when a single broken destination receives
+     *  thousands of packets. The first hit per tuple is logged loudly so
+     *  the operator notices in `journalctl`; subsequent hits stay at debug. */
+    private loggedDropTuples;
     constructor(opts: PacketRouterOptions);
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -47,6 +54,13 @@ export declare class PacketRouter extends EventEmitter {
      */
     private sendKeepalivesToActiveSessions;
     getStats(): ForwardingStats;
+    /**
+     * Record a drop and bump per-destination diagnostics. Logs the FIRST
+     * occurrence of each (dstIp, reason) at info level so the failure mode
+     * shows up in `journalctl` without needing AGENTNET_LOG_LEVEL=debug.
+     * Subsequent drops are summed into the counter.
+     */
+    private recordDrop;
     /**
      * Handle outgoing packet (app -> TUN -> Carrier).
      */

package/dist/router/packet-router.js

@@ -25,6 +25,13 @@ export class PacketRouter extends EventEmitter {
         packetsDropped: 0,
         activeSessions: 0,
     };
+    /** Per-destination drop reasons. Exposed via getStats() for `agentnet diag`. */
+    dropsByDst = new Map();
+    /** (dstIp,reason) tuples we've already logged at info level — avoids
+     *  spamming the journal when a single broken destination receives
+     *  thousands of packets. The first hit per tuple is logged loudly so
+     *  the operator notices in `journalctl`; subsequent hits stay at debug. */
+    loggedDropTuples = new Set();
     constructor(opts) {
         super();
         this.tunDevice = opts.tunDevice;
@@ -137,10 +144,37 @@ export class PacketRouter extends EventEmitter {
         }
     }
     getStats() {
+        const dropsByDst = {};
+        for (const [dstIp, info] of this.dropsByDst) {
+            dropsByDst[dstIp] = info;
+        }
         return {
             ...this.stats,
             activeSessions: this.sessionManager.getActiveCount(),
+            dropsByDst,
+        };
+    }
+    /**
+     * Record a drop and bump per-destination diagnostics. Logs the FIRST
+     * occurrence of each (dstIp, reason) at info level so the failure mode
+     * shows up in `journalctl` without needing AGENTNET_LOG_LEVEL=debug.
+     * Subsequent drops are summed into the counter.
+     */
+    recordDrop(dstIp, reason, errorMsg) {
+        this.stats.packetsDropped++;
+        const existing = this.dropsByDst.get(dstIp);
+        const next = {
+            count: (existing?.count ?? 0) + 1,
+            lastReason: reason,
+            lastError: errorMsg ? errorMsg.slice(0, 200) : undefined,
+            lastAt: Date.now(),
         };
+        this.dropsByDst.set(dstIp, next);
+        const tuple = `${dstIp}|${reason}`;
+        if (!this.loggedDropTuples.has(tuple)) {
+            this.loggedDropTuples.add(tuple);
+            this.logger.info(`Drop ${dstIp}: ${reason}${errorMsg ? ` — ${errorMsg.slice(0, 120)}` : ""} (further drops with this reason silenced)`);
+        }
     }
     /**
      * Handle outgoing packet (app -> TUN -> Carrier).
@@ -150,8 +184,7 @@ export class PacketRouter extends EventEmitter {
             return;
         const parsed = IpParser.parse(packet);
         if (!parsed) {
-            this.stats.packetsDropped++;
-            this.logger.debug("Dropped invalid IP packet");
+            this.recordDrop("unknown", "invalid-ip");
             return;
         }
         // Get our own pubkey for ACL (we are the source for outbound)
@@ -159,7 +192,7 @@ export class PacketRouter extends EventEmitter {
         const proto = IpParser.protoName(parsed.protocol);
         // Only forward TCP/UDP packets that have ports
         if (parsed.dstPort === undefined && proto !== "icmp") {
-            this.stats.packetsDropped++;
+            this.recordDrop(parsed.dstIp, "no-port");
             return;
         }
         // ACL check (outbound)
@@ -178,11 +211,23 @@ export class PacketRouter extends EventEmitter {
                 return;
             }
         }
-        // Get session for destination
-        const session = await this.sessionManager.getOrOpenSession(parsed.dstIp);
+        // Get session for destination. getOrOpenSession returns null for two
+        // distinct reasons; we want them distinguished in diag so the operator
+        // can tell "I forgot to add this peer to IPAM" from "the friend session
+        // hasn't completed yet." sessionManager.classify() looks up the IPAM
+        // state without triggering a handshake.
+        let session;
+        try {
+            session = await this.sessionManager.getOrOpenSession(parsed.dstIp);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.recordDrop(parsed.dstIp, "handshake-failed", msg);
+            return;
+        }
         if (!session) {
-            this.stats.packetsDropped++;
-            this.logger.debug(`No peer for ${parsed.dstIp}, dropping`);
+            const reason = this.sessionManager.classifyMissingSession(parsed.dstIp);
+            this.recordDrop(parsed.dstIp, reason);
             return;
         }
         // Send packet
@@ -192,16 +237,8 @@ export class PacketRouter extends EventEmitter {
             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}`);
-            }
+            this.recordDrop(parsed.dstIp, "send-failed", msg);
         }
     }
     /**
@@ -240,7 +277,7 @@ export class PacketRouter extends EventEmitter {
         // 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++;
+            this.recordDrop(parsed.dstIp, "tun-down");
             return;
         }
         try {
@@ -249,16 +286,8 @@ export class PacketRouter extends EventEmitter {
             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);
-            }
+            this.recordDrop(parsed.dstIp, "tun-write-failed", msg);
         }
     }
     setupCarrierHandlers() {

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

@@ -5,6 +5,7 @@
 import type { PacketSession } from "../carrier/packet-session.js";
 import type { PeerManager } from "../carrier/peer-manager.js";
 import type { Ipam } from "../ipam/ipam.js";
+import type { DropReason } from "./types.js";
 export declare class SessionManager {
     private peerManager;
     private ipam;
@@ -25,6 +26,13 @@ export declare class SessionManager {
      * Get session by destination IP (no handshake)
      */
     getSession(dstIp: string): PacketSession | null;
+    /**
+     * Classify why getOrOpenSession() returned null for a given dstIp. Used
+     * by PacketRouter to record an accurate drop reason in diag without
+     * having to plumb a (session | string-reason) union through the hot
+     * path.
+     */
+    classifyMissingSession(dstIp: string): DropReason;
     /**
      * Register a session that was opened by remote peer (responder side).
      * Called when PeerManager auto-creates session for inbound HANDSHAKE_REQ.

package/dist/router/session-manager.js

@@ -13,16 +13,16 @@ export class SessionManager {
         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.
+        // Mirror PeerManager's policy: drop the IP→session cache on
+        // disconnect only. `connected` events fire repeatedly during
+        // initial session-up (TCP relay route, then UDP holepunch) and
+        // dropping on each one races with the handshake we just started.
         this.peerManager.on("friend-connection", (evt) => {
+            if (evt.status === "connected")
+                return;
             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.logger.debug(`Dropping ${record.name} (${record.virtualIp}) session on friend-disconnect`);
                 this.sessions.delete(record.virtualIp);
             }
         });
@@ -74,6 +74,21 @@ export class SessionManager {
     getSession(dstIp) {
         return this.sessions.get(dstIp) || null;
     }
+    /**
+     * Classify why getOrOpenSession() returned null for a given dstIp. Used
+     * by PacketRouter to record an accurate drop reason in diag without
+     * having to plumb a (session | string-reason) union through the hot
+     * path.
+     */
+    classifyMissingSession(dstIp) {
+        const record = this.ipam.resolveIp(dstIp);
+        if (!record)
+            return "no-ipam-record";
+        if (!this.peerManager.isFriendOnline(record.carrierId)) {
+            return "friend-offline";
+        }
+        return "handshake-failed";
+    }
     /**
      * Register a session that was opened by remote peer (responder side).
      * Called when PeerManager auto-creates session for inbound HANDSHAKE_REQ.

package/dist/router/types.d.ts

@@ -12,10 +12,29 @@ export interface ParsedPacket {
 export declare const IP_PROTO_TCP = 6;
 export declare const IP_PROTO_UDP = 17;
 export declare const IP_PROTO_ICMP = 1;
+/**
+ * Why a single outbound packet was dropped. Tracked per-destination so
+ * `agentnet diag` can answer the operator's first question — "why
+ * isn't my ping working?" — without forcing them to crank up the
+ * log level.
+ */
+export type DropReason = "invalid-ip" | "no-port" | "no-ipam-record" | "friend-offline" | "handshake-failed" | "send-failed" | "tun-write-failed" | "tun-down";
+export interface DstDropInfo {
+    /** Total drops to this destination. */
+    count: number;
+    /** Most recent reason. */
+    lastReason: DropReason;
+    /** Truncated error message from the most recent drop, if any. */
+    lastError?: string;
+    /** Timestamp (ms since epoch) of the most recent drop. */
+    lastAt: number;
+}
 export interface ForwardingStats {
     packetsForwarded: number;
     packetsReceived: number;
     packetsDenied: number;
     packetsDropped: number;
     activeSessions: number;
+    /** Per-destination drop diagnostics. Keyed by virtual IP. */
+    dropsByDst?: Record<string, DstDropInfo>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/lan",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Private virtual LAN for self-hosted services and AI agents, built on Elastos Carrier. NAT-traversal, name service, ACL, all over a peer-to-peer mesh — no public IP required.",
   "type": "module",
   "main": "./dist/index.js",