@decentnetwork/peer 0.1.17 → 0.1.18

package/dist/peer.js

@@ -16,6 +16,7 @@ import { loadOrCreateKeyPair } from "./crypto/keypair.js";
 import { base58ToBytes } from "./utils/base58.js";
 import { UdpTransport } from "./transport/udp.js";
 import { bytesToHex, concatBytes, randomBytes } from "./utils/bytes.js";
+import { buildBindingRequest, decodeStun, decodeXorMappedAddress, findAttr, STUN_ATTR_XOR_MAPPED_ADDRESS, STUN_BINDING_SUCCESS } from "./stun.js";
 const ANNOUNCE_WAIT_TIMEOUT_MS = readEnvInt("DECENT_ANNOUNCE_WAIT_TIMEOUT_MS", 4000);
 const MAX_FRIEND_ROUTE_ATTEMPTS = readEnvInt("DECENT_FRIEND_ROUTE_MAX_ATTEMPTS", 12);
 // How many in-flight announce step1 requests to fan out at once. Toxcore
@@ -115,6 +116,13 @@ const PACKET_ID_USERSTATUS = 50; // friend's user status (1 byte enum)
 const PACKET_ID_TYPING = 51; // typing indicator (1 byte bool)
 const PACKET_ID_MESSAGE = 64; // text message (Carrier FlatBuffers payload)
 const PACKET_ID_ACTION = 65; // /me action message
