@decentnetwork/peer 0.1.138 → 0.1.139

package/dist/compat/inline-file.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Inline files over the Carrier (bulk)message channel — the only file path the
+ * native Beagle apps can see online (toxcore's file transfer 80-82 is invisible
+ * to the Carrier C SDK).
+ *
+ * There are TWO envelopes in the wild:
+ *
+ *  - iOS / Beagle group chats: a FileModel JSON envelope, base64 payload —
+ *    {"data":"<base64>","fileExtension":".jpg","fileName":"…","type":"image"}
+ *    (handled as text in peer.ts, since it is valid UTF-8).
+ *
+ *  - Android 1:1 chats (CarrierFileHelper.packFilePayload): a BINARY envelope
+ *    with a big-endian length prefix, no base64 —
+ *
+ *        [uint32 BE metaLen][meta JSON][raw file bytes]
+ *        meta = {"type":"file","filename":…,"contentType":…,"size":N}
+ *
+ *    The body is real binary, so it never survives a UTF-8 decode: it has to be
+ *    recognised on the raw bytes, or the file is shredded into U+FFFD mojibake.
+ */
+/** Metadata Android puts in front of the bytes. */
+export type AndroidFileEnvelope = {
+    name: string;
+    contentType: string;
+    data: Uint8Array;
+    /** `size` as declared in the header — may disagree with data.length on a
+     *  truncated payload, which the caller can report. */
+    declaredSize?: number;
+};
+/**
+ * Decode Android's binary file envelope. Returns undefined for anything that
+ * isn't one (ordinary chat text included) — never throws.
+ */
+export declare function decodeAndroidFileEnvelope(bytes: Uint8Array): AndroidFileEnvelope | undefined;
+/** Build the same envelope Android builds, byte for byte (key order included). */
+export declare function encodeAndroidFileEnvelope(name: string, data: Uint8Array, contentType?: string): Uint8Array;
+/** Classify an inline file the way the Beagle apps do — by MIME type when the
+ *  sender bothered to set a real one, otherwise by extension. */
+export declare function inlineFileTypeFor(name: string, contentType?: string): "image" | "audio" | "text" | "unknown";

package/dist/compat/inline-file.js

