@decentnetwork/peer 0.1.111 → 0.1.113

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/index.d.ts

@@ -10,4 +10,4 @@ export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";
 export type { CarrierPacket, FriendMessagePacket, FriendRequestPacket, InviteReqPacket, InviteRspPacket } from "./compat/packet.js";
 export type { ToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export type { CarrierAddressParts } from "./compat/address.js";
-export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";

package/dist/peer.d.ts

@@ -1,6 +1,6 @@
 import { type BootstrapResult } from "./compat/bootstrap.js";
 import type { FriendRecord } from "./store/friends.js";
-import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";
 export declare class Peer {
     #private;
     private constructor();
@@ -84,9 +84,21 @@ export declare class Peer {
      */
     removeFriend(pubkey: string): boolean;
     sendText(pubkey: string, text: string): Promise<void>;
+    /**
+     * Send text and keep retransmitting until the peer explicitly ACKs it.
+     *
+     * The receiving peer sends that ACK only after every onText handler returns
+     * successfully. If a handler persists to an inbox, return its write Promise
+     * from the handler; then this method resolves only after that durable write
+     * completed on the far side. Pass a stable deliveryId when retrying an item
+     * from an application outbox across process restarts.
+     */
+    sendTextUntilAck(pubkey: string, text: string, opts?: SendTextUntilAckOptions): Promise<{
+        deliveryId: string;
+    }>;
     waitForFriendConnected(pubkey: string, timeoutMs?: number): Promise<boolean>;
     onFriendRequest(cb: (req: FriendRequest) => void): void;
-    onText(cb: (msg: TextMessage) => void): void;
+    onText(cb: (msg: TextMessage) => unknown | Promise<unknown>): void;
     /** Files received inline over (bulk)messages — the iOS/C Carrier apps'
      *  native way of sending images/audio online (FileModel JSON envelope). */
     onInlineFile(cb: (evt: InlineFileEvent) => void): void;

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))
@@ -168,15 +186,18 @@ const PEER_NICKNAME = process.env.DECENT_PEER_NAME ?? "@decentnetwork/peer";
 const PEER_STATUS_MESSAGE = process.env.DECENT_PEER_STATUS_MESSAGE ?? "decent peer";
 const GREETING_TEXT = process.env.DECENT_GREETING_TEXT ?? "";
 // AgentNet wire-protocol version advertised in the userinfo profile (field 7).
-// Bump when the wire capabilities change so peers can negotiate. v1 marks a peer
-// that carries this field AND supports the toxcore file-transfer channel
-// (PACKET_ID_FILE 80-82) for large files — a sender can prefer that over inline
-// bulkmsg (capped at CARRIER_MAX_APP_BULKMSG_LEN) when the peer's protoVersion>=1.
-const AGENTNET_PROTO_VERSION = 1;
+// v1 marks a peer that supports the toxcore file-transfer channel. v2 adds
+// application-level text delivery ACKs: senders keep outbox entries until the
+// receiver's onText handler has returned successfully.
+const AGENTNET_PROTO_VERSION = 2;
 // Peer package version, advertised as the default appVersion when the embedder
 // doesn't override it. Read lazily so a bundler that inlines this file doesn't
 // need the package.json at runtime.
-const PEER_PKG_VERSION = "0.1.91";
+const PEER_PKG_VERSION = "0.1.112";
+const TEXT_ACK_PREFIX = "\x1eDNPACK1:";
+const TEXT_ACK_TIMEOUT_MS = readEnvInt("DECENT_TEXT_ACK_TIMEOUT_MS", 300_000);
+const TEXT_ACK_RETRY_MS = readEnvInt("DECENT_TEXT_ACK_RETRY_MS", 5_000);
+const TEXT_AUTO_ACK_TIMEOUT_MS = readEnvInt("DECENT_TEXT_AUTO_ACK_TIMEOUT_MS", 15_000);
 // Toxcore Messenger.h packet IDs (live inside encrypted 0x1b crypto data plain payload)
 const PACKET_ID_PADDING = 0;
 const PACKET_ID_REQUEST = 1; // request retransmission of unreceived packets
@@ -240,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();
@@ -273,6 +309,10 @@ export class Peer {
     #nodeBlacklist = new Map();
     #pendingFriendRequests = new Map();
     #friends = new Map();
+    #textHandlers = new Set();
+    #pendingTextAcks = new Map();
+    #deliveredTextIds = new Set();
+    #deliveredTextOrder = [];
     #friendStoreFile;
     #persistSeq = 0; // makes atomic friend-store temp filenames unique per write
     #cookieSymmetricKey;
@@ -296,6 +336,10 @@ 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();
     #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
@@ -614,6 +658,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. */
@@ -1059,6 +1110,16 @@ export class Peer {
         }
     }
     async sendText(pubkey, text) {
+        if (text.length > 0 && !text.startsWith(TEXT_ACK_PREFIX) && this.#shouldRequireTextAck(pubkey)) {
+            await this.sendTextUntilAck(pubkey, text, {
+                timeoutMs: TEXT_AUTO_ACK_TIMEOUT_MS,
+                retryIntervalMs: Math.min(TEXT_ACK_RETRY_MS, TEXT_AUTO_ACK_TIMEOUT_MS)
+            });
+            return;
+        }
+        await this.#sendTextPlain(pubkey, text);
+    }
+    async #sendTextPlain(pubkey, text) {
         const friend = this.#friends.get(pubkey);
         if (!friend) {
             throw new Error(`Not a friend: ${pubkey}`);
@@ -1175,6 +1236,75 @@ export class Peer {
         }
         throw new Error("friend is offline and no express node is configured");
     }
+    #shouldRequireTextAck(pubkey) {
+        const friend = this.#friends.get(pubkey);
+        if ((friend?.protoVersion ?? 0) >= 2)
+            return true;
+        // decentlan data-plane peers run with expressControlPlaneOnly so an
+        // accepted local send must not be treated as final delivery. A short ACK
+        // timeout makes the caller keep its outbox item and retry on reconnect.
+        return this.#opts.expressControlPlaneOnly === true;
+    }
+    /**
+     * Send text and keep retransmitting until the peer explicitly ACKs it.
+     *
+     * The receiving peer sends that ACK only after every onText handler returns
+     * successfully. If a handler persists to an inbox, return its write Promise
+     * from the handler; then this method resolves only after that durable write
+     * completed on the far side. Pass a stable deliveryId when retrying an item
+     * from an application outbox across process restarts.
+     */
+    async sendTextUntilAck(pubkey, text, opts = {}) {
+        const deliveryId = opts.deliveryId ?? createTextDeliveryId();
+        const retryIntervalMs = Math.max(250, opts.retryIntervalMs ?? TEXT_ACK_RETRY_MS);
+        const timeoutMs = Math.max(retryIntervalMs, opts.timeoutMs ?? TEXT_ACK_TIMEOUT_MS);
+        const envelope = encodeTextAckEnvelope({ t: "msg", id: deliveryId, text });
+        const started = Date.now();
+        let lastError;
+        while (Date.now() - started < timeoutMs) {
+            const remaining = Math.max(1, timeoutMs - (Date.now() - started));
+            const waitMs = Math.min(retryIntervalMs, remaining);
+            const ackPromise = this.#waitForTextAck(deliveryId, waitMs);
+            try {
+                await this.#sendTextPlain(pubkey, envelope);
+            }
+            catch (error) {
+                this.#cancelTextAckWait(deliveryId);
+                lastError = error;
+                await sleep(waitMs);
+                continue;
+            }
+            if (await ackPromise) {
+                return { deliveryId };
+            }
+        }
+        this.#cancelTextAckWait(deliveryId);
+        throw lastError ?? new Error(`text delivery ACK timed out for ${pubkey}`);
+    }
+    #waitForTextAck(deliveryId, timeoutMs) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#pendingTextAcks.delete(deliveryId);
+                resolve(false);
+            }, timeoutMs);
+            timer.unref?.();
+            this.#pendingTextAcks.set(deliveryId, {
+                resolve: () => {
+                    clearTimeout(timer);
+                    this.#pendingTextAcks.delete(deliveryId);
+                    resolve(true);
+                },
+                reject: () => {
+                    clearTimeout(timer);
+                    this.#pendingTextAcks.delete(deliveryId);
+                    resolve(false);
+                }
+            });
+        });
+    }
+    #cancelTextAckWait(deliveryId) {
+        this.#pendingTextAcks.get(deliveryId)?.reject(new Error("text delivery ACK wait cancelled"));
+    }
     waitForFriendConnected(pubkey, timeoutMs = 30000) {
         return this.#waitForFriendConnected(pubkey, timeoutMs);
     }
