@decentnetwork/lan 0.1.74 → 0.1.76

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

@@ -6,13 +6,15 @@ import type { PacketFrame } from "./types.js";
 export interface PacketSessionOptions {
     peerId: string;
     sessionId: number;
-    sendText: (text: string) => Promise<void>;
+    /** Send a raw decentlan frame over the given Carrier custom packet id
+     *  (PACKET_ID_DL_SESSION for handshake, PACKET_ID_DL_IP for data). */
+    sendFrame: (frame: Uint8Array, packetId: number) => Promise<void>;
     onClose?: () => void;
 }
 export declare class PacketSession extends EventEmitter {
     private peerId;
     private sessionId;
-    private sendText;
+    private sendFrame;
     private isActive;
     private handshakeTimeout;
     private handshakePromise;

package/dist/carrier/packet-session.js

@@ -3,11 +3,11 @@
  */
 import { EventEmitter } from "events";
 import { FrameCodec } from "./frame.js";
-import { FRAME_OPCODE_HANDSHAKE_REQ, FRAME_OPCODE_DATA, } from "./types.js";
+import { FRAME_OPCODE_HANDSHAKE_REQ, FRAME_OPCODE_DATA, PACKET_ID_DL_SESSION, PACKET_ID_DL_IP, } from "./types.js";
 export class PacketSession extends EventEmitter {
     peerId;
     sessionId;
-    sendText;
+    sendFrame;
     isActive = false;
     handshakeTimeout = null;
     handshakePromise = null;
@@ -15,7 +15,7 @@ export class PacketSession extends EventEmitter {
         super();
         this.peerId = opts.peerId;
         this.sessionId = opts.sessionId;
-        this.sendText = opts.sendText;
+        this.sendFrame = opts.sendFrame;
         this.on("close", () => {
             if (opts.onClose) {
                 opts.onClose();
@@ -38,9 +38,8 @@ export class PacketSession extends EventEmitter {
             return this.handshakePromise;
         }
         this.handshakePromise = new Promise((resolve, reject) => {
-            // Send handshake request
+            // Send handshake request (lossless session channel — must arrive)
             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);
@@ -67,7 +66,7 @@ export class PacketSession extends EventEmitter {
                 this.handshakePromise = null;
                 reject(new Error(`Handshake aborted for peer ${this.peerId}`));
             });
-            this.sendText(frameBase64).catch((error) => {
+            this.sendFrame(frame, PACKET_ID_DL_SESSION).catch((error) => {
                 if (this.handshakeTimeout) {
                     clearTimeout(this.handshakeTimeout);
                 }
@@ -82,9 +81,10 @@ export class PacketSession extends EventEmitter {
             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);
+            // IP data → lossy custom packet (best-effort; inner TCP handles
+            // reliability — see docs/PROTOCOL.md, avoids TCP-over-TCP).
+            await this.sendFrame(frame, PACKET_ID_DL_IP);
         }
         catch (error) {
             // Don't tear down the whole session for a single failed sendText —

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

@@ -152,5 +152,16 @@ export declare class PeerManager extends EventEmitter {
      * Send a HANDSHAKE_ACK frame to a peer.
      */
     private sendHandshakeAck;
+    /**
+     * Send a dora control message to a dora server over the dora custom packet
+     * (162, lossless). Replaces the old `DORA:`-prefixed text on packet 64.
+     */
+    sendDora(userid: string, text: string): Promise<void>;
+    /**
+     * Route a decoded decentlan frame to its packet-session, creating or
+     * replacing the session on a HANDSHAKE_REQ (handles the Carrier re-pair
+     * case where both sides hold different sessionIds).
+     */
+    private handleDecodedFrame;
     private setupEventHandlers;
 }

package/dist/carrier/peer-manager.js

@@ -6,13 +6,8 @@ import { Peer } from "@decentnetwork/peer";
 import { EventEmitter } from "events";
 import { PacketSession } from "./packet-session.js";
 import { FrameCodec } from "./frame.js";
-import { FRAME_OPCODE_HANDSHAKE_ACK, } from "./types.js";
+import { FRAME_OPCODE_HANDSHAKE_ACK, PACKET_ID_DL_SESSION, PACKET_ID_DL_DORA, PACKET_ID_DL_IP, } from "./types.js";
 import { Logger } from "../utils/logger.js";
-// Dora wire-prefix. Kept inline (rather than imported from @decentnetwork/dora) to
-// avoid coupling peer-manager — a transport-layer module — to an
-// application-protocol package. The prefix is part of decentlan's text
-// channel contract and must match the constant defined in dora's types.ts.
-const DORA_PREFIX = "DORA:";
 export class PeerManager extends EventEmitter {
     peer = null;
     identity = null;
@@ -331,11 +326,11 @@ export class PeerManager extends EventEmitter {
         const session = new PacketSession({
             peerId: pubkey,
             sessionId,
-            sendText: async (text) => {
+            sendFrame: async (frame, packetId) => {
                 if (!this.peer) {
                     throw new Error("Peer not available");
                 }
-                await this.peer.sendText(pubkey, text);
+                await this.peer.sendCustomPacket(pubkey, packetId, frame);
             },
             onClose: () => {
                 this.sessions.delete(pubkey);
@@ -364,8 +359,42 @@ export class PeerManager extends EventEmitter {
             throw new Error("Peer not available");
         }
         const frame = FrameCodec.encode(new Uint8Array(0), sessionId, FRAME_OPCODE_HANDSHAKE_ACK);
-        const frameBase64 = Buffer.from(frame).toString("base64");
-        await this.peer.sendText(pubkey, frameBase64);
+        await this.peer.sendCustomPacket(pubkey, PACKET_ID_DL_SESSION, frame);
+    }
+    /**
+     * Send a dora control message to a dora server over the dora custom packet
+     * (162, lossless). Replaces the old `DORA:`-prefixed text on packet 64.
+     */
+    async sendDora(userid, text) {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        await this.peer.sendCustomPacket(userid, PACKET_ID_DL_DORA, Buffer.from(text, "utf-8"));
+    }
+    /**
+     * Route a decoded decentlan frame to its packet-session, creating or
+     * replacing the session on a HANDSHAKE_REQ (handles the Carrier re-pair
+     * case where both sides hold different sessionIds).
+     */
+    handleDecodedFrame(pubkey, frame) {
+        let session = this.sessions.get(pubkey);
+        if (FrameCodec.isHandshakeRequest(frame.opcode)) {
+            if (session && session.getSessionId() !== frame.sessionId) {
+                this.logger.info(`Replacing stale session for ${pubkey} (old=${session.getSessionId()}, new=${frame.sessionId})`);
+                session.close();
+                session = undefined;
+            }
+            if (!session) {
+                this.logger.info(`Auto-creating session for inbound peer ${pubkey} (sessionId=${frame.sessionId})`);
+                session = this.createSession(pubkey, frame.sessionId);
+            }
+        }
+        if (session) {
+            session.handleIncomingFrame(frame);
+        }
+        else {
+            this.logger.debug(`No session for peer ${pubkey}, ignoring frame opcode=0x${frame.opcode.toString(16)}`);
+        }
     }
     setupEventHandlers() {
         if (!this.peer) {
@@ -406,54 +435,37 @@ export class PeerManager extends EventEmitter {
                 }
             }
         });
-        // Text messages contain our framed packets
+        // Packet 64 (PACKET_ID_MESSAGE) is now CHAT only — plain Carrier text,
+        // interoperable with native Carrier clients. IP traffic and dora moved to
+        // their own custom packets (onCustomPacket below). See docs/PROTOCOL.md.
         this.peer.onText((message) => {
+            // Empty messages are kickSessionEstablishment keepalives — ignore.
+            if (message.text.length === 0) {
+                return;
+            }
+            this.emit("message", message.pubkey, message.text);
+        });
+        // decentlan custom packets: IP data (192, lossy), session handshake
+        // (161, lossless), dora control (162, lossless). Each on its own Carrier
+        // packet id — a chat message can never be mistaken for an IP packet, and
+        // no crafted message can inject onto the TUN.
+        this.peer.onCustomPacket(({ pubkey, id, data }) => {
             try {
-                // Silently skip empty messages — kickSessionEstablishment sends
-                // an empty sendText to trigger the SDK's #initiateSession path,
-                // and the receiver doesn't need to log a warning for that.
-                if (message.text.length === 0) {
-                    return;
-                }
-                // Dora messages share the same text channel as packet frames but
-                // carry a `DORA:` ASCII prefix that's not valid base64. Route them
-                // to whoever is subscribed (DoraClient/DoraServer in daemon).
-                if (message.text.startsWith(DORA_PREFIX)) {
-                    this.emit("dora-message", message.pubkey, message.text);
-                    return;
-                }
-                const frameData = Buffer.from(message.text, "base64");
-                const frame = FrameCodec.decode(new Uint8Array(frameData));
-                if (!frame) {
-                    this.logger.warn(`Invalid frame from ${message.pubkey}`);
+                if (id === PACKET_ID_DL_DORA) {
+                    this.emit("dora-message", pubkey, Buffer.from(data).toString("utf-8"));
                     return;
                 }
-                let session = this.sessions.get(message.pubkey);
-                // For HANDSHAKE_REQ: always create or REPLACE the session with the
-                // new sessionId. Without this, after a Carrier session drop + re-pair
-                // the peer's new HANDSHAKE_REQ would be dropped because the existing
-                // local session has the old sessionId — so the responder never sends
-                // HANDSHAKE_ACK and the initiator times out forever.
-                if (FrameCodec.isHandshakeRequest(frame.opcode)) {
-                    if (session && session.getSessionId() !== frame.sessionId) {
-                        this.logger.info(`Replacing stale session for ${message.pubkey} (old=${session.getSessionId()}, new=${frame.sessionId})`);
-                        session.close();
-                        session = undefined;
+                if (id === PACKET_ID_DL_IP || id === PACKET_ID_DL_SESSION) {
+                    const frame = FrameCodec.decode(data);
+                    if (!frame) {
+                        this.logger.warn(`Invalid frame from ${pubkey} (packet ${id})`);
+                        return;
                     }
-                    if (!session) {
-                        this.logger.info(`Auto-creating session for inbound peer ${message.pubkey} (sessionId=${frame.sessionId})`);
-                        session = this.createSession(message.pubkey, frame.sessionId);
-                    }
-                }
-                if (session) {
-                    session.handleIncomingFrame(frame);
-                }
-                else {
-                    this.logger.debug(`No session for peer ${message.pubkey}, ignoring frame opcode=0x${frame.opcode.toString(16)}`);
+                    this.handleDecodedFrame(pubkey, frame);
                 }
             }
             catch (error) {
-                this.logger.error(`Error processing frame from ${message.pubkey}:`, error);
+                this.logger.error(`Error processing custom packet from ${pubkey}:`, error);
             }
         });
         // Friend requests

package/dist/carrier/types.d.ts

@@ -8,3 +8,6 @@ export declare const FRAME_OPCODE_HANDSHAKE_ACK = 2;
 export declare const FRAME_OPCODE_DATA = 16;
 export declare const FRAME_MAGIC = 170;
 export declare const FRAME_HEADER_SIZE = 6;
+export declare const PACKET_ID_DL_SESSION = 161;
+export declare const PACKET_ID_DL_DORA = 162;
+export declare const PACKET_ID_DL_IP = 192;

package/dist/carrier/types.js

@@ -9,3 +9,10 @@ export const FRAME_OPCODE_DATA = 0x10;
 // Frame structure
 export const FRAME_MAGIC = 0xaa;
 export const FRAME_HEADER_SIZE = 6; // magic(1) + length(2) + sessionId(2) + opcode(1)
+// decentlan application packet IDs in toxcore's custom ranges (see
+// docs/PROTOCOL.md). Sent via peer.sendCustomPacket / received via
+// peer.onCustomPacket — a separate channel from chat (PACKET_ID_MESSAGE 64),
+// so IP traffic can never be confused with a Carrier message.
+export const PACKET_ID_DL_SESSION = 161; // lossless: session handshake frames (must arrive)
+export const PACKET_ID_DL_DORA = 162; // lossless: dora control (must arrive)
+export const PACKET_ID_DL_IP = 192; // lossy: IP data frames (best-effort; inner TCP retransmits)

package/dist/daemon/server.d.ts

@@ -51,11 +51,25 @@ export declare class DaemonServer {
      */
     private startPeerStatusSummary;
     getStatus(): DaemonStatus;
+    /** Per-peer timestamp of the last self-heal friend-request re-send, so
+     *  the watchdog escalates at most once per SELF_HEAL_REFRIEND_MS. */
+    private reFriendAt;
+    /** How long a friend must stay non-online before we re-send the
+     *  friend-request again. Long enough not to flood express for a roster
+     *  full of genuinely-dead nodes, short enough to recover a wedged but
+     *  live peer in well under a minute. */
+    private static readonly SELF_HEAL_REFRIEND_MS;
     /**
-     * Periodically poke the SDK to (re-)initiate a session with the friend.
-     * This works around the asymmetric friendOnline issue: without this,
-     * one side may never spontaneously try to talk to the other and the
-     * friend stays perpetually offline.
+     * Periodically poke the SDK to (re-)initiate a session with the friend,
+     * and SELF-HEAL a wedged one. `kickSessionEstablishment` is the weak
+     * nudge; for a friend that's accepted but stuck `offline` (the classic
+     * NAT-to-NAT case where one side restarted, or a connection that simply
+     * died and never recovered) it isn't enough. So when a peer stays
+     * non-online, we escalate to re-sending the actual friend-request — the
+     * strong kick that forces a fresh Carrier handshake. This is the
+     * automatic version of `agentnet friend-request <addr>`, so a private or
+     * friend-invited exit recovers on its own instead of needing a human to
+     * run a command (which an invited operator never will).
      */
     private kickSessionForever;
     /**

package/dist/daemon/server.js

@@ -649,16 +649,47 @@ export class DaemonServer {
             activeSessions: this.packetRouter?.getStats().activeSessions || 0,
         };
     }
+    /** Per-peer timestamp of the last self-heal friend-request re-send, so
+     *  the watchdog escalates at most once per SELF_HEAL_REFRIEND_MS. */
+    reFriendAt = new Map();
+    /** How long a friend must stay non-online before we re-send the
+     *  friend-request again. Long enough not to flood express for a roster
+     *  full of genuinely-dead nodes, short enough to recover a wedged but
+     *  live peer in well under a minute. */
+    static SELF_HEAL_REFRIEND_MS = 45_000;
     /**
-     * Periodically poke the SDK to (re-)initiate a session with the friend.
-     * This works around the asymmetric friendOnline issue: without this,
-     * one side may never spontaneously try to talk to the other and the
-     * friend stays perpetually offline.
+     * Periodically poke the SDK to (re-)initiate a session with the friend,
+     * and SELF-HEAL a wedged one. `kickSessionEstablishment` is the weak
+     * nudge; for a friend that's accepted but stuck `offline` (the classic
+     * NAT-to-NAT case where one side restarted, or a connection that simply
+     * died and never recovered) it isn't enough. So when a peer stays
+     * non-online, we escalate to re-sending the actual friend-request — the
+     * strong kick that forces a fresh Carrier handshake. This is the
+     * automatic version of `agentnet friend-request <addr>`, so a private or
+     * friend-invited exit recovers on its own instead of needing a human to
+     * run a command (which an invited operator never will).
      */
     async kickSessionForever(carrierId, name) {
         while (this.isRunning) {
             try {
                 await this.peerManager.kickSessionEstablishment(carrierId);
+                const f = this.peerManager
+                    .getFriends()
+                    .find((x) => x.carrierId === carrierId || x.pubkey === carrierId);
+                if (f && f.status === "online") {
+                    // Healthy — clear the timer so a future drop re-heals promptly.
+                    this.reFriendAt.delete(carrierId);
+                }
+                else if (f && f.status !== "online" && f.address) {
+                    const last = this.reFriendAt.get(carrierId) ?? 0;
+                    if (Date.now() - last >= DaemonServer.SELF_HEAL_REFRIEND_MS) {
+                        this.reFriendAt.set(carrierId, Date.now());
+                        this.logger.info(`Self-heal: ${name} is ${f.status} — re-sending friend-request to re-establish the session`);
+                        void this.peerManager
+                            .sendFriendRequest(f.address, "decentlan: self-heal")
+                            .catch((err) => this.logger.debug(`self-heal friend-request ${name}: ${err instanceof Error ? err.message : err}`));
+                    }
+                }
             }
             catch (err) {
                 this.logger.debug(`kickSessionEstablishment ${name}: ${err}`);

package/dist/dora/dora-integration.js

@@ -40,7 +40,7 @@ export class DoraIntegration {
         this.logger = new Logger({ prefix: "Dora" });
         this.client = new DoraClient({
             registryUserids: opts.config.userids ?? [],
-            sendText: (toUserid, text) => opts.peerManager.sendText(toUserid, text),
+            sendText: (toUserid, text) => opts.peerManager.sendDora(toUserid, text),
             onText: (handler) => {
                 opts.peerManager.on("dora-message", (fromUserid, text) => {
                     handler(fromUserid, text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/lan",
-  "version": "0.1.74",
+  "version": "0.1.76",
   "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",
@@ -77,7 +77,7 @@
   },
   "dependencies": {
     "@decentnetwork/dora": "^0.1.6",
-    "@decentnetwork/peer": "^0.1.32",
+    "@decentnetwork/peer": "^0.1.33",
     "js-yaml": "^4.1.0",
     "yargs": "^17.7.2"
   },