@decentnetwork/peer 0.1.112 → 0.1.114

package/dist/compat/filetransfer.d.ts

@@ -43,13 +43,20 @@ export type FtEmit = (event: string, payload: Record<string, unknown>) => void;
 export type FtIsLanPath = (friendId: string) => boolean;
 export type FtPathKind = "lan" | "udp-direct" | "relay";
 export type FtPathKindFn = (friendId: string) => FtPathKind;
+/** Fired every watchdog tick while the zero-delivery breaker is engaged: the
+ *  current bulk path is delivering NOTHING (no ack progress). The embedder
+ *  should fail the transfer over to its reliable path (e.g. pin file traffic
+ *  to the TCP relay) — inbound-UDP freshness does NOT prove our outbound UDP
+ *  reaches the peer, and a one-way path looks exactly like this. */
+export type FtDeadPathFn = (friendId: string) => void;
 export declare class FileTransferManager {
     #private;
     private readonly send;
     private readonly emit;
     private readonly isLanPath;
     private readonly pathKind;
-    constructor(send: FtSend, emit: FtEmit, isLanPath?: FtIsLanPath, pathKind?: FtPathKindFn);
+    private readonly onDeadPath;
+    constructor(send: FtSend, emit: FtEmit, isLanPath?: FtIsLanPath, pathKind?: FtPathKindFn, onDeadPath?: FtDeadPathFn);
     /** Enable resumable receives: partials are persisted under `dir` and matched
      *  on re-offer by content-hash fileId. Unset = in-memory only (no resume). */
     setResumeDir(dir: string): void;

package/dist/compat/filetransfer.js

@@ -136,6 +136,17 @@ const LAN_BDP_RTT_FLOOR_MS = 50;
 const LAN_CWND_INIT_CHUNKS = Math.ceil((LAN_PACE_INIT_BPS * (LAN_BDP_RTT_FLOOR_MS / 1000) * 2) / MAX_FILE_DATA_SIZE);
 const WATCHDOG_MS = 150; // stall poll cadence / base no-progress patience
 const WATCHDOG_MAX_MS = 8000; // cap the RTT-adaptive stall patience (must exceed a slow path's RTT so acks aren't mistaken for a stall)
+// Zero-delivery circuit breaker: after this many consecutive stalls with NO ack
+// progress, stop go-back-N re-blasting the window and drop to a single probe
+// chunk per patience tick. File chunks are RELIABLE on the relay (never dropped
+// under backpressure) while IP/ping packets are droppable, so re-blasting a
+// window into a path that is delivering nothing monopolizes the shared relay
+// socket and starves ping/IP for the whole SEND_GIVEUP_MS minute (observed
+// mac→lili: 0 acks in 60 s, ping 100% loss while sending, recovers on giveup).
+// A healthy path clears `stalls` on every ack advance and never reaches this;
+// a genuinely lost hole is probed with exactly the missing chunk, which is
+// strictly more precise than re-sending the whole window anyway.
+const STALL_PROBE_THRESHOLD = 3;
 const FAST_RT_MIN_MS = 40; // min gap between fast-retransmits of the same hole (≈1 RTT)
 const ACK_THROTTLE_MS = 15; // coalesce receiver acks (fast enough to drive fast-retransmit)
 const REACK_MS = 200; // receiver keep-alive re-ack cadence
@@ -210,16 +221,18 @@ export class FileTransferManager {
     emit;
     isLanPath;
     pathKind;
+    onDeadPath;
     #sending = new Map();
     #receiving = new Map();
     // When set, incoming transfers persist their contiguous prefix here so a
     // dropped/restarted transfer resumes instead of restarting (断点续传).
     #resumeDir;
-    constructor(send, emit, isLanPath = () => false, pathKind = (friendId) => (this.isLanPath(friendId) ? "lan" : "relay")) {
+    constructor(send, emit, isLanPath = () => false, pathKind = (friendId) => (this.isLanPath(friendId) ? "lan" : "relay"), onDeadPath = () => { }) {
         this.send = send;
         this.emit = emit;
         this.isLanPath = isLanPath;
         this.pathKind = pathKind;
+        this.onDeadPath = onDeadPath;
     }
     /** Enable resumable receives: partials are persisted under `dir` and matched
      *  on re-offer by content-hash fileId. Unset = in-memory only (no resume). */
@@ -767,6 +780,12 @@ export class FileTransferManager {
             st.acked = Math.min(ackedOffset, st.size);
             st.lastAckAdvanceMs = nowT;
             st.stalls = 0;
+            // Once a transfer hit the zero-delivery breaker, keep the embedder's
+            // dead-path failover armed for its remainder — recovery happened ON the
+            // failover path, so letting the pin lapse would swing DATA back onto the
+            // path that was delivering nothing.
+            if (st.deadPathTripped)
+                this.onDeadPath(friendId);
             // Resume: if the receiver's ack jumps ahead of where we've sent (it had a
             // persisted partial), skip the send cursor past the bytes it already has
             // instead of re-transmitting them.
@@ -1051,6 +1070,26 @@ export class FileTransferManager {
             st.parityHighBlock = ackBlock - 1;
         st.lastLossMs = nowMs(); // keep FEC ON so the re-emit actually fires
     }
+    // Zero-delivery probe: exactly one chunk at the ack frontier, no window
+    // re-blast, no parity. Keeps a dead/black-holed path's cost near zero
+    // (~1.4 KB per patience tick) so the shared relay socket still carries
+    // ping/IP, while still being the precise retransmit for a lost hole.
+    async #sendProbeChunk(friendId, st) {
+        const off = st.acked;
+        const end = Math.min(off + MAX_FILE_DATA_SIZE, st.size);
+        if (end <= off)
+            return;
+        if (st.nextSend < end)
+            st.nextSend = end; // pump resumes AFTER the probed chunk on recovery
+        try {
+            await this.send(friendId, PACKET_ID_FILE_DATA, encodeFileData(st.fileNumber, off, st.data.subarray(off, end)));
+        }
+        catch { /* transport down — the watchdog re-probes on its next tick */ }
+        if (process.env.DECENT_DEBUG || process.env.DECENT_DEBUG_VERBOSE) {
+            console.error(`[file-ft] dead-path-probe friend=${friendId.slice(0, 8)} num=${st.fileNumber} ` +
+                `stalls=${st.stalls} acked=${st.acked}/${st.size}`);
+        }
+    }
     // Single send loop. Awaits each send so net_crypto / the UDP socket applies
     // backpressure (fire-and-forget blasted the whole window into the macOS UDP
     // buffer at once → systematic overflow/drops the retransmit couldn't dig out
@@ -1094,6 +1133,19 @@ export class FileTransferManager {
                 st.cwnd = Math.max(CWND_MIN_CHUNKS, Math.floor(st.cwnd / 2));
                 st.lastAckAdvanceMs = nowMs();
                 st.lastResendMs = nowMs();
+                if (st.stalls >= STALL_PROBE_THRESHOLD) {
+                    // Path is delivering nothing — probe with one chunk instead of
+                    // re-blasting the window, so the shared relay keeps carrying
+                    // ping/IP. Any ack advance resets `stalls` and resumes the pump.
+                    // Also tell the embedder to fail DATA over to its reliable path:
+                    // the classic cause here is one-way UDP (their packets keep our
+                    // udpFresh alive while ours are black-holed), which no amount of
+                    // probing on the same path can fix.
+                    st.deadPathTripped = true;
+                    this.onDeadPath(friendId);
+                    void this.#sendProbeChunk(friendId, st);
+                    return;
+                }
                 this.#rewindRetransmit(st); // go-back-N + re-emit tail parity
                 void this.#pump(friendId, st);
             }, WATCHDOG_MS);

package/dist/peer.js

@@ -160,6 +160,24 @@ const LAN_SWEEP_EXTRA_HOSTS = (process.env.DECENT_LAN_SWEEP_EXTRA_HOSTS ?? "")
     .split(",")
     .map((s) => s.trim())
     .filter((s) => s.length > 0);
+// Same-host probe: on cookie-request RETRIES, also send the request to our
+// OWN physical IPv4 addresses (plus loopback) at the native default ports.
+// This is the iOS-Simulator-on-this-Mac case: the sim shares the host's
+// IP, so when the host's DHCP address changes BOTH sides keep retrying the
+// dead stored endpoint forever, and DHT/onion refresh can't rescue a
+// same-host peer (router hairpin). Unlike the full /24 sweep (default OFF
+// — its burst saturated the NAT table and killed onion announces), these
+// few unicast packets to ourselves never leave the machine, so this is
+// safe to keep always-on. DECENT_LAN_SELF_PROBE=0 disables.
+const LAN_SELF_PROBE_ENABLED = readEnvInt("DECENT_LAN_SELF_PROBE", 1) !== 0;
+// toxcore NET_PACKET_LAN_DISCOVERY: [0x21][sender DHT pk (32)] — plaintext.
+// A native node that receives one DHT-bootstraps back to the source, i.e. it
+// sends us a getnodes/ping carrying its CURRENT (per-run ephemeral) DHT pk in
+// the clear. That round-trip is the only way to re-learn a native friend's
+// DHT key without onion announces: cookie requests encrypted to a stale DHT
+// key are silently undecryptable (observed live: iPhone answered mini but
+// ignored 780+ cookie retries from mac-dev — same endpoint, stale key).
+const NET_PACKET_LAN_DISCOVERY = 0x21;
 const LAN_DISCOVERY_PORTS = (process.env.DECENT_LAN_DISCOVERY_PORTS ?? "33445,33446,33447,33448,33449")
     .split(",")
     .map((s) => Number.parseInt(s.trim(), 10))
@@ -243,6 +261,21 @@ export class Peer {
             Date.now() - session.lastUdpRecvMs < 4_000)
             return "udp-direct";
         return "relay";
+    }, (friendId) => {
+        // Zero-delivery breaker tripped: the bulk path is delivering nothing.
+        // The classic cause is one-way UDP — the peer's inbound packets keep
+        // udpFresh alive while our outbound UDP is black-holed (their ACCEPT
+        // arrived over the TCP relay, which proves the SESSION, not the UDP
+        // path). Pin this friend's file traffic to the reliable relay so the
+        // probes — and the resumed pump once acks return — actually arrive.
+        // Rolling window: re-armed every tick while dead; expires after the
+        // transfer finishes or gives up, so a later transfer re-tries UDP.
+        const session = this.#friendSessions.get(friendId);
+        const lan = !!session?.lanRemoteHost && session.remote?.host === session.lanRemoteHost;
+        if (!lan) {
+            this.#fileRelayNegotiationUntil.set(friendId, Date.now() + 30_000);
+            this.#debugLog(`file dead-path failover: pinning ${friendId} file traffic to relay for 30s`);
+        }
     });
     #keyPair;
     #udp = new UdpTransport();
