@decentnetwork/peer 0.1.138 → 0.1.140

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/index.d.ts

@@ -14,4 +14,4 @@ export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";
 export type { CarrierPacket, FriendMessagePacket, FriendRequestPacket, InviteReqPacket, InviteRspPacket } from "./compat/packet.js";
 export type { ToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export type { CarrierAddressParts } from "./compat/address.js";
-export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";
+export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InlineSendResult, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";

package/dist/peer.d.ts

@@ -1,7 +1,7 @@
 import { type BootstrapResult } from "./compat/bootstrap.js";
 import type { FriendRecord } from "./store/friends.js";
 import { type CarrierTurnServerInfo, type RtcIceServer } from "./ice-servers.js";
-import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";
+import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InlineSendResult, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";
 export declare class Peer {
     #private;
     private constructor();
@@ -140,7 +140,16 @@ export declare class Peer {
         name: string;
         data: Uint8Array;
         fileType?: "image" | "audio" | "text" | "unknown";
-    }): Promise<void>;
+        deliveryTimeoutMs?: number;
+    }): Promise<InlineSendResult>;
+    /**
+     * True when this friend is a NATIVE Carrier client (iOS/Android/C SDK): its
+     * DHT/relay key differs from its identity key, where a JS peer announces its
+     * identity key as its DHT key. Natives cannot see the toxcore file-transfer
+     * protocol (sendFile) — the inline envelope is their only file path — and
+     * they never speak the JS text-ACK scheme.
+     */
+    isNativeFriend(pubkey: string): boolean;
     /** Fired when a peer sends a Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST).
      *  This is the channel the iOS/Android WebRTC SDK uses for call signaling —
      *  each RtcSignal arrives as an "invite" with ext="carrier" and `data` the

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";
@@ -1239,6 +1240,9 @@ export class Peer {
         }
         await this.#sendTextPlain(pubkey, text);
     }
+    /** What #sendTextPlain actually did with the message — callers that promise
+     *  delivery semantics (inline files) need to know the path and, for the live
+     *  path, where the send window stood after the last fragment. */
     async #sendTextPlain(pubkey, text) {
         const friend = this.#friends.get(pubkey);
         if (!friend) {
@@ -1306,7 +1310,10 @@ export class Peer {
                 for (const p of livePackets) {
                     await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, p);
                 }
-                return;
+                // Every fragment got a packet number BELOW the counter's position now —
+                // when the peer's implicit acks advance the window past it, the whole
+                // message is confirmed on their device.
+                return { via: "online", endPacketNumber: this.#friendSessions.get(pubkey)?.sendPacketNumber };
             }
             catch (error) {
                 const emsg = error.message;
@@ -1342,7 +1349,7 @@ export class Peer {
         // no session is simply a no-op.
         if (text.length === 0) {
             this.#debugLog(`sendText: empty connection-kick to ${pubkey} with no live session — dropping (not flooding express)`);
-            return;
+            return { via: "online" };
         }
         // Offline / fallback path via Carrier express HTTP store-and-forward.
         // Skipped entirely in control-plane-only mode (decentlan's data plane):
@@ -1352,7 +1359,7 @@ export class Peer {
         if (this.#express?.hasNodes() && !this.#opts.expressControlPlaneOnly) {
             await this.#express.sendOfflineText(pubkey, packet);
             this.#debugLog(`sendText: queued via express for ${pubkey}`);
-            return;
+            return { via: "offline" };
         }
         throw new Error("friend is offline and no express node is configured");
     }
@@ -1555,9 +1562,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({
@@ -1569,7 +1574,77 @@ export class Peer {
         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);
+        // The confirmation window scales with the payload: a floor for handshake
+        // latency plus time to move the envelope at a conservative 50 KB/s, capped
+        // so a dead session can't pin the caller for ages.
+        const deliveryTimeoutMs = opts.deliveryTimeoutMs ??
+            Math.min(180_000, 20_000 + Math.ceil(envelope.length / 50));
+        if (this.#shouldRequireTextAck(pubkey)) {
+            // JS peer: the app-level text-ACK is the strongest confirmation there is
+            // — the receiving app parsed the envelope. The retry interval must be
+            // longer than one full send of the payload, or a slow path gets the
+            // whole multi-MB envelope re-blasted mid-flight.
+            await this.sendTextUntilAck(pubkey, envelope, {
+                timeoutMs: deliveryTimeoutMs,
+                retryIntervalMs: Math.max(TEXT_ACK_RETRY_MS, Math.ceil(envelope.length / 100))
+            });
+            return { delivery: "acked" };
+        }
+        // Native peer (iOS/Android/C): it will never speak our text-ACK envelope,
+        // but its toxcore DOES acknowledge every reliable packet — the very signal
+        // its own SDK surfaces to the app as "Delivered". Wait for the send window
+        // to drain past our fragments.
+        const outcome = await this.#sendTextPlain(pubkey, envelope);
+        if (outcome.via === "offline")
+            return { delivery: "offline" };
+        if (outcome.endPacketNumber === undefined)
+            return { delivery: "accepted" };
+        const acked = await this.#awaitTransportAck(pubkey, outcome.endPacketNumber, deliveryTimeoutMs);
+        this.#debugLog(`inline file "${opts.name}" to ${pubkey}: transport ${acked ? "ACKED" : `NOT confirmed within ${deliveryTimeoutMs}ms`}`);
+        return { delivery: acked ? "acked" : "accepted" };
+    }
+    /**
+     * True once the friend's implicit acks (PACKET_ID_REQUEST walks) have moved
+     * our reliable send window past `endPacketNumber` — i.e. every packet we had
+     * sent by that point is confirmed received on their device. False when the
+     * window doesn't drain in time or the session dies/rekeys under us (a new
+     * session restarts the numbering, so the old position proves nothing).
+     */
+    async #awaitTransportAck(pubkey, endPacketNumber, timeoutMs) {
+        const watched = this.#friendSessions.get(pubkey);
+        if (!watched)
+            return false;
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const session = this.#friendSessions.get(pubkey);
+            if (session !== watched || !session.established)
+                return false;
+            const start = session.sendBufferStartNum;
+            if (start !== undefined) {
+                // Wraparound-safe: the window is ≤8192 packets, so a "distance" over
+                // 2^31 means start has passed endPacketNumber.
+                const pending = (endPacketNumber - start) >>> 0;
+                if (pending === 0 || pending > 0x80000000)
+                    return true;
+            }
+            else if (!session.sendArray || session.sendArray.size === 0) {
+                return true; // nothing left unacknowledged at all
+            }
+            if (Date.now() >= deadline)
+                return false;
+            await sleep(250);
+        }
+    }
+    /**
+     * True when this friend is a NATIVE Carrier client (iOS/Android/C SDK): its
+     * DHT/relay key differs from its identity key, where a JS peer announces its
+     * identity key as its DHT key. Natives cannot see the toxcore file-transfer
+     * protocol (sendFile) — the inline envelope is their only file path — and
+     * they never speak the JS text-ACK scheme.
+     */
+    isNativeFriend(pubkey) {
+        const friend = this.#friends.get(pubkey);
+        return !!(friend?.dhtPubkey && friend.dhtPubkey !== friend.pubkey);
     }
     /** Fired when a peer sends a Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST).
      *  This is the channel the iOS/Android WebRTC SDK uses for call signaling —
@@ -3013,7 +3088,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 +4301,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 +4567,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/dist/types/peer.d.ts

@@ -135,6 +135,23 @@ export type TextMessage = {
      *  can see when online delivery is failing and only offline messages land. */
     via?: "online" | "offline";
 };
+/**
+ * Outcome of an inline-file send — the caller's ONLY honest basis for a "sent"
+ * checkmark. "Bytes left this machine" is not delivery.
+ */
+export type InlineSendResult = {
+    /**
+     * - "acked": the peer CONFIRMED receipt — an app-level ACK from a JS peer,
+     *   or the toxcore transport ACK from a native one (the same signal Android
+     *   surfaces as ReceiptState.Delivered). Safe to mark "sent".
+     * - "accepted": the transport took the bytes but no confirmation arrived in
+     *   the window. NOT delivered as far as anyone can prove — mark it failed or
+     *   queued, never "sent".
+     * - "offline": stored on the express relay for the peer's next pull. Mark
+     *   it queued.
+     */
+    delivery: "acked" | "accepted" | "offline";
+};
 export type SendTextUntilAckOptions = {
     /** Stable id for retries across a caller-managed outbox. Defaults to a random id. */
     deliveryId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.138",
+  "version": "0.1.140",
   "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",