@@ -1202,7 +1332,65 @@ export class Peer {
         this.#events.on("friendRequest", cb);
     }
     onText(cb) {
-        this.#events.on("text", cb);
+        this.#textHandlers.add(cb);
+    }
+    async #dispatchTextMessage(msg) {
+        const envelope = decodeTextAckEnvelope(msg.text);
+        if (envelope?.t === "ack") {
+            this.#pendingTextAcks.get(envelope.id)?.resolve();
+            return;
+        }
+        let deliveryId;
+        let text = msg.text;
+        if (envelope?.t === "msg") {
+            deliveryId = envelope.id;
+            text = envelope.text;
+            if (this.#deliveredTextIds.has(deliveryId)) {
+                await this.#sendTextAck(msg.pubkey, deliveryId);
+                return;
+            }
+        }
+        if (this.#textHandlers.size === 0) {
+            if (deliveryId)
+                this.#debugLog(`text delivery ${deliveryId} from ${msg.pubkey} has no onText handlers; not ACKing`);
+            return;
+        }
+        const ack = deliveryId
+            ? async () => { await this.#sendTextAck(msg.pubkey, deliveryId); }
+            : undefined;
+        const delivered = { ...msg, text, deliveryId, ack };
+        try {
+            for (const handler of this.#textHandlers) {
+                await handler(delivered);
+            }
+        }
+        catch (error) {
+            this.#debugLog(`text handler failed for ${msg.pubkey}: ${error.message}`);
+            return;
+        }
+        if (deliveryId) {
+            this.#rememberDeliveredTextId(deliveryId);
+            await ack?.();
+        }
+    }
+    async #sendTextAck(pubkey, deliveryId) {
+        try {
+            await this.sendText(pubkey, encodeTextAckEnvelope({ t: "ack", id: deliveryId }));
+        }
+        catch (error) {
+            this.#debugLog(`text ACK send failed for ${pubkey}: ${error.message}`);
+        }
+    }
+    #rememberDeliveredTextId(deliveryId) {
+        if (this.#deliveredTextIds.has(deliveryId))
+            return;
+        this.#deliveredTextIds.add(deliveryId);
+        this.#deliveredTextOrder.push(deliveryId);
+        while (this.#deliveredTextOrder.length > 4096) {
+            const old = this.#deliveredTextOrder.shift();
+            if (old)
+                this.#deliveredTextIds.delete(old);
+        }
     }
     /** Files received inline over (bulk)messages — the iOS/C Carrier apps'
      *  native way of sending images/audio online (FileModel JSON envelope). */
