@decentnetwork/peer 0.1.40 → 0.1.42

package/dist/compat/dht-rpc.d.ts

@@ -0,0 +1,25 @@
+import type { KeyPair } from "../crypto/keypair.js";
+export declare const NET_PACKET_PING_REQUEST = 0;
+export declare const NET_PACKET_PING_RESPONSE = 1;
+export declare const NET_PACKET_GET_NODES = 2;
+export declare const NET_PACKET_SEND_NODES = 4;
+export type DhtRpcPacket = {
+    type: number;
+    senderPublicKey: Uint8Array;
+    plain: Uint8Array;
+};
+export declare function encodeDhtRpc(type: number, sender: KeyPair, recipientPublicKey: Uint8Array, plain: Uint8Array): Uint8Array;
+export declare function decodeDhtRpc(packet: Uint8Array, ourSecretKey: Uint8Array): DhtRpcPacket | undefined;
+export declare function buildPingPlain(type: number, pingId: Uint8Array): Uint8Array;
+export declare function parsePingPlain(plain: Uint8Array): {
+    innerType: number;
+    pingId: Uint8Array;
+} | undefined;
+export declare function buildGetNodesPlain(targetPublicKey: Uint8Array, pingId: Uint8Array): Uint8Array;
+export declare function parseGetNodesPlain(plain: Uint8Array): {
+    target: Uint8Array;
+    pingId: Uint8Array;
+} | undefined;
+export declare function buildSendNodesPlain(packedNodes: Uint8Array, count: number, pingId: Uint8Array): Uint8Array;
+export declare function parseSendNodesNodeBytes(plain: Uint8Array): Uint8Array | undefined;
+export declare function packUdpNodeV4(host: string, port: number, pk: Uint8Array): Uint8Array | undefined;

package/dist/compat/dht-rpc.js

