@decentnetwork/peer 0.1.81 → 0.1.83

package/dist/compat/packet.d.ts

@@ -1,6 +1,9 @@
 export declare const PACKET_TYPE_USERINFO = 3;
 export declare const PACKET_TYPE_FRIEND_REQUEST = 6;
 export declare const PACKET_TYPE_MESSAGE = 33;
+export declare const PACKET_TYPE_BULKMSG = 36;
+export declare const CARRIER_MAX_APP_MESSAGE_LEN = 1024;
+export declare const CARRIER_MAX_APP_BULKMSG_LEN: number;
 export type UserInfoPacket = {
     type: typeof PACKET_TYPE_USERINFO;
     avatar: boolean;
@@ -22,7 +25,16 @@ export type FriendMessagePacket = {
     ext?: string;
     data: Uint8Array;
 };
-export type CarrierPacket = UserInfoPacket | FriendRequestPacket | FriendMessagePacket;
+export type BulkMsgPacket = {
+    type: typeof PACKET_TYPE_BULKMSG;
+    ext?: string;
+    /** Full message length — set on the FIRST fragment only, 0 on the rest. */
+    totalsz: number;
+    /** Shared id linking all fragments of one message. */
+    tid: bigint;
+    data: Uint8Array;
+};
+export type CarrierPacket = UserInfoPacket | FriendRequestPacket | FriendMessagePacket | BulkMsgPacket;
 /**
  * Encode a Carrier `userinfo` packet (FB type 3). The Carrier C SDK sends
  * this every time the local user's name / status message / profile fields
@@ -52,4 +64,15 @@ export declare function encodeFriendRequestPacket(opts: {
     hello?: string;
 }): Uint8Array;
 export declare function encodeFriendMessagePacket(data: Uint8Array | string, ext?: string): Uint8Array;
+/**
+ * Encode one Carrier `bulkmsg` fragment (PACKET_TYPE_BULKMSG = 36). Field
+ * layout per src/carrier/packet.fbs: 0=ext string, 1=totalsz uint,
+ * 2=tid long, 3=data [ubyte]. Mirrors the C SDK's send_bulk_message.
+ */
+export declare function encodeBulkMsgPacket(opts: {
+    ext?: string;
+    totalsz: number;
+    tid: bigint;
+    data: Uint8Array;
+}): Uint8Array;
 export declare function decodeCarrierPacket(bytes: Uint8Array): CarrierPacket;

package/dist/compat/packet.js

@@ -2,12 +2,20 @@ import { Builder, ByteBuffer, Encoding } from "flatbuffers";
 export const PACKET_TYPE_USERINFO = 3;
 export const PACKET_TYPE_FRIEND_REQUEST = 6;
 export const PACKET_TYPE_MESSAGE = 33;
+export const PACKET_TYPE_BULKMSG = 36;
+// Carrier C SDK message-size constants (carrier.h). A single friendmsg may
+// carry at most 1024 bytes; anything larger is split into BULKMSG fragments
+// of <=1024 raw bytes sharing one tid (totalsz set on the FIRST fragment
+// only), reassembled in arrival order by the receiver.
+export const CARRIER_MAX_APP_MESSAGE_LEN = 1024;
+export const CARRIER_MAX_APP_BULKMSG_LEN = 5 * 1024 * 1024;
 // Body type indices into FlatBuffers `anybody` union (carrier/packet.fbs).
 // The .fbs declares: userinfo, friendreq, friendmsg, invitereq, invitersp,
 // bulkmsg — flatbuffers maps those to 1, 2, 3, 4, 5, 6 (NONE = 0).
 const ANYBODY_USERINFO = 1;
 const ANYBODY_FRIENDREQ = 2;
 const ANYBODY_FRIENDMSG = 3;
+const ANYBODY_BULKMSG = 6;
 /**
  * Encode a Carrier `userinfo` packet (FB type 3). The Carrier C SDK sends
  * this every time the local user's name / status message / profile fields
@@ -69,6 +77,29 @@ export function encodeFriendMessagePacket(data, ext) {
     const friendMsg = builder.endObject();
     return finishCarrierPacket(builder, PACKET_TYPE_MESSAGE, ANYBODY_FRIENDMSG, friendMsg);
 }
+/**
+ * Encode one Carrier `bulkmsg` fragment (PACKET_TYPE_BULKMSG = 36). Field
+ * layout per src/carrier/packet.fbs: 0=ext string, 1=totalsz uint,
+ * 2=tid long, 3=data [ubyte]. Mirrors the C SDK's send_bulk_message.
+ */
+export function encodeBulkMsgPacket(opts) {
+    const builder = new Builder(opts.data.length + 128);
+    const dataOffset = builder.createByteVector(opts.data);
+    const extOffset = opts.ext ? builder.createString(opts.ext) : 0;
+    builder.startObject(4);
+    builder.addFieldOffset(3, dataOffset, 0);
+    if (opts.tid !== 0n) {
+        builder.addFieldInt64(2, opts.tid, BigInt(0));
+    }
+    if (opts.totalsz) {
+        builder.addFieldInt32(1, opts.totalsz, 0);
+    }
+    if (extOffset) {
+        builder.addFieldOffset(0, extOffset, 0);
+    }
+    const bulk = builder.endObject();
+    return finishCarrierPacket(builder, PACKET_TYPE_BULKMSG, ANYBODY_BULKMSG, bulk);
+}
 export function decodeCarrierPacket(bytes) {
     const bb = new ByteBuffer(bytes);
     const root = bb.readInt32(bb.position()) + bb.position();
@@ -106,6 +137,15 @@ export function decodeCarrierPacket(bytes) {
             data: readByteVectorField(body, 1) ?? new Uint8Array()
         };
     }
+    if (type === PACKET_TYPE_BULKMSG && bodyType === ANYBODY_BULKMSG) {
+        return {
+            type,
+            ext: readStringField(body, 0) ?? undefined,
+            totalsz: readUint32Field(body, 1),
+            tid: readInt64Field(body, 2),
+            data: readByteVectorField(body, 3) ?? new Uint8Array()
+        };
+    }
     throw new Error(`unsupported carrier packet type/body: ${type}/${bodyType}`);
 }
 function finishCarrierPacket(builder, type, bodyType, bodyOffset) {
@@ -125,6 +165,14 @@ function readUint8Field(table, field) {
     const offset = table.bb.__offset(table.bb_pos, 4 + field * 2);
     return offset ? table.bb.readUint8(table.bb_pos + offset) : 0;
 }
+function readUint32Field(table, field) {
+    const offset = table.bb.__offset(table.bb_pos, 4 + field * 2);
+    return offset ? table.bb.readUint32(table.bb_pos + offset) : 0;
+}
+function readInt64Field(table, field) {
+    const offset = table.bb.__offset(table.bb_pos, 4 + field * 2);
+    return offset ? table.bb.readInt64(table.bb_pos + offset) : BigInt(0);
+}
 function readStringField(table, field) {
     const offset = table.bb.__offset(table.bb_pos, 4 + field * 2);
     if (!offset) {

package/dist/peer.d.ts

@@ -1,6 +1,6 @@
 import { type BootstrapResult } from "./compat/bootstrap.js";
 import type { FriendRecord } from "./store/friends.js";
-import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
 export declare class Peer {
     #private;
     private constructor();
@@ -82,6 +82,23 @@ export declare class Peer {
     waitForFriendConnected(pubkey: string, timeoutMs?: number): Promise<boolean>;
     onFriendRequest(cb: (req: FriendRequest) => void): void;
     onText(cb: (msg: TextMessage) => void): void;
+    /** Files received inline over (bulk)messages — the iOS/C Carrier apps'
+     *  native way of sending images/audio online (FileModel JSON envelope). */
+    onInlineFile(cb: (evt: InlineFileEvent) => void): void;
+    /**
+     * Send a file INLINE over the message channel the way iOS/C Carrier apps
+     * do: a FileModel JSON envelope ({data: base64, fileExtension, fileName,
+     * type}) carried as a (bulk)message. This is the ONLY file path a native
+     * Beagle client can receive online — the toxcore file transfer (80-82)
+     * used by sendFile() is invisible to the Carrier C SDK. Best for images
+     * and small files; the hard protocol cap is ~5MB (base64-inflated), keep
+     * real use well below it.
+     */
+    sendInlineFile(pubkey: string, opts: {
+        name: string;
+        data: Uint8Array;
+        fileType?: "image" | "audio" | "text" | "unknown";
+    }): Promise<void>;
     /**
      * Send an application-defined custom packet to a friend. `id` selects the
      * channel and its delivery class by toxcore range: **160–191 lossless**

package/dist/peer.js

@@ -5,7 +5,7 @@ import { dirname, join } from "node:path";
 import nacl from "tweetnacl";
 import { carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
 import { LegacyBootstrapClient } from "./compat/bootstrap.js";
-import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket } from "./compat/packet.js";
+import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, PACKET_TYPE_BULKMSG, CARRIER_MAX_APP_MESSAGE_LEN, CARRIER_MAX_APP_BULKMSG_LEN, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeBulkMsgPacket } from "./compat/packet.js";
 import { NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID, createOnionAnnounceRequest, createOnionDataPacket, createOnionDataRequest, createOnionRequest0, openOnionAnnounceResponse, openOnionDataPacket, openOnionDataResponse } from "./compat/tox-onion.js";
 import { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 import { NET_PACKET_PING_REQUEST, NET_PACKET_PING_RESPONSE, NET_PACKET_GET_NODES, NET_PACKET_SEND_NODES, encodeDhtRpc, decodeDhtRpc, buildPingPlain, parsePingPlain, buildGetNodesPlain, parseGetNodesPlain, buildSendNodesPlain, parseSendNodesNodeBytes, packUdpNodeV4 } from "./compat/dht-rpc.js";
@@ -306,6 +306,11 @@ export class Peer {
     // #initiateSession every few seconds for every friend; without this
     // dedupe, lower-pubkey side floods the log with "deferring to peer".
     #initiateSkipLogged = new Set();
+    // In-flight Carrier BULKMSG reassemblies, keyed `${friendId}:${tid}`.
+    // Fragments are appended in arrival order (the lossless stream keeps
+    // them ordered) and the message completes when totalsz bytes arrived.
+    // Mirrors the C SDK's bulkmsgs hashtable with its 60s assembly timeout.
+    #bulkAssembly = new Map();
     // When we FIRST deferred initiation to a higher-pubkey peer (per friend).
     // If the peer hasn't established within the grace window we break the
     // defer and initiate ourselves (see #initiateSession). Cleared whenever a
@@ -955,6 +960,30 @@ export class Peer {
             }
         }
         const packet = encodeFriendMessagePacket(text);
+        // Carrier C peers accept at most 1024 raw bytes per friendmsg; larger
+        // messages MUST be split into BULKMSG fragments (shared tid, totalsz on
+        // the first fragment) or a native receiver drops them. The express
+        // fallback below still posts the single big MESSAGE packet — that's
+        // what the C SDK does offline too.
+        const rawText = new TextEncoder().encode(text);
+        let livePackets;
+        if (rawText.length > CARRIER_MAX_APP_MESSAGE_LEN) {
+            if (rawText.length > CARRIER_MAX_APP_BULKMSG_LEN) {
+                throw new Error(`message exceeds bulk limit (${rawText.length} > ${CARRIER_MAX_APP_BULKMSG_LEN})`);
+            }
+            const tid = (BigInt(Date.now()) << 20n) ^ BigInt(Math.floor(Math.random() * 0xfffff));
+            livePackets = [];
+            for (let off = 0; off < rawText.length; off += CARRIER_MAX_APP_MESSAGE_LEN) {
+                livePackets.push(encodeBulkMsgPacket({
+                    totalsz: off === 0 ? rawText.length : 0,
+                    tid,
+                    data: rawText.subarray(off, Math.min(off + CARRIER_MAX_APP_MESSAGE_LEN, rawText.length))
+                }));
+            }
+        }
+        else {
+            livePackets = [packet];
+        }
         // Try the live in-session path first when any transport is up
         // (UDP via session.remote, or TCP relay via session.hasTcpRoute).
         // #sendMessengerPacket internally fans out to both transports and
@@ -980,7 +1009,9 @@ export class Peer {
             && provenInbound;
         if (liveSession) {
             try {
-                await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, packet);
+                for (const p of livePackets) {
+                    await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, p);
+                }
                 return;
             }
             catch (error) {
@@ -1060,6 +1091,40 @@ export class Peer {
     onText(cb) {
         this.#events.on("text", cb);
     }
+    /** Files received inline over (bulk)messages — the iOS/C Carrier apps'
+     *  native way of sending images/audio online (FileModel JSON envelope). */
+    onInlineFile(cb) {
+        this.#events.on("inlineFile", cb);
+    }
+    /**
+     * Send a file INLINE over the message channel the way iOS/C Carrier apps
+     * do: a FileModel JSON envelope ({data: base64, fileExtension, fileName,
+     * type}) carried as a (bulk)message. This is the ONLY file path a native
+     * Beagle client can receive online — the toxcore file transfer (80-82)
+     * used by sendFile() is invisible to the Carrier C SDK. Best for images
+     * and small files; the hard protocol cap is ~5MB (base64-inflated), keep
+     * real use well below it.
+     */
+    async sendInlineFile(pubkey, opts) {
+        const dot = opts.name.lastIndexOf(".");
+        const ext = dot > 0 ? opts.name.slice(dot).toLowerCase() : "";
+        const base = dot > 0 ? opts.name.slice(0, dot) : opts.name;
+        const type = opts.fileType ?? ([".png", ".jpg", ".jpeg", ".gif", ".webp", ".heic"].includes(ext) ? "image" :
+            [".m4a", ".mp3", ".aac", ".wav", ".ogg"].includes(ext) ? "audio" :
+                [".txt", ".md", ".log"].includes(ext) ? "text" : "unknown");
+        // Key order matters for byte-identical envelopes with iOS (JSONEncoder
+        // .sortedKeys): data, fileExtension, fileName, type — alphabetical.
+        const envelope = JSON.stringify({
+            data: Buffer.from(opts.data).toString("base64"),
+            fileExtension: ext,
+            fileName: base,
+            type
+        });
+        if (envelope.length > CARRIER_MAX_APP_BULKMSG_LEN) {
+            throw new Error(`inline file too large for the message channel (${envelope.length} bytes encoded, max ${CARRIER_MAX_APP_BULKMSG_LEN})`);
+        }
+        await this.sendText(pubkey, envelope);
+    }
     /**
      * Send an application-defined custom packet to a friend. `id` selects the
      * channel and its delivery class by toxcore range: **160–191 lossless**
@@ -1994,14 +2059,43 @@ export class Peer {
                     return;
                 }
                 if (kind === PACKET_ID_MESSAGE || kind === PACKET_ID_ACTION) {
-                    // Plain text inside (no Carrier FlatBuffers wrapper). Some peers
-                    // send raw UTF-8, others send a Carrier message packet — try both.
-                    let text = tryDecodeCarrierMessagePacket(inner) ?? decodeUtf8Best(inner);
+                    this.#setFriendOnline(friendId, remote.address, remote.port);
+                    // Decode the Carrier FlatBuffers wrapper when present. A BULKMSG
+                    // fragment (Carrier C splits any message >1024 bytes this way —
+                    // e.g. iOS Beagle images, which are FileModel JSON envelopes)
+                    // goes to the reassembler and only emits once complete; before
+                    // this, every fragment surfaced as a separate garbage "text".
+                    let text;
+                    let carrier;
+                    try {
+                        carrier = decodeCarrierPacket(inner);
+                    }
+                    catch { /* raw utf-8 peer */ }
+                    if (carrier?.type === PACKET_TYPE_BULKMSG) {
+                        const complete = this.#assembleBulkMsg(friendId, carrier);
+                        if (!complete)
+                            return; // more fragments pending
+                        text = decodeUtf8Best(complete);
+                        this.#debugLog(`bulkmsg complete from ${friendId} (${complete.length} bytes)`);
+                    }
+                    else if (carrier?.type === PACKET_TYPE_MESSAGE) {
+                        text = new TextDecoder().decode(carrier.data);
+                    }
+                    else {
+                        text = decodeUtf8Best(inner);
+                    }
+                    // Carrier C peers terminate strings with a NUL — strip it so chat
+                    // text doesn't carry an invisible trailing byte.
+                    text = text?.replace(/\0+$/u, "");
                     if (!text) {
                         this.#debugLog(`crypto message packet decode failed from ${friendId}`);
                         return;
                     }
-                    this.#setFriendOnline(friendId, remote.address, remote.port);
+                    // iOS Beagle sends files inline as a FileModel JSON envelope
+                    // ({data: base64, fileExtension, fileName, type}) — surface those
+                    // as files, not as a wall of base64 text.
+                    if (this.#tryEmitInlineFile(friendId, text, "online"))
+                        return;
                     this.#events.emit("text", {
                         pubkey: friendId,
                         text,
@@ -2370,6 +2464,10 @@ export class Peer {
                     // Malformed pubkey, fall through.
                 }
             }
+            // Offline images/audio arrive as the same FileModel JSON envelope
+            // (iOS posts the whole thing as one express MESSAGE packet).
+            if (this.#tryEmitInlineFile(fromUserId, text, "offline"))
+                return;
             this.#events.emit("text", { pubkey: fromUserId, text, via: "offline" });
         }
         catch {
@@ -3113,6 +3211,72 @@ export class Peer {
             });
         }
     }
+    /** Append a Carrier BULKMSG fragment; returns the full reassembled
+     *  message when the last fragment lands, undefined while pending.
+     *  Mirrors the C SDK's handle_friend_bulkmsg: totalsz on the first
+     *  fragment sizes the buffer; fragments append in arrival order. */
+    #assembleBulkMsg(friendId, frag) {
+        const now = Date.now();
+        // Lazy expiry sweep (C uses a 60s assembly timeout).
+        for (const [key, entry] of this.#bulkAssembly) {
+            if (entry.expireAtMs < now)
+                this.#bulkAssembly.delete(key);
+        }
+        const key = `${friendId}:${frag.tid.toString()}`;
+        let entry = this.#bulkAssembly.get(key);
+        if (!entry) {
+            if (!frag.totalsz || frag.totalsz > CARRIER_MAX_APP_BULKMSG_LEN) {
+                this.#debugLog(`bulkmsg from ${friendId} with invalid/missing totalsz ${frag.totalsz} — dropped`);
+                return undefined;
+            }
+            entry = { total: frag.totalsz, chunks: [], got: 0, expireAtMs: now + 60_000 };
+            this.#bulkAssembly.set(key, entry);
+        }
+        if (frag.data.length === 0 || entry.got + frag.data.length > entry.total) {
+            this.#debugLog(`bulkmsg fragment from ${friendId} overflows totalsz — dropped`);
+            this.#bulkAssembly.delete(key);
+            return undefined;
+        }
+        entry.chunks.push(frag.data);
+        entry.got += frag.data.length;
+        if (entry.got < entry.total)
+            return undefined;
+        this.#bulkAssembly.delete(key);
+        return concatBytes(entry.chunks);
+    }
+    /** iOS Beagle sends files inline as a JSON envelope over (bulk)messages:
+     *  {"data":"<base64>","fileExtension":".jpg","fileName":"…","type":"image"}.
+     *  Detect it, decode, and emit an inlineFile event instead of dumping
+     *  base64 into the chat. Returns true when handled. */
+    #tryEmitInlineFile(friendId, text, via) {
+        // The Carrier C SDK sends messages with a trailing C-string NUL, which
+        // JSON.parse rejects. iOS's own decoder strips NULs before parsing
+        // (CodableUtil.decode: replacingOccurrences(of: "\0")) — mirror that.
+        const trimmed = text.replaceAll("\0", "").trim();
+        if (!trimmed.startsWith("{") || !trimmed.includes("\"fileName\"") || !trimmed.includes("\"data\"")) {
+            return false;
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.data !== "string" || typeof parsed.fileName !== "string")
+                return false;
+            const data = Uint8Array.from(Buffer.from(parsed.data, "base64"));
+            const ext = parsed.fileExtension ?? "";
+            const name = parsed.fileName.endsWith(ext) ? parsed.fileName : parsed.fileName + ext;
+            this.#events.emit("inlineFile", {
+                pubkey: friendId,
+                name,
+                fileType: parsed.type,
+                data,
+                via
+            });
+            this.#debugLog(`inline file from ${friendId}: "${name}" (${data.length} bytes, ${via})`);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /** Toxcore handle_request_packet: parse the peer's PACKET_ID_REQUEST and
      *  (a) implicitly ACK every walked packet number that isn't requested,
      *  (b) retransmit the requested ones from the send buffer. */

package/dist/types/peer.d.ts

@@ -114,6 +114,22 @@ export type CustomPacketEvent = {
     id: number;
     data: Uint8Array;
 };
+/**
+ * A file received INLINE over the message channel — the way iOS/C Carrier
+ * apps send images/audio online: a FileModel JSON envelope
+ * ({data: base64, fileExtension, fileName, type}) carried as a
+ * (bulk)message. Distinct from the toxcore file-transfer path (sendFile),
+ * which native Carrier clients cannot see.
+ */
+export type InlineFileEvent = {
+    pubkey: string;
+    /** File name including extension. */
+    name: string;
+    /** The sender's declared type ("image" | "audio" | "text" | …), if any. */
+    fileType?: string;
+    data: Uint8Array;
+    via: "online" | "offline";
+};
 export type LookupResult = {
     pubkey: string;
     status: "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.81",
+  "version": "0.1.83",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",