@decentnetwork/peer 0.1.83 → 0.1.85

package/dist/compat/packet.d.ts

@@ -1,9 +1,16 @@
 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_INVITE_REQUEST = 34;
+export declare const PACKET_TYPE_INVITE_RESPONSE = 35;
 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 declare const INVITE_DATA_UNIT = 1280;
+export declare const CARRIER_MAX_INVITE_DATA_LEN = 8192;
+export declare const CARRIER_MAX_BUNDLE_LEN = 511;
+export declare const CARRIER_MAX_EXTENSION_NAME_LEN = 31;
+export declare const CARRIER_EXTENSION_NAME = "carrier";
 export type UserInfoPacket = {
     type: typeof PACKET_TYPE_USERINFO;
     avatar: boolean;
@@ -34,7 +41,39 @@ export type BulkMsgPacket = {
     tid: bigint;
     data: Uint8Array;
 };
-export type CarrierPacket = UserInfoPacket | FriendRequestPacket | FriendMessagePacket | BulkMsgPacket;
+/**
+ * One `invitereq` fragment (PACKET_TYPE_INVITE_REQUEST = 34). Field layout per
+ * carrier/packet.fbs: 0=ext string, 1=tid long, 2=bundle string, 3=totalsz
+ * uint, 4=data [uint8]. Mirrors carrier_invite_friend's per-fragment packet.
+ */
+export type InviteReqPacket = {
+    type: typeof PACKET_TYPE_INVITE_REQUEST;
+    ext?: string;
+    tid: bigint;
+    bundle?: string;
+    /** Full data length — set on the FIRST fragment only, 0 on the rest. */
+    totalsz: number;
+    data: Uint8Array;
+};
+/**
+ * One `invitersp` fragment (PACKET_TYPE_INVITE_RESPONSE = 35). Field layout:
+ * 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=status int, 5=reason string, 6=data.
+ * A non-zero status means "refused" (reason set, no data); status 0 means
+ * "confirmed" and carries data. The iOS WebRTC receiver never sends these
+ * (each RtcSignal is a one-way invitereq), but we decode them for completeness
+ * and can emit them if a peer does reply.
+ */
+export type InviteRspPacket = {
+    type: typeof PACKET_TYPE_INVITE_RESPONSE;
+    ext?: string;
+    tid: bigint;
+    bundle?: string;
+    totalsz: number;
+    status: number;
+    reason?: string;
+    data: Uint8Array;
+};
+export type CarrierPacket = UserInfoPacket | FriendRequestPacket | FriendMessagePacket | InviteReqPacket | InviteRspPacket | 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
@@ -75,4 +114,33 @@ export declare function encodeBulkMsgPacket(opts: {
     tid: bigint;
     data: Uint8Array;
 }): Uint8Array;
+/**
+ * Encode ONE `invitereq` fragment (PACKET_TYPE_INVITE_REQUEST = 34). Field
+ * layout per packet.fbs invitereq: 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=data.
+ * Callers fragment the payload (INVITE_DATA_UNIT) and share one tid; only the
+ * first fragment sets totalsz (and the optional bundle). Mirrors the do/while
+ * in carrier_invite_friend.
+ */
+export declare function encodeInviteReqPacket(opts: {
+    ext?: string;
+    tid: bigint;
+    bundle?: string;
+    totalsz: number;
+    data: Uint8Array;
+}): Uint8Array;
+/**
+ * Encode ONE `invitersp` fragment (PACKET_TYPE_INVITE_RESPONSE = 35). Field
+ * layout: 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=status, 5=reason, 6=data.
+ * status !== 0 → refused (reason set, no data); status === 0 → confirmed
+ * (carries data). Mirrors carrier_reply_friend_invite.
+ */
+export declare function encodeInviteRspPacket(opts: {
+    ext?: string;
+    tid: bigint;
+    bundle?: string;
+    totalsz: number;
+    status: number;
+    reason?: string;
+    data?: Uint8Array;
+}): Uint8Array;
 export declare function decodeCarrierPacket(bytes: Uint8Array): CarrierPacket;

package/dist/compat/packet.js

@@ -2,6 +2,8 @@ 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_INVITE_REQUEST = 34;
+export const PACKET_TYPE_INVITE_RESPONSE = 35;
 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
@@ -9,12 +11,29 @@ export const PACKET_TYPE_BULKMSG = 36;
 // 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;
+// Carrier friend-invite constants (carrier.c / carrier.h). An invite carries
+// up to 8192 bytes of application data, fragmented into INVITE_DATA_UNIT-byte
+// chunks sharing one tid — the first fragment carries totalsz (and the
+// optional bundle), the rest carry totalsz=0. This is exactly the transport
+// the iOS/Android WebRTC SDK uses for call signaling (RtcSignal JSON), sent
+// via the "carrier" extension (CarrierExtension.sendInviteFriendRequest →
+// carrier_invite_friend(to="<userid>:carrier", bundle=NULL, ...)).
+export const INVITE_DATA_UNIT = 1280;
+export const CARRIER_MAX_INVITE_DATA_LEN = 8192;
+export const CARRIER_MAX_BUNDLE_LEN = 511;
+export const CARRIER_MAX_EXTENSION_NAME_LEN = 31;
+// The extension name the native SDK registers/sends under; the `ext` field of
+// every invitereq/invitersp on the wire. WebRTC signaling MUST use this so the
+// remote's registerExtension handler fires.
+export const CARRIER_EXTENSION_NAME = "carrier";
 // 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_INVITEREQ = 4;
+const ANYBODY_INVITERSP = 5;
 const ANYBODY_BULKMSG = 6;
 /**
  * Encode a Carrier `userinfo` packet (FB type 3). The Carrier C SDK sends
@@ -100,6 +119,73 @@ export function encodeBulkMsgPacket(opts) {
     const bulk = builder.endObject();
     return finishCarrierPacket(builder, PACKET_TYPE_BULKMSG, ANYBODY_BULKMSG, bulk);
 }
+/**
+ * Encode ONE `invitereq` fragment (PACKET_TYPE_INVITE_REQUEST = 34). Field
+ * layout per packet.fbs invitereq: 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=data.
+ * Callers fragment the payload (INVITE_DATA_UNIT) and share one tid; only the
+ * first fragment sets totalsz (and the optional bundle). Mirrors the do/while
+ * in carrier_invite_friend.
+ */
+export function encodeInviteReqPacket(opts) {
+    const builder = new Builder(opts.data.length + 128);
+    const dataOffset = builder.createByteVector(opts.data);
+    const bundleOffset = opts.bundle ? builder.createString(opts.bundle) : 0;
+    const extOffset = opts.ext ? builder.createString(opts.ext) : 0;
+    builder.startObject(5);
+    builder.addFieldOffset(4, dataOffset, 0);
+    if (opts.totalsz) {
+        builder.addFieldInt32(3, opts.totalsz, 0);
+    }
+    if (bundleOffset) {
+        builder.addFieldOffset(2, bundleOffset, 0);
+    }
+    if (opts.tid !== 0n) {
+        builder.addFieldInt64(1, opts.tid, BigInt(0));
+    }
+    if (extOffset) {
+        builder.addFieldOffset(0, extOffset, 0);
+    }
+    const ireq = builder.endObject();
+    return finishCarrierPacket(builder, PACKET_TYPE_INVITE_REQUEST, ANYBODY_INVITEREQ, ireq);
+}
+/**
+ * Encode ONE `invitersp` fragment (PACKET_TYPE_INVITE_RESPONSE = 35). Field
+ * layout: 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=status, 5=reason, 6=data.
+ * status !== 0 → refused (reason set, no data); status === 0 → confirmed
+ * (carries data). Mirrors carrier_reply_friend_invite.
+ */
+export function encodeInviteRspPacket(opts) {
+    const payload = opts.data ?? new Uint8Array();
+    const builder = new Builder(payload.length + 128);
+    const dataOffset = payload.length ? builder.createByteVector(payload) : 0;
+    const reasonOffset = opts.reason ? builder.createString(opts.reason) : 0;
+    const bundleOffset = opts.bundle ? builder.createString(opts.bundle) : 0;
+    const extOffset = opts.ext ? builder.createString(opts.ext) : 0;
+    builder.startObject(7);
+    if (dataOffset) {
+        builder.addFieldOffset(6, dataOffset, 0);
+    }
+    if (reasonOffset) {
+        builder.addFieldOffset(5, reasonOffset, 0);
+    }
+    if (opts.status) {
+        builder.addFieldInt32(4, opts.status, 0);
+    }
+    if (opts.totalsz) {
+        builder.addFieldInt32(3, opts.totalsz, 0);
+    }
+    if (bundleOffset) {
+        builder.addFieldOffset(2, bundleOffset, 0);
+    }
+    if (opts.tid !== 0n) {
+        builder.addFieldInt64(1, opts.tid, BigInt(0));
+    }
+    if (extOffset) {
+        builder.addFieldOffset(0, extOffset, 0);
+    }
+    const irsp = builder.endObject();
+    return finishCarrierPacket(builder, PACKET_TYPE_INVITE_RESPONSE, ANYBODY_INVITERSP, irsp);
+}
 export function decodeCarrierPacket(bytes) {
     const bb = new ByteBuffer(bytes);
     const root = bb.readInt32(bb.position()) + bb.position();
@@ -146,6 +232,28 @@ export function decodeCarrierPacket(bytes) {
             data: readByteVectorField(body, 3) ?? new Uint8Array()
         };
     }
+    if (type === PACKET_TYPE_INVITE_REQUEST && bodyType === ANYBODY_INVITEREQ) {
+        return {
+            type,
+            ext: readStringField(body, 0) ?? undefined,
+            tid: readInt64Field(body, 1),
+            bundle: readStringField(body, 2) ?? undefined,
+            totalsz: readUint32Field(body, 3),
+            data: readByteVectorField(body, 4) ?? new Uint8Array()
+        };
+    }
+    if (type === PACKET_TYPE_INVITE_RESPONSE && bodyType === ANYBODY_INVITERSP) {
+        return {
+            type,
+            ext: readStringField(body, 0) ?? undefined,
+            tid: readInt64Field(body, 1),
+            bundle: readStringField(body, 2) ?? undefined,
+            totalsz: readUint32Field(body, 3),
+            status: readInt32Field(body, 4),
+            reason: readStringField(body, 5) ?? undefined,
+            data: readByteVectorField(body, 6) ?? new Uint8Array()
+        };
+    }
     throw new Error(`unsupported carrier packet type/body: ${type}/${bodyType}`);
 }
 function finishCarrierPacket(builder, type, bodyType, bodyOffset) {
@@ -169,6 +277,10 @@ 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 readInt32Field(table, field) {
+    const offset = table.bb.__offset(table.bb_pos, 4 + field * 2);
+    return offset ? table.bb.readInt32(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);

package/dist/compat/tcp-relay-pool.d.ts

@@ -17,6 +17,8 @@ export type TcpRelayPoolEvents = {
     peerData: (friendPublicKey: Uint8Array, payload: Uint8Array) => void;
     /** Inbound OOB_RECV (used for friend requests via TCP). */
     oob: (senderPublicKey: Uint8Array, payload: Uint8Array) => void;
+    /** Inbound onion response routed back through a relay (announce / onion data). */
+    onionResponse: (packet: Uint8Array) => void;
     /** Number of currently-connected relays changed (for diagnostics). */
     status: (connected: number, total: number) => void;
 };
@@ -67,6 +69,15 @@ export declare class TcpRelayPool extends EventEmitter {
     sendToFriend(friendPublicKey: Uint8Array, payload: Uint8Array, droppable?: boolean): number;
     /** Diagnostics. */
     connectedCount(): number;
+    /**
+     * Send an onion request (createOnionRequest0Tcp packet) through up to `fanout`
+     * connected relays. Each relay forwards it to node B over UDP and routes the
+     * onion response back over TCP (surfaced via the pool's "onionResponse"
+     * event). Returns the number of relays the request was handed to (0 = none
+     * connected). Fanning out across a few relays covers the case where one relay
+     * can't reach node B.
+     */
+    sendOnionRequest(packet: Uint8Array, fanout?: number): number;
     /**
      * Snapshot of currently-connected relays for inclusion in DHT-PK
      * announce extras. Mirrors toxcore's `tcp_copy_connected_relays`.

package/dist/compat/tcp-relay-pool.js

@@ -211,6 +211,25 @@ export class TcpRelayPool extends EventEmitter {
     connectedCount() {
         return this.#relays.filter((r) => r.client?.state() === "connected").length;
     }
+    /**
+     * Send an onion request (createOnionRequest0Tcp packet) through up to `fanout`
+     * connected relays. Each relay forwards it to node B over UDP and routes the
+     * onion response back over TCP (surfaced via the pool's "onionResponse"
+     * event). Returns the number of relays the request was handed to (0 = none
+     * connected). Fanning out across a few relays covers the case where one relay
+     * can't reach node B.
+     */
+    sendOnionRequest(packet, fanout = 2) {
+        let sent = 0;
+        for (const r of this.#relays) {
+            if (sent >= fanout)
+                break;
+            if (r.client?.state() === "connected" && r.client.sendOnionRequest(packet)) {
+                sent += 1;
+            }
+        }
+        return sent;
+    }
     /**
      * Snapshot of currently-connected relays for inclusion in DHT-PK
      * announce extras. Mirrors toxcore's `tcp_copy_connected_relays`.
@@ -304,6 +323,9 @@ export class TcpRelayPool extends EventEmitter {
         client.on("oob", (senderKey, payload) => {
             this.emit("oob", new Uint8Array(senderKey), payload);
         });
+        client.on("onionResponse", (packet) => {
+            this.emit("onionResponse", new Uint8Array(packet));
+        });
         try {
             await client.connect(10_000);
         }

package/dist/compat/tcp-relay.d.ts

@@ -54,6 +54,10 @@ export type TcpRelayEvents = {
     oob: (senderPublicKey: Uint8Array, payload: Uint8Array) => void;
     /** Pong (response to our ping). */
     pong: (pingId: bigint) => void;
+    /** Inbound TCP_PACKET_ONION_RESPONSE — the raw onion packet (announce or
+     *  onion-data response), routed back through this relay. Treat exactly like a
+     *  UDP onion datagram. */
+    onionResponse: (packet: Uint8Array) => void;
 };
 export declare class TcpRelayClient extends EventEmitter {
     #private;
@@ -85,6 +89,15 @@ export declare class TcpRelayClient extends EventEmitter {
     sendToFriend(friendPublicKey: Uint8Array, payload: Uint8Array, droppable?: boolean): boolean;
     /** Send a PING; relay echoes it as PONG. ping_id is opaque 8 bytes. */
     sendPing(): boolean;
+    /**
+     * Send an onion request THROUGH this relay (toxcore TCP_client.c::
+     * send_onion_request). `packet` is a create_onion_packet_tcp payload
+     * (createOnionRequest0Tcp) — the relay acts as onion node A, forwards it to
+     * node B over UDP, and routes the onion response back to us over this TCP
+     * connection as TCP_PACKET_ONION_RESPONSE (surfaced via the "onionResponse"
+     * event). This is the NAT-resilient announce / friend-lookup path.
+     */
+    sendOnionRequest(packet: Uint8Array): boolean;
     /** Send DATA payload to the friend at `connectionId`. */
     sendData(connectionId: number, payload: Uint8Array, droppable?: boolean): boolean;
     /** Send OOB_SEND (used for delivering friend requests via TCP relay). */

package/dist/compat/tcp-relay.js

@@ -379,6 +379,16 @@ export class TcpRelayClient extends EventEmitter {
                 this.emit("oob", sender, payload);
                 return;
             }
+            case TCP_PACKET_ONION_RESPONSE: {
+                // The relay forwarded an onion response addressed to us (announce
+                // response / onion data response). `body` is the raw onion packet —
+                // identical to what would have arrived over UDP — so the Peer feeds it
+                // through the same NET_PACKET_ONION_* handling.
+                if (body.length === 0)
+                    return;
+                this.emit("onionResponse", new Uint8Array(body));
+                return;
+            }
             default: {
                 if (type >= 16) {
                     // DATA forwarded by relay from a connected peer. Resolve
@@ -445,6 +455,19 @@ export class TcpRelayClient extends EventEmitter {
         const pingId = randomBytes(8);
         return this.#sendFrame(concatBytes([Uint8Array.of(TCP_PACKET_PING), pingId]));
     }
+    /**
+     * Send an onion request THROUGH this relay (toxcore TCP_client.c::
+     * send_onion_request). `packet` is a create_onion_packet_tcp payload
+     * (createOnionRequest0Tcp) — the relay acts as onion node A, forwards it to
+     * node B over UDP, and routes the onion response back to us over this TCP
+     * connection as TCP_PACKET_ONION_RESPONSE (surfaced via the "onionResponse"
+     * event). This is the NAT-resilient announce / friend-lookup path.
+     */
+    sendOnionRequest(packet) {
+        if (packet.length === 0)
+            return false;
+        return this.#sendFrame(concatBytes([Uint8Array.of(TCP_PACKET_ONION_REQUEST), packet]));
+    }
     /** Send DATA payload to the friend at `connectionId`. */
     sendData(connectionId, payload, droppable = false) {
         if (connectionId < 16 || connectionId > 0xff)

package/dist/compat/tox-onion.d.ts

@@ -49,6 +49,33 @@ export declare function createOnionRequest0(opts: {
     nodeDPort: number;
     payloadForNodeD: Uint8Array;
 }): Uint8Array;
+/**
+ * Build an onion request to send OVER A TCP RELAY (toxcore
+ * onion.c::create_onion_packet_tcp). When the onion path's first hop is a TCP
+ * relay we're already connected to, the relay itself acts as node A — so the
+ * packet OMITS node A's layer and is sent as the payload of TCP_PACKET_ONION_
+ * REQUEST. The relay forwards it to node B over UDP and routes the response
+ * back to us over the same TCP connection (TCP_PACKET_ONION_RESPONSE).
+ *
+ * This is the NAT-resilient discovery path native Beagle uses as primary:
+ * self-announce and friend-route lookups survive a NAT that drops the UDP
+ * onion return path, because the TCP relay handles the round-trip.
+ *
+ * Layout (== create_onion_packet_tcp): the UDP builder's inner `bPart` with a
+ * bare nonce prepended (no NET_PACKET_ONION_REQUEST_0 type byte, no node-A box):
+ *   [nonce 24][ipport(B)][tempPubB 32][box_B([ipport(C)][tempPubC 32][box_C([ipport(D)][payload])])]
+ */
+export declare function createOnionRequest0Tcp(opts: {
+    nodeBHost: string;
+    nodeBPort: number;
+    nodeBPublicKey: Uint8Array;
+    nodeCHost: string;
+    nodeCPort: number;
+    nodeCPublicKey: Uint8Array;
+    nodeDHost: string;
+    nodeDPort: number;
+    payloadForNodeD: Uint8Array;
+}): Uint8Array;
 export declare function openOnionDataResponse(packet: Uint8Array, opts: {
     dataSecretKey: Uint8Array;
 }): {

package/dist/compat/tox-onion.js

@@ -112,6 +112,44 @@ export function createOnionRequest0(opts) {
         aEncrypted
     ]);
 }
+/**
+ * Build an onion request to send OVER A TCP RELAY (toxcore
+ * onion.c::create_onion_packet_tcp). When the onion path's first hop is a TCP
+ * relay we're already connected to, the relay itself acts as node A — so the
+ * packet OMITS node A's layer and is sent as the payload of TCP_PACKET_ONION_
+ * REQUEST. The relay forwards it to node B over UDP and routes the response
+ * back to us over the same TCP connection (TCP_PACKET_ONION_RESPONSE).
+ *
+ * This is the NAT-resilient discovery path native Beagle uses as primary:
+ * self-announce and friend-route lookups survive a NAT that drops the UDP
+ * onion return path, because the TCP relay handles the round-trip.
+ *
+ * Layout (== create_onion_packet_tcp): the UDP builder's inner `bPart` with a
+ * bare nonce prepended (no NET_PACKET_ONION_REQUEST_0 type byte, no node-A box):
+ *   [nonce 24][ipport(B)][tempPubB 32][box_B([ipport(C)][tempPubC 32][box_C([ipport(D)][payload])])]
+ */
+export function createOnionRequest0Tcp(opts) {
+    ensureLen(opts.nodeBPublicKey, KEY_SIZE, "node B public key");
+    ensureLen(opts.nodeCPublicKey, KEY_SIZE, "node C public key");
+    const nonce = randomBytes(NONCE_SIZE);
+    const dPart = concatBytes([packIpPort(opts.nodeDHost, opts.nodeDPort), opts.payloadForNodeD]);
+    const key2 = nacl.box.keyPair();
+    const cEncrypted = nacl.box(dPart, nonce, opts.nodeCPublicKey, key2.secretKey);
+    const cPart = concatBytes([
+        packIpPort(opts.nodeCHost, opts.nodeCPort),
+        key2.publicKey,
+        cEncrypted
+    ]);
+    const key1 = nacl.box.keyPair();
+    const bEncrypted = nacl.box(cPart, nonce, opts.nodeBPublicKey, key1.secretKey);
+    // No node-A box: the relay is node A. Just [nonce][ipport(B)][tempPubB][box_B].
+    return concatBytes([
+        nonce,
+        packIpPort(opts.nodeBHost, opts.nodeBPort),
+        key1.publicKey,
+        bEncrypted
+    ]);
+}
 export function openOnionDataResponse(packet, opts) {
     if (packet.length < 1 + NONCE_SIZE + KEY_SIZE + 16) {
         return undefined;

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 export { Peer } from "./peer.js";
 export { CARRIER_ADDRESS_SIZE, CARRIER_PUBLIC_KEY_SIZE, carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
-export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket } from "./compat/packet.js";
+export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, PACKET_TYPE_INVITE_REQUEST, PACKET_TYPE_INVITE_RESPONSE, INVITE_DATA_UNIT, CARRIER_MAX_INVITE_DATA_LEN, CARRIER_EXTENSION_NAME, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeInviteReqPacket, encodeInviteRspPacket } from "./compat/packet.js";
 export { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, CRYPTO_PACKET_NAT_PING, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export { NET_PACKET_ONION_ANNOUNCE_REQUEST, NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_REQUEST, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID } from "./compat/tox-onion.js";
 export { signDetached, verifyDetached, SIGNATURE_LENGTH } from "./crypto/sign.js";
 export { base58ToBytes, bytesToBase58 } from "./utils/base58.js";
 export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";
-export type { CarrierPacket, FriendMessagePacket, FriendRequestPacket } from "./compat/packet.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, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 export { Peer } from "./peer.js";
 export { CARRIER_ADDRESS_SIZE, CARRIER_PUBLIC_KEY_SIZE, carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
-export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket } from "./compat/packet.js";
+export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, PACKET_TYPE_INVITE_REQUEST, PACKET_TYPE_INVITE_RESPONSE, INVITE_DATA_UNIT, CARRIER_MAX_INVITE_DATA_LEN, CARRIER_EXTENSION_NAME, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeInviteReqPacket, encodeInviteRspPacket } from "./compat/packet.js";
 export { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, CRYPTO_PACKET_NAT_PING, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export { NET_PACKET_ONION_ANNOUNCE_REQUEST, NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_REQUEST, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID } from "./compat/tox-onion.js";
 export { signDetached, verifyDetached, SIGNATURE_LENGTH } from "./crypto/sign.js";

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, InlineFileEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
 export declare class Peer {
     #private;
     private constructor();
@@ -99,6 +99,34 @@ export declare class Peer {
         data: Uint8Array;
         fileType?: "image" | "audio" | "text" | "unknown";
     }): Promise<void>;
+    /** 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
+     *  reassembled JSON. */
+    onInvite(cb: (evt: InviteEvent) => void): void;
+    /** Fired when a peer replies to one of our invites (PACKET_TYPE_INVITE_RESPONSE).
+     *  Not used by the one-way WebRTC signaling flow, but surfaced for peers that
+     *  do reply. */
+    onInviteResponse(cb: (evt: InviteResponseEvent) => void): void;
+    /**
+     * Send a Carrier friend-invite to a peer — the transport the iOS/Android
+     * Elastos WebRTC SDK listens on (CarrierExtension.registerExtension). Used
+     * for realtime call signaling: pass the RtcSignal JSON as `data` and the
+     * remote's registerExtension handler fires with it.
+     *
+     * Wire-compatible with carrier_invite_friend: sends PACKET_TYPE_INVITE_REQUEST
+     * packets over the reliable message channel, `ext` = "carrier" by default,
+     * fragmented into INVITE_DATA_UNIT (1280-byte) chunks sharing one tid (first
+     * fragment carries totalsz + optional bundle). Signaling is realtime, so this
+     * requires a live session and does NOT fall back to offline express — a call
+     * signal to an unreachable peer should fail fast, not queue.
+     *
+     * @returns the tid used (lets callers correlate a later invite-response).
+     */
+    sendInvite(pubkey: string, data: Uint8Array | string, opts?: {
+        ext?: string | null;
+        bundle?: string;
+    }): Promise<bigint>;
     /**
      * 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,8 +5,8 @@ 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, 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 { 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 } 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";
 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";
 import { FileTransferManager, PACKET_ID_FILE_SENDREQUEST, PACKET_ID_FILE_CONTROL, PACKET_ID_FILE_DATA, PACKET_ID_FILE_FEC } from "./compat/filetransfer.js";
@@ -311,6 +311,10 @@ export class Peer {
     // 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();
+    // Reassembly buffer for multi-fragment Carrier invites (WebRTC signaling).
+    // Keyed by `${friendId}:${tid}`; namespaced separately from #bulkAssembly so
+    // a bulkmsg and an invite that happen to share a tid can't collide.
+    #inviteAssembly = 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
@@ -507,6 +511,22 @@ export class Peer {
                 this.#tcpRelays?.requestRoute(senderKey);
                 this.#handleTcpDatagram(senderKey, payload);
             });
+            // Onion responses routed back through a TCP relay (announce responses,
+            // onion data responses). This is the NAT-resilient discovery path: when
+            // UDP onion is blocked, the relay does the round-trip. Inject the raw
+            // onion packet into the SAME "datagram" stream the UDP transport feeds,
+            // so #onDatagram AND the ad-hoc announce/route waiters
+            // (#waitForAnnounceResponse) process it identically. Synthetic remote so
+            // no real UDP endpoint is adopted from it.
+            this.#tcpRelays.on("onionResponse", (packet) => {
+                if (packet.length === 0)
+                    return;
+                this.#udp.emit("datagram", {
+                    data: Buffer.from(packet),
+                    remote: { address: "tcp-relay", port: 0 },
+                    viaRelay: true
+                });
+            });
             // Don't await — pool reconnects on its own and we want start() to
             // return promptly so the demo can call joinNetwork() in parallel.
             void this.#tcpRelays.start().catch((error) => {
@@ -1125,6 +1145,81 @@ export class Peer {
         }
         await this.sendText(pubkey, envelope);
     }
+    /** 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
+     *  reassembled JSON. */
+    onInvite(cb) {
+        this.#events.on("invite", cb);
+    }
+    /** Fired when a peer replies to one of our invites (PACKET_TYPE_INVITE_RESPONSE).
+     *  Not used by the one-way WebRTC signaling flow, but surfaced for peers that
+     *  do reply. */
+    onInviteResponse(cb) {
+        this.#events.on("inviteResponse", cb);
+    }
+    /**
+     * Send a Carrier friend-invite to a peer — the transport the iOS/Android
+     * Elastos WebRTC SDK listens on (CarrierExtension.registerExtension). Used
+     * for realtime call signaling: pass the RtcSignal JSON as `data` and the
+     * remote's registerExtension handler fires with it.
+     *
+     * Wire-compatible with carrier_invite_friend: sends PACKET_TYPE_INVITE_REQUEST
+     * packets over the reliable message channel, `ext` = "carrier" by default,
+     * fragmented into INVITE_DATA_UNIT (1280-byte) chunks sharing one tid (first
+     * fragment carries totalsz + optional bundle). Signaling is realtime, so this
+     * requires a live session and does NOT fall back to offline express — a call
+     * signal to an unreachable peer should fail fast, not queue.
+     *
+     * @returns the tid used (lets callers correlate a later invite-response).
+     */
+    async sendInvite(pubkey, data, opts = {}) {
+        const friend = this.#friends.get(pubkey);
+        if (!friend) {
+            throw new Error(`Not a friend: ${pubkey}`);
+        }
+        const payload = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        if (payload.length === 0 || payload.length > CARRIER_MAX_INVITE_DATA_LEN) {
+            throw new Error(`invite data must be 1..${CARRIER_MAX_INVITE_DATA_LEN} bytes (got ${payload.length})`);
+        }
+        // `ext: null` sends a plain invite (no extension); default is the "carrier"
+        // extension the native WebRTC SDK registers under.
+        const ext = opts.ext === null ? undefined : (opts.ext ?? CARRIER_EXTENSION_NAME);
+        const bundle = opts.bundle;
+        let session = this.#friendSessions.get(pubkey);
+        if (!session?.established) {
+            await this.#initiateSession(pubkey).catch(() => { });
+            const established = await this.#waitForFriendConnected(pubkey, 5000).catch(() => false);
+            if (established)
+                session = this.#friendSessions.get(pubkey);
+        }
+        if (!session?.established || !session.sessionSharedKey || !session.ourBaseNonce || !(session.remote || session.hasTcpRoute)) {
+            throw new Error(`cannot send invite: no live session to ${pubkey} (peer offline?)`);
+        }
+        // Fragment exactly like carrier_invite_friend: first fragment carries
+        // totalsz and the optional bundle (which counts against the first unit),
+        // the rest carry totalsz=0. bundle is usually absent for WebRTC.
+        const tid = (BigInt(Date.now()) << 20n) ^ BigInt(Math.floor(Math.random() * 0xfffff)) | 1n;
+        const bundleLen = bundle ? new TextEncoder().encode(bundle).length : 0;
+        let off = 0;
+        let first = true;
+        while (off < payload.length) {
+            const unit = first && bundle ? INVITE_DATA_UNIT - bundleLen : INVITE_DATA_UNIT;
+            const end = Math.min(off + unit, payload.length);
+            const p = encodeInviteReqPacket({
+                ext,
+                tid,
+                bundle: first ? bundle : undefined,
+                totalsz: first ? payload.length : 0,
+                data: payload.subarray(off, end)
+            });
+            await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, p);
+            off = end;
+            first = false;
+        }
+        this.#debugLog(`invite sent to ${pubkey}: ext="${ext ?? ""}" (${payload.length} bytes, tid=${tid})`);
+        return tid;
+    }
     /**
      * Send an application-defined custom packet to a friend. `id` selects the
      * channel and its delivery class by toxcore range: **160–191 lossless**
@@ -2071,6 +2166,39 @@ export class Peer {
                         carrier = decodeCarrierPacket(inner);
                     }
                     catch { /* raw utf-8 peer */ }
+                    // Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST/RESPONSE = 34/35)
+                    // rides this same PACKET_ID_MESSAGE channel — it's what the iOS/Android
+                    // WebRTC SDK uses for call signaling via the "carrier" extension. Large
+                    // signals (SDP offers) fragment by tid like bulkmsg; reassemble then
+                    // surface as an "invite" event (NOT chat text).
+                    if (carrier?.type === PACKET_TYPE_INVITE_REQUEST) {
+                        const complete = this.#assembleInvite(friendId, carrier);
+                        if (!complete)
+                            return; // more fragments pending
+                        this.#events.emit("invite", {
+                            pubkey: friendId,
+                            ext: carrier.ext,
+                            bundle: carrier.bundle,
+                            data: complete
+                        });
+                        this.#debugLog(`invite from ${friendId}: ext="${carrier.ext ?? ""}" (${complete.length} bytes)`);
+                        return;
+                    }
+                    if (carrier?.type === PACKET_TYPE_INVITE_RESPONSE) {
+                        const complete = carrier.status === 0 ? this.#assembleInvite(friendId, carrier) : new Uint8Array();
+                        if (carrier.status === 0 && !complete)
+                            return; // more fragments pending
+                        this.#events.emit("inviteResponse", {
+                            pubkey: friendId,
+                            ext: carrier.ext,
+                            bundle: carrier.bundle,
+                            status: carrier.status,
+                            reason: carrier.reason,
+                            data: complete ?? new Uint8Array()
+                        });
+                        this.#debugLog(`invite-response from ${friendId}: status=${carrier.status} ext="${carrier.ext ?? ""}"`);
+                        return;
+                    }
                     if (carrier?.type === PACKET_TYPE_BULKMSG) {
                         const complete = this.#assembleBulkMsg(friendId, carrier);
                         if (!complete)
@@ -3244,6 +3372,41 @@ export class Peer {
         this.#bulkAssembly.delete(key);
         return concatBytes(entry.chunks);
     }
+    /** Append a Carrier invite fragment (INVITE_REQUEST/RESPONSE); returns the
+     *  full reassembled payload when the last fragment lands, undefined while
+     *  pending. Mirrors #assembleBulkMsg but caps at CARRIER_MAX_INVITE_DATA_LEN
+     *  (8192) and uses a separate buffer. Single-fragment invites (the common
+     *  case for small WebRTC signals) complete on the first call. */
+    #assembleInvite(friendId, frag) {
+        const now = Date.now();
+        for (const [key, entry] of this.#inviteAssembly) {
+            if (entry.expireAtMs < now)
+                this.#inviteAssembly.delete(key);
+        }
+        const key = `${friendId}:${frag.tid.toString()}`;
+        let entry = this.#inviteAssembly.get(key);
+        if (!entry) {
+            // First fragment carries totalsz. A lone fragment whose data already
+            // equals totalsz completes immediately below.
+            if (!frag.totalsz || frag.totalsz > CARRIER_MAX_INVITE_DATA_LEN) {
+                this.#debugLog(`invite from ${friendId} with invalid/missing totalsz ${frag.totalsz} — dropped`);
+                return undefined;
+            }
+            entry = { total: frag.totalsz, chunks: [], got: 0, expireAtMs: now + 60_000 };
+            this.#inviteAssembly.set(key, entry);
+        }
+        if (frag.data.length === 0 || entry.got + frag.data.length > entry.total) {
+            this.#debugLog(`invite fragment from ${friendId} overflows totalsz — dropped`);
+            this.#inviteAssembly.delete(key);
+            return undefined;
+        }
+        entry.chunks.push(frag.data);
+        entry.got += frag.data.length;
+        if (entry.got < entry.total)
+            return undefined;
+        this.#inviteAssembly.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
@@ -5096,6 +5259,32 @@ export class Peer {
             payloadForNodeD
         });
         await this.#sendPacket(packet, path.nodeA.node);
+        // NAT-resilient duplicate: ALSO send this onion request over connected TCP
+        // relays (toxcore create_onion_packet_tcp). The relay acts as node A and
+        // forwards to node B over UDP, routing the response back over TCP — so
+        // self-announce AND friend-route discovery survive a NAT that drops the UDP
+        // onion return path (the residential-ISP case where selfAnnounceStoredOn
+        // stays 0 and native peers can never find us). Same sendBack as the UDP
+        // attempt, so whichever transport answers first resolves the waiter.
+        if (this.#tcpRelays && this.#tcpRelays.connectedCount() > 0) {
+            try {
+                const tcpPacket = createOnionRequest0Tcp({
+                    nodeBHost: path.nodeB.host,
+                    nodeBPort: path.nodeB.port,
+                    nodeBPublicKey: path.nodeB.publicKey,
+                    nodeCHost: path.nodeC.host,
+                    nodeCPort: path.nodeC.port,
+                    nodeCPublicKey: path.nodeC.publicKey,
+                    nodeDHost: nodeD.host,
+                    nodeDPort: nodeD.port,
+                    payloadForNodeD
+                });
+                this.#tcpRelays.sendOnionRequest(tcpPacket);
+            }
+            catch {
+                /* malformed path node key — the UDP attempt above still stands */
+            }
+        }
         return path;
     }
     #selectOnionPath(nodeD, pathOffset = 0) {

package/dist/types/peer.d.ts

@@ -130,6 +130,35 @@ export type InlineFileEvent = {
     data: Uint8Array;
     via: "online" | "offline";
 };
+/**
+ * A Carrier friend-invite request received from a peer (PACKET_TYPE_INVITE_REQUEST).
+ * This is the transport the iOS/Android Elastos WebRTC SDK uses for call
+ * signaling: each RtcSignal (offer/answer/candidate/bye JSON) is sent as a
+ * one-way invite under the "carrier" extension. `data` is the reassembled
+ * application payload (JSON for WebRTC; NUL-terminated by native C senders).
+ */
+export type InviteEvent = {
+    pubkey: string;
+    /** Extension name — "carrier" for WebRTC/extension invites, undefined for a plain invite. */
+    ext?: string;
+    /** Optional bundle string set by the sender (usually absent). */
+    bundle?: string;
+    data: Uint8Array;
+};
+/**
+ * A Carrier friend-invite response (PACKET_TYPE_INVITE_RESPONSE). The iOS
+ * WebRTC receiver never sends these (signaling is one-way invitereq both
+ * ways), but a peer that calls reply_friend_invite produces one. status 0 =
+ * confirmed (carries data); non-zero = refused (reason set, no data).
+ */
+export type InviteResponseEvent = {
+    pubkey: string;
+    ext?: string;
+    bundle?: string;
+    status: number;
+    reason?: string;
+    data: Uint8Array;
+};
 export type LookupResult = {
     pubkey: string;
     status: "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "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",
@@ -67,6 +67,8 @@
     "demo:js-to-js": "pnpm run build && node scripts/js-to-js-demo.mjs",
     "demo:tox-dht-crypto": "pnpm run build && node scripts/tox-dht-crypto-demo.mjs",
     "test:compat": "pnpm run build && node scripts/compat-selftest.mjs",
+    "test:invite": "pnpm run build && node scripts/invite-selftest.mjs",
+    "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"