@decentnetwork/peer 0.1.79 → 0.1.81

package/dist/compat/express.js

@@ -28,6 +28,7 @@ export class LegacyExpressClient {
             return {
                 host: node.host,
                 port: node.port,
+                tls: node.tls !== false, // default HTTPS; opt into HTTP with tls:false
                 sharedKey: nacl.box.before(expressPk, this.#selfKeyPair.secretKey)
             };
         });
@@ -152,7 +153,8 @@ export class LegacyExpressClient {
         throw lastError instanceof Error ? lastError : new Error(String(lastError));
     }
     async #http(node, method, path, body) {
-        const url = `https://${node.host}:${node.port}/${path}`;
+        const scheme = node.tls ? "https" : "http";
+        const url = `${scheme}://${node.host}:${node.port}/${path}`;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
         try {

package/dist/compat/net-crypto.d.ts

@@ -80,5 +80,9 @@ export declare function openCryptoDataPacket(packet: Uint8Array, opts: {
     bufferStart: number;
     packetNumber: number;
     nonceLast2: number;
+    /** The exact nonce this packet decrypted with. The caller must track
+     *  recvBaseNonce = usedNonce (+1 for the next expected) — NOT overwrite
+     *  just the low two bytes, which loses the carry into byte 21. */
+    usedNonce: Uint8Array;
 } | undefined;
 export declare function incrementNonce(nonce: Uint8Array): void;

package/dist/compat/net-crypto.js

@@ -191,9 +191,27 @@ export function openCryptoDataPacket(packet, opts) {
     if (packet.length <= CRYPTO_DATA_PACKET_MIN_SIZE || packet[0] !== NET_PACKET_CRYPTO_DATA) {
         return undefined;
     }
+    // The wire carries only the low 16 bits of the sender's nonce counter.
+    // Reconstruct the full nonce like toxcore handle_data_packet: advance a
+    // COPY of our tracked nonce by the uint16 difference WITH CARRY into the
+    // upper bytes. The old code overwrote the two low bytes in place, which
+    // silently dropped the carry whenever packet loss spanned a 64k nonce
+    // wrap — from then on EVERY packet failed to decrypt until re-handshake
+    // (observed as endless "no session matched" from high-rate peers, whose
+    // counters wrap every ~30-60s of CCTV/file traffic).
     const nonce = opts.recvBaseNonce.slice();
-    nonce[nonce.length - 2] = packet[1];
-    nonce[nonce.length - 1] = packet[2];
+    const trackedLow = ((nonce[nonce.length - 2] << 8) | nonce[nonce.length - 1]) >>> 0;
+    const wireLow = ((packet[1] << 8) | packet[2]) >>> 0;
+    const diff = (wireLow - trackedLow) & 0xffff;
+    if (diff < 0x8000) {
+        addToNonceCounter(nonce, diff);
+    }
+    else {
+        // The wire counter is BEHIND our tracked one — a reordered/duplicate
+        // packet from earlier in the stream (dual-path UDP+relay delivery
+        // reorders constantly). Step backward with borrow.
+        subFromNonceCounter(nonce, 0x10000 - diff);
+    }
     const cipher = packet.slice(3);
     const plain = nacl.secretbox.open(cipher, nonce, opts.sessionSharedKey);
     if (!plain || plain.length <= CRYPTO_DATA_PLAIN_HEADER_LENGTH) {
@@ -212,9 +230,29 @@ export function openCryptoDataPacket(packet, opts) {
         payload: plain.slice(payloadOffset),
         bufferStart,
         packetNumber,
-        nonceLast2: ((packet[1] << 8) | packet[2]) >>> 0
+        nonceLast2: ((packet[1] << 8) | packet[2]) >>> 0,
+        usedNonce: nonce
     };
 }
+/** Add `count` to the big-endian nonce counter with carry (toxcore
+ *  increment_nonce_number). */
+function addToNonceCounter(nonce, count) {
+    let carry = count >>> 0;
+    for (let i = nonce.length - 1; i >= 0 && carry > 0; i--) {
+        const sum = nonce[i] + (carry & 0xff);
+        nonce[i] = sum & 0xff;
+        carry = (carry >>> 8) + (sum > 0xff ? 1 : 0);
+    }
+}
+/** Subtract `count` from the big-endian nonce counter with borrow. */
+function subFromNonceCounter(nonce, count) {
+    let borrow = count >>> 0;
+    for (let i = nonce.length - 1; i >= 0 && borrow > 0; i--) {
+        const sub = nonce[i] - (borrow & 0xff);
+        nonce[i] = sub & 0xff;
+        borrow = (borrow >>> 8) + (sub < 0 ? 1 : 0);
+    }
+}
 function createCookie(opts) {
     const timestamp = BigInt(Math.floor(Date.now() / 1000));
     const contents = concatBytes([

package/dist/compat/tcp-relay-pool.js

@@ -23,7 +23,17 @@ import { EventEmitter } from "node:events";
 import { base58ToBytes } from "../utils/base58.js";
 import { TcpRelayClient } from "./tcp-relay.js";
 const KEY_SIZE = 32;
-const MAX_RELAY_CONNECTIONS = 3;
+// Connect to (up to) this many bootstrap nodes as persistent TCP relays. It was
+// 3 — but the pool picks the FIRST N in order, so a peer only met friends whose
+// relays happened to be in its own top-3. A NATIVE peer (iOS/Android) reaches us
+// ONLY over a relay we both sit on (OOB cookie handshake); if our top-3 doesn't
+// include the relay it uses, it's stuck "connecting" forever — even though we
+// share the node further down the list (observed: iOS uses sh.callt.net =
+// 47.100.103.201 as its #1 relay, which sat at #7 in our bootstrap so we never
+// connected to it). Covering more of the shared bootstrap set makes the same-
+// relay rendezvous reliable for native peers. Cheap: a handful of extra idle TCP
+// keepalives.
+const MAX_RELAY_CONNECTIONS = 8;
 const RECONNECT_BASE_MS = 5_000;
 const RECONNECT_MAX_MS = 120_000;
 export class TcpRelayPool extends EventEmitter {

package/dist/peer.js

@@ -1,7 +1,7 @@
 import { EventEmitter } from "node:events";
 import { mkdir, readFile, writeFile, rename } from "node:fs/promises";
 import { networkInterfaces } from "node:os";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import nacl from "tweetnacl";
 import { carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
 import { LegacyBootstrapClient } from "./compat/bootstrap.js";
@@ -255,6 +255,22 @@ export class Peer {
     // unconnected friend (the "accepted friend that never connects" wedge —
     // requestRoute only fired once at startup and was never retried).
     #routeRequestCooldown = new Map();
+    // The onion route that carried the last successful announce exchange with
+    // each announce node ("host:port" -> path | "direct"). A node's ping_id is
+    // bound to the SOURCE ip:port it saw the request arrive from (the path's
+    // exit hop, or us when direct). Step2 of a self-announce must therefore
+    // travel the exact route step1 used — re-selecting a path (scores mutate
+    // between calls) or falling back direct changes the source, the node
+    // rejects the ping_id, and the announce NEVER stores (observed: zero
+    // isStored=2 across an entire run — nobody could find us to learn our
+    // announce data key).
+    #announceRouteUsed = new Map();
+    // Last-known DHT pubkey per friend (identity id -> dht pk). Sessions get
+    // deleted on timeout, but relay ROUTING_REQUESTs must keep using the key
+    // the friend handshakes relays with — for native peers that's the DHT key,
+    // not the identity key. Without this survives-teardown copy, every re-link
+    // attempt after a session teardown silently used the wrong key.
+    #friendDhtKeys = new Map();
     // Per-friend cooldown for RE-SENDING the friend-request to a friend that's
     // never been accepted (still "requested"). On reconnect / restart we must
     // re-offer — the original request can be lost while the friend was offline.
@@ -290,6 +306,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();
+    // When we FIRST deferred initiation to a higher-pubkey peer (per friend).
+    // If the peer hasn't established within the grace window we break the
+    // defer and initiate ourselves (see #initiateSession). Cleared whenever a
+    // session establishes so each outage gets a fresh window.
+    #initiateDeferSinceMs = new Map();
     // Per-friend last time we deleted a desynced session (rate-limit; survives the
     // session deletion, unlike a field on the session object itself).
     #lastDesyncDeleteMs = new Map();
@@ -336,11 +357,19 @@ export class Peer {
             keyPair: this.#keyPair,
             transport: this.#udp
         });
-        const announceGenerated = createEphemeralKeyPair();
-        this.#announceDataKey = {
-            publicKey: announceGenerated.publicKey,
-            secretKey: announceGenerated.secretKey
-        };
+        // The announce data key MUST survive restarts. Native toxcore peers cache
+        // our last-known data pk and keep encrypting onion data (DHT-PK announces,
+        // friend requests) to it until they re-discover our announce on the DHT —
+        // which can take a long time when our self-announce store rate is weak.
+        // With an ephemeral per-run key, every restart silently invalidated every
+        // friend's cached key: 100% of inbound onion data failed to decrypt
+        // ("onion data response decrypt failed"), so we never learned a native
+        // friend's UDP endpoint or current relay list, and a dropped relay route
+        // could never self-heal (the iOS online-flap bug).
+        {
+            const announceKeyPath = join(dirname(this.#opts.keyFile), "announce-data-key.json");
+            this.#announceDataKey = await loadOrCreateKeyPair(announceKeyPath);
+        }
         this.#cookieSymmetricKey = randomBytes(32);
         await this.#loadPersistedFriends();
         if (this.#opts.expressNodes && this.#opts.expressNodes.length > 0) {
@@ -390,15 +419,23 @@ export class Peer {
                 this.#handleTcpDatagram(friendKey, payload);
             });
             this.#tcpRelays.on("friendOnline", (friendKey) => {
-                const friendId = carrierIdFromPublicKey(friendKey);
-                this.#debugLog(`tcp_relay friend_online ${friendId}`);
+                // The pool reports the key the peer handshook the relay with — for
+                // native peers that's the DHT key. Map it to the real friend id so
+                // route state + session kick land on the REAL session, not a ghost.
+                const friendId = this.#friendIdForPoolKey(friendKey);
+                this.#debugLog(`tcp_relay friend_online ${carrierIdFromPublicKey(friendKey)} (friend=${friendId})`);
                 // Mark the (existing or new) session as having a TCP route so
                 // outbound goes through the relay even if no UDP endpoint is
                 // known. Then kick #initiateSession — this issues a cookie
                 // request that will travel via TCP if no UDP path exists.
                 const session = this.#friendSessions.get(friendId) ?? this.#newSessionShell();
                 session.hasTcpRoute = true;
-                session.friendRealPublicKey ??= new Uint8Array(friendKey);
+                if (friendId === carrierIdFromPublicKey(friendKey)) {
+                    session.friendRealPublicKey ??= new Uint8Array(friendKey);
+                }
+                else {
+                    session.friendDhtPublicKey ??= new Uint8Array(friendKey);
+                }
                 this.#friendSessions.set(friendId, session);
                 if (!session.established) {
                     // A fresh relay-online signal means the peer just (re)connected —
@@ -413,12 +450,18 @@ export class Peer {
                 }
             });
             this.#tcpRelays.on("friendOffline", (friendKey) => {
-                const friendId = carrierIdFromPublicKey(friendKey);
+                const friendId = this.#friendIdForPoolKey(friendKey);
                 const session = this.#friendSessions.get(friendId);
                 if (session) {
                     session.hasTcpRoute = false;
                 }
-                this.#debugLog(`tcp_relay friend_offline ${friendId}`);
+                this.#debugLog(`tcp_relay friend_offline ${carrierIdFromPublicKey(friendKey)} (friend=${friendId})`);
+                // Re-assert the route right away (idempotent). A native peer that
+                // blips off a relay (network switch, app background, relay rotation)
+                // reconnects seconds later — with our ROUTING_REQUEST already parked,
+                // the relay re-links the moment it returns and fires friendOnline,
+                // instead of the session sitting pathless until the periodic sweep.
+                this.#tcpRelays?.requestRoute(friendKey);
             });
             this.#tcpRelays.on("status", (connected, total) => {
                 this.#debugLog(`tcp_pool ${connected}/${total} relays connected`);
@@ -465,14 +508,25 @@ export class Peer {
                 this.#debugLog(`tcp pool initial start failed: ${error.message}`);
             });
             // Pre-route every persisted friend so the pool watches for them
-            // the moment a relay is up.
-            for (const friend of this.#friends.values()) {
+            // the moment a relay is up — under BOTH keys: identity (JS peers)
+            // and the persisted DHT key (native peers handshake relays with it).
+            for (const [friendId, friend] of this.#friends.entries()) {
                 try {
                     const pk = base58ToBytes(friend.pubkey);
                     if (pk.length === 32)
                         this.#tcpRelays.requestRoute(pk);
                 }
                 catch { /* skip malformed */ }
+                if (friend.dhtPubkey && friend.dhtPubkey !== friend.pubkey) {
+                    try {
+                        const dhtPk = base58ToBytes(friend.dhtPubkey);
+                        if (dhtPk.length === 32) {
+                            this.#friendDhtKeys.set(friendId, dhtPk);
+                            this.#tcpRelays.requestRoute(dhtPk);
+                        }
+                    }
+                    catch { /* skip malformed */ }
+                }
             }
         }
         this.#started = true;
@@ -905,10 +959,25 @@ export class Peer {
         // (UDP via session.remote, or TCP relay via session.hasTcpRoute).
         // #sendMessengerPacket internally fans out to both transports and
         // returns true if at least one accepted; throws only if zero did.
+        //
+        // CRUCIAL: also require the session to be PROVEN — we've decrypted a real
+        // packet from the peer within FRIEND_TIMEOUT_MS. `established` alone can be a
+        // half-open / key-desynced session (common JS<->native case): our transport
+        // ACCEPTS the encrypted packet (so #sendMessengerPacket returns success, no
+        // throw) but the peer can't decrypt it, so the message is silently swallowed
+        // — and because the direct send "succeeded", the express fallback below never
+        // runs. Observed: an offline message to a desynced iOS peer showed "sent"
+        // yet never reached the peer OR the express relay (0 rows). Gating on recent
+        // inbound routes such sends to express store-and-forward instead of losing
+        // them. A genuinely-healthy session proves itself within a ping RTT (~4-8s),
+        // so at most the first message of a cold conversation takes the express path.
+        const provenInbound = session?.lastPingRecvMs !== undefined &&
+            Date.now() - session.lastPingRecvMs < FRIEND_TIMEOUT_MS;
         const liveSession = session?.established
             && session.sessionSharedKey
             && session.ourBaseNonce
-            && (session.remote || session.hasTcpRoute);
+            && (session.remote || session.hasTcpRoute)
+            && provenInbound;
         if (liveSession) {
             try {
                 await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, packet);
@@ -1136,21 +1205,61 @@ export class Peer {
      * starts with `tcp:` so downstream code can recognize the origin
      * and avoid setting `session.remote` to a UDP-shaped value.
      */
+    /** Record a friend's DHT pubkey: in-memory (survives session teardown) and
+     *  persisted on the friend record (survives restarts, so start() can park
+     *  relay routes under the right key before the friend announces again). */
+    #learnFriendDhtKey(friendId, dhtPublicKey) {
+        if (dhtPublicKey.length !== 32)
+            return;
+        this.#friendDhtKeys.set(friendId, new Uint8Array(dhtPublicKey));
+        const friend = this.#friends.get(friendId);
+        if (friend) {
+            const b58 = carrierIdFromPublicKey(dhtPublicKey);
+            if (friend.dhtPubkey !== b58) {
+                this.#friends.set(friendId, { ...friend, dhtPubkey: b58 });
+                this.#persistFriends();
+            }
+        }
+    }
+    /** Resolve a TCP-relay-pool key (the key the peer handshook the relay
+     *  with) to OUR friend id. For JS peers the two coincide; native peers
+     *  (iOS/Android) sit on relays under their DHT key — without this
+     *  mapping, every pool event (friendOnline/friendOffline/inbound data
+     *  bookkeeping) landed on a GHOST session keyed by the DHT key while the
+     *  real session (keyed by identity) never saw route state change. */
+    #friendIdForPoolKey(poolKey) {
+        const asId = carrierIdFromPublicKey(poolKey);
+        if (this.#friends.has(asId))
+            return asId;
+        for (const [friendId, dhtPk] of this.#friendDhtKeys) {
+            if (bytesEqual(dhtPk, poolKey))
+                return friendId;
+        }
+        return asId;
+    }
     #handleTcpDatagram(friendKey, payload) {
-        const friendId = carrierIdFromPublicKey(friendKey);
-        // Mark the session as TCP-routed if we don't have it yet.
+        const poolId = carrierIdFromPublicKey(friendKey);
+        // Route-state bookkeeping belongs on the REAL friend's session (mapped
+        // via the DHT key for native peers), not a ghost keyed by the pool key.
+        const friendId = this.#friendIdForPoolKey(friendKey);
         let session = this.#friendSessions.get(friendId);
         if (!session) {
             session = this.#newSessionShell();
-            session.friendRealPublicKey = new Uint8Array(friendKey);
             this.#friendSessions.set(friendId, session);
         }
         session.hasTcpRoute = true;
-        session.friendRealPublicKey ??= new Uint8Array(friendKey);
-        // Feed through the regular dispatcher with synthetic remote.
+        if (friendId !== poolId) {
+            session.friendDhtPublicKey ??= new Uint8Array(friendKey);
+        }
+        else {
+            session.friendRealPublicKey ??= new Uint8Array(friendKey);
+        }
+        // Feed through the regular dispatcher with synthetic remote. Keep the
+        // POOL key in the remote tag: the crypto layer matched sessions by this
+        // exact string during the (proven-working) handshake flow.
         this.#onDatagram({
             data: Buffer.from(payload),
-            remote: { address: `tcp:${friendId}`, port: 0 }
+            remote: { address: `tcp:${poolId}`, port: 0 }
         });
     }
     /** True when the synthetic remote was constructed by #handleTcpDatagram. */
@@ -1250,6 +1359,15 @@ export class Peer {
                     this.#debugLog(`cookie response: no tcp relay accepted oob send for ${senderId}`);
                 }
             }
+            else if (this.#isUnroutableSelfSource(remote.address, remote.port)) {
+                // The request arrived sourced from our own TUN address (or our own
+                // socket) — an overlay routing artifact. Replying there loops into
+                // ourselves and dies. Answer over the relay OOB path instead, which
+                // the peer reliably receives. (A self PHYSICAL address with a
+                // different port is a same-host peer and gets the normal UDP reply.)
+                const sent = this.#tcpRelays?.sendOobToFriend(request.senderDhtPublicKey, response) ?? 0;
+                this.#debugLog(`cookie response: source ${remote.address}:${remote.port} is an unroutable self-source — replied via tcp_oob instead (relays=${sent})`);
+            }
             else {
                 void this.#sendPacket(response, { host: remote.address, port: remote.port })
                     .then(() => {
@@ -1431,6 +1549,9 @@ export class Peer {
                 if (!state.friendDhtPublicKey)
                     state.friendDhtPublicKey = hs.senderDhtPublicKey;
             }
+            if (hs.senderDhtPublicKey && hs.senderDhtPublicKey.length === 32) {
+                this.#learnFriendDhtKey(friendId, hs.senderDhtPublicKey);
+            }
             const wasEstablished = state.established === true;
             // Detect a real session reset: the peer is offering NEW session
             // keys (different ephemeral session pubkey from before). When
@@ -1479,14 +1600,25 @@ export class Peer {
                 // 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) {
-                    // Reject a new-key handshake while our session is alive — toxcore does
-                    // the same. (The "half-open breaker" that accepted these after N tries
-                    // was reverted: accepting a new key ROTATES the session, which churned
-                    // healthy sessions; the real fix was the TURN-crash fix, not this.)
+                // The peer has RE-KEYED if it's sending us crypto data we can't decrypt
+                // more recently than the last packet we could — our "alive" signal above
+                // is stale (it counts packets from just before the peer flapped). This is
+                // the flapping iOS/native case: iOS drops, re-handshakes with a fresh
+                // session key, then sends online messages we can't decrypt because we're
+                // still holding the dead keys and rejecting its fix-up handshake for the
+                // whole 32s timeout. Accept the fresh handshake NOW to resync. Safe: a
+                // healthy session never produces undecryptable data, so peerReKeyed stays
+                // false for it — this can't churn a live session (the reverted "half-open
+                // breaker" churned because it accepted new keys with NO such evidence).
+                const peerReKeyed = state.undecryptableRecvMs !== undefined &&
+                    state.undecryptableRecvMs > (state.lastPingRecvMs ?? 0);
+                if (sinceEstablished > 1000 && currentSessionAlive && !peerReKeyed) {
                     this.#debugVerboseLog(`hs_recv ignored friend=${friendId} (new session pubkey on live established session, ${sinceEstablished}ms after establish)`);
                     return;
                 }
+                if (peerReKeyed) {
+                    this.#debugLog(`hs_recv accepting re-handshake friend=${friendId} (peer re-keyed: undecryptable data since last good packet)`);
+                }
                 this.#debugLog(`hs_recv accepting re-handshake friend=${friendId} (current session wedged/dead, ` +
                     `lastPingRecv=${state.lastPingRecvMs ? Date.now() - state.lastPingRecvMs + "ms ago" : "never"})`);
             }
@@ -1495,6 +1627,10 @@ export class Peer {
             state.sessionSharedKey = nacl.box.before(hs.sessionPublicKey, state.ourSessionKeyPair.secretKey);
             state.established = true;
             state.sessionEstablishedAtMs = Date.now();
+            // Fresh session up — reset the higher-pubkey defer window for the
+            // next outage (see #initiateSession).
+            this.#initiateDeferSinceMs.delete(friendId);
+            this.#initiateSkipLogged.delete(friendId);
             if (this.#remoteIsTcp(remote)) {
                 state.hasTcpRoute = true;
                 // Don't set state.remote — there's no UDP endpoint for this peer.
@@ -1505,6 +1641,11 @@ export class Peer {
             if (isNewSession) {
                 state.sendPacketNumber = 0;
                 state.receiveBufferStart = 0;
+                // Packet numbers restart at 0 — parked retransmit payloads from
+                // the previous session are meaningless (and would resend under
+                // colliding numbers). Drop them.
+                state.sendArray = undefined;
+                state.sendBufferStartNum = undefined;
             }
             else {
                 state.sendPacketNumber ??= 0;
@@ -1670,6 +1811,13 @@ export class Peer {
                     }
                     state.lastRelayRecvMs = Date.now();
                 }
+                else if (this.#isUnroutableSelfSource(remote.address, remote.port)) {
+                    // Sourced from our own TUN address / own socket (overlay routing
+                    // artifact): the payload is real — deliver it — but this is NOT a
+                    // usable bidirectional UDP path. Don't adopt it (replies loop into
+                    // our own interface) and don't mark UDP-confirmed, or the punch
+                    // machinery stops trying to establish a REAL direct path.
+                }
                 else {
                     // Adopt the source as our send endpoint — via #adoptRemote, which
                     // refuses to downgrade off a locked physical-LAN path to a public /
@@ -1688,12 +1836,44 @@ export class Peer {
                 if (!isSingleTransportKind && opened.packetNumber < (state.receiveBufferStart ?? 0)) {
                     continue;
                 }
-                state.peerBaseNonce[state.peerBaseNonce.length - 2] = packet[1];
-                state.peerBaseNonce[state.peerBaseNonce.length - 1] = packet[2];
-                incrementNonce(state.peerBaseNonce);
-                state.receiveBufferStart = Math.max(state.receiveBufferStart ?? 0, (opened.packetNumber + 1) >>> 0);
+                // Track the receive nonce from the EXACT nonce this packet used
+                // (openCryptoDataPacket reconstructs it with full carry/borrow).
+                // The old two-byte overwrite dropped the carry into byte 21 when
+                // loss spanned a 64k counter wrap, permanently desyncing the
+                // session. Only move FORWARD — a late reordered packet must not
+                // drag the tracked nonce backward.
+                {
+                    const trackedLow = ((state.peerBaseNonce[state.peerBaseNonce.length - 2] << 8) | state.peerBaseNonce[state.peerBaseNonce.length - 1]) >>> 0;
+                    const fwd = ((opened.nonceLast2 - trackedLow) & 0xffff) < 0x8000;
+                    if (fwd) {
+                        state.peerBaseNonce = opened.usedNonce.slice();
+                        incrementNonce(state.peerBaseNonce);
+                    }
+                }
                 const kind = opened.payload[0];
                 const inner = opened.payload.slice(1);
+                // Advance our ack point ONLY for kinds that actually consume a
+                // reliable packet number on the sender. Toxcore sends REQUEST(1)
+                // and lossy (>=192) packets with num = send_array.buffer_end — the
+                // NEXT UNUSED number, not stored in its send array. Counting those
+                // advanced our receiveBufferStart to buffer_end+1, i.e. we then
+                // acked one more packet than the peer ever sent — and toxcore's
+                // handle_data_packet_core REJECTS any packet whose buffer_start is
+                // out of its send window (clear_buffer_until -> return -1). Result:
+                // from the peer's FIRST retransmit request onward, every packet we
+                // sent was discarded whole (fresh and retransmitted alike) and the
+                // peer went deaf until it re-keyed — the final piece of the iOS
+                // session churn. The JS droppable bulk channel (bulkDataPacketId)
+                // reuses the current number without consuming it, so it must not
+                // advance the ack point either (also fixes reliable packets being
+                // dropped as duplicates after a droppable burst under the same
+                // number).
+                const consumesReliableNumber = kind !== PACKET_ID_REQUEST &&
+                    !(kind !== undefined && kind >= 192) &&
+                    kind !== this.#opts.bulkDataPacketId;
+                if (consumesReliableNumber) {
+                    state.receiveBufferStart = Math.max(state.receiveBufferStart ?? 0, (opened.packetNumber + 1) >>> 0);
+                }
                 // Toxcore file transfer (FILE_SENDREQUEST/CONTROL/DATA = 80/81/82).
                 if (this.#fileTransfer.handlePacket(friendId, kind, inner))
                     return;
@@ -1729,9 +1909,13 @@ export class Peer {
                     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.
-                    this.#debugVerboseLog(`crypto request packet received from ${friendId} (no retransmit queue)`);
+                    // Lossless retransmission request (toxcore handle_request_packet).
+                    // Bytes are 1-based deltas walking our send window from
+                    // sendBufferStartNum: a matching delta marks that packet number
+                    // REQUESTED (peer is missing it — resend); every walked number
+                    // that doesn't match is implicitly ACKED (peer has it — drop from
+                    // the buffer). 0 is a +255 filler.
+                    this.#handleRetransmitRequest(friendId, state, inner);
                     return;
                 }
                 if (kind === PACKET_ID_SHARE_RELAYS) {
@@ -1820,7 +2004,8 @@ export class Peer {
                     this.#setFriendOnline(friendId, remote.address, remote.port);
                     this.#events.emit("text", {
                         pubkey: friendId,
-                        text
+                        text,
+                        via: "online"
                     });
                     this.#debugLog(`crypto ${kind === PACKET_ID_ACTION ? "action" : "message"} from ${friendId}: "${text}"`);
                     return;
@@ -1852,6 +2037,25 @@ export class Peer {
             // CRASH (TURN DNS); with that fixed, sessions stay converged on their own.
             // Just drop the undecryptable packet — net_crypto's normal re-handshake
             // path recovers a genuinely dead session.
+            // If this came over the TCP relay (synthetic tcp:<friendId> remote) we KNOW
+            // which friend sent it. Record the decrypt failure so the handshake path can
+            // distinguish a re-keyed peer (desync — accept its fresh handshake now) from
+            // a live one, instead of holding dead keys for the full timeout while every
+            // online message is silently dropped.
+            if (remote.address.startsWith("tcp:")) {
+                // remote carries the POOL key id (native peers: DHT key) — map to
+                // the real friend so the desync marker lands on the real session.
+                let desyncFriendId = remote.address.slice(4);
+                try {
+                    desyncFriendId = this.#friendIdForPoolKey(base58ToBytes(desyncFriendId));
+                }
+                catch { /* keep raw id */ }
+                const ds = this.#friendSessions.get(desyncFriendId);
+                if (ds?.established) {
+                    ds.undecryptableRecvMs = Date.now();
+                    this.#debugVerboseLog(`undecryptable crypto data from ${desyncFriendId} (peer likely re-keyed)`);
+                }
+            }
             this.#debugVerboseLog(`crypto data received from ${remote.address}:${remote.port} but no session matched`);
             return;
         }
@@ -1949,6 +2153,7 @@ export class Peer {
         session.lastDhtPkNoReplay = noReplay;
         session.friendRealPublicKey ??= senderPublicKey;
         session.friendDhtPublicKey = friendDhtPublicKey;
+        this.#learnFriendDhtKey(senderId, friendDhtPublicKey);
         // A DHT-PK announce from this friend IS the proof they've accepted
         // our friend request — only friends actively trying to reach us send
         // these. Mark acceptedAt so subsequent peer.sendFriendRequest calls
@@ -2165,7 +2370,7 @@ export class Peer {
                     // Malformed pubkey, fall through.
                 }
             }
-            this.#events.emit("text", { pubkey: fromUserId, text });
+            this.#events.emit("text", { pubkey: fromUserId, text, via: "offline" });
         }
         catch {
             // Ignore invalid offline payloads.
@@ -2459,7 +2664,10 @@ export class Peer {
                 dataPublicKey: this.#announceDataKey.publicKey,
                 sendBack: c.sendBack,
                 allowDirectFallback: true,
-                attempts: SELF_ANNOUNCE_ATTEMPTS
+                attempts: SELF_ANNOUNCE_ATTEMPTS,
+                // ping_id is source-bound: step2 must exit from the same hop
+                // step1 did or the node rejects it and nothing ever stores.
+                reuseRoute: true
             })));
             for (let j = 0; j < step1Hits.length; j++) {
                 const { c, resp1 } = step1Hits[j];
@@ -2474,6 +2682,7 @@ export class Peer {
                     catch { /* best-effort */ }
                 if (final.isStored === 2) {
                     storedNodes.push(c.node);
+                    this.#debugLog(`self announce STORED on ${c.node.host}:${c.node.port} (total ${storedNodes.length})`);
                     // Keep dhtHealth.selfAnnounceStoredOn live within the loop,
                     // not just at the end, so we see growth in real time.
                     this.#lastSelfAnnounceStoredCount = storedNodes.length;
@@ -2564,8 +2773,17 @@ export class Peer {
                 // sessions a long grace so a blackout doesn't churn them via re-handshake;
                 // unproven sessions still time out fast to self-heal a wedged handshake.
                 const proven = session.lastPingRecvMs !== undefined;
-                const deadline = proven ? PROVEN_SESSION_HARD_TIMEOUT_MS : FRIEND_TIMEOUT_MS;
-                if (proven && silentFor > FRIEND_TIMEOUT_MS && silentFor <= deadline) {
+                // A relay-only session (synthetic tcp: remote, no UDP path) whose
+                // relay route is gone has NO transport at all — nothing can arrive
+                // and nothing we send leaves. The proven-session blackout grace
+                // exists for UDP paths that black out (GFW) while both ends keep
+                // keys; it must NOT keep a transportless relay session as a 180s
+                // zombie (iOS flap: peer sees us vanish while we still show them
+                // online and drop every send). Fast-track those to teardown.
+                const relayOnly = !session.remote || session.remote.host.startsWith("tcp:");
+                const pathless = relayOnly && !session.hasTcpRoute;
+                const deadline = proven && !pathless ? PROVEN_SESSION_HARD_TIMEOUT_MS : FRIEND_TIMEOUT_MS;
+                if (proven && !pathless && silentFor > FRIEND_TIMEOUT_MS && silentFor <= deadline) {
                     // Blackout grace: keep the proven session and keep probing (the
                     // keepalive + UDP re-punch + relay-keepalive below all still run). Do
                     // NOT delete or re-handshake — that's what desyncs and churns. The peer,
@@ -2587,6 +2805,11 @@ export class Peer {
                         const pk = base58ToBytes(friend.pubkey);
                         if (pk.length === 32)
                             this.#tcpRelays?.requestRoute(pk);
+                        // Native peers sit on relays under their DHT key — re-request
+                        // that too or the relay never re-links after this teardown.
+                        const dhtPk = this.#friendDhtKeys.get(friendId);
+                        if (dhtPk && dhtPk.length === 32)
+                            this.#tcpRelays?.requestRoute(dhtPk);
                     }
                     catch { /* skip malformed */ }
                     continue;
@@ -2774,30 +2997,46 @@ export class Peer {
             // 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) {
-                // No UDP endpoint AND no relay route yet. For a peer whose DHT
-                // self-announce never stored (WSL2, symmetric NAT, restrictive
-                // firewall), neither onion discovery nor UDP punch can ever find
-                // them — the ONLY bootstrap is the TCP relay: ask our relays to
-                // route to the friend's pubkey, and when they're also connected to
-                // a shared relay the pool fires `friendOnline` -> #initiateSession.
-                // requestRoute was only issued once at start(); if the friend or a
-                // relay wasn't connected in that instant it was never retried, so an
-                // accepted friend could sit at "requested" forever (the WSL-client-
-                // never-gets-an-IP bug). Re-assert it here on a cooldown — cheap and
-                // idempotent — so it eventually catches once both ends share a relay.
+            // Route parking runs for EVERY non-established friend — deliberately
+            // NOT gated on haveEndpoint. A stale persisted remoteHost (e.g. a
+            // bootstrap ip:port cached by an old bug) counts as an "endpoint" and
+            // used to suppress this block entirely, so the friend was never
+            // watched on any relay and could only ever be reached by spamming
+            // cookies at the dead address (the iOS-simulator-forever-offline bug).
+            // For a peer whose DHT self-announce never stored (WSL2, symmetric
+            // NAT, restrictive firewall), the TCP relay is the ONLY bootstrap:
+            // ask our relays to route to the friend's keys; when both ends share
+            // a relay the pool fires `friendOnline` -> #initiateSession.
+            // Re-asserted on a cooldown — cheap and idempotent.
+            {
                 const lastRouteReq = this.#routeRequestCooldown.get(friendId) ?? 0;
                 if (this.#tcpRelays && now - lastRouteReq > 15_000) {
                     try {
                         const pk = base58ToBytes(friend.pubkey);
+                        // The relay routes CRYPTO_DATA by the key the peer CONNECTED to the
+                        // relay with. For a NATIVE peer (iOS/Android) that's its DHT key,
+                        // NOT its identity key — and the send path already routes by
+                        // friendDhtPublicKey. Requesting the route ONLY under the identity
+                        // key (as before) meant the relay never linked us to the peer: its
+                        // handshake arrives OOB (which needs no route), but every continuous
+                        // CRYPTO_DATA packet (chat + keepalives) was silently dropped, so the
+                        // session came up then went dead in 32s. Request the DHT key too so
+                        // the routed path actually establishes; keep the identity key for
+                        // toxcore peers where the two match.
+                        const dhtPk = this.#friendSessions.get(friendId)?.friendDhtPublicKey ?? this.#friendDhtKeys.get(friendId);
+                        if (dhtPk && dhtPk.length === 32) {
+                            this.#tcpRelays.requestRoute(dhtPk);
+                        }
                         if (pk.length === 32) {
                             this.#tcpRelays.requestRoute(pk);
                             this.#routeRequestCooldown.set(friendId, now);
-                            this.#debugLog(`re-requesting relay route for unconnected friend ${friendId}`);
+                            this.#debugVerboseLog(`re-requesting relay route for unconnected friend ${friendId}${dhtPk ? " (+dht key)" : ""}`);
                         }
                     }
                     catch { /* skip malformed pubkey */ }
                 }
+            }
+            if (!haveEndpoint) {
                 // Re-SEND the friend-request to a friend we've never had accepted
                 // (still "requested"). The original can be lost — the friend was
                 // offline/restarting, a relay blipped, or onion had no return path.
@@ -2874,6 +3113,77 @@ export class Peer {
             });
         }
     }
+    /** Toxcore handle_request_packet: parse the peer's PACKET_ID_REQUEST and
+     *  (a) implicitly ACK every walked packet number that isn't requested,
+     *  (b) retransmit the requested ones from the send buffer. */
+    #handleRetransmitRequest(friendId, session, data) {
+        const start = session.sendBufferStartNum;
+        const end = session.sendPacketNumber;
+        if (start === undefined || end === undefined || !session.sendArray || session.sendArray.size === 0) {
+            return;
+        }
+        let cursor = 0;
+        let n = 1;
+        const requested = [];
+        for (let i = start; i !== end; i = (i + 1) >>> 0) {
+            if (cursor >= data.length)
+                break;
+            if (n === data[cursor]) {
+                requested.push(i);
+                cursor++;
+                n = 0;
+            }
+            else {
+                // Peer has this one — implicit ack, free it.
+                session.sendArray.delete(i);
+            }
+            if (n === 255) {
+                n = 1;
+                if (data[cursor] !== 0)
+                    return; // malformed filler
+                cursor++;
+            }
+            else {
+                n++;
+            }
+        }
+        // Advance the window past the acked prefix.
+        let s = start;
+        while (s !== end && !session.sendArray.has(s))
+            s = (s + 1) >>> 0;
+        session.sendBufferStartNum = s;
+        if (requested.length === 0)
+            return;
+        this.#debugLog(`retransmit request from ${friendId}: resending ${requested.length} packet(s) [${requested.slice(0, 8).join(",")}${requested.length > 8 ? ",…" : ""}]`);
+        void (async () => {
+            for (const num of requested) {
+                const payload = session.sendArray?.get(num);
+                if (!payload)
+                    continue;
+                try {
+                    await this.#resendReliablePacket(friendId, session, num, payload);
+                }
+                catch { /* transport hiccup — peer will re-request */ }
+            }
+        })();
+    }
+    /** Re-send a parked reliable packet with its ORIGINAL packet number but
+     *  the CURRENT nonce counter (toxcore retransmissions do the same — the
+     *  receiver reconstructs the nonce from the wire bytes, while the packet
+     *  number slots it into the gap in their receive window). */
+    async #resendReliablePacket(friendId, session, packetNumber, payload) {
+        if (!session.established || !session.sessionSharedKey || !session.ourBaseNonce)
+            return;
+        const encrypted = createCryptoDataPacket({
+            sessionSharedKey: session.sessionSharedKey,
+            sentNonce: session.ourBaseNonce,
+            bufferStart: session.receiveBufferStart ?? 0,
+            packetNumber,
+            payload
+        });
+        incrementNonce(session.ourBaseNonce);
+        await this.#sendToFriend(friendId, encrypted, session, false, false);
+    }
     async #sendMessengerPacket(friendId, kind, data) {
         const session = this.#friendSessions.get(friendId);
         if (!session?.established || !session.sessionSharedKey || !session.ourBaseNonce) {
@@ -2892,7 +3202,35 @@ export class Peer {
             payload
         });
         incrementNonce(session.ourBaseNonce);
-        session.sendPacketNumber = (packetNumber + 1) >>> 0;
+        // Reliable-sequence hygiene. Only packets we will actually DELIVER reliably
+        // may consume the reliable packet-number sequence. The app's high-volume bulk
+        // channel (bulkDataPacketId, e.g. decentlan IP=163) and toxcore lossy packets
+        // (192-254) are DROPPED under backpressure — if they burn a reliable number
+        // first, the drop punches a PERMANENT hole in the stream. A native (iOS/C)
+        // peer does strict in-order net_crypto delivery and stalls EVERYTHING after a
+        // hole (incl. chat 64), sending PACKET_ID_REQUEST for a retransmit we never do
+        // (no retransmit queue) — silently wedging online chat with native peers.
+        // File transfer is bulk but NEVER dropped (queued reliably), so it keeps its
+        // number. So advance the reliable number for everything EXCEPT the droppable
+        // bulk-IP channel and lossy packets; the crypto nonce still advances above so
+        // decryption stays in sync regardless.
+        const isFileTransfer = kind === PACKET_ID_FILE_SENDREQUEST || kind === PACKET_ID_FILE_CONTROL || kind === PACKET_ID_FILE_DATA || kind === PACKET_ID_FILE_FEC;
+        const isBulkData = (this.#opts.bulkDataPacketId !== undefined && kind === this.#opts.bulkDataPacketId) || isFileTransfer;
+        const isDroppable = (isBulkData && !isFileTransfer) || kind >= 192;
+        if (!isDroppable) {
+            session.sendPacketNumber = (packetNumber + 1) >>> 0;
+            // Park the plaintext for retransmission (native peers stall their
+            // whole lossless stream on a gap until we honor PACKET_ID_REQUEST).
+            session.sendArray ??= new Map();
+            session.sendBufferStartNum ??= packetNumber;
+            session.sendArray.set(packetNumber, payload);
+            // Bound the buffer: beyond this window the peer has either acked via
+            // REQUEST packets or the session is beyond saving anyway.
+            while (session.sendArray.size > 1024 && session.sendBufferStartNum !== session.sendPacketNumber) {
+                session.sendArray.delete(session.sendBufferStartNum);
+                session.sendBufferStartNum = (session.sendBufferStartNum + 1) >>> 0;
+            }
+        }
         session.lastPingSentMs = Date.now();
         // Bulk IP-forwarding data (PACKET_ID_MESSAGE) is the high-volume
         // traffic. Once UDP is established it should ride UDP exclusively and
@@ -2925,12 +3263,10 @@ export class Peer {
         // happens to finish before reordering bites. Pinning file transfer to a
         // single transport keeps the chunks in send order. (Reliability across a
         // lossy path still wants a reorder buffer + retransmit — tracked separately.)
-        const isFileTransfer = kind === PACKET_ID_FILE_SENDREQUEST || kind === PACKET_ID_FILE_CONTROL || kind === PACKET_ID_FILE_DATA || kind === PACKET_ID_FILE_FEC;
-        const isBulkData = (this.#opts.bulkDataPacketId !== undefined && kind === this.#opts.bulkDataPacketId) || isFileTransfer;
         // File transfer rides the relay RELIABLY (never dropped under backpressure):
         // a dropped IP/CCTV packet is fine (the stream moves on), but a dropped file
         // chunk corrupts the file (no retransmit). So bulk IP data stays droppable
-        // while file transfer is queued.
+        // while file transfer is queued. (isBulkData / isFileTransfer computed above.)
         await this.#sendToFriend(friendId, encrypted, session, isBulkData, isFileTransfer);
     }
     /**
@@ -3134,6 +3470,11 @@ export class Peer {
         if (!friend) {
             return;
         }
+        // An unroutable self-source is never the friend's endpoint (see
+        // #adoptRemote) — don't let it poison the in-memory record either.
+        if (this.#isUnroutableSelfSource(host, port)) {
+            return;
+        }
         // Important: do NOT persist this candidate to disk. Speculative endpoint
         // hints (from DHT-PK extras, sendnodes-derived knownNodes, etc.) are
         // frequently stale relay addresses that aren't actually the friend's
@@ -3166,6 +3507,7 @@ export class Peer {
         }
         if (dhtPublicKey) {
             session.friendDhtPublicKey = dhtPublicKey;
+            this.#learnFriendDhtKey(friendId, dhtPublicKey);
         }
     }
     /** Single choke point for setting session.remote (the direct-UDP send
@@ -3176,7 +3518,26 @@ export class Peer {
      *  is just a string compare and is safe to call from the per-packet hot path.
      *  Replacing the per-packet getPhysicalLanSubnets() call here was the fix for
      *  the CCTV CPU regression. */
+    /** True when replying to host:port would never reach a peer: the host is
+     *  one of our own TUN/overlay addresses (replies re-enter the overlay
+     *  router and loop), or it's literally our own UDP socket. A self
+     *  PHYSICAL address with a DIFFERENT port is routable — that's a
+     *  same-host peer (e.g. the iOS simulator running on this Mac). */
+    #isUnroutableSelfSource(host, port) {
+        if (isOwnVirtualAddress(host))
+            return true;
+        if (!isOwnAddress(host))
+            return false;
+        const ourPort = this.#udp?.localPort();
+        return ourPort !== undefined && port === ourPort;
+    }
     #adoptRemote(session, host, port) {
+        // NEVER adopt an unroutable self-source as a friend's remote — replies
+        // would loop into our own interface and die, the peer never hears back
+        // and re-handshakes forever.
+        if (this.#isUnroutableSelfSource(host, port)) {
+            return;
+        }
         if (session.lanRemoteHost &&
             session.remote?.host === session.lanRemoteHost &&
             host !== session.lanRemoteHost) {
@@ -3685,13 +4046,33 @@ export class Peer {
             }
         }
         if (pkCmp < 0) {
-            // We're the responder side — wait for peer's COOKIE_REQUEST.
-            // Log once per friend to avoid noise from repeated probe calls.
-            if (!this.#initiateSkipLogged.has(friendId)) {
-                this.#initiateSkipLogged.add(friendId);
-                this.#debugLog(`initiate session: deferring to higher-pubkey peer ${friendId}`);
+            // We're the responder side — wait for peer's COOKIE_REQUEST...
+            // but NOT forever. A higher-pubkey peer that still holds a proven
+            // session from before OUR restart never re-initiates (its side looks
+            // healthy; only its data — encrypted with keys we no longer have —
+            // arrives here as an endless undecryptable flood). Deferring
+            // unconditionally is a PERMANENT deadlock: observed live as a dozen
+            // fleet peers "online at the relay, spraying undecryptable data,
+            // never reconnecting" after a mac-dev restart. Toxcore's tie-break
+            // assumes both sides know the session is dead; here only WE do. So:
+            // defer for a grace window; if the peer hasn't established by then,
+            // initiate anyway — the duplicate-handshake fast path and the
+            // re-handshake acceptance rules handle the both-initiate races the
+            // defer was protecting against.
+            const firstDefer = this.#initiateDeferSinceMs.get(friendId);
+            const now = Date.now();
+            if (firstDefer === undefined) {
+                this.#initiateDeferSinceMs.set(friendId, now);
+            }
+            if (firstDefer === undefined || now - firstDefer < 30_000) {
+                // Log once per friend to avoid noise from repeated probe calls.
+                if (!this.#initiateSkipLogged.has(friendId)) {
+                    this.#initiateSkipLogged.add(friendId);
+                    this.#debugLog(`initiate session: deferring to higher-pubkey peer ${friendId}`);
+                }
+                return false;
             }
-            return false;
+            this.#debugLog(`initiate session: higher-pubkey peer ${friendId} hasn't established in ${Math.round((now - firstDefer) / 1000)}s — breaking defer, initiating`);
         }
         // Prefer DHT key learned from DHTPK updates; fallback to real key.
         const friendDhtPk = session?.friendDhtPublicKey ?? friendRealPk;
@@ -4229,26 +4610,22 @@ export class Peer {
         if (ourUdpPort && ourUdpPort > 0) {
             const ourDhtPk = this.#keyPair?.publicKey;
             if (ourDhtPk && ourDhtPk.length === 32) {
-                // Enumerate non-loopback IPv4 addresses on this host.
-                // We use os.networkInterfaces() rather than guessing — this
-                // covers a multi-homed peer with several reachable IPs.
+                // Enumerate non-loopback IPv4 addresses on this host — PHYSICAL
+                // interfaces only (getPhysicalLanAddresses applies VIRTUAL_IFACE_RE).
+                // The old raw networkInterfaces() walk also advertised our own TUN
+                // address (agentnet0's 10.86.x.y): native peers then sent their UDP
+                // cookie/handshake/session packets to our VIRTUAL ip — into the TUN
+                // maze — and we replied to that same poisoned source, so neither
+                // side's packets arrived and the peer saw us flap online/offline
+                // forever (the iOS-simulator churn).
                 try {
-                    const ifaces = (await import("os")).networkInterfaces();
                     const seenIps = new Set();
-                    for (const iface of Object.values(ifaces)) {
-                        if (!iface)
-                            continue;
-                        for (const addr of iface) {
-                            if (addr.family !== "IPv4")
-                                continue;
-                            if (addr.internal)
+                    for (const address of getPhysicalLanAddresses()) {
+                        {
+                            if (seenIps.has(address))
                                 continue;
-                            if (addr.address === "0.0.0.0")
-                                continue;
-                            if (seenIps.has(addr.address))
-                                continue;
-                            seenIps.add(addr.address);
-                            const parts = addr.address
+                            seenIps.add(address);
+                            const parts = address
                                 .split(".")
                                 .map((p) => Number.parseInt(p, 10));
                             if (parts.length !== 4 || parts.some((n) => !(n >= 0 && n <= 255)))
@@ -4429,32 +4806,53 @@ export class Peer {
             dataPublicKey: opts.dataPublicKey,
             sendBack: opts.sendBack
         });
-        const attempts = opts.attempts ?? 3;
-        for (let attempt = 0; attempt < attempts; attempt++) {
+        const nodeId = `${opts.node.host}:${opts.node.port}`;
+        const pinnedRoute = opts.reuseRoute ? this.#announceRouteUsed.get(nodeId) : undefined;
+        const exchange = async (forcedPath) => {
             const waiter = this.#waitForAnnounceResponse(opts.node, opts.sendBack, {
                 requesterSecretKey: opts.senderSecretKey,
                 nodePublicKey: opts.nodePublicKey
             });
-            await this.#sendThroughOnionPath(request, opts.node, attempt);
+            const routeUsed = await this.#sendThroughOnionPath(request, opts.node, 0, forcedPath);
             const response = await waiter;
             if (response) {
-                this.#recordNodeSuccess(`${opts.node.host}:${opts.node.port}`);
+                this.#recordNodeSuccess(nodeId);
+                this.#announceRouteUsed.set(nodeId, routeUsed);
                 return response;
             }
-            this.#recordNodeFailure(`${opts.node.host}:${opts.node.port}`);
+            this.#recordNodeFailure(nodeId);
+            return undefined;
+        };
+        if (pinnedRoute) {
+            // The pinned route is the only one whose source the node's ping_id can
+            // match — retry it rather than wandering to other paths.
+            const pinnedAttempts = Math.max(1, opts.attempts ?? 3);
+            for (let attempt = 0; attempt < pinnedAttempts; attempt++) {
+                const response = await exchange(pinnedRoute);
+                if (response)
+                    return response;
+            }
+            return undefined;
         }
-        if (opts.allowDirectFallback) {
+        const attempts = opts.attempts ?? 3;
+        for (let attempt = 0; attempt < attempts; attempt++) {
             const waiter = this.#waitForAnnounceResponse(opts.node, opts.sendBack, {
                 requesterSecretKey: opts.senderSecretKey,
                 nodePublicKey: opts.nodePublicKey
             });
-            await this.#sendPacket(request, opts.node);
+            const routeUsed = await this.#sendThroughOnionPath(request, opts.node, attempt);
             const response = await waiter;
             if (response) {
-                this.#recordNodeSuccess(`${opts.node.host}:${opts.node.port}`);
+                this.#recordNodeSuccess(nodeId);
+                this.#announceRouteUsed.set(nodeId, routeUsed);
                 return response;
             }
-            this.#recordNodeFailure(`${opts.node.host}:${opts.node.port}`);
+            this.#recordNodeFailure(nodeId);
+        }
+        if (opts.allowDirectFallback) {
+            const response = await exchange("direct");
+            if (response)
+                return response;
         }
         return undefined;
     }
@@ -4513,12 +4911,12 @@ export class Peer {
         const wrapped = concatBytes([Uint8Array.of(0x69, 0x76, 0x65, 0x67), packet]);
         await this.#udp.send(Buffer.from(wrapped), node.host, node.port);
     }
-    async #sendThroughOnionPath(payloadForNodeD, nodeD, pathOffset = 0) {
-        const path = this.#selectOnionPath(nodeD, pathOffset);
+    async #sendThroughOnionPath(payloadForNodeD, nodeD, pathOffset = 0, forcedPath) {
+        const path = forcedPath === "direct" ? undefined : forcedPath ?? this.#selectOnionPath(nodeD, pathOffset);
         if (!path) {
             this.#debugLog(`no onion path for ${nodeD.host}:${nodeD.port}, sending direct`);
             await this.#sendPacket(payloadForNodeD, nodeD);
-            return;
+            return "direct";
         }
         this.#debugLog(`sending onion initial via ${path.nodeA.node.host}:${path.nodeA.node.port} to ${nodeD.host}:${nodeD.port}`);
         const packet = createOnionRequest0({
@@ -4534,6 +4932,7 @@ export class Peer {
             payloadForNodeD
         });
         await this.#sendPacket(packet, path.nodeA.node);
+        return path;
     }
     #selectOnionPath(nodeD, pathOffset = 0) {
         const nodeDId = `${nodeD.host}:${nodeD.port}`;
@@ -4754,6 +5153,14 @@ export class Peer {
                     remotePort: undefined,
                     status: record.status === "online" ? "offline" : record.status
                 };
+                // Scrub a remoteHost on one of our own VIRTUAL/TUN interfaces (older
+                // builds could cache the self-poisoned TUN source) — sends there
+                // loop through the overlay and die. Self PHYSICAL addresses are kept:
+                // a same-host peer (iOS simulator) legitimately lives there.
+                if (trusted.remoteHost && isOwnVirtualAddress(trusted.remoteHost)) {
+                    trusted.remoteHost = undefined;
+                    trusted.remotePort = undefined;
+                }
                 this.#friends.set(record.pubkey, trusted);
             }
             this.#debugLog(`loaded ${this.#friends.size} persisted friends`);
@@ -5116,6 +5523,8 @@ function isCgnatAddress(host) {
 let _lanIfaceCacheMs = 0;
 let _lanAddrsCache = [];
 let _lanSubnetsCache = [];
+let _allOwnAddrsCache = new Set();
+let _ownVirtualAddrsCache = new Set();
 function refreshLanIfaceCache() {
     const now = Date.now();
     if (_lanIfaceCacheMs !== 0 && now - _lanIfaceCacheMs < 5000)
@@ -5123,12 +5532,22 @@ function refreshLanIfaceCache() {
     _lanIfaceCacheMs = now;
     const addrs = [];
     const subnets = [];
+    const allOwn = new Set();
+    const ownVirtual = new Set();
     try {
         for (const [name, list] of Object.entries(networkInterfaces())) {
-            if (!list || VIRTUAL_IFACE_RE.test(name))
+            if (!list)
                 continue;
+            const virtual = VIRTUAL_IFACE_RE.test(name);
             for (const info of list) {
-                if (info.family !== "IPv4" || info.internal || isCgnatAddress(info.address))
+                if (info.family !== "IPv4")
+                    continue;
+                // ALL own addresses — including virtual/TUN interfaces — feed the
+                // self-source checks (see isOwnAddress/isOwnVirtualAddress).
+                allOwn.add(info.address);
+                if (virtual)
+                    ownVirtual.add(info.address);
+                if (virtual || info.internal || isCgnatAddress(info.address))
                     continue;
                 addrs.push(info.address);
                 const addr = ipv4ToInt(info.address);
@@ -5144,6 +5563,23 @@ function refreshLanIfaceCache() {
     }
     _lanAddrsCache = addrs;
     _lanSubnetsCache = subnets;
+    _allOwnAddrsCache = allOwn;
+    _ownVirtualAddrsCache = ownVirtual;
+}
+/** True when host is one of THIS machine's own IPv4 addresses (any
+ *  interface, physical or virtual/TUN). Cached (see refreshLanIfaceCache). */
+function isOwnAddress(host) {
+    refreshLanIfaceCache();
+    return _allOwnAddrsCache.has(host);
+}
+/** True when host belongs to one of our own VIRTUAL/TUN interfaces (e.g.
+ *  agentnet0's 10.86.x.y). Packets sent there re-enter the overlay router
+ *  and loop — never a usable peer endpoint. A self PHYSICAL address with a
+ *  DIFFERENT port is fine: that's a same-host peer (e.g. the iOS simulator
+ *  on this Mac), and local delivery works. */
+function isOwnVirtualAddress(host) {
+    refreshLanIfaceCache();
+    return _ownVirtualAddrsCache.has(host);
 }
 function getPhysicalLanAddresses() {
     refreshLanIfaceCache();

package/dist/store/friends.d.ts

@@ -14,4 +14,9 @@ export type FriendRecord = {
      *  has been pending. */
     requestedAt?: number;
     acceptedAt?: number;
+    /** Base58 DHT pubkey the friend last announced (native peers handshake
+     *  relays with this key, NOT their identity key). Persisted so a restart
+     *  can immediately park relay ROUTING_REQUESTs under the right key
+     *  instead of waiting for the friend's next DHT-PK announce. */
+    dhtPubkey?: string;
 };

package/dist/types/peer.d.ts

@@ -11,6 +11,13 @@ export type NetworkNode = {
      * relays this way in DHT-PK extras.
      */
     isTcp?: boolean;
+    /** Express relays only: transport scheme. Defaults to HTTPS. Set `false` to
+     *  reach an express node over plain HTTP — the express payload is already
+     *  end-to-end encrypted (nacl.secretbox), so HTTP keeps CONTENT private from
+     *  on-path observers; it does expose the userIDs in the request path. Lets a
+     *  relay run on a raw IP with no TLS cert / domain / ICP filing, exactly like
+     *  a bootstrap node. */
+    tls?: boolean;
     /** Decoded 32-byte form of `pk`, cached lazily on first use so the hot
      *  DHT-distance sort (#closestKnownNodes, run on every get_nodes we answer)
      *  doesn't base58-decode the whole table on every call. */
@@ -87,6 +94,10 @@ export type FriendInfoEvent = {
 export type TextMessage = {
     pubkey: string;
     text: string;
+    /** Delivery path: "online" = live net_crypto session (direct/relay), "offline"
+     *  = express store-and-forward. Lets the UI color the two differently so a user
+     *  can see when online delivery is failing and only offline messages land. */
+    via?: "online" | "offline";
 };
 /**
  * An application-defined custom packet received from a friend, over the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.79",
+  "version": "0.1.81",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,7 +68,8 @@
     "demo:tox-dht-crypto": "pnpm run build && node scripts/tox-dht-crypto-demo.mjs",
     "test:compat": "pnpm run build && node scripts/compat-selftest.mjs",
     "smoke:join": "node scripts/smoke-join.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:express": "pnpm run build && node scripts/express-scheme-selftest.mjs"
   },
   "dependencies": {
     "flatbuffers": "^25.9.23",