@decentnetwork/lan 0.1.256 → 0.1.258

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

@@ -81,6 +81,18 @@ export declare class PeerManager extends EventEmitter {
     sign(message: Uint8Array): Uint8Array;
     /** Offer a file to a friend (toxcore-standard transfer). Returns the fileId. */
     sendFile(userid: string, data: Uint8Array, name: string): string | null;
+    /**
+     * Send an APPLICATION packet to a friend. The payload is opaque to
+     * decentlan — this is the extension point that lets an app (beagle, an
+     * agent, any IPC client) run its own protocol over our Carrier session
+     * without a change in here.
+     *
+     * `id` must be in PACKET_ID_APP_MIN..MAX. Rejecting anything else is a
+     * security boundary, not tidiness: our own 161-164 carry session handshakes,
+     * dora control and IP frames, so a caller allowed to pick those ids could
+     * forge a handshake or inject a packet onto a peer's TUN.
+     */
+    sendAppPacket(userid: string, id: number, data: Uint8Array): Promise<void>;
     /** Send a file INLINE over the message channel (FileModel JSON envelope,
      *  bulkmsg-split) — the only file path native iOS/C Carrier clients can
      *  receive online. Use for native friends; JS friends keep sendFile(). */

package/dist/carrier/peer-manager.js

@@ -7,7 +7,7 @@ import { EventEmitter } from "events";
 import { OfflineCallBridge } from "./offline-call.js";
 import { PacketSession } from "./packet-session.js";
 import { FrameCodec } from "./frame.js";
-import { FRAME_OPCODE_HANDSHAKE_ACK, PACKET_ID_DL_SESSION, PACKET_ID_DL_DORA, PACKET_ID_DL_IP, PACKET_ID_DL_RATE, } from "./types.js";
+import { FRAME_OPCODE_HANDSHAKE_ACK, PACKET_ID_DL_SESSION, PACKET_ID_DL_DORA, PACKET_ID_DL_IP, PACKET_ID_DL_RATE, isAppPacketId, } from "./types.js";
 import { Logger } from "../utils/logger.js";
 /**
  * True when a Carrier invite send failed for a reason that will recur
@@ -165,6 +165,25 @@ export class PeerManager extends EventEmitter {
             throw new Error("Peer not created. Call create() first.");
         return this.peer.sendFile(userid, data, { name });
     }
+    /**
+     * Send an APPLICATION packet to a friend. The payload is opaque to
+     * decentlan — this is the extension point that lets an app (beagle, an
+     * agent, any IPC client) run its own protocol over our Carrier session
+     * without a change in here.
+     *
+     * `id` must be in PACKET_ID_APP_MIN..MAX. Rejecting anything else is a
+     * security boundary, not tidiness: our own 161-164 carry session handshakes,
+     * dora control and IP frames, so a caller allowed to pick those ids could
+     * forge a handshake or inject a packet onto a peer's TUN.
+     */
+    async sendAppPacket(userid, id, data) {
+        if (!this.peer)
+            throw new Error("Peer not created. Call create() first.");
+        if (!isAppPacketId(id)) {
+            throw new Error(`packet id ${id} is outside the application range 165-191`);
+        }
+        await this.peer.sendCustomPacket(userid, id, data);
+    }
     /** Send a file INLINE over the message channel (FileModel JSON envelope,
      *  bulkmsg-split) — the only file path native iOS/C Carrier clients can
      *  receive online. Use for native friends; JS friends keep sendFile(). */
@@ -687,6 +706,13 @@ export class PeerManager extends EventEmitter {
                         return;
                     }
                     this.handleDecodedFrame(pubkey, frame);
+                    return;
+                }
+                // Application range: hand the bytes up untouched. We do not parse them,
+                // so a malformed app payload can never reach any decentlan code path —
+                // validating it is the receiving app's job, at its own trust boundary.
+                if (isAppPacketId(id)) {
+                    this.emit("app-packet", pubkey, id, data);
                 }
             }
             catch (error) {

package/dist/carrier/types.d.ts

@@ -12,3 +12,7 @@ export declare const PACKET_ID_DL_SESSION = 161;
 export declare const PACKET_ID_DL_DORA = 162;
 export declare const PACKET_ID_DL_IP = 163;
 export declare const PACKET_ID_DL_RATE = 164;
+export declare const PACKET_ID_APP_MIN = 165;
+export declare const PACKET_ID_APP_MAX = 191;
+/** True when `id` is in the application range apps may send and receive on. */
+export declare function isAppPacketId(id: unknown): id is number;

package/dist/carrier/types.js

@@ -31,3 +31,23 @@ export const PACKET_ID_DL_IP = 163; // lossless: IP data frames (must traverse r
 // so it stops overrunning the path and inducing congestion drops. Payload: a
 // single uint32be = delivered bytes/sec. Rare + tiny, so lossless is free.
 export const PACKET_ID_DL_RATE = 164;
+// --- application packet range -----------------------------------------------
+// 165-191 is handed to APPLICATIONS built on this daemon (beagle, agents, any
+// IPC client). decentlan carries these bytes and never interprets them, so an
+// app can add a protocol of its own without a change here — the reason this
+// range exists at all is so no app ever has to modify the SDK again.
+//
+// Lossless (160-191), like everything else we own: an app-level control message
+// that vanishes on a relay-only session is worse than useless. See the note on
+// PACKET_ID_DL_IP for why lossy is not an option on GFW-crossing paths.
+//
+// The range deliberately STARTS above our own ids. An IPC client is local, but
+// it is not necessarily this daemon's code, and letting it emit on 161-164
+// would let it forge session handshakes, dora control, or IP frames at a peer —
+// i.e. inject onto someone's TUN. The bound is enforced on send AND on receive.
+export const PACKET_ID_APP_MIN = 165;
+export const PACKET_ID_APP_MAX = 191;
+/** True when `id` is in the application range apps may send and receive on. */
+export function isAppPacketId(id) {
+    return typeof id === "number" && Number.isInteger(id) && id >= PACKET_ID_APP_MIN && id <= PACKET_ID_APP_MAX;
+}

package/dist/daemon/ipc.d.ts

@@ -94,6 +94,12 @@ export interface IpcHandlers {
      *  Carrier "carrier" friend-invite extension — the channel iOS/Android Beagle
      *  listen on for calls. Backs the desktop UI's audio/video calls. */
     callSignal: (userid: string, data: string) => Promise<void>;
+    /** Send an application packet (opaque bytes on a Carrier custom-packet id in
+     *  the 165-191 app range) to a friend. The extension point for apps built on
+     *  this daemon: beagle's chat components ride it, and so can anything else,
+     *  without adding an op per feature. Inbound ones arrive as
+     *  `{type:"app", userid, packetId, data}` events on `subscribe`. */
+    appSend: (userid: string, packetId: number, data: Uint8Array) => Promise<void>;
     /** Long-poll for inbound call-signaling payloads. Resolves with any queued
      *  signals immediately, otherwise holds the connection until one arrives or a
      *  ~20s timeout elapses (then resolves empty). The UI re-polls to get
@@ -121,7 +127,7 @@ export interface IpcHandlers {
     selfRestart: () => Promise<Record<string, unknown>>;
 }
 export interface IpcRequest {
-    op: "friend-request" | "ping" | "diag" | "friends-pending" | "friends-accept" | "friends-reject" | "chat-send" | "chat-log-local" | "file-log-local" | "chat-history" | "friends-list" | "friend-remove" | "friend-set-alias" | "friends-autoaccept" | "set-profile" | "file-send" | "file-delete" | "file-cancel" | "file-retry" | "chat-mark-read" | "subscribe" | "sign" | "call-signal" | "call-poll" | "proxy-reload" | "proxy-access" | "self-restart";
+    op: "friend-request" | "ping" | "diag" | "friends-pending" | "friends-accept" | "friends-reject" | "chat-send" | "chat-log-local" | "file-log-local" | "chat-history" | "friends-list" | "friend-remove" | "friend-set-alias" | "friends-autoaccept" | "set-profile" | "file-send" | "file-delete" | "file-cancel" | "file-retry" | "chat-mark-read" | "subscribe" | "sign" | "call-signal" | "call-poll" | "proxy-reload" | "proxy-access" | "app-send" | "self-restart";
     address?: string;
     hello?: string;
     userid?: string;
@@ -137,8 +143,11 @@ export interface IpcRequest {
     ts?: number;
     enabled?: boolean;
     ids?: string[];
-    /** RtcSignal JSON payload for the "call-signal" op. */
+    /** RtcSignal JSON payload for the "call-signal" op; base64 payload for
+     *  "app-send". */
     data?: string;
+    /** Carrier custom-packet id for the "app-send" op (165-191). */
+    packetId?: number;
 }
 export interface IpcResponseOk {
     ok: true;

package/dist/daemon/ipc.js

@@ -276,6 +276,24 @@ export class IpcServer {
                 await this.handlers.callSignal(req.userid, req.data);
                 return;
             }
+            case "app-send": {
+                if (!req.userid)
+                    throw new Error("userid is required");
+                if (typeof req.packetId !== "number")
+                    throw new Error("packetId is required");
+                if (typeof req.data !== "string")
+                    throw new Error("data is required (base64)");
+                // Base64 is the only sane way to carry bytes through a newline-delimited
+                // JSON socket. Buffer.from is lenient — it silently skips invalid chars
+                // rather than throwing — so re-encode and compare: a caller that sends
+                // corrupt base64 must be told, not have truncated bytes put on the wire.
+                const bytes = Buffer.from(req.data, "base64");
+                if (bytes.toString("base64").replace(/=+$/, "") !== req.data.replace(/=+$/, "")) {
+                    throw new Error("data is not valid base64");
+                }
+                await this.handlers.appSend(req.userid, req.packetId, new Uint8Array(bytes));
+                return { sent: bytes.length };
+            }
             case "call-poll":
                 return await this.handlers.callPoll();
             case "proxy-reload":

package/dist/daemon/server.js

@@ -698,6 +698,11 @@ export class DaemonServer {
                     // session (throws if the peer is unreachable, so the UI can surface it).
                     await this.peerManager.sendCallSignal(userid, data);
                 },
+                appSend: async (userid, packetId, data) => {
+                    // Opaque passthrough. The range check lives in PeerManager so it
+                    // applies to every caller, not just this socket.
+                    await this.peerManager.sendAppPacket(userid, packetId, data);
+                },
                 callPoll: async () => {
                     // Drain immediately if signals are queued; otherwise hold up to ~20s
                     // for one to arrive (near-instant delivery without a WebSocket). The
@@ -1196,6 +1201,18 @@ export class DaemonServer {
                 for (const wake of waiters)
                     wake();
             });
+            // Application packets (165-191) — push straight to IPC subscribers as
+            // base64. The daemon never parses them: whatever protocol an app runs up
+            // there is the app's business, and keeping it opaque is what lets apps
+            // evolve without touching this SDK.
+            this.peerManager.on("app-packet", (pubkey, packetId, data) => {
+                this.ipcEvents.emit("event", {
+                    type: "app",
+                    userid: pubkey,
+                    packetId,
+                    data: Buffer.from(data).toString("base64"),
+                });
+            });
             this.peerManager.on("friend-request", (req) => {
                 void pubkeyHexToUserid(req.pubkey).then((userid) => {
                     const who = `${req.name || "(unnamed)"} ${userid}`;

package/dist/router/packet-router.js

@@ -17,6 +17,12 @@ const RATE_REPORT_INTERVAL_MS = 1000;
 // pacing a trickle (SSH/keepalives), and it keeps reports sparse. The pacer's
 // loss window derives its verdict from these reports vs. what it sent.
 const RATE_REPORT_MIN_BYTES = 32 * 1024; // ~256 kbps sustained
+/** Session keepalive: one zero byte on the data channel.
+ *
+ *  Deliberately not a valid IP packet — the receiver recognises and swallows
+ *  it. It exists only to keep the Carrier session warm, so it must never be
+ *  counted as forwarded traffic OR as a drop. */
+const KEEPALIVE_PACKET = new Uint8Array([0]);
 export class PacketRouter extends EventEmitter {
     tunDevice;
     peerManager;
@@ -198,7 +204,7 @@ export class PacketRouter extends EventEmitter {
             if (!session?.isConnected())
                 continue;
             try {
-                await session.send(new Uint8Array([0])); // 1-byte keepalive, dropped at receiver
+                await session.send(KEEPALIVE_PACKET);
             }
             catch {
                 // ignore — session may have just gone offline
@@ -345,8 +351,30 @@ export class PacketRouter extends EventEmitter {
             return;
         const parsed = IpParser.parse(packet);
         if (!parsed) {
-            this.stats.packetsDropped++;
-            this.logger.debug("Dropped invalid incoming IP packet");
+            // Classify instead of lumping. IpParser returns null for three very
+            // different situations and they need different fixes: a short packet
+            // means the transport handed us a truncated frame (MTU / reassembly),
+            // while IPv6 means the SENDER is forwarding traffic we never support --
+            // one is a bug in us, the other is a filter missing upstream. Recording
+            // it per-source also makes it visible in `agentnet diag`, which is how
+            // this stayed hidden: the old code bumped the counter and logged at
+            // debug, so tens of thousands of drops had neither reason nor owner.
+            // OUR OWN keepalive, not a loss. sendKeepalivesToActiveSessions emits a
+            // single zero byte on the data channel and the receiver was counting
+            // every one of them as a dropped packet: 24015 "drops" on mac-dev with
+            // only ~2038 attributable, 16919 on cn against 5. That made the drop
+            // metric useless exactly when it was needed to explain real packet loss,
+            // and sent this investigation down a wrong path first. Swallow it
+            // silently — it did its job by arriving.
+            if (packet.length === KEEPALIVE_PACKET.length && packet[0] === KEEPALIVE_PACKET[0]) {
+                return;
+            }
+            const reason = packet.length < 20
+                ? "inbound-too-short"
+                : ((packet[0] >> 4) & 0x0f) !== 4
+                    ? "inbound-not-ipv4"
+                    : "inbound-bad-header";
+            this.recordDrop(`from:${srcPubkey.slice(0, 12)}`, reason, `len=${packet.length}`);
             return;
         }
         // Auto-learn (srcPubkey -> srcIp) into IPAM. Without this, ubuntu

package/dist/router/types.d.ts

@@ -18,7 +18,7 @@ export declare const IP_PROTO_ICMP = 1;
  * 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 type DropReason = "invalid-ip" | "inbound-too-short" | "inbound-not-ipv4" | "inbound-bad-header" | "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;

package/dist/ui/desktop/app.js

@@ -1,4 +1,4 @@
-window.__DK_UI_VERSION="0.1.256";
+window.__DK_UI_VERSION="0.1.258";
 const ICON_PATHS = {
   // ---- tab bar (the four must feel like one set) ----
   users: '<path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2"/><circle cx="9" cy="7" r="4"/><path d="M22 21v-2a4 4 0 0 0-3-3.87"/><path d="M16 3.13a4 4 0 0 1 0 7.75"/>',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/lan",
-  "version": "0.1.256",
+  "version": "0.1.258",
   "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",
@@ -84,7 +84,7 @@
   },
   "dependencies": {
     "@decentnetwork/dora": "^0.1.14",
-    "@decentnetwork/peer": "^0.1.123",
+    "@decentnetwork/peer": "^0.1.124",
     "@decentnetwork/peer-webrtc": "^0.2.10",
     "ink": "^5.2.1",
     "js-yaml": "^4.1.0",