@decentnetwork/peer 0.1.17 → 0.1.19

package/dist/peer.js

@@ -16,6 +16,16 @@ 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";
+import { TurnClient } from "./turn.js";
+import { createSocket as createDgramSocket } from "dgram";
+// Dedicated TURN relay servers — fixed public relays used as a stable
+// fallback path when direct UDP hole-punch fails or flaps (symmetric NAT,
+// NAT remaps, lossy direct path). A relay endpoint never NAT-flaps, so the
+// path stays put even when the peers' NATs churn. Static long-term creds.
+const TURN_RELAY_SERVERS = [
+    { host: "tokyo.fi.chat", port: 3478, username: "allcom", password: "allcompass" }
+];
 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,11 +125,28 @@ 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();
     #keyPair;
     #udp = new UdpTransport();
+    // TURN relay (stable fallback path). One node-level allocation on its own
+    // dedicated UDP socket — kept separate from #udp so net_crypto/DHT and the
+    // TURN control protocol never share a socket (no demux). Inbound relayed
+    // data is injected into #onDatagram as if it arrived directly from the
+    // peer's relay address; outbound to a peer's relay address goes through
+    // #turnClient.sendTo. Lazily allocated on first need.
+    #turnClient;
+    #turnSocket;
+    #ourRelayAddr;
+    #turnAllocating;
     #bootstrap;
     #dht = new LegacyDhtClient();
     #knownNodes;
@@ -192,6 +219,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();
@@ -385,6 +417,17 @@ export class Peer {
         }
         this.#udp.off("datagram", this.#onDatagram);
         await this.#udp.stop();