@@ -0,0 +1,100 @@
+// Classic toxcore DHT request/response packets (DHT.c): ping and get_nodes.
+//
+// These are what make a node *findable* and *discoverable* over UDP — the
+// mechanism native C++/iOS/Android Carrier clients use to locate a friend's
+// live UDP ip:port and net_crypto to it directly (fast), instead of falling
+// back to a TCP relay (slow). Without answering these, a JS peer is invisible
+// in the DHT: a native client's get_nodes search for our key finds nothing,
+// so it can never punch UDP to us. See peer.ts #handleDhtRpc / #doDhtMaintenance.
+//
+// Wire format (dht_create_packet): no recipient key on the wire (unlike the
+// 0x20 CRYPTO_PACKET) — the recipient identifies us by the sender key field.
+//   [type(1)] [sender DHT public key(32)] [nonce(24)] [crypto_box(plain)+MAC]
+// Encrypted to the recipient's DHT pk with our DHT sk.
+import nacl from "tweetnacl";
+import { concatBytes, randomBytes } from "../utils/bytes.js";
+export const NET_PACKET_PING_REQUEST = 0x00;
+export const NET_PACKET_PING_RESPONSE = 0x01;
+export const NET_PACKET_GET_NODES = 0x02;
+export const NET_PACKET_SEND_NODES = 0x04;
+const KEY_SIZE = 32;
+const NONCE_SIZE = 24;
+const MAC_SIZE = 16;
+function isDhtRpcType(t) {
+    return (t === NET_PACKET_PING_REQUEST ||
+        t === NET_PACKET_PING_RESPONSE ||
+        t === NET_PACKET_GET_NODES ||
+        t === NET_PACKET_SEND_NODES);
+}
+export function encodeDhtRpc(type, sender, recipientPublicKey, plain) {
+    const nonce = randomBytes(NONCE_SIZE);
+    const encrypted = nacl.box(plain, nonce, recipientPublicKey, sender.secretKey);
+    return concatBytes([Uint8Array.of(type), sender.publicKey, nonce, encrypted]);
+}
+export function decodeDhtRpc(packet, ourSecretKey) {
+    if (packet.length < 1 + KEY_SIZE + NONCE_SIZE + MAC_SIZE)
+        return undefined;
+    const type = packet[0];
+    if (!isDhtRpcType(type))
+        return undefined;
+    const senderPublicKey = packet.slice(1, 1 + KEY_SIZE);
+    const nonce = packet.slice(1 + KEY_SIZE, 1 + KEY_SIZE + NONCE_SIZE);
+    const encrypted = packet.slice(1 + KEY_SIZE + NONCE_SIZE);
+    const plain = nacl.box.open(encrypted, nonce, senderPublicKey, ourSecretKey);
+    if (!plain)
+        return undefined;
+    return { type, senderPublicKey, plain };
+}
+// ---- plaintext payload builders/parsers ----
+// ping req/resp plain: [type(1)][ping_id(8)]; the type byte is echoed inside
+// (toxcore uses it as a sanity check). ping_id is opaque, echoed by the peer.
+export function buildPingPlain(type, pingId) {
+    return concatBytes([Uint8Array.of(type), pingId.slice(0, 8)]);
+}
+export function parsePingPlain(plain) {
+    if (plain.length < 1 + 8)
+        return undefined;
+    return { innerType: plain[0], pingId: plain.slice(1, 9) };
+}
+// get_nodes plain: [target public key(32)][sendback ping_id(8)].
+export function buildGetNodesPlain(targetPublicKey, pingId) {
+    return concatBytes([targetPublicKey.slice(0, 32), pingId.slice(0, 8)]);
+}
+export function parseGetNodesPlain(plain) {
+    if (plain.length < 32 + 8)
+        return undefined;
+    return { target: plain.slice(0, 32), pingId: plain.slice(32, 40) };
+}
+// send_nodes plain: [count(1)][packed nodes...][sendback ping_id(8)].
+// (Nodes are parsed by peer.ts parsePackedNodes; we only split off the count
+//  prefix and trailing ping_id here.)
+export function buildSendNodesPlain(packedNodes, count, pingId) {
+    return concatBytes([Uint8Array.of(count & 0xff), packedNodes, pingId.slice(0, 8)]);
+}
+export function parseSendNodesNodeBytes(plain) {
+    if (plain.length < 1 + 8)
+        return undefined;
+    const count = plain[0];
+    if (count === 0)
+        return new Uint8Array(0);
+    // node region is everything between the count byte and the trailing 8-byte ping_id
+    return plain.slice(1, plain.length - 8);
+}
+// packed UDP IPv4 node (toxcore Node_format): [family=2][ip(4)][port BE(2)][pk(32)] = 39 bytes
+export function packUdpNodeV4(host, port, pk) {
+    const parts = host.split(".").map((p) => Number.parseInt(p, 10));
+    if (parts.length !== 4 || parts.some((n) => !(n >= 0 && n <= 255)))
+        return undefined;
+    if (pk.length !== 32 || !(port > 0 && port <= 0xffff))
+        return undefined;
+    const out = new Uint8Array(1 + 4 + 2 + 32);
+    out[0] = 2; // UDP_FAMILY_IPV4
+    out[1] = parts[0];
+    out[2] = parts[1];
+    out[3] = parts[2];
+    out[4] = parts[3];
+    out[5] = (port >> 8) & 0xff;
+    out[6] = port & 0xff;
+    out.set(pk, 7);
+    return out;
+}

package/dist/peer.d.ts

@@ -147,4 +147,34 @@ export declare class Peer {
         cookieRequestSentMs: number | null;
     } | null;
     waitForFriendRequest(timeoutMs?: number): Promise<FriendRequest>;