@@ -303,6 +336,18 @@ export class Peer {
     #selfAnnounceTimer;
     #friendConnectionTimer;
     #lanDiscoveryTimer;
+    /** Recent LAN-discovery probe targets ("host:port" → friend we probed for).
+     *  When a DHT packet later arrives from one of these sources, its sender pk
+     *  is that friend's CURRENT DHT key — see #refreshFriendDhtKeyFromDht. */
+    #lanProbeTargets = new Map();
+    /** Exclusive turn-taking for OWN-HOST probe targets. Own-host targets
+     *  (our IPs + loopback at native ports) are shared by every stranded
+     *  friend, so concurrent probes overwrite each other's #lanProbeTargets
+     *  mapping and the reply gets credited to whoever probed last (observed
+     *  live: the simulator's key landed on an unrelated friend). One friend
+     *  holds the slot at a time; per-friend candidate probes are unaffected. */
+    #ownHostProbeFriendId;
+    #ownHostProbeUntilMs = 0;
     #dhtMaintenanceTimer;
     // Per-friend last DHT-PK send time, keyed by friendId, used even when no
     // session entry exists yet so the connection loop does not flood DHT-PK
@@ -621,6 +666,13 @@ export class Peer {
                 }
             }
         }
+        // Run the friend-connection loop from start(), not only after a
+        // successful joinNetwork(): when every bootstrap is unreachable
+        // (offline LAN, walled network), persisted same-LAN/same-host friends
+        // must still get their cookie retries + rescue probes — otherwise a
+        // daemon with dead bootstraps never reconnects to peers sitting right
+        // next to it. Idempotent with the joinNetwork() call.
+        this.#ensureFriendConnectionLoop();
         this.#started = true;
     }
     /** Lazy session shell used when we want to attach state before any handshake. */