+        // Release the TURN allocation + its dedicated socket.
+        try {
+            this.#turnClient?.close();
+            this.#turnSocket?.close();
+        }
+        catch {
+            // best-effort
+        }
+        this.#turnClient = undefined;
+        this.#turnSocket = undefined;
+        this.#ourRelayAddr = undefined;
         this.#started = false;
     }
     pubkey() {
@@ -880,7 +923,7 @@ export class Peer {
     #remoteIsTcp(remote) {
         return remote.address.startsWith("tcp:");
     }
-    #onDatagram = ({ data, remote }) => {
+    #onDatagram = ({ data, remote, viaRelay }) => {
         if (!this.#keyPair) {
             return;
         }
@@ -1178,13 +1221,26 @@ export class Peer {
                 isNewSession &&
                 state.sessionEstablishedAtMs !== undefined) {
                 const sinceEstablished = Date.now() - state.sessionEstablishedAtMs;
-                if (sinceEstablished > 1000) {
+                // Only reject the fresh handshake if our CURRENT session is
+                // actually alive — i.e. carrying data. A wedged "established"
+                // session that's receiving nothing must NOT block a re-handshake,
+                // or a peer that dropped + restarted can never reconnect: it keeps
+                // sending fresh handshakes and we keep rejecting them against a
+                // corpse. (This is the all-exits-outage bug: mac held a dead
+                // "established" session for cn and ignored every reconnect
+                // attempt.) If we haven't received a packet within FRIEND_TIMEOUT_MS
+                // the current session is dead — fall through and accept the new one.
+                const lastAlive = state.lastPingRecvMs ?? state.sessionEstablishedAtMs;
+                const currentSessionAlive = Date.now() - lastAlive < FRIEND_TIMEOUT_MS;
+                if (sinceEstablished > 1000 && currentSessionAlive) {
                     // Verbose only — peers retransmit handshakes aggressively, so
                     // this line fires dozens of times per minute on a stuck pair
                     // and drowns out signal. Visible with DECENT_DEBUG_VERBOSE=1.
-                    this.#debugVerboseLog(`hs_recv ignored friend=${friendId} (new session pubkey on established session, ${sinceEstablished}ms after establish)`);
+                    this.#debugVerboseLog(`hs_recv ignored friend=${friendId} (new session pubkey on live established session, ${sinceEstablished}ms after establish)`);
                     return;
                 }
+                this.#debugLog(`hs_recv accepting re-handshake friend=${friendId} (current session wedged/dead, ` +
+                    `lastPingRecv=${state.lastPingRecvMs ? Date.now() - state.lastPingRecvMs + "ms ago" : "never"})`);
             }
             state.peerSessionPublicKey = hs.sessionPublicKey;
             state.peerBaseNonce = hs.baseNonce.slice();
@@ -1212,6 +1268,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) {
@@ -1307,8 +1372,21 @@ export class Peer {
                 if (this.#remoteIsTcp(remote)) {
                     state.hasTcpRoute = true;
                 }
+                else if (viaRelay) {
+                    // Arrived over the TURN relay. Track relay freshness separately;
+                    // do NOT set state.remote (that's the direct endpoint). The relay
+                    // address it came from is already in state.relayRemote.
+                    if (!state.lastRelayRecvMs) {
+                        this.#debugLog(`relay_confirmed friend=${friendId} via=${remote.address}:${remote.port} (TURN relay path live)`);
+                    }
+                    state.lastRelayRecvMs = Date.now();
+                }
                 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 +1417,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.
@@ -2091,10 +2174,33 @@ export class Peer {
             const session = this.#friendSessions.get(friendId);
             // Established session: keepalive + timeout monitoring
             if (session?.established) {
-                if (session.lastPingRecvMs && now - session.lastPingRecvMs > FRIEND_TIMEOUT_MS) {
-                    this.#debugLog(`session timeout for ${friendId} (no ping in ${FRIEND_TIMEOUT_MS}ms)`);
+                // Liveness: time out a session that hasn't received ANY packet
+                // within FRIEND_TIMEOUT_MS — measured from the last received ping
+                // OR, if we've never received one, from when the session was
+                // established. The previous `lastPingRecvMs &&` guard skipped the
+                // check entirely when lastPingRecvMs was undefined, so a session
+                // that established but never carried a single packet (the path
+                // died at/just-after handshake) lived forever reporting
+                // transport=both while IP forwarding was 100% loss, and never tore
+                // down to re-handshake. Tearing it down here drops it to the
+                // non-established branch below, which re-initiates a fresh
+                // connection — turning a permanent wedge into a ~timeout self-heal.
+                const lastAlive = session.lastPingRecvMs ?? session.sessionEstablishedAtMs ?? now;
+                if (now - lastAlive > FRIEND_TIMEOUT_MS) {
+                    this.#debugLog(`session timeout for ${friendId} (no ping in ${now - lastAlive}ms; ` +
+                        `lastPingRecv=${session.lastPingRecvMs ?? "never"}) — tearing down to re-handshake`);
                     this.#friendSessions.delete(friendId);
                     this.#setFriendOffline(friendId);
+                    // Re-assert the relay route so the friend-connection bootstrap
+                    // (CONNECTION_NOTIFICATION -> #initiateSession) can re-fire on
+                    // re-establishment. requestRoute is idempotent, so this is a
+                    // no-op if the route is still live.
+                    try {
+                        const pk = base58ToBytes(friend.pubkey);
+                        if (pk.length === 32)
+                            this.#tcpRelays?.requestRoute(pk);
+                    }
+                    catch { /* skip malformed */ }
                     continue;
                 }
                 if (!session.lastPingSentMs || now - session.lastPingSentMs > FRIEND_PING_INTERVAL_MS) {
@@ -2125,14 +2231,55 @@ 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
+                // >4s — matched to #sendToFriend's 4s freshness window, so the
+                // moment bulk data starts bridging over the relay we're already
+                // re-offering + re-punching to restore the direct path (e.g. after
+                // a NAT port remap). A healthy path refreshes lastUdpRecvMs every
+                // ~1s via keepalive/data, so this never fires while UDP works.
+                // Relay keepalive — runs even when the direct path is perfectly
+                // healthy, so the TURN relay stays ready as an instant fallback.
+                // Without this the relay's permission (and the candidate exchange)
+                // silently lapse after ~5min and a later direct-path failure falls
+                // all the way back to the slow tcp-relay. Re-send our offer (so the
+                // peer refreshes ITS permission for our relay) and re-permit the
+                // peer's relay on our own allocation. Cheap, every 2min.
+                if (session.established && session.hasTcpRoute) {
+                    const RELAY_KEEPALIVE_MS = 120_000;
+                    if (now - (session.lastRelayKeepaliveMs ?? 0) > RELAY_KEEPALIVE_MS) {
+                        session.lastRelayKeepaliveMs = now;
+                        void this.#sendUdpEndpointOffer(friendId).catch(() => undefined);
+                        if (session.relayRemote && this.#turnClient) {
+                            const rr = session.relayRemote;
+                            void this.#turnClient
+                                .createPermission({ family: 4, address: rr.host, port: rr.port })
+                                .then(() => { session.relayPermittedAtMs = Date.now(); })
+                                .catch(() => undefined);
+                        }
+                    }
+                }
+                const udpConfirmed = session.lastUdpRecvMs !== undefined && now - session.lastUdpRecvMs < 4_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;
@@ -2227,10 +2374,18 @@ export class Peer {
                     });
                 }
             }
-            // No active session: try to establish one if we know the friend's endpoint.
-            // If we don't, the C++-initiated path can still bring up the session
-            // when peer reaches us — so this is only one of two ways to recover.
-            const haveEndpoint = (friend.remoteHost && friend.remotePort) || session?.remote;
+            // No active session: try to establish one if we know the friend's
+            // endpoint. A friend reachable over the TCP relay counts — the cookie
+            // request + handshake go over the relay OOB (the log shows
+            // `cookie_sent udp=0 tcp=1`). Without including hasTcpRoute here, a
+            // relay-only friend whose handshake didn't complete on the first try
+            // (peer's handshake-back was lost) was NEVER retried — the cookie
+            // retry below was gated on a UDP endpoint — so the session stayed
+            // stuck forever at "friend_online but never established". That is the
+            // post-restart reconnection wedge that took down cn/callpass: relay
+            // bridged them, cookie+handshake fired once, didn't complete, and
+            // nothing re-tried it. Counting the relay route lets the retry fire.
+            const haveEndpoint = (friend.remoteHost && friend.remotePort) || session?.remote || session?.hasTcpRoute;
             if (!haveEndpoint) {
                 const dhtPk = session?.friendDhtPublicKey;
                 if (dhtPk) {
@@ -2312,7 +2467,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,12 +2487,28 @@ 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;
-        if (s?.remote) {
+        const realUdpRemote = s?.remote && !s.remote.host?.startsWith("tcp:") && s.remote.port !== 0;
+        // "Fresh" = we've received UDP from this peer within the last few
+        // seconds, so the direct endpoint is currently live. When the peer's
+        // NAT remaps its port (observed periodically on residential/cloud
+        // NATs) the old endpoint goes dark and lastUdpRecvMs goes stale.
+        const udpFresh = !!realUdpRemote &&
+            s?.lastUdpRecvMs !== undefined &&
+            Date.now() - s.lastUdpRecvMs < 4_000;
+        // Bulk IP data rides the direct path ONLY while it's fresh. When it
+        // goes stale (likely a NAT remap mid-stream), we do NOT keep firing
+        // into the dead endpoint and we do NOT duplicate onto UDP — we bridge
+        // over the relay until the re-punch restores UDP (which refreshes
+        // lastUdpRecvMs). This converts a multi-second blackout into a few
+        // seconds of higher relay latency. Control packets always probe UDP
+        // (to keep the NAT mapping warm) so we still try UDP for them.
+        const tryUdp = realUdpRemote && (isBulkData ? udpFresh : true);
+        if (tryUdp && s?.remote) {
             try {
                 await this.#sendPacket(packet, s.remote);
                 udpOk = true;
@@ -2336,6 +2517,25 @@ export class Peer {
                 firstError = error;
             }
         }
+        // Fresh direct path → send over UDP only: no relay fan-out, no
+        // duplicates, no relay backlog. Applies to both data and control.
+        if (udpFresh && udpOk) {
+            return;
+        }
+        // Tier 2: TURN relay (tokyo) — a fast (~280ms) stable fallback that
+        // never NAT-flaps. Used when the direct path isn't fresh (remap, loss,
+        // symmetric NAT). For bulk data, once the relay path is *confirmed*
+        // (we've received over it recently) it carries data on its own — no
+        // tcp-relay fan-out, no duplicates. Until confirmed, we still also try
+        // tcp below so a packet isn't lost while the relay path warms up.
+        let relayOk = false;
+        if (s?.relayRemote && s.relayPermitted) {
+            relayOk = this.#sendViaRelay(packet, s.relayRemote);
+            const relayConfirmed = s.lastRelayRecvMs !== undefined && Date.now() - s.lastRelayRecvMs < 8_000;
+            if (isBulkData && relayOk && relayConfirmed) {
+                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
@@ -2356,7 +2556,7 @@ export class Peer {
                 }
             }
         }
-        if (!udpOk && !tcpOk) {
+        if (!udpOk && !relayOk && !tcpOk) {
             throw firstError ?? new Error(`no transport accepted send for ${friendId}`);
         }
     }
@@ -2473,6 +2673,259 @@ 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() {
+        // Short cache: when our NAT remaps the socket's external port, we must
+        // re-learn it quickly so the re-punch offers the *new* endpoint. A
+        // long cache would keep us advertising a dead port for its full
+        // lifetime, stalling recovery. Gather is only called during
+        // (re)establishment/re-punch, so a short cache costs little.
+        const CACHE_MS = 5_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.
+     */
+    /**
+     * Lazily allocate our node-level TURN relay on its own dedicated UDP
+     * socket. Returns our public relay address (on the TURN server) which we
+     * advertise to peers so they can reach us via the relay even when direct
+     * UDP can't be punched. Relayed data is injected into #onDatagram tagged
+     * `viaRelay` so it updates the relay freshness, not the direct endpoint.
+     */
+    async #ensureTurnRelay() {
+        if (this.#ourRelayAddr)
+            return this.#ourRelayAddr;
+        if (this.#turnAllocating)
+            return this.#turnAllocating;
+        this.#turnAllocating = (async () => {
+            for (const srv of TURN_RELAY_SERVERS) {
+                try {
+                    const sock = createDgramSocket("udp4");
+                    await new Promise((resolve, reject) => {
+                        sock.once("error", reject);
+                        sock.bind(0, () => {
+                            sock.off("error", reject);
+                            resolve();
+                        });
+                    });
+                    const client = new TurnClient({
+                        sock,
+                        creds: { host: srv.host, port: srv.port, realm: "", username: srv.username, password: srv.password }
+                    });
+                    const alloc = await client.allocate();
+                    client.onData((peer, data) => {
+                        // Re-inject relayed payload as if it arrived directly from the
+                        // peer's relay address. viaRelay keeps it off the direct path.
+                        this.#onDatagram({
+                            data: Buffer.from(data),
+                            remote: { address: peer.address, port: peer.port },
+                            viaRelay: true
+                        });
+                    });
+                    this.#turnSocket = sock;
+                    this.#turnClient = client;
+                    this.#ourRelayAddr = { host: alloc.relayedAddress.address, port: alloc.relayedAddress.port };
+                    this.#debugLog(`turn relay allocated on ${srv.host}: ${this.#ourRelayAddr.host}:${this.#ourRelayAddr.port}`);
+                    return this.#ourRelayAddr;
+                }
+                catch (error) {
+                    this.#debugLog(`turn relay allocate failed on ${srv.host}: ${error.message}`);
+                }
+            }
+            return undefined;
+        })();
+        const result = await this.#turnAllocating;
+        this.#turnAllocating = undefined;
+        return result;
+    }
+    /** Wrap + send a packet to a peer's TURN relay address via our own
+     *  allocation. Mirrors #sendPacket's carrier-magic framing so the peer's
+     *  #onDatagram processes it identically to a direct datagram. */
+    #sendViaRelay(packet, relay) {
+        if (!this.#turnClient)
+            return false;
+        const wrapped = concatBytes([Uint8Array.of(0x69, 0x76, 0x65, 0x67), packet]);
+        try {
+            this.#turnClient.sendTo({ family: 4, address: relay.host, port: relay.port }, wrapped);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    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;
+        // Also advertise our TURN relay address (bytes 6-11) as a second
+        // candidate. Best-effort: if the relay can't be allocated we just send
+        // the 6-byte srflx-only offer (older peers ignore the extra bytes).
+        const relay = await this.#ensureTurnRelay().catch(() => undefined);
+        const relayOctets = relay ? relay.host.split(".").map((s) => parseInt(s, 10)) : undefined;
+        const relayValid = relayOctets && relayOctets.length === 4 && !relayOctets.some((o) => Number.isNaN(o));
+        const payload = new Uint8Array(relayValid ? 12 : 6);
+        payload.set(octets, 0);
+        payload[4] = (srflx.port >> 8) & 0xff;
+        payload[5] = srflx.port & 0xff;
+        if (relayValid && relay) {
+            payload.set(relayOctets, 6);
+            payload[10] = (relay.port >> 8) & 0xff;
+            payload[11] = relay.port & 0xff;
+        }
+        try {
+            await this.#sendMessengerPacket(friendId, PACKET_ID_UDP_ENDPOINT, payload);
+            this.#debugLog(`udp-endpoint offer sent to ${friendId}: direct=${srflx.host}:${srflx.port}` +
+                (relayValid && relay ? ` relay=${relay.host}:${relay.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;
+        // If the offer carries a TURN relay candidate (bytes 6-11), remember it
+        // and permit it on our own allocation so data can flow peer→relay→us.
+        if (payload.length >= 12) {
+            const relayHost = `${payload[6]}.${payload[7]}.${payload[8]}.${payload[9]}`;
+            const relayPort = ((payload[10] << 8) | payload[11]) >>> 0;
+            if (relayPort !== 0) {
+                const changed = session.relayRemote?.host !== relayHost || session.relayRemote?.port !== relayPort;
+                session.relayRemote = { host: relayHost, port: relayPort };
+                if (changed)
+                    session.relayPermitted = false;
+                // (Re)create the permission on first sight, on address change, or
+                // when the existing one is aging toward coturn's ~5min expiry.
+                const permitAgeMs = Date.now() - (session.relayPermittedAtMs ?? 0);
+                if (!session.relayPermitted || permitAgeMs > 90_000) {
+                    void this.#ensureTurnRelay()
+                        .then(() => this.#turnClient?.createPermission({ family: 4, address: relayHost, port: relayPort }))
+                        .then(() => {
+                        const first = !session.relayPermitted;
+                        session.relayPermitted = true;
+                        session.relayPermittedAtMs = Date.now();
+                        if (first)
+                            this.#debugLog(`turn permission created for ${friendId} relay ${relayHost}:${relayPort}`);
+                    })
+                        .catch(() => undefined);
+                }
+            }
+        }
+        // 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).