@@ -1546,6 +1734,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
@@ -2620,7 +2824,7 @@ export class Peer {
             // (iOS posts the whole thing as one express MESSAGE packet).
             if (this.#tryEmitInlineFile(fromUserId, text, "offline"))
                 return;
-            this.#events.emit("text", { pubkey: fromUserId, text, via: "offline" });
+            void this.#dispatchTextMessage({ pubkey: fromUserId, text, via: "offline" });
         }
         catch {
             // Ignore invalid offline payloads.
@@ -3607,7 +3811,7 @@ export class Peer {
             // as files, not as a wall of base64 text.
             if (this.#tryEmitInlineFile(friendId, text, "online"))
                 return;
-            this.#events.emit("text", {
+            void this.#dispatchTextMessage({
                 pubkey: friendId,
                 text,
                 via: "online"
@@ -4322,7 +4526,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 };
@@ -4933,12 +5143,79 @@ 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.
+                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.
+                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
@@ -4948,13 +5225,13 @@ 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;
         }
@@ -5003,9 +5280,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 {
@@ -5026,9 +5303,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 {
@@ -5102,6 +5379,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);
@@ -5173,6 +5454,58 @@ 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 identifies as an existing DIFFERENT friend (JS peers use
+        // their stable real key as DHT key) — don't cross-wire.
+        const byDht = this.#friendByDhtPk(senderId);
+        if (byDht && byDht.friendId !== friendId)
+            return;
+        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;
@@ -6057,6 +6390,33 @@ function decodeUtf8Best(payload) {
         return "";
     }
 }
+function encodeTextAckEnvelope(envelope) {
+    return TEXT_ACK_PREFIX + Buffer.from(JSON.stringify(envelope), "utf8").toString("base64url");
+}
+function decodeTextAckEnvelope(text) {
+    if (!text.startsWith(TEXT_ACK_PREFIX))
+        return undefined;
+    try {
+        const raw = Buffer.from(text.slice(TEXT_ACK_PREFIX.length), "base64url").toString("utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.t === "ack" && typeof parsed.id === "string" && parsed.id.length > 0) {
+            return { t: "ack", id: parsed.id };
+        }
+        if (parsed.t === "msg" &&
+            typeof parsed.id === "string" &&
+            parsed.id.length > 0 &&
+            typeof parsed.text === "string") {
+            return { t: "msg", id: parsed.id, text: parsed.text };
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function createTextDeliveryId() {
+    return `${Date.now().toString(36)}-${Buffer.from(randomBytes(12)).toString("base64url")}`;
+}
 function tryDecodeCarrierMessagePacket(payload) {
     try {
         const decoded = decodeCarrierPacket(payload);

package/dist/types/peer.d.ts

@@ -122,11 +122,26 @@ export type FriendInfoEvent = {
 export type TextMessage = {
     pubkey: string;
     text: string;
+    /** Stable id for SDK-level acknowledged delivery. Present only for messages
+     *  sent with sendTextUntilAck(). Receivers can persist this id for dedupe. */
+    deliveryId?: string;
+    /** Send the delivery ACK. The SDK calls this automatically after all onText
+     *  handlers return successfully; handlers that need durable inbox semantics
+     *  should return a Promise that resolves only after the inbox write is done. */
+    ack?: () => Promise<void>;
     /** 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";
 };
+export type SendTextUntilAckOptions = {
+    /** Stable id for retries across a caller-managed outbox. Defaults to a random id. */
+    deliveryId?: string;
+    /** How long to keep retrying before rejecting. Defaults to 5 minutes. */
+    timeoutMs?: number;
+    /** Delay between retransmit attempts while no ACK has arrived. Defaults to 5s. */
+    retryIntervalMs?: number;
+};
 /**
  * An application-defined custom packet received from a friend, over the
  * toxcore custom packet ranges: lossless `160–191` (reliable, ordered) or

package/package.json

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