@@ -1690,6 +1742,22 @@ export class Peer {
                 catch { /* best-effort */ }
             }).catch(() => { });
         }
+        // toxcore LAN discovery (0x21, plaintext [id][sender dht pk]): answer like
+        // native DHT_bootstrap does — DHT-ping the announcer. Our ping reveals OUR
+        // current DHT pk + live endpoint to them, and their ping/response feeds
+        // #refreshFriendDhtKeyFromDht on their side. This is the reply half of the
+        // stranded-friend rescue probes (see #initiateSession).
+        if (packet[0] === NET_PACKET_LAN_DISCOVERY &&
+            packet.length === 33 &&
+            this.#keyPair &&
+            !this.#remoteIsTcp(remote)) {
+            const announcedPk = packet.slice(1, 33);
+            if (!Buffer.from(announcedPk).equals(Buffer.from(this.#keyPair.publicKey))) {
+                const announcerId = carrierIdFromPublicKey(announcedPk);
+                void this.#sendDhtPing({ host: remote.address, port: remote.port, pk: announcerId, isTcp: false }).catch(() => undefined);
+            }
+            return;
+        }
         // Classic toxcore DHT RPC (ping / get_nodes / send_nodes). Answering these
         // is what makes us *findable* over UDP: a native iOS/Android peer searches
         // the DHT for our key, a neighbour that holds our address returns it, then
@@ -4466,7 +4534,13 @@ export class Peer {
         }
         if (session.lanRemoteHost &&
             session.remote?.host === session.lanRemoteHost &&
-            host !== session.lanRemoteHost) {
+            host !== session.lanRemoteHost &&
+            // Same-host exception: a peer on THIS machine (iOS Simulator) moves
+            // with us when our DHCP address changes — the old LAN lock target is
+            // dead and the peer now answers from our own current address (or
+            // loopback). Refusing that move pins the session to the dead IP
+            // forever. isOwnAddress is cached; no syscall on the hot path.
+            !(host === "127.0.0.1" || isOwnAddress(host))) {
             return; // stay locked on the physical-LAN path
         }
         session.remote = { host, port };
@@ -5077,12 +5151,88 @@ export class Peer {
                     // Keep best-effort behavior.
                 }
             }
+            // Rescue probes (retries only). Two stale-state failure modes keep a
+            // native friend unreachable forever even though it is alive nearby:
+            //   1. Stale ENDPOINT, same host: an iOS Simulator shares this
+            //      machine's IP, so after a DHCP change both sides hold the dead
+            //      old IP and hairpin blocks every refresh path — but the sim is
+            //      always reachable at our current own IP.
+            //   2. Stale DHT KEY, live endpoint: a native's DHT keypair rotates
+            //      every app restart; cookie requests encrypted to the old key
+            //      are silently dropped (iPhone ignored 780+ retries from
+            //      mac-dev while answering mini from the same endpoint).
+            // So on each retry, (a) fan the cookie request out to our own
+            // addresses at the native ports (fixes 1 when the key is current),
+            // and (b) send plaintext LAN-discovery probes to every candidate and
+            // own-host target — a native answers with a DHT packet that carries
+            // its CURRENT DHT key, which #refreshFriendDhtKeyFromDht picks up
+            // (fixes 2, and 1+2 combined). All local/LAN unicast, a handful of
+            // packets per retry cycle.
+            let selfSent = 0;
+            if (LAN_SELF_PROBE_ENABLED && (this.#cookieRetryCount.get(friendId) ?? 0) >= 1) {
+                const ourLocalPort = this.#udp.localPort();
+                const lanDiscovery = new Uint8Array(33);
+                lanDiscovery[0] = NET_PACKET_LAN_DISCOVERY;
+                lanDiscovery.set(this.#keyPair.publicKey, 1);
+                const probeNow = Date.now();
+                // Prune stale probe bookkeeping so the map stays bounded.
+                for (const [k, v] of this.#lanProbeTargets) {
+                    if (probeNow - v.sentMs > 300_000)
+                        this.#lanProbeTargets.delete(k);
+                }
+                const probe = async (host, port, alsoCookie) => {
+                    const key = `${host}:${port}`;
+                    this.#lanProbeTargets.set(key, { friendId, sentMs: probeNow });
+                    try {
+                        await this.#sendPacket(lanDiscovery, { host, port });
+                        if (alsoCookie) {
+                            await this.#sendPacket(packet, { host, port });
+                            selfSent += 1;
+                        }
+                    }
+                    catch {
+                        // best-effort
+                    }
+                };
+                const tried = new Set();
+                // (b) known candidates — refresh a rotated DHT key at a live endpoint.
+                // Per-friend targets: no mapping ambiguity, always allowed.
+                for (const candidate of connectCandidates) {
+                    const key = `${candidate.host}:${candidate.port}`;
+                    if (tried.has(key))
+                        continue;
+                    tried.add(key);
+                    await probe(candidate.host, candidate.port, false); // cookie already sent above
+                }
+                // (a)+(b) own-host targets — find a same-host peer after an IP change.
+                // SHARED targets: only the current slot holder probes them, so the
+                // reply maps to exactly one friend. Slot rotates by expiry; the
+                // cookie backoff staggers contenders so every stranded friend
+                // eventually gets a turn.
+                if (this.#ownHostProbeFriendId === friendId || probeNow >= this.#ownHostProbeUntilMs) {
+                    this.#ownHostProbeFriendId = friendId;
+                    this.#ownHostProbeUntilMs = probeNow + 10_000;
+                    for (const host of [...getLocalIpv4Addresses(), "127.0.0.1"]) {
+                        if (isOwnVirtualAddress(host))
+                            continue; // never probe into the overlay
+                        for (const port of LAN_SWEEP_PORTS) {
+                            if (port === ourLocalPort)
+                                continue; // our own socket
+                            const key = `${host}:${port}`;
+                            if (tried.has(key))
+                                continue;
+                            tried.add(key);
+                            await probe(host, port, true);
+                        }
+                    }
+                }
+            }
             // Also send via TCP relay if available, in parallel. Whichever
             // arrives at the friend first triggers their cookie response.
             if (tcpAvailable && this.#tcpRelays) {
                 tcpSent = this.#tcpRelays.sendToFriend(friendRealPk, packet);
             }
-            if (sent === 0 && tcpSent === 0) {
+            if (sent === 0 && tcpSent === 0 && selfSent === 0) {
                 throw new Error("no cookie request packet was sent");
             }
             // Each unmatched attempt grows the per-friend backoff. Resets when a
@@ -5092,21 +5242,30 @@ export class Peer {
             const primaryDesc = connectCandidates.length > 0
                 ? `${connectCandidates[0].host}:${connectCandidates[0].port}`
                 : `tcp-relay`;
-            const cookieKey = `${primaryDesc}|udp=${sent}|tcp=${tcpSent}`;
+            const cookieKey = `${primaryDesc}|udp=${sent}|tcp=${tcpSent}|self=${selfSent}`;
             if (this.#lastCookieSentKey.get(friendId) !== cookieKey) {
-                this.#debugLog(`cookie_sent friend=${friendId} udp=${sent} tcp=${tcpSent} primary=${primaryDesc}`);
+                this.#debugLog(`cookie_sent friend=${friendId} udp=${sent} tcp=${tcpSent} self=${selfSent} primary=${primaryDesc}`);
                 this.#lastCookieSentKey.set(friendId, cookieKey);
             }
             else {
-                this.#debugVerboseLog(`cookie_sent friend=${friendId} udp=${sent} tcp=${tcpSent} primary=${primaryDesc} (retry ${this.#cookieRetryCount.get(friendId)})`);
+                this.#debugVerboseLog(`cookie_sent friend=${friendId} udp=${sent} tcp=${tcpSent} self=${selfSent} primary=${primaryDesc} (retry ${this.#cookieRetryCount.get(friendId)})`);
             }
             return true;
         }
         catch (error) {
             this.#debugLog(`cookie request send failed for ${friendId}: ${error.message}`);
+            // A failed send is still a failed ATTEMPT: count it so (a) backoff
+            // grows instead of hammering a dead address at base cadence forever,
+            // and (b) the rescue probes (gated on retryCount >= 1) still fire for
+            // a friend whose sole candidate errors at the syscall level — before
+            // this, such a friend never probed and could never be rescued.
+            this.#cookieRetryCount.set(friendId, (this.#cookieRetryCount.get(friendId) ?? 0) + 1);
             session.pendingEcho = undefined;
             session.pendingCookiePeerDhtPublicKey = undefined;
-            session.cookieRequestSentMs = undefined;
+            // Keep cookieRequestSentMs (set at attempt start): it is the loop's
+            // `lastAttempt`. Clearing it made lastAttempt 0, so the cooldown gate
+            // always passed and a friend whose sends error retried every 250ms
+            // tick forever — the "cookie request send failed" log flood.
             return false;
         }
     }
@@ -5147,9 +5306,9 @@ export class Peer {
         // default so this is invisible for real-device tests, opt-in for
         // loopback or other known-fixed targets via env var.
         for (const host of LAN_SWEEP_EXTRA_HOSTS) {
-            if (ourLocalIps.includes(host))
-                continue;
             for (const port of LAN_SWEEP_PORTS) {
+                // Skip only our own socket — a same-host peer (iOS Simulator) lives
+                // at our own IP on a different port, so own-IP hosts must be probed.
                 if (port === ourLocalPort && ourLocalIps.includes(host))
                     continue;
                 try {
@@ -5170,9 +5329,9 @@ export class Peer {
                 continue;
             for (let addr = (network + 1) >>> 0; addr < broadcast; addr = (addr + 1) >>> 0) {
                 const host = `${(addr >>> 24) & 0xff}.${(addr >>> 16) & 0xff}.${(addr >>> 8) & 0xff}.${addr & 0xff}`;
-                if (ourLocalIps.includes(host))
-                    continue;
                 for (const port of LAN_SWEEP_PORTS) {
+                    // Skip only our own socket, not our whole IP — the iOS Simulator
+                    // shares this host's address on its own port.
                     if (ourLocalPort === port && ourLocalIps.includes(host))
                         continue;
                     try {
@@ -5246,6 +5405,10 @@ export class Peer {
         // keeps mutual reachability alive across the mesh.
         if (remote.port > 0 && !this.#remoteIsTcp(remote)) {
             this.addKnownNodes([{ host: remote.address, port: remote.port, pk: senderId, isTcp: false }]);
+            // A DHT packet carries the sender's CURRENT DHT pk in the clear — if
+            // this source answers one of our LAN-discovery rescue probes, harvest
+            // the key: it un-strands friends whose ephemeral DHT key rotated.
+            this.#refreshFriendDhtKeyFromDht(decoded.senderPublicKey, senderId, remote.address, remote.port);
         }
         if (decoded.type === NET_PACKET_PING_REQUEST) {
             const ping = parsePingPlain(decoded.plain);
@@ -5317,6 +5480,72 @@ export class Peer {
             return;
         }
     }
+    /** A DHT packet arrived from `host:port` with `senderDhtPk` in the clear.
+     *  If that source matches a LAN-discovery rescue probe we sent (or an
+     *  endpoint candidate of a stranded friend), adopt the pk as the friend's
+     *  CURRENT DHT key. Natives rotate their DHT keypair every app restart, so
+     *  a peer that only holds the old key sends cookie requests the friend
+     *  cannot decrypt — correct endpoint, silent drop, stuck forever.
+     *
+     *  Safety: only unestablished sessions are touched (a live session's key
+     *  is by definition correct), and if the adopted key turns out to belong
+     *  to a different node, the crypto handshake cannot complete against the
+     *  friend's REAL key — the rescue just fails and normal retries continue. */
+    #refreshFriendDhtKeyFromDht(senderDhtPk, senderId, host, port) {
+        const key = `${host}:${port}`;
+        let friendId;
+        const probed = this.#lanProbeTargets.get(key);
+        if (probed && Date.now() - probed.sentMs < 300_000) {
+            friendId = probed.friendId;
+        }
+        else {
+            // No probe bookkeeping — still match a stranded friend's known
+            // endpoint candidates (the friend may DHT-ping us spontaneously).
+            for (const [fid, session] of this.#friendSessions) {
+                if (session.established)
+                    continue;
+                if (session.endpointCandidates?.some((c) => c.host === host && c.port === port)) {
+                    friendId = fid;
+                    break;
+                }
+            }
+        }
+        if (!friendId)
+            return;
+        // The sender pk currently maps to a DIFFERENT friend. If that friend's
+        // session is ESTABLISHED, the key genuinely belongs to them — don't
+        // cross-wire. If it is NOT established, the mapping itself may be a
+        // mis-credited earlier probe reply (shared own-host targets), and
+        // refusing here would permanently lock the true owner out — steal it
+        // and scrub the other friend's stale copy so routing stops confusing
+        // the two. A wrong steal self-corrects: the real-key handshake cannot
+        // complete against the wrong node.
+        const byDht = this.#friendByDhtPk(senderId);
+        if (byDht && byDht.friendId !== friendId) {
+            const otherSession = this.#friendSessions.get(byDht.friendId);
+            if (otherSession?.established)
+                return;
+            this.#debugLog(`dht_key_steal ${senderId} from=${byDht.friendId} to=${friendId} (other unestablished)`);
+            if (otherSession?.friendDhtPublicKey && Buffer.from(otherSession.friendDhtPublicKey).equals(Buffer.from(senderDhtPk))) {
+                otherSession.friendDhtPublicKey = undefined;
+            }
+            this.#friendDhtKeys.delete(byDht.friendId);
+        }
+        if (senderId === friendId)
+            return; // already keyed by real pk — nothing to refresh
+        const session = this.#friendSessions.get(friendId);
+        if (!session || session.established)
+            return;
+        const current = session.friendDhtPublicKey;
+        if (current && Buffer.from(current).equals(Buffer.from(senderDhtPk)))
+            return;
+        this.#debugLog(`dht_key_refreshed friend=${friendId} via=${key} old=${current ? carrierIdFromPublicKey(current) : "none"} new=${senderId}`);
+        this.#cacheFriendRemote(friendId, host, port, undefined, senderDhtPk);
+        // Drop the backoff so the next cookie request (now decryptable) goes out
+        // promptly instead of waiting out minutes of accumulated failures.
+        this.#cookieRetryCount.delete(friendId);
+        void this.#initiateSession(friendId).catch(() => undefined);
+    }
     async #sendDhtGetNodes(node, targetPublicKey) {
         if (!this.#keyPair || !node.pk || node.isTcp)
             return;

package/package.json

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