@decentnetwork/peer 0.1.84 → 0.1.86

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

@@ -45,6 +45,11 @@ export declare class Peer {
         selfAnnounceStoredOn: number;
         udpLocalPort: number | null;
         tcpRelayConnected: number;
+        /** TCP-relay onion diagnostics: requests handed to relays / responses
+         *  routed back. If sent>0 but recv=0, relays aren't returning onion
+         *  responses (relay doesn't forward, or wire mismatch). */
+        tcpOnionSent: number;
+        tcpOnionRecv: number;
         /** The specific relay endpoints this peer has live connections to.
          *  Lets us compare two peers' relay sets — if there's NO overlap,
          *  net_crypto handshake packets between them have nowhere to route

package/dist/peer.js

@@ -6,7 +6,7 @@ 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, 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, openOnionAnnounceResponse, openOnionDataPacket, openOnionDataResponse } from "./compat/tox-onion.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";
@@ -280,6 +280,12 @@ export class Peer {
     // 25s forever for stale persisted entries.
     #dhtPkConsecutiveFailures = new Map();
     #lastSelfAnnounceStoredCount = -1;
+    // Diagnostics for the TCP-relay onion path (announce/discovery over TCP).
+    // Surfaced in dhtHealth so `agentnet diag` shows whether it's active without
+    // needing verbose logs: sent = onion requests handed to relays, recv = onion
+    // responses routed back over TCP.
+    #diagTcpOnionSent = 0;
+    #diagTcpOnionRecv = 0;
     // Per-friend last-logged route count from #discoverFriendRoutes so we
     // only emit a "routes=N for friend=…" debug line when it changes.
     #lastLoggedRoutesForFriend = new Map();
@@ -511,6 +517,24 @@ 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.#diagTcpOnionRecv += 1;
+                this.#debugVerboseLog(`tcp onion response received (${packet.length} bytes, type=${packet[0]})`);
+                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) => {
@@ -670,6 +694,8 @@ export class Peer {
             selfAnnounceStoredOn: this.#lastSelfAnnounceStoredCount,
             udpLocalPort: this.#udp?.localPort() ?? null,
             tcpRelayConnected: relays.length,
+            tcpOnionSent: this.#diagTcpOnionSent,
+            tcpOnionRecv: this.#diagTcpOnionRecv,
             tcpRelayEndpoints: relays.map((r) => ({ host: r.host, port: r.port })),
         };
     }
@@ -5243,6 +5269,36 @@ 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
+                });
+                const sent = this.#tcpRelays.sendOnionRequest(tcpPacket);
+                if (sent > 0) {
+                    this.#diagTcpOnionSent += 1;
+                    this.#debugVerboseLog(`tcp onion request sent via ${sent} relay(s) to ${nodeD.host}:${nodeD.port} (B=${path.nodeB.host} C=${path.nodeC.host})`);
+                }
+            }
+            catch {
+                /* malformed path node key — the UDP attempt above still stands */
+            }
+        }
         return path;
     }
     #selectOnionPath(nodeD, pathOffset = 0) {

package/package.json

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