+    /**
+     * After a friend sends us PACKET_ID_ONLINE, push our nickname + status
+     * message so their UI replaces "unknown" with our actual display name,
+     * and optionally fire off a configured greeting message. Idempotent —
+     * tracked per friend so we don't spam every keepalive cycle.
+     *
+     * Sends are sequenced with small delays so the receiving peer's UI layer
+     * doesn't process three messenger packets in the same render frame —
+     * iOS Beagle 1.8.6 has a SwiftUI use-after-free in
+     * `_UIHostingView.beginTransaction()` when nickname / status / message
+     * arrive in rapid succession at session establishment, observed as
+     * EXC_BAD_ACCESS in the iOS app's main thread.
+     */
+    /**
+     * Update our own profile (display name / status-message description) at
+     * runtime and re-push it to friends. `name` maps to the toxcore nickname
+     * (PACKET_ID_NICKNAME) and the Carrier USERINFO `name`; `description` maps to
+     * the USERINFO descr / status message. Re-arms the per-friend "profile sent"
+     * flag so every friend receives the update, and proactively pushes to anyone
+     * currently online. The greeting is NOT re-sent (its flag is left intact).
+     */
+    setUserInfo(info: {
+        name?: string;
+        description?: string;
+    }): void;
+    /** Our current display name + status-message description. */
+    userInfo(): {
+        name: string;
+        description: string;
+    };
 }

package/dist/peer.js

