@decentnetwork/lan 0.1.256 → 0.1.257

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/ui/desktop/app.js

@@ -1,4 +1,4 @@
-window.__DK_UI_VERSION="0.1.256";
+window.__DK_UI_VERSION="0.1.257";
 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.257",
   "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",