+// Custom lossless range (toxcore reserves 160-191 for custom lossless
+// packets). We use 160 to carry a peer's server-reflexive UDP endpoint
+// so the other side can hole-punch directly — the job onion-announce was
+// supposed to do but can't against the live bootnodes. Peers that don't
+// understand this ID simply fall through and ignore it. Payload is 6
+// bytes: 4-byte IPv4 + 2-byte big-endian port.
+const PACKET_ID_UDP_ENDPOINT = 160;
 export class Peer {
     #opts;
     #events = new EventEmitter();
@@ -192,6 +200,11 @@ export class Peer {
     // #initiateSession every few seconds for every friend; without this
     // dedupe, lower-pubkey side floods the log with "deferring to peer".
     #initiateSkipLogged = new Set();
+    // Cached server-reflexive (public) UDP endpoint of our #udp socket,
+    // learned via STUN. Cone-NAT mappings are stable for the socket
+    // lifetime, so we only re-probe every ~60s. Used to tell friends where
+    // to hole-punch us (PACKET_ID_UDP_ENDPOINT).
+    #srflxCache;
     // Per-friend tracking sets so we send our nickname/status/greeting once
     // per session rather than on every PACKET_ID_ONLINE arrival.
     #profileSentTo = new Set();
@@ -1212,6 +1225,15 @@ export class Peer {
             this.#debugLog(`hs_recv friend=${friendId} initiated=${weInitiated ? 1 : 0} remote=${remote.address}:${remote.port}`);
             if (!wasEstablished) {
                 this.#debugLog(`friend_connected friend=${friendId} remote=${remote.address}:${remote.port}`);
+                // If we only have a TCP-relay path, immediately tell the peer our
+                // public UDP endpoint so they can hole-punch — don't wait for the
+                // 15s UDP-retry loop, which can miss a flapping relay session's
+                // short-lived establishment window. Both sides do this on every
+                // (re)establishment, so a brief tcp-relay window is enough to
+                // bootstrap the direct UDP path. See docs/UDP-DIRECT-PLAN.md.
+                if (state.hasTcpRoute && !state.remote) {
+                    void this.#sendUdpEndpointOffer(friendId).catch(() => undefined);
+                }
             }
             const friend = this.#friends.get(friendId);
             if (friend) {
@@ -1309,6 +1331,10 @@ export class Peer {
                 }
                 else {
                     state.remote = { host: remote.address, port: remote.port };
+                    if (!state.lastUdpRecvMs) {
+                        this.#debugLog(`udp_confirmed friend=${friendId} via=${remote.address}:${remote.port} (direct UDP path live)`);
+                    }
+                    state.lastUdpRecvMs = Date.now();
                 }
                 state.receiveBufferStart = Math.max(state.receiveBufferStart ?? 0, (opened.packetNumber + 1) >>> 0);
                 const kind = opened.payload[0];
@@ -1339,6 +1365,11 @@ export class Peer {
                     this.#debugVerboseLog(`crypto alive (keepalive) received from ${friendId}`);
                     return;
                 }
+                if (kind === PACKET_ID_UDP_ENDPOINT) {
+                    // Peer told us their public UDP endpoint — hole-punch to it.
+                    this.#handleUdpEndpointOffer(friendId, inner);
+                    return;
+                }
                 if (kind === PACKET_ID_REQUEST) {
                     // Lossless retransmission request from peer. Full reliable stream
                     // not yet implemented in JS port, so just acknowledge by logging.
@@ -2125,14 +2156,36 @@ export class Peer {
                 // with the real endpoint and #sendMessengerPacket picks UDP
                 // over TCP from then on. Throttled to UDP_RETRY_INTERVAL_MS so
                 // the loop's 250ms tick doesn't flood DHT lookups.
-                const realUdpRemote = session.remote &&
-                    !session.remote.host?.startsWith("tcp:") &&
-                    session.remote.port !== 0;
-                if (!realUdpRemote && session.hasTcpRoute) {
-                    const UDP_RETRY_INTERVAL_MS = 15_000;
+                // Gate on whether direct UDP is *confirmed* (we've actually
+                // received a packet over a real UDP endpoint recently), NOT on
+                // whether session.remote happens to hold a UDP-shaped value —
+                // #handleUdpEndpointOffer sets session.remote optimistically
+                // before the punch is proven, so using it here would stop the
+                // offer/punch retry prematurely and deadlock a half-punched pair.
+                // Treat the UDP path as needing re-punch once it's been quiet for
+                // >7s. This is deliberately close to #sendToFriend's 10s
+                // relay-fallback threshold: if UDP stalls, we want the re-offer +
+                // re-punch to fire almost immediately so the direct path recovers
+                // before much traffic spills onto the slow relay (whose queue can
+                // back up 20s+ on the China↔US leg). A healthy path refreshes
+                // lastUdpRecvMs every ~1s via keepalive/data, so this never fires
+                // while UDP is working.
+                const udpConfirmed = session.lastUdpRecvMs !== undefined && now - session.lastUdpRecvMs < 7_000;
+                if (!udpConfirmed && session.hasTcpRoute) {
+                    // Aggressive re-punch cadence: the relay path is lossy, so a few
+                    // offers may drop before one lands and both sides punch in the
+                    // same window. 3s keeps recovery snappy without flooding.
+                    const UDP_RETRY_INTERVAL_MS = 3_000;
                     const lastTry = session.lastUdpRetryMs ?? 0;
                     if (now - lastTry > UDP_RETRY_INTERVAL_MS) {
                         session.lastUdpRetryMs = now;
+                        // Out-of-band UDP endpoint exchange (works where the broken
+                        // onion-announce DHT discovery below does not): tell the peer
+                        // our STUN-learned public endpoint over the messenger channel.
+                        // When they do the same, both sides feed each other's endpoint
+                        // into endpointCandidates and hole-punch. Cone↔cone gets a
+                        // direct ~one-RTT UDP path; see docs/UDP-DIRECT-PLAN.md.
+                        void this.#sendUdpEndpointOffer(friendId).catch(() => undefined);
                         // Recompute friend's real public key for the DHT-PK push.
                         // Same fallback chain as the cooldown branch below.
                         let friendRealPk = session.friendRealPublicKey;
@@ -2312,7 +2365,17 @@ export class Peer {
         incrementNonce(session.ourBaseNonce);
         session.sendPacketNumber = (packetNumber + 1) >>> 0;
         session.lastPingSentMs = Date.now();
-        await this.#sendToFriend(friendId, encrypted, session);
+        // Bulk IP-forwarding data (PACKET_ID_MESSAGE) is the high-volume
+        // traffic. Once UDP is established it should ride UDP exclusively and
+        // NEVER spill onto the TCP relay during a UDP hiccup — the relay's
+        // China↔US queue backs up 20s+ and every spilled packet returns as a
+        // hugely-delayed duplicate. Control packets (keepalives, endpoint
+        // offers, profile) keep the relay fallback so the session and the
+        // re-punch survive a UDP outage. Brief UDP gaps just drop a few data
+        // packets (the proxied TCP stream retransmits) and the re-punch loop
+        // restores the direct path within a few seconds.
+        const isBulkData = kind === PACKET_ID_MESSAGE;
+        await this.#sendToFriend(friendId, encrypted, session, isBulkData);
     }
     /**
      * Send `packet` to `friendId` over whichever transport(s) are
@@ -2322,11 +2385,12 @@ export class Peer {
      * receiving end (toxcore does the same when both transports are up).
      * Throws only if zero transports succeeded.
      */
-    async #sendToFriend(friendId, packet, session) {
+    async #sendToFriend(friendId, packet, session, isBulkData = false) {
         const s = session ?? this.#friendSessions.get(friendId);
         let udpOk = false;
         let tcpOk = false;
         let firstError;
+        const realUdpRemote = s?.remote && !s.remote.host?.startsWith("tcp:") && s.remote.port !== 0;
         if (s?.remote) {
             try {
                 await this.#sendPacket(packet, s.remote);
@@ -2336,6 +2400,29 @@ export class Peer {
                 firstError = error;
             }
         }
+        // UDP-confirmed-ever: we've successfully received at least one UDP
+        // packet from this peer, so the direct path has worked at some point.
+        const udpEverConfirmed = s?.lastUdpRecvMs !== undefined;
+        // Bulk IP-forwarding data: send UDP-ONLY once the direct path has ever
+        // been confirmed. Never spill onto the relay (its backlog is the
+        // source of the 20s-late duplicates). A transient UDP gap just drops a
+        // few packets; the re-punch loop (every 3s when UDP is quiet >7s)
+        // restores the path, and control traffic on the relay keeps the
+        // session alive meanwhile.
+        if (isBulkData && udpOk && realUdpRemote && udpEverConfirmed) {
+            return;
+        }
+        // Control traffic: once direct UDP is confirmed *recently* (<10s),
+        // also send UDP-only to avoid steady-state duplicates; otherwise fan
+        // out over UDP + relay so control reaches the peer even when the
+        // direct path is down (this is what lets the re-punch recover).
+        const udpLiveRecent = udpOk &&
+            realUdpRemote &&
+            s?.lastUdpRecvMs !== undefined &&
+            Date.now() - s.lastUdpRecvMs < 10_000;
+        if (udpLiveRecent) {
+            return;
+        }
         if (this.#tcpRelays) {
             // The TCP relay routes by the friend's DHT pubkey (= the pubkey
             // they handshook the relay with), not by the friend's real
@@ -2473,6 +2560,147 @@ export class Peer {
             .sort((a, b) => b.updatedMs - a.updatedMs)
             .slice(0, 12);
     }
+    /**
+     * Learn our own server-reflexive (public) UDP endpoint by sending a
+     * STUN binding-request to a bootnode on its STUN port (3478) over the
+     * SAME #udp socket net_crypto uses — so the reflexive port matches
+     * where our crypto data will actually arrive. Cached briefly because
+     * a cone NAT's mapping is stable for the socket's lifetime.
+     *
+     * Returns undefined if no bootnode answers within the timeout.
+     */
+    async #gatherOwnSrflx() {
+        const CACHE_MS = 60_000;
+        const now = Date.now();
+        if (this.#srflxCache && now - this.#srflxCache.atMs < CACHE_MS) {
+            return this.#srflxCache.addr;
+        }
+        const bootnodes = this.#opts.bootstrapNodes;
+        if (!bootnodes || bootnodes.length === 0)
+            return undefined;
+        // Try up to 3 bootnodes; first answer wins.
+        for (const bn of bootnodes.slice(0, 3)) {
+            const req = buildBindingRequest();
+            const txnHex = Buffer.from(req.slice(8, 20)).toString("hex");
+            const addr = await new Promise((resolve) => {
+                const interceptor = (data, rinfo) => {
+                    if (rinfo.address !== bn.host || rinfo.port !== 3478)
+                        return false;
+                    const msg = decodeStun(data);
+                    if (!msg || msg.type !== STUN_BINDING_SUCCESS)
+                        return false;
+                    if (Buffer.from(msg.transactionId).toString("hex") !== txnHex)
+                        return false;
+                    const xma = findAttr(msg, STUN_ATTR_XOR_MAPPED_ADDRESS);
+                    const parsed = xma ? decodeXorMappedAddress(xma, msg.transactionId) : undefined;
+                    this.#udp.removeStunInterceptor(interceptor);
+                    clearTimeout(timer);
+                    resolve(parsed ? { host: parsed.address, port: parsed.port } : undefined);
+                    return true; // consume — don't let it reach net_crypto/DHT dispatch
+                };
+                const timer = setTimeout(() => {
+                    this.#udp.removeStunInterceptor(interceptor);
+                    resolve(undefined);
+                }, 2000);
+                this.#udp.addStunInterceptor(interceptor);
+                this.#udp.sendDirect(Buffer.from(req), bn.host, 3478).catch(() => {
+                    this.#udp.removeStunInterceptor(interceptor);
+                    clearTimeout(timer);
+                    resolve(undefined);
+                });
+            });
+            if (addr) {
+                this.#srflxCache = { addr, atMs: now };
+                return addr;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Tell a friend our public UDP endpoint over the (already-working,
+     * possibly tcp-relay) messenger channel, so they can hole-punch to us.
+     * This is the out-of-band substitute for the broken DHT/onion-announce
+     * endpoint discovery. Both peers do this symmetrically; on receipt each
+     * feeds the other's endpoint into endpointCandidates and punches.
+     */
+    async #sendUdpEndpointOffer(friendId) {
+        const session = this.#friendSessions.get(friendId);
+        if (!session?.established)
+            return;
+        const srflx = await this.#gatherOwnSrflx();
+        if (!srflx)
+            return;
+        const octets = srflx.host.split(".").map((s) => parseInt(s, 10));
+        if (octets.length !== 4 || octets.some((o) => Number.isNaN(o)))
+            return;
+        const payload = new Uint8Array(6);
+        payload.set(octets, 0);
+        payload[4] = (srflx.port >> 8) & 0xff;
+        payload[5] = srflx.port & 0xff;
+        try {
+            await this.#sendMessengerPacket(friendId, PACKET_ID_UDP_ENDPOINT, payload);
+            this.#debugLog(`udp-endpoint offer sent to ${friendId}: ${srflx.host}:${srflx.port}`);
+        }
+        catch {
+            // best-effort — the retry loop will try again
+        }
+    }
+    /**
+     * A friend told us their public UDP endpoint. Feed it as a high-value
+     * candidate and immediately spray a few raw punch datagrams at it to
+     * open our own cone-NAT mapping toward their address:port, then kick a
+     * session initiation (the higher-pubkey side sends the cookie request;
+     * both sides' mappings are now open so it gets through). Mirrors the
+     * proven standalone hole-punch.
+     */
+    #handleUdpEndpointOffer(friendId, payload) {
+        if (payload.length < 6)
+            return;
+        const host = `${payload[0]}.${payload[1]}.${payload[2]}.${payload[3]}`;
+        const port = ((payload[4] << 8) | payload[5]) >>> 0;
+        if (port === 0)
+            return;
+        const session = this.#friendSessions.get(friendId);
+        if (!session)
+            return;
+        // Don't punch toward ourselves.
+        if (getLocalIpv4Addresses().includes(host) && this.#udp.localPort() === port)
+            return;
+        this.#rememberEndpointCandidate(session, host, port);
+        this.#debugLog(`udp-endpoint offer from ${friendId}: ${host}:${port} — punching`);
+        // Spray a handful of tiny punch datagrams (0xF2 is not a recognized
+        // Carrier/DHT/net_crypto packet type, so the peer's #onDatagram
+        // ignores them — their only purpose is opening our NAT mapping
+        // toward host:port so the peer's crypto data can reach us).
+        const punch = Uint8Array.of(0xf2);
+        let n = 0;
+        const punchTimer = setInterval(() => {
+            this.#udp.sendDirectSync(Buffer.from(punch), host, port);
+            if (++n >= 6)
+                clearInterval(punchTimer);
+        }, 120);
+        // Point this session's UDP remote at the peer's reflexive endpoint
+        // (unless we already have a confirmed real UDP remote). hasTcpRoute
+        // stays true, so #sendToFriend fans crypto data out over BOTH UDP
+        // and TCP relay: TCP keeps the session alive even if the punch
+        // fails, while every UDP-bound keepalive/packet that makes it
+        // through the freshly-punched hole causes the peer's CRYPTO_DATA
+        // handler to set THEIR remote to our endpoint (peer.ts ~1564) —
+        // upgrading the path to direct UDP in both directions with no new
+        // handshake. If UDP never works, the periodic offer re-punches.
+        const haveRealUdp = session.remote && !session.remote.host?.startsWith("tcp:") && session.remote.port !== 0;
+        if (!haveRealUdp) {
+            session.remote = { host, port };
+        }
+        // Nudge a keepalive out immediately so the upgrade doesn't wait for
+        // the next periodic ALIVE — fans out over UDP (punched) + TCP.
+        if (session.established) {
+            void this.#sendMessengerPacket(friendId, PACKET_ID_ALIVE, new Uint8Array()).catch(() => undefined);
+        }
+        else {
+            void this.#initiateSession(friendId).catch(() => undefined);
+        }
+    }
     #collectSessionEndpointCandidates(friendId, friend, session) {
         // Three buckets: same-LAN private (highest priority for direct UDP),
         // public/routable, and other private (different LAN, last-resort).

package/dist/stun.d.ts

@@ -0,0 +1,117 @@
+/**
+ * STUN message codec (RFC 5389 + parts of 5766 for TURN integration).
+ *
+ * Supports the subset we need:
+ *  - Binding Request / Binding Success Response (RFC 5389) for SRFLX
+ *    discovery and ICE connectivity checks.
+ *  - Long-term credential MESSAGE-INTEGRITY (HMAC-SHA1) and FINGERPRINT,
+ *    needed by the bootnode TURN servers (coturn).
+ *  - XOR-MAPPED-ADDRESS decoding.
+ *  - USERNAME, REALM, NONCE, ERROR-CODE attributes (TURN auth dance).
+ *  - SOFTWARE / FINGERPRINT attributes for being polite.
+ *
+ * Wire format:
+ *
+ *   0                   1                   2                   3
+ *   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *  |0 0|     STUN Message Type     |         Message Length        |
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *  |                         Magic Cookie                          |
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *  |                                                               |
+ *  |                     Transaction ID (96 bits)                  |
+ *  |                                                               |
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *
+ * Attributes follow as { type: u16, length: u16, value: bytes, pad to 4 }.
+ *
+ * MESSAGE-INTEGRITY is HMAC-SHA1 over the entire message up to (not
+ * including) the MESSAGE-INTEGRITY attribute itself, with the message
+ * length pre-adjusted as if MESSAGE-INTEGRITY were present.
+ */
+export declare const STUN_MAGIC_COOKIE = 554869826;
+export declare const STUN_BINDING_REQUEST = 1;
+export declare const STUN_BINDING_SUCCESS = 257;
+export declare const STUN_BINDING_ERROR = 273;
+export declare const TURN_ALLOCATE_REQUEST = 3;
+export declare const TURN_ALLOCATE_SUCCESS = 259;
+export declare const TURN_ALLOCATE_ERROR = 275;
+export declare const TURN_REFRESH_REQUEST = 4;
+export declare const TURN_REFRESH_SUCCESS = 260;
+export declare const TURN_CREATE_PERMISSION_REQUEST = 8;
+export declare const TURN_CREATE_PERMISSION_SUCCESS = 264;
+export declare const TURN_SEND_INDICATION = 22;
+export declare const TURN_DATA_INDICATION = 23;
+export declare const STUN_ATTR_MAPPED_ADDRESS = 1;
+export declare const STUN_ATTR_USERNAME = 6;
+export declare const STUN_ATTR_MESSAGE_INTEGRITY = 8;
+export declare const STUN_ATTR_ERROR_CODE = 9;
+export declare const STUN_ATTR_REALM = 20;
+export declare const STUN_ATTR_NONCE = 21;
+export declare const STUN_ATTR_XOR_MAPPED_ADDRESS = 32;
+export declare const STUN_ATTR_SOFTWARE = 32802;
+export declare const STUN_ATTR_FINGERPRINT = 32808;
+export declare const STUN_ATTR_CHANNEL_NUMBER = 12;
+export declare const STUN_ATTR_LIFETIME = 13;
+export declare const STUN_ATTR_XOR_PEER_ADDRESS = 18;
+export declare const STUN_ATTR_DATA = 19;
+export declare const STUN_ATTR_XOR_RELAYED_ADDRESS = 22;
+export declare const STUN_ATTR_REQUESTED_TRANSPORT = 25;
+export declare const STUN_ATTR_DONT_FRAGMENT = 26;
+export interface StunAttribute {
+    type: number;
+    value: Uint8Array;
+}
+export interface StunMessage {
+    type: number;
+    transactionId: Uint8Array;
+    attributes: StunAttribute[];
+}
+export interface AddressValue {
+    family: 4 | 6;
+    address: string;
+    port: number;
+}
+export declare function newTransactionId(): Uint8Array;
+/**
+ * Encode a STUN message. If `integrityKey` is provided, a
+ * MESSAGE-INTEGRITY attribute (HMAC-SHA1) is appended. If `fingerprint`
+ * is true, a FINGERPRINT (CRC32 XOR 0x5354554e) is appended last.
+ *
+ * The order matters because MESSAGE-INTEGRITY must be computed over
+ * the message *as if* it were the last attribute (with length already
+ * adjusted), and FINGERPRINT must be computed over the message
+ * including MESSAGE-INTEGRITY.
+ */
+export declare function encodeStun(message: StunMessage, opts?: {
+    integrityKey?: Uint8Array;
+    fingerprint?: boolean;
+}): Uint8Array;
+export declare function decodeStun(data: Uint8Array): StunMessage | undefined;
+export declare function findAttr(message: StunMessage, type: number): Uint8Array | undefined;
+/**
+ * Decode XOR-MAPPED-ADDRESS (RFC 5389 §15.2). The high bits of the
+ * port and the address are XORed with the magic cookie + transactionId.
+ */
+export declare function decodeXorMappedAddress(value: Uint8Array, transactionId: Uint8Array): AddressValue | undefined;
+/** Encode XOR-MAPPED-ADDRESS for outgoing STUN responses (TURN, conn check). */
+export declare function encodeXorMappedAddress(addr: AddressValue, transactionId: Uint8Array): Uint8Array;
+export declare function encodeErrorCode(code: number, reason: string): Uint8Array;
+export declare function decodeErrorCode(value: Uint8Array): {
+    code: number;
+    reason: string;
+} | undefined;
+/**
+ * Long-term-credential integrity key: MD5("username:realm:password").
+ * RFC 5389 §15.4. coturn uses this.
+ */
+export declare function longTermIntegrityKey(username: string, realm: string, password: string): Uint8Array;
+/** Short-term-credential integrity key: just the password as UTF-8. */
+export declare function shortTermIntegrityKey(password: string): Uint8Array;
+export declare function buildBindingRequest(transactionId?: Uint8Array): Uint8Array;
+export declare function buildBindingRequestWithIntegrity(opts: {
+    username: string;
+    password: string;
+    transactionId?: Uint8Array;
+}): Uint8Array;