@decentnetwork/peer 0.1.18 → 0.1.19

package/dist/peer.js

@@ -17,6 +17,15 @@ 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
@@ -128,6 +137,16 @@ export class Peer {
     #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;
@@ -398,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() {
@@ -893,7 +923,7 @@ export class Peer {
     #remoteIsTcp(remote) {
         return remote.address.startsWith("tcp:");
     }
-    #onDatagram = ({ data, remote }) => {
+    #onDatagram = ({ data, remote, viaRelay }) => {
         if (!this.#keyPair) {
             return;
         }
@@ -1191,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();
@@ -1329,6 +1372,15 @@ 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) {
@@ -2122,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) {
@@ -2163,14 +2238,33 @@ export class Peer {
                 // 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;
+                // >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
@@ -2280,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) {
@@ -2391,7 +2493,22 @@ export class Peer {
         let tcpOk = false;
         let firstError;
         const realUdpRemote = s?.remote && !s.remote.host?.startsWith("tcp:") && s.remote.port !== 0;
-        if (s?.remote) {
+        // "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;
@@ -2400,28 +2517,24 @@ 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) {
+        // 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;
         }
-        // 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;
+        // 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
@@ -2443,7 +2556,7 @@ export class Peer {
                 }
             }
         }
-        if (!udpOk && !tcpOk) {
+        if (!udpOk && !relayOk && !tcpOk) {
             throw firstError ?? new Error(`no transport accepted send for ${friendId}`);
         }
     }
@@ -2570,7 +2683,12 @@ export class Peer {
      * Returns undefined if no bootnode answers within the timeout.
      */
     async #gatherOwnSrflx() {
-        const CACHE_MS = 60_000;
+        // 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;
@@ -2623,6 +2741,74 @@ export class Peer {
      * 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)
@@ -2633,13 +2819,25 @@ export class Peer {
         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);
+        // 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}: ${srflx.host}:${srflx.port}`);
+            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
@@ -2663,6 +2861,33 @@ export class Peer {
         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;

package/package.json

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