@@ -8,6 +8,7 @@ import { LegacyBootstrapClient } from "./compat/bootstrap.js";
 import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket } from "./compat/packet.js";
 import { NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID, createOnionAnnounceRequest, createOnionDataPacket, createOnionDataRequest, createOnionRequest0, openOnionAnnounceResponse, openOnionDataPacket, openOnionDataResponse } from "./compat/tox-onion.js";
 import { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
+import { NET_PACKET_PING_REQUEST, NET_PACKET_PING_RESPONSE, NET_PACKET_GET_NODES, NET_PACKET_SEND_NODES, encodeDhtRpc, decodeDhtRpc, buildPingPlain, parsePingPlain, buildGetNodesPlain, parseGetNodesPlain, buildSendNodesPlain, parseSendNodesNodeBytes, packUdpNodeV4 } from "./compat/dht-rpc.js";
 import { NET_PACKET_CRYPTO_DATA, NET_PACKET_CRYPTO_HS, NET_PACKET_COOKIE_REQUEST, NET_PACKET_COOKIE_RESPONSE, createCookieRequest, createCookieResponse, createCryptoDataPacket, createCryptoHandshake, openCookieRequest, openCookieResponse, openCryptoDataPacket, openCryptoHandshake, incrementNonce } from "./compat/net-crypto.js";
 import { LegacyExpressClient } from "./compat/express.js";
 import { TcpRelayPool } from "./compat/tcp-relay-pool.js";
@@ -44,6 +45,10 @@ const NODE_BLACKLIST_MAX_TTL_MS = readEnvInt("DECENT_NODE_BLACKLIST_MAX_TTL_MS",
 const FRIEND_ANNOUNCE_ATTEMPTS = readEnvInt("DECENT_FRIEND_ANNOUNCE_ATTEMPTS", 1);
 const JOIN_ANNOUNCE_TIMEOUT_MS = readEnvInt("DECENT_JOIN_ANNOUNCE_TIMEOUT_MS", 12000);
 const SELF_ANNOUNCE_INTERVAL_MS = readEnvInt("DECENT_SELF_ANNOUNCE_INTERVAL_MS", 20000);
+// Classic-DHT maintenance cadence. Every tick we get_nodes toward our own key
+// (so neighbours store our address and native peers can find our UDP endpoint)
+// and toward each not-yet-UDP friend's key (so we find theirs and punch).
+const DHT_MAINTENANCE_INTERVAL_MS = readEnvInt("DECENT_DHT_MAINTENANCE_INTERVAL_MS", 15000);
 const MAX_SELF_ANNOUNCE_TARGETS = readEnvInt("DECENT_SELF_ANNOUNCE_TARGETS", 16);
 const SELF_ANNOUNCE_ATTEMPTS = readEnvInt("DECENT_SELF_ANNOUNCE_ATTEMPTS", 3);
 // Self-announce batch size — number of step1 / step2 requests to fan out
@@ -194,6 +199,7 @@ export class Peer {
     #selfAnnounceTimer;
     #friendConnectionTimer;
     #lanDiscoveryTimer;
+    #dhtMaintenanceTimer;
     // Per-friend last DHT-PK send time, keyed by friendId, used even when no
     // session entry exists yet so the connection loop does not flood DHT-PK
     // requests when route discovery keeps failing.
@@ -437,6 +443,10 @@ export class Peer {
             clearInterval(this.#selfAnnounceTimer);
             this.#selfAnnounceTimer = undefined;
         }
+        if (this.#dhtMaintenanceTimer) {
+            clearInterval(this.#dhtMaintenanceTimer);
+            this.#dhtMaintenanceTimer = undefined;
+        }
         if (this.#friendConnectionTimer) {
             clearInterval(this.#friendConnectionTimer);
             this.#friendConnectionTimer = undefined;
@@ -488,6 +498,7 @@ export class Peer {
         this.#knownNodes = dedupeNodes([result.respondingNode, ...discovered, ...this.#opts.bootstrapNodes]);
         await this.#runSelfAnnounce(false, Date.now() + JOIN_ANNOUNCE_TIMEOUT_MS);
         this.#ensureSelfAnnounceLoop();
+        this.#ensureDhtMaintenanceLoop();
         this.#ensureFriendConnectionLoop();
         this.#ensureExpressPullLoop();
         // Kick off an immediate friend connection cycle so persisted friends with
@@ -1066,6 +1077,19 @@ export class Peer {
                 catch { /* best-effort */ }
             }).catch(() => { });
         }
+        // Classic toxcore DHT RPC (ping / get_nodes / send_nodes). Answering these
+        // is what makes us *findable* over UDP: a native iOS/Android peer searches
+        // the DHT for our key, a neighbour that holds our address returns it, then
+        // the native peer pings/get_nodes us directly and net_cryptos over UDP.
+        // DHT is UDP-only, so ignore anything arriving via a TCP relay.
+        if ((packet[0] === NET_PACKET_PING_REQUEST ||
+            packet[0] === NET_PACKET_PING_RESPONSE ||
+            packet[0] === NET_PACKET_GET_NODES ||
+            packet[0] === NET_PACKET_SEND_NODES) &&
+            !this.#remoteIsTcp(remote)) {
+            this.#handleDhtRpc(packet, remote);
+            return;
+        }
         if (packet[0] === NET_PACKET_CRYPTO) {
             const opened = openToxDhtCryptoRequest(packet, this.#keyPair);
             if (!opened) {
@@ -2700,8 +2724,15 @@ export class Peer {
         // id (decentlan's IP channel = 163) via bulkDataPacketId so its
         // high-volume traffic gets the same single-transport routing instead of
         // fanning out over UDP + relay + TCP relay (which delivers 3-4 duplicates).
-        const isBulkData = kind === PACKET_ID_MESSAGE ||
-            (this.#opts.bulkDataPacketId !== undefined && kind === this.#opts.bulkDataPacketId);
+        // Chat (PACKET_ID_MESSAGE = 64) is LOW-volume and must be RELIABLE, so it
+        // is NOT bulk: it dual-sends over UDP + relay and net_crypto retransmits,
+        // so a reply still lands when the peer's UDP path is briefly stale (iOS
+        // app suspend / NAT remap) instead of being fired into a dead endpoint and
+        // silently lost. Only the app-declared high-volume channel (bulkDataPacketId,
+        // e.g. decentlan IP=163) stays bulk / single-transport to avoid the relay
+        // backlog + duplicate fan-out that high packet rates cause. Chat is sparse
+        // and net_crypto dedups by packet number, so dual-send is safe here.
+        const isBulkData = this.#opts.bulkDataPacketId !== undefined && kind === this.#opts.bulkDataPacketId;
         await this.#sendToFriend(friendId, encrypted, session, isBulkData);
     }
     /**
@@ -2801,6 +2832,34 @@ export class Peer {
      * arrive in rapid succession at session establishment, observed as
      * EXC_BAD_ACCESS in the iOS app's main thread.
      */
+    /**
+     * Update our own profile (display name / status-message description) at
+     * runtime and re-push it to friends. `name` maps to the toxcore nickname
+     * (PACKET_ID_NICKNAME) and the Carrier USERINFO `name`; `description` maps to
+     * the USERINFO descr / status message. Re-arms the per-friend "profile sent"
+     * flag so every friend receives the update, and proactively pushes to anyone
+     * currently online. The greeting is NOT re-sent (its flag is left intact).
+     */
+    setUserInfo(info) {
+        const opts = this.#opts;
+        if (info.name !== undefined)
+            opts.nickname = info.name;
+        if (info.description !== undefined)
+            opts.statusMessage = info.description;
+        this.#profileSentTo.clear();
+        for (const [friendId, s] of this.#friendSessions.entries()) {
+            if (s.established)
+                this.#sendProfileAndGreeting(friendId);
+        }
+    }
+    /** Our current display name + status-message description. */
+    userInfo() {
+        const opts = this.#opts;
+        return {
+            name: opts.nickname ?? PEER_NICKNAME,
+            description: opts.statusMessage ?? PEER_STATUS_MESSAGE,
+        };
+    }
     #sendProfileAndGreeting(friendId) {
         if (!this.#profileSentTo.has(friendId)) {
             this.#profileSentTo.add(friendId);
@@ -3544,6 +3603,193 @@ export class Peer {
             this.#debugLog(`lan_sweep friend=${friendId} probes=${probes}`);
         }
     }
+    // ===================== classic toxcore DHT (ping / get_nodes) ==========
+    // Answering and issuing these makes a JS peer a real DHT node — the thing
+    // native C++/iOS/Android Carrier clients rely on to find a friend's live UDP
+    // ip:port and net_crypto to it directly. Previously peer.js was a DHT *client*
+    // only (bootstrap get_nodes), so it was invisible: native peers couldn't find
+    // our UDP endpoint and every session fell back to the slow TCP relay.
+    #dhtPingId() {
+        return randomBytes(8);
+    }
+    // The known nodes closest (XOR distance) to `target`, UDP-only, with a valid
+    // 32-byte key — the candidates a get_nodes lookup should converge through.
+    #closestKnownNodes(target, limit) {
+        const withPk = [];
+        for (const node of this.#knownNodes) {
+            if (!node.pk || node.isTcp)
+                continue;
+            try {
+                const pk = base58ToBytes(node.pk);
+                if (pk.length === 32)
+                    withPk.push({ node, pk });
+            }
+            catch { /* skip malformed */ }
+        }
+        withPk.sort((a, b) => xorCloser(target, a.pk, b.pk));
+        return withPk.slice(0, limit).map((e) => e.node);
+    }
+    #friendByDhtPk(dhtPkBase58) {
+        for (const [friendId, session] of this.#friendSessions.entries()) {
+            const dpk = session.friendDhtPublicKey;
+            if (dpk && carrierIdFromPublicKey(dpk) === dhtPkBase58) {
+                return { friendId, realPk: session.friendRealPublicKey ?? dpk };
+            }
+        }
+        return undefined;
+    }
+    #handleDhtRpc(packet, remote) {
+        if (!this.#keyPair)
+            return;
+        const decoded = decodeDhtRpc(packet, this.#keyPair.secretKey);
+        if (!decoded)
+            return;
+        const senderId = carrierIdFromPublicKey(decoded.senderPublicKey);
+        // Learn the sender's real reachable UDP address: populates our table and
+        // keeps mutual reachability alive across the mesh.
+        if (remote.port > 0 && !this.#remoteIsTcp(remote)) {
+            this.addKnownNodes([{ host: remote.address, port: remote.port, pk: senderId, isTcp: false }]);
+        }
+        if (decoded.type === NET_PACKET_PING_REQUEST) {
+            const ping = parsePingPlain(decoded.plain);
+            if (!ping)
+                return;
+            // Echo ping_id so the peer marks us alive and keeps us in its table
+            // (= keeps us findable through it).
+            const plain = buildPingPlain(NET_PACKET_PING_RESPONSE, ping.pingId);
+            const resp = encodeDhtRpc(NET_PACKET_PING_RESPONSE, this.#keyPair, decoded.senderPublicKey, plain);
+            void this.#sendPacket(resp, { host: remote.address, port: remote.port }).catch(() => undefined);
+            return;
+        }
+        if (decoded.type === NET_PACKET_PING_RESPONSE) {
+            return; // liveness already recorded via addKnownNodes above
+        }
+        if (decoded.type === NET_PACKET_GET_NODES) {
+            const gn = parseGetNodesPlain(decoded.plain);
+            if (!gn)
+                return;
+            // Reply with up to 4 known nodes closest to the searched key. When a
+            // native peer searches for OUR key, replying from our socket reveals our
+            // address to them directly, and the hint lets their lookup converge.
+            const packedParts = [];
+            let count = 0;
+            for (const node of this.#closestKnownNodes(gn.target, 4)) {
+                if (!node.pk)
+                    continue;
+                let pk;
+                try {
+                    pk = base58ToBytes(node.pk);
+                }
+                catch {
+                    continue;
+                }
+                const packed = packUdpNodeV4(node.host, node.port, pk);
+                if (packed) {
+                    packedParts.push(packed);
+                    count++;
+                }
+            }
+            const nodesBytes = packedParts.length ? concatBytes(packedParts) : new Uint8Array(0);
+            const plain = buildSendNodesPlain(nodesBytes, count, gn.pingId);
+            const resp = encodeDhtRpc(NET_PACKET_SEND_NODES, this.#keyPair, decoded.senderPublicKey, plain);
+            void this.#sendPacket(resp, { host: remote.address, port: remote.port }).catch(() => undefined);
+            return;
+        }
+        if (decoded.type === NET_PACKET_SEND_NODES) {
+            const nodeBytes = parseSendNodesNodeBytes(decoded.plain);
+            if (!nodeBytes || nodeBytes.length === 0)
+                return;
+            const nodes = parsePackedNodes(nodeBytes).filter((n) => !n.isTcp);
+            if (nodes.length)
+                this.addKnownNodes(nodes);
+            // If a returned node IS one of our friends' DHT keys, we just learned
+            // their live UDP endpoint — cache it and kick a UDP cookie to punch.
+            for (const node of nodes) {
+                if (!node.pk)
+                    continue;
+                const match = this.#friendByDhtPk(node.pk);
+                if (!match)
+                    continue;
+                try {
+                    this.#cacheFriendRemote(match.friendId, node.host, node.port, match.realPk, base58ToBytes(node.pk));
+                    this.#debugLog(`dht_search found UDP endpoint for ${match.friendId} at ${node.host}:${node.port}`);
+                    void this.#initiateSession(match.friendId).catch(() => undefined);
+                }
+                catch { /* malformed key */ }
+            }
+            return;
+        }
+    }
+    async #sendDhtGetNodes(node, targetPublicKey) {
+        if (!this.#keyPair || !node.pk || node.isTcp)
+            return;
+        let recipientPk;
+        try {
+            recipientPk = base58ToBytes(node.pk);
+        }
+        catch {
+            return;
+        }
+        if (recipientPk.length !== 32)
+            return;
+        const plain = buildGetNodesPlain(targetPublicKey, this.#dhtPingId());
+        const pkt = encodeDhtRpc(NET_PACKET_GET_NODES, this.#keyPair, recipientPk, plain);
+        await this.#sendPacket(pkt, { host: node.host, port: node.port }).catch(() => undefined);
+    }
+    async #sendDhtPing(node) {
+        if (!this.#keyPair || !node.pk || node.isTcp)
+            return;
+        let recipientPk;
+        try {
+            recipientPk = base58ToBytes(node.pk);
+        }
+        catch {
+            return;
+        }
+        if (recipientPk.length !== 32)
+            return;
+        const plain = buildPingPlain(NET_PACKET_PING_REQUEST, this.#dhtPingId());
+        const pkt = encodeDhtRpc(NET_PACKET_PING_REQUEST, this.#keyPair, recipientPk, plain);
+        await this.#sendPacket(pkt, { host: node.host, port: node.port }).catch(() => undefined);
+    }
+    #ensureDhtMaintenanceLoop() {
+        if (this.#dhtMaintenanceTimer || DHT_MAINTENANCE_INTERVAL_MS <= 0)
+            return;
+        this.#dhtMaintenanceTimer = setInterval(() => {
+            void this.#doDhtMaintenance().catch(() => undefined);
+        }, DHT_MAINTENANCE_INTERVAL_MS);
+        if (typeof this.#dhtMaintenanceTimer.unref === "function")
+            this.#dhtMaintenanceTimer.unref();
+        void this.#doDhtMaintenance().catch(() => undefined); // become findable right after join
+    }
+    async #doDhtMaintenance() {
+        if (!this.#keyPair)
+            return;
+        const selfPk = this.#keyPair.publicKey;
+        // 1. get_nodes toward our OWN key → neighbours store our address → native
+        //    peers searching for us learn our UDP endpoint and can punch (findable).
+        for (const node of this.#closestKnownNodes(selfPk, 8)) {
+            void this.#sendDhtGetNodes(node, selfPk);
+        }
+        // 2. For each friend not on a confirmed UDP path, get_nodes toward THEIR
+        //    DHT key → learn their UDP endpoint → punch from our side.
+        for (const [, session] of this.#friendSessions.entries()) {
+            const dpk = session.friendDhtPublicKey;
+            if (!dpk)
+                continue;
+            const udpConfirmed = session.lastUdpRecvMs !== undefined && Date.now() - session.lastUdpRecvMs < 8_000;
+            if (udpConfirmed)
+                continue;
+            for (const node of this.#closestKnownNodes(dpk, 6)) {
+                void this.#sendDhtGetNodes(node, dpk);
+            }
+        }
+        // 3. Keep a handful of nodes warm (and ourselves in their tables).
+        for (const node of this.#knownNodes.slice(0, 8)) {
+            if (!node.isTcp)
+                void this.#sendDhtPing(node);
+        }
+    }
     /**
      * Send an onion DHT-PK announcement to a friend so they learn our DHT
      * public key + endpoint hints. This is the bidirectional partner of the
@@ -3652,6 +3898,36 @@ export class Peer {
                             packed.push(entry);
                         }
                     }
+                    // Also advertise our PUBLIC reflexive (srflx) UDP endpoint, learned
+                    // via STUN. The LAN entries above only help same-LAN peers; a peer
+                    // across the internet — e.g. a native iOS/Android Beagle client —
+                    // needs our NAT-mapped public ip:port to send a UDP cookie request
+                    // and punch. Without it they only ever learn our TCP relays and the
+                    // session sits on the slow transpacific relay forever. This is the
+                    // "STUN-style reflexive discovery" the LAN-only code deferred; it's
+                    // what makes Mac<->phone text go UDP-direct. The receiver already
+                    // consumes 0x02 entries (#handleOnionDhtPk -> #cacheFriendRemote).
+                    try {
+                        const srflx = await this.#gatherOwnSrflx();
+                        if (srflx && srflx.port > 0 && !seenIps.has(srflx.host)) {
+                            const parts = srflx.host.split(".").map((p) => Number.parseInt(p, 10));
+                            if (parts.length === 4 && !parts.some((n) => !(n >= 0 && n <= 255))) {
+                                const entry = new Uint8Array(1 + 4 + 2 + 32);
+                                entry[0] = 0x02; // UDP_FAMILY_IPV4
+                                entry[1] = parts[0];
+                                entry[2] = parts[1];
+                                entry[3] = parts[2];
+                                entry[4] = parts[3];
+                                entry[5] = (srflx.port >> 8) & 0xff;
+                                entry[6] = srflx.port & 0xff;
+                                entry.set(ourDhtPk, 7);
+                                packed.push(entry);
+                            }
+                        }
+                    }
+                    catch {
+                        // STUN gather failed — fall through with LAN + relay extras only.
+                    }
                 }
                 catch {
                     // os import or interface enumeration failed; skip UDP extras

package/package.json

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