@@ -0,0 +1,80 @@
+/**
+ * Inline files over the Carrier (bulk)message channel — the only file path the
+ * native Beagle apps can see online (toxcore's file transfer 80-82 is invisible
+ * to the Carrier C SDK).
+ *
+ * There are TWO envelopes in the wild:
+ *
+ *  - iOS / Beagle group chats: a FileModel JSON envelope, base64 payload —
+ *    {"data":"<base64>","fileExtension":".jpg","fileName":"…","type":"image"}
+ *    (handled as text in peer.ts, since it is valid UTF-8).
+ *
+ *  - Android 1:1 chats (CarrierFileHelper.packFilePayload): a BINARY envelope
+ *    with a big-endian length prefix, no base64 —
+ *
+ *        [uint32 BE metaLen][meta JSON][raw file bytes]
+ *        meta = {"type":"file","filename":…,"contentType":…,"size":N}
+ *
+ *    The body is real binary, so it never survives a UTF-8 decode: it has to be
+ *    recognised on the raw bytes, or the file is shredded into U+FFFD mojibake.
+ */
+/** Android's own unpackPayload() bounds, mirrored so we accept exactly what it
+ *  sends and reject anything else cheaply. */
+const MAX_META_LEN = 4096;
+/**
+ * Decode Android's binary file envelope. Returns undefined for anything that
+ * isn't one (ordinary chat text included) — never throws.
+ */
+export function decodeAndroidFileEnvelope(bytes) {
+    // A 4-byte big-endian length below 4096 always starts with two zero bytes,
+    // which no chat text ever does — cheap reject before touching the JSON.
+    if (bytes.length < 6 || bytes[0] !== 0 || bytes[1] !== 0)
+        return undefined;
+    const metaLen = ((bytes[2] << 8) | bytes[3]) >>> 0;
+    if (metaLen < 2 || metaLen > MAX_META_LEN || 4 + metaLen > bytes.length)
+        return undefined;
+    try {
+        const json = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(4, 4 + metaLen));
+        const meta = JSON.parse(json);
+        if (meta.type !== "file" || typeof meta.filename !== "string" || meta.filename.length === 0)
+            return undefined;
+        return {
+            name: meta.filename,
+            contentType: typeof meta.contentType === "string" ? meta.contentType : "application/octet-stream",
+            data: bytes.slice(4 + metaLen),
+            declaredSize: typeof meta.size === "number" ? meta.size : undefined
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Build the same envelope Android builds, byte for byte (key order included). */
+export function encodeAndroidFileEnvelope(name, data, contentType = "application/octet-stream") {
+    const meta = new TextEncoder().encode(JSON.stringify({ type: "file", filename: name, contentType, size: data.length }));
+    const out = new Uint8Array(4 + meta.length + data.length);
+    new DataView(out.buffer).setUint32(0, meta.length, false);
+    out.set(meta, 4);
+    out.set(data, 4 + meta.length);
+    return out;
+}
+/** Classify an inline file the way the Beagle apps do — by MIME type when the
+ *  sender bothered to set a real one, otherwise by extension. */
+export function inlineFileTypeFor(name, contentType) {
+    const mime = (contentType ?? "").toLowerCase();
+    if (mime.startsWith("image/"))
+        return "image";
+    if (mime.startsWith("audio/"))
+        return "audio";
+    if (mime.startsWith("text/"))
+        return "text";
+    const dot = name.lastIndexOf(".");
+    const ext = dot > 0 ? name.slice(dot).toLowerCase() : "";
+    if ([".png", ".jpg", ".jpeg", ".gif", ".webp", ".heic", ".heif", ".bmp"].includes(ext))
+        return "image";
+    if ([".m4a", ".mp3", ".aac", ".wav", ".ogg"].includes(ext))
+        return "audio";
+    if ([".txt", ".md", ".log"].includes(ext))
+        return "text";
+    return "unknown";
+}

package/dist/peer.js

@@ -7,6 +7,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 { decodeAndroidFileEnvelope, inlineFileTypeFor } from "./compat/inline-file.js";
 import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, PACKET_TYPE_BULKMSG, PACKET_TYPE_INVITE_REQUEST, PACKET_TYPE_INVITE_RESPONSE, CARRIER_MAX_APP_MESSAGE_LEN, CARRIER_MAX_APP_BULKMSG_LEN, INVITE_DATA_UNIT, CARRIER_MAX_INVITE_DATA_LEN, CARRIER_EXTENSION_NAME, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeBulkMsgPacket, encodeInviteReqPacket, encodeRetransmitRequest } from "./compat/packet.js";
 import { NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID, createOnionAnnounceRequest, createOnionDataPacket, createOnionDataRequest, createOnionRequest0, createOnionRequest0Tcp, 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";
@@ -1555,9 +1556,7 @@ export class Peer {
         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");
+        const type = opts.fileType ?? inlineFileTypeFor(opts.name);
         // Key order matters for byte-identical envelopes with iOS (JSONEncoder
         // .sortedKeys): data, fileExtension, fileName, type — alphabetical.
         const envelope = JSON.stringify({
@@ -3013,7 +3012,11 @@ export class Peer {
                 }
             }
             // Offline images/audio arrive as the same FileModel JSON envelope
-            // (iOS posts the whole thing as one express MESSAGE packet).
+            // (iOS posts the whole thing as one express MESSAGE packet), or as
+            // Android's binary [len][meta][bytes] envelope (ExpressNodeClient uses
+            // the very same packFilePayload as the online path).
+            if (this.#tryEmitBinaryInlineFile(fromUserId, decoded.data, "offline"))
+                return;
             if (this.#tryEmitInlineFile(fromUserId, text, "offline"))
                 return;
             void this.#dispatchTextMessage({ pubkey: fromUserId, text, via: "offline" });
@@ -4222,19 +4225,27 @@ export class Peer {
                 this.#debugLog(`invite-response from ${friendId}: status=${carrier.status} ext="${carrier.ext ?? ""}"`);
                 return;
             }
+            // The message body as it arrived, still undecoded. Android Beagle sends
+            // files as a BINARY envelope (see #tryEmitBinaryInlineFile), and raw file
+            // bytes do not survive a UTF-8 decode — so the sniff has to run here, on
+            // the bytes, before anything turns them into a string.
+            let raw;
             if (carrier?.type === PACKET_TYPE_BULKMSG) {
                 const complete = this.#assembleBulkMsg(friendId, carrier, packetNumber);
                 if (!complete)
                     return; // more fragments pending
-                text = decodeUtf8Best(complete);
+                raw = complete;
                 this.#debugLog(`bulkmsg complete from ${friendId} (${complete.length} bytes)`);
             }
             else if (carrier?.type === PACKET_TYPE_MESSAGE) {
-                text = new TextDecoder().decode(carrier.data);
+                raw = carrier.data;
             }
             else {
-                text = decodeUtf8Best(inner);
+                raw = inner;
             }
+            if (this.#tryEmitBinaryInlineFile(friendId, raw, "online"))
+                return;
+            text = decodeUtf8Best(raw);
             // 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, "");
@@ -4480,6 +4491,28 @@ export class Peer {
             return false;
         }
     }
+    /** Android Beagle sends files as a BINARY envelope over the (bulk)message
+     *  channel — [uint32 BE metaLen][meta JSON][raw bytes], no base64. Raw file
+     *  bytes do not survive a UTF-8 decode, so this sniff runs on the UNDECODED
+     *  payload; before it existed such a message landed in the chat as a wall of
+     *  U+FFFD mojibake with the file lost. Returns true when handled. */
+    #tryEmitBinaryInlineFile(friendId, bytes, via) {
+        const envelope = decodeAndroidFileEnvelope(bytes);
+        if (!envelope)
+            return false;
+        if (envelope.declaredSize !== undefined && envelope.declaredSize !== envelope.data.length) {
+            this.#debugLog(`inline file from ${friendId}: declared ${envelope.declaredSize}B, got ${envelope.data.length}B`);
+        }
+        this.#events.emit("inlineFile", {
+            pubkey: friendId,
+            name: envelope.name,
+            fileType: inlineFileTypeFor(envelope.name, envelope.contentType),
+            data: envelope.data,
+            via
+        });
+        this.#debugLog(`inline file (Android envelope) from ${friendId}: "${envelope.name}" (${envelope.data.length} bytes, ${via})`);
+        return true;
+    }
     /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.138",
+  "version": "0.1.139",
   "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",
@@ -74,7 +74,8 @@
     "test:tcp-onion": "pnpm run build && node scripts/tcp-onion-selftest.mjs",
     "smoke:join": "node scripts/smoke-join.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test:express": "pnpm run build && node scripts/express-scheme-selftest.mjs"
+    "test:express": "pnpm run build && node scripts/express-scheme-selftest.mjs",
+    "test:inline-file": "pnpm run build && node scripts/inline-file-selftest.mjs"
   },
   "dependencies": {
     "flatbuffers": "^25.9.23",