@decentnetwork/peer 0.1.0

package/dist/peer.js

@@ -0,0 +1,3425 @@
+import { EventEmitter } from "node:events";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { networkInterfaces } from "node:os";
+import { dirname } from "node:path";
+import nacl from "tweetnacl";
+import { carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
+import { LegacyBootstrapClient } from "./compat/bootstrap.js";
+import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket } from "./compat/packet.js";
+import { NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID, createOnionAnnounceRequest, createOnionDataPacket, createOnionDataRequest, createOnionRequest0, openOnionAnnounceResponse, openOnionDataPacket, openOnionDataResponse } from "./compat/tox-onion.js";
+import { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
+import { NET_PACKET_CRYPTO_DATA, NET_PACKET_CRYPTO_HS, NET_PACKET_COOKIE_REQUEST, NET_PACKET_COOKIE_RESPONSE, createCookieRequest, createCookieResponse, createCryptoDataPacket, createCryptoHandshake, openCookieRequest, openCookieResponse, openCryptoDataPacket, openCryptoHandshake, incrementNonce } from "./compat/net-crypto.js";
+import { LegacyExpressClient } from "./compat/express.js";
+import { TcpRelayPool } from "./compat/tcp-relay-pool.js";
+import { LegacyDhtClient } from "./compat/dht.js";
+import { loadOrCreateKeyPair } from "./crypto/keypair.js";
+import { base58ToBytes } from "./utils/base58.js";
+import { UdpTransport } from "./transport/udp.js";
+import { bytesToHex, concatBytes, randomBytes } from "./utils/bytes.js";
+const ANNOUNCE_WAIT_TIMEOUT_MS = readEnvInt("DECENT_ANNOUNCE_WAIT_TIMEOUT_MS", 4000);
+const MAX_FRIEND_ROUTE_ATTEMPTS = readEnvInt("DECENT_FRIEND_ROUTE_MAX_ATTEMPTS", 12);
+// How many in-flight announce step1 requests to fan out at once. Toxcore
+// pipelines all 12 of its onion clients in parallel; we batch up to this
+// many concurrent #sendAnnounceAndWait calls so the worst-case walk drops
+// from (per-node-timeout × 12) ≈ 60s down to ~10s. Configurable via
+// DECENT_FRIEND_ROUTE_BATCH_SIZE — set to 1 to revert to sequential.
+const FRIEND_ROUTE_BATCH_SIZE = readEnvInt("DECENT_FRIEND_ROUTE_BATCH_SIZE", 8);
+// Node soft-blacklist: after N consecutive failures (timeouts) a node
+// is parked for a TTL window so we don't waste batch slots on it.
+// Set NODE_BLACKLIST_THRESHOLD=0 to disable. Successful response from
+// the same node clears it instantly.
+const NODE_BLACKLIST_THRESHOLD = readEnvInt("DECENT_NODE_BLACKLIST_THRESHOLD", 5);
+const NODE_BLACKLIST_BASE_TTL_MS = readEnvInt("DECENT_NODE_BLACKLIST_BASE_TTL_MS", 60_000);
+const NODE_BLACKLIST_MAX_TTL_MS = readEnvInt("DECENT_NODE_BLACKLIST_MAX_TTL_MS", 600_000);
+const FRIEND_ANNOUNCE_ATTEMPTS = readEnvInt("DECENT_FRIEND_ANNOUNCE_ATTEMPTS", 1);
+const JOIN_ANNOUNCE_TIMEOUT_MS = readEnvInt("DECENT_JOIN_ANNOUNCE_TIMEOUT_MS", 12000);
+const SELF_ANNOUNCE_INTERVAL_MS = readEnvInt("DECENT_SELF_ANNOUNCE_INTERVAL_MS", 20000);
+const MAX_SELF_ANNOUNCE_TARGETS = readEnvInt("DECENT_SELF_ANNOUNCE_TARGETS", 16);
+const SELF_ANNOUNCE_ATTEMPTS = readEnvInt("DECENT_SELF_ANNOUNCE_ATTEMPTS", 3);
+// Self-announce batch size — number of step1 / step2 requests to fan out
+// at once. Toxcore's onion_client.c::do_announce keeps up to
+// MAX_ONION_CLIENTS_ANNOUNCE (12) in flight. Configurable via env.
+const SELF_ANNOUNCE_BATCH_SIZE = readEnvInt("DECENT_SELF_ANNOUNCE_BATCH_SIZE", 12);
+const ONION_DATA_ATTEMPTS = readEnvInt("DECENT_ONION_DATA_ATTEMPTS", 5);
+const EXPRESS_PULL_INTERVAL_MS = readEnvInt("DECENT_EXPRESS_PULL_INTERVAL_MS", 4000);
+// Keepalive cadence. Toxcore's `friend_connection.h` uses
+// FRIEND_PING_INTERVAL=8s and FRIEND_CONNECTION_TIMEOUT=32s, but our
+// connection loop only ticks every 5s, so the actual ping cadence
+// drifts to 8-13s. With a few drops in a row, iOS Beagle hits its 32s
+// `ping_lastrecv` timeout, marks us offline in the UI, and re-issues
+// a cookie request — observed as repeated `cookie request received`
+// log lines while messages keep flowing on the underlying crypto
+// session. Halve the threshold so the connection loop *always* sends
+// a ping well within iOS's timeout window.
+const FRIEND_PING_INTERVAL_MS = readEnvInt("DECENT_FRIEND_PING_INTERVAL_MS", 4000);
+// Friend connection loop tick. Toxcore's main loop uses MIN_RUN_INTERVAL=50ms
+// and dynamically goes up to 1s when idle (Messenger.c:2578). Our previous
+// 2000ms fixed tick made every reactive event (DHT-PK send after a friend
+// comes online, OOB cookie reply scheduling, ROUTING_REQUEST after we learn
+// a relay) wait up to 2 seconds before firing. Default 250ms picks the
+// middle of toxcore's reactive range — fast enough to keep responsiveness,
+// slow enough not to burn CPU on idle peers. Tunable via env.
+const FRIEND_CONNECTION_LOOP_MS = readEnvInt("DECENT_FRIEND_CONNECTION_LOOP_MS", 250);
+const FRIEND_TIMEOUT_MS = readEnvInt("DECENT_FRIEND_TIMEOUT_MS", 32000);
+const LAN_DISCOVERY_INTERVAL_MS = readEnvInt("DECENT_LAN_DISCOVERY_INTERVAL_MS", 10000);
+// When a same-LAN friend's actual address is unknown (it's not in their
+// DHT-PK extras and their NAT-mapped public IP doesn't accept our UDP),
+// sweep every host in our local /24 subnet with a cookie request at the
+// standard toxcore ports. Set to 0 to disable.
+// LAN sweep: bursts ~250 cookie-request probes across the local /24 to
+// rescue friends whose actual address isn't in their DHT-PK extras (e.g.
+// iOS Simulator on the same Mac). This is *only* useful for same-LAN
+// peer development. Against a real remote peer it produces 250+ wasted
+// UDP packets per friend per cycle, which can saturate the local NAT
+// table and cause every subsequent outbound onion announce to silently
+// timeout (observed on Mac with two stale persisted friends — every
+// announce step1 was dropped). Default OFF; opt in with
+// DECENT_LAN_SWEEP_AFTER_MS=6000 if you're testing against an iOS
+// Simulator on the same machine.
+const LAN_SWEEP_AFTER_MS = readEnvInt("DECENT_LAN_SWEEP_AFTER_MS", 0);
+// Default to a single port to keep the sweep burst small (~254 probes per
+// /24 instead of ~1270). Override DECENT_LAN_SWEEP_PORTS=33445,33446,...
+// only when probing for peers that bind to non-default ports.
+const LAN_SWEEP_PORTS = (process.env.DECENT_LAN_SWEEP_PORTS ?? "33445")
+    .split(",")
+    .map((s) => Number.parseInt(s.trim(), 10))
+    .filter((n) => Number.isFinite(n) && n > 0 && n <= 0xffff);
+// Optional comma-separated list of additional UDP hosts the LAN sweep
+// should probe in addition to the /24 subnets we're attached to.
+// Useful when testing against the iOS Simulator on the same host
+// (DECENT_LAN_SWEEP_EXTRA_HOSTS=127.0.0.1) or a known fixed peer
+// address. Default is empty so a real iOS device on the LAN behaves
+// identically to before.
+const LAN_SWEEP_EXTRA_HOSTS = (process.env.DECENT_LAN_SWEEP_EXTRA_HOSTS ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+const LAN_DISCOVERY_PORTS = (process.env.DECENT_LAN_DISCOVERY_PORTS ?? "33445,33446,33447,33448,33449")
+    .split(",")
+    .map((s) => Number.parseInt(s.trim(), 10))
+    .filter((n) => Number.isFinite(n) && n > 0 && n <= 0xffff);
+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 ?? "";
+// 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
+const PACKET_ID_KILL = 2;
+const PACKET_ID_ALIVE = 16; // keepalive
+const PACKET_ID_SHARE_RELAYS = 17; // TCP relay sharing
+const PACKET_ID_ONLINE = 24; // friend is online
+const PACKET_ID_OFFLINE = 25; // friend going offline
+const PACKET_ID_NICKNAME = 48; // friend's display name (UTF-8)
+const PACKET_ID_STATUSMESSAGE = 49; // friend's status message
+const PACKET_ID_USERSTATUS = 50; // friend's user status (1 byte enum)
+const PACKET_ID_TYPING = 51; // typing indicator (1 byte bool)
+const PACKET_ID_MESSAGE = 64; // text message (Carrier FlatBuffers payload)
+const PACKET_ID_ACTION = 65; // /me action message
+export class Peer {
+    #opts;
+    #events = new EventEmitter();
+    #keyPair;
+    #udp = new UdpTransport();
+    #bootstrap;
+    #dht = new LegacyDhtClient();
+    #knownNodes;
+    #announceDataKey;
+    #lastSelfAnnounceMs = 0;
+    #debug = process.env.DECENT_DEBUG === "1" || process.env.DECENT_DEBUG_VERBOSE === "1";
+    #debugVerbose = process.env.DECENT_DEBUG_VERBOSE === "1";
+    #packetTrace = process.env.DECENT_PACKET_TRACE === "1";
+    #lastFriendRequestDispatch;
+    #nodeHealth = new Map();
+    /**
+     * Soft blacklist: nodeId -> expiry timestamp (ms). Populated by
+     * #recordNodeFailure once a node has accumulated NODE_BLACKLIST_THRESHOLD
+     * consecutive failures without a success. Cleared by #recordNodeSuccess
+     * (any successful round-trip lifts the ban). Each candidate-selection
+     * site filters via #isNodeBlacklisted before adding a node to its queue.
+     */
+    #nodeBlacklist = new Map();
+    #pendingFriendRequests = new Map();
+    #friends = new Map();
+    #friendStoreFile;
+    #cookieSymmetricKey;
+    #friendSessions = new Map();
+    #express;
+    #expressPollTimer;
+    /**
+     * Pool of persistent TCP relay connections. Carrier bootstrap nodes
+     * also serve as TCP relay servers (toxcore TCP_server.c) on the same
+     * pubkey. iOS Beagle peers advertise *only* TCP relay endpoints in
+     * their DHT-PK extras (the 0x82 = TCP_FAMILY_IPV4 entries we saw),
+     * so without this pool we cannot interop with iOS at all when their
+     * UDP path is closed by NAT.
+     */
+    #tcpRelays;
+    #selfAnnounceTimer;
+    #friendConnectionTimer;
+    #lanDiscoveryTimer;
+    // 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
+    // requests when route discovery keeps failing.
+    #dhtPkSendCooldown = new Map();
+    // Per-friend consecutive "no routes available" count for DHT-PK so the
+    // backoff grows if a friend stays unreachable, instead of retrying every
+    // 25s forever for stale persisted entries.
+    #dhtPkConsecutiveFailures = new Map();
+    #lastSelfAnnounceStoredCount = -1;
+    // Per-friend last-logged route count from #discoverFriendRoutes so we
+    // only emit a "routes=N for friend=…" debug line when it changes.
+    #lastLoggedRoutesForFriend = new Map();
+    // Per-friend last "cookie_sent" key (friend+host+port) so retries to the
+    // same endpoint don't spam debug; the first attempt and any change still log.
+    #lastCookieSentKey = new Map();
+    // Per-friend last endpoint we logged via "endpoint_selected" — same purpose
+    // as #lastCookieSentKey but for the selection step. Without dedupe the log
+    // line fired every loop tick because `session.remote` oscillates between
+    // candidates as inbound DHT-PK extras arrive.
+    #lastEndpointSelectedKey = new Map();
+    // Per-friend consecutive cookie-request failures (no matching cookie
+    // response received before the next attempt). Used to compute exponential
+    // backoff so an unreachable persisted friend stops dominating the friend
+    // connection loop with cookie-request bursts every 8 seconds.
+    #cookieRetryCount = new Map();
+    // Per-friend "we already warned this peer is TCP-only" set.
+    #tcpOnlyWarningShown = new Set();
+    // Per-friend "we already noted there's no known endpoint" set so the
+    // #initiateSession path doesn't spam every connection-loop tick.
+    #noEndpointWarned = new Set();
+    // Per-friend "we already logged that we're deferring initiation to the
+    // higher-pubkey peer" set. The connection loop re-enters
+    // #initiateSession every few seconds for every friend; without this
+    // dedupe, lower-pubkey side floods the log with "deferring to peer".
+    #initiateSkipLogged = new Set();
+    // Per-friend tracking sets so we send our nickname/status/greeting once
+    // per session rather than on every PACKET_ID_ONLINE arrival.
+    #profileSentTo = new Set();
+    #greetingSentTo = new Set();
+    #selfAnnouncePromise;
+    #selfAnnouncePauseDepth = 0;
+    #started = false;
+    constructor(opts) {
+        this.#opts = {
+            ...opts,
+            compatibilityMode: opts.compatibilityMode ?? "legacy"
+        };
+        this.#knownNodes = [...opts.bootstrapNodes];
+        this.#friendStoreFile = opts.friendStoreFile ?? `${opts.keyFile}.friends.json`;
+    }
+    static async create(opts) {
+        if (opts.compatibilityMode && opts.compatibilityMode !== "legacy") {
+            throw new Error("Only legacy compatibility mode is supported in this skeleton");
+        }
+        if (!opts.bootstrapNodes.length) {
+            throw new Error("At least one bootstrap node is required");
+        }
+        return new Peer(opts);
+    }
+    async start() {
+        if (this.#started) {
+            return;
+        }
+        this.#keyPair = await loadOrCreateKeyPair(this.#opts.keyFile);
+        this.#bootstrap = new LegacyBootstrapClient({
+            nodes: this.#opts.bootstrapNodes,
+            keyPair: this.#keyPair,
+            transport: this.#udp
+        });
+        const announceGenerated = createEphemeralKeyPair();
+        this.#announceDataKey = {
+            publicKey: announceGenerated.publicKey,
+            secretKey: announceGenerated.secretKey
+        };
+        this.#cookieSymmetricKey = randomBytes(32);
+        await this.#loadPersistedFriends();
+        if (this.#opts.expressNodes && this.#opts.expressNodes.length > 0) {
+            this.#express = new LegacyExpressClient({
+                nodes: this.#opts.expressNodes,
+                selfKeyPair: this.#keyPair,
+                selfUserId: this.userid(),
+                selfAddress: this.address(),
+                callbacks: {
+                    onOfflineFriendRequest: (fromUserId, packet) => {
+                        this.#emitOfflineFriendRequest(fromUserId, packet);
+                    },
+                    onOfflineFriendMessage: (fromUserId, packet) => {
+                        this.#emitOfflineFriendMessage(fromUserId, packet);
+                    }
+                }
+            });
+        }
+        this.#udp.on("datagram", this.#onDatagram);
+        await this.#udp.start();
+        // Spin up the TCP relay pool. We pass the same bootstrap node list
+        // we already have — every Carrier bootstrap is also a TCP relay
+        // server on the same pubkey. The pool opens up to 3 connections in
+        // parallel; failures don't abort start because pool internally
+        // schedules reconnects.
+        if (this.#opts.bootstrapNodes.length > 0) {
+            // maxConnections matches toxcore's default (3). Initial overlap
+            // with another peer drawing 3 from the same 14-node bootstrap
+            // list is ~21% — looks low, but the gap is closed by the
+            // dynamic-relay-add path: when a friend's DHT-PK announce
+            // arrives carrying TCP_FAMILY_IPV4 entries in extras, we open
+            // those specific relays (see #handleOnionDhtPk). After one
+            // round-trip of DHT-PK announces (which we send every ~25s for
+            // every non-established friend), the pool naturally grows to
+            // include every relay any of our friends actually use.
+            //
+            // Override with DECENT_TCP_MAX_RELAYS=N to test brute-force
+            // overlap (set N up to bootstrapNodes.length).
+            const maxRelays = Number.parseInt(process.env.DECENT_TCP_MAX_RELAYS ?? "3", 10);
+            this.#tcpRelays = new TcpRelayPool({
+                relays: this.#opts.bootstrapNodes,
+                selfKeyPair: this.#keyPair,
+                maxConnections: maxRelays,
+                label: this.#opts.debugLabel
+            });
+            this.#tcpRelays.on("peerData", (friendKey, payload) => {
+                this.#handleTcpDatagram(friendKey, payload);
+            });
+            this.#tcpRelays.on("friendOnline", (friendKey) => {
+                const friendId = carrierIdFromPublicKey(friendKey);
+                this.#debugLog(`tcp_relay friend_online ${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);
+                this.#friendSessions.set(friendId, session);
+                if (!session.established) {
+                    void this.#initiateSession(friendId).catch(() => { });
+                }
+            });
+            this.#tcpRelays.on("friendOffline", (friendKey) => {
+                const friendId = carrierIdFromPublicKey(friendKey);
+                const session = this.#friendSessions.get(friendId);
+                if (session) {
+                    session.hasTcpRoute = false;
+                }
+                this.#debugLog(`tcp_relay friend_offline ${friendId}`);
+            });
+            this.#tcpRelays.on("status", (connected, total) => {
+                this.#debugLog(`tcp_pool ${connected}/${total} relays connected`);
+            });
+            // OOB_RECV bridge. iPad's friend_connection issues OOB_SEND with a
+            // cookie request payload (NET_PACKET_COOKIE_REQUEST = 0x18) when
+            // it can't find our DHT-PK announce on the DHT — exactly the
+            // situation we hit on residential ISPs. Toxcore handles the
+            // symmetric case in net_crypto.c::tcp_oob_callback. Feed any
+            // such inbound through the same #onDatagram dispatcher we use
+            // for UDP, with a synthetic tcp: remote so session.remote isn't
+            // poisoned with a fake UDP host.
+            this.#tcpRelays.on("oob", (senderKey, payload) => {
+                if (payload.length === 0)
+                    return;
+                const kind = payload[0];
+                // We currently only act on cookie request / response / handshake.
+                // Friend-request OOB delivery uses a different path
+                // (CRYPTO_PACKET_FRIEND_REQ inside an onion data packet).
+                // NOTE: cookie *response* (0x19) was previously dropped here,
+                // which broke TCP-relay-only friend pairing — added 0x19 so the
+                // initiator side can receive its response.
+                if (kind !== NET_PACKET_COOKIE_REQUEST &&
+                    kind !== NET_PACKET_COOKIE_RESPONSE &&
+                    kind !== NET_PACKET_CRYPTO_HS) {
+                    return;
+                }
+                const senderId = carrierIdFromPublicKey(senderKey);
+                this.#debugLog(`tcp_oob_recv from ${senderId} kind=0x${kind.toString(16)} len=${payload.length}`);
+                // Issue ROUTING_REQUEST for the sender's DHT pubkey on every
+                // connected relay so the relay links us with cid. Without
+                // this, post-handshake messenger traffic (PACKET_ID_ONLINE,
+                // ALIVE, etc.) has no way out via TCP — sendToFriend returns
+                // 0 because no cid maps to the sender's pubkey, and iPad
+                // never sees us as online even though the crypto session is
+                // up. Idempotent: already-requested routes are a no-op on
+                // each underlying client.
+                this.#tcpRelays?.requestRoute(senderKey);
+                this.#handleTcpDatagram(senderKey, payload);
+            });
+            // Don't await — pool reconnects on its own and we want start() to
+            // return promptly so the demo can call joinNetwork() in parallel.
+            void this.#tcpRelays.start().catch((error) => {
+                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()) {
+                try {
+                    const pk = base58ToBytes(friend.pubkey);
+                    if (pk.length === 32)
+                        this.#tcpRelays.requestRoute(pk);
+                }
+                catch { /* skip malformed */ }
+            }
+        }
+        this.#started = true;
+    }
+    /** Lazy session shell used when we want to attach state before any handshake. */
+    #newSessionShell() {
+        return {
+            ourSessionKeyPair: createEphemeralKeyPair(),
+            ourBaseNonce: randomBytes(24)
+        };
+    }
+    async stop() {
+        if (this.#tcpRelays) {
+            await this.#tcpRelays.stop().catch(() => { });
+            this.#tcpRelays = undefined;
+        }
+        if (this.#expressPollTimer) {
+            clearInterval(this.#expressPollTimer);
+            this.#expressPollTimer = undefined;
+        }
+        if (this.#selfAnnounceTimer) {
+            clearInterval(this.#selfAnnounceTimer);
+            this.#selfAnnounceTimer = undefined;
+        }
+        if (this.#friendConnectionTimer) {
+            clearInterval(this.#friendConnectionTimer);
+            this.#friendConnectionTimer = undefined;
+        }
+        this.#udp.off("datagram", this.#onDatagram);
+        await this.#udp.stop();
+        this.#started = false;
+    }
+    pubkey() {
+        if (!this.#keyPair) {
+            throw new Error("Peer is not started");
+        }
+        return bytesToHex(this.#keyPair.publicKey);
+    }
+    userid() {
+        if (!this.#keyPair) {
+            throw new Error("Peer is not started");
+        }
+        return carrierIdFromPublicKey(this.#keyPair.publicKey);
+    }
+    address() {
+        if (!this.#keyPair) {
+            throw new Error("Peer is not started");
+        }
+        return carrierAddressFromPublicKey(this.#keyPair.publicKey);
+    }
+    async joinNetwork() {
+        if (!this.#bootstrap) {
+            throw new Error("Peer is not started");
+        }
+        const result = await this.#bootstrap.join();
+        this.#recordNodeSuccess(`${result.respondingNode.host}:${result.respondingNode.port}`);
+        const discovered = result.discoveredNodes.map((node) => ({
+            host: node.host,
+            port: node.port,
+            pk: carrierIdFromPublicKey(node.publicKey)
+        }));
+        this.#knownNodes = dedupeNodes([result.respondingNode, ...discovered, ...this.#opts.bootstrapNodes]);
+        await this.#runSelfAnnounce(false, Date.now() + JOIN_ANNOUNCE_TIMEOUT_MS);
+        this.#ensureSelfAnnounceLoop();
+        this.#ensureFriendConnectionLoop();
+        this.#ensureExpressPullLoop();
+        // Kick off an immediate friend connection cycle so persisted friends with
+        // a cached endpoint try to reconnect right away instead of waiting 5s.
+        void this.#doFriendConnections().catch((error) => {
+            this.#debugLog(`initial friend connection cycle failed: ${error.message}`);
+        });
+        return result;
+    }
+    async lookup(pubkey) {
+        return this.#dht.lookup(pubkey);
+    }
+    async announceSelf(timeoutMs = 15000) {
+        return this.#runSelfAnnounce(true, Date.now() + timeoutMs);
+    }
+    addKnownNodes(nodes) {
+        this.#knownNodes = dedupeNodes([...nodes, ...this.#knownNodes]);
+    }
+    knownNodes() {
+        return [...this.#knownNodes];
+    }
+    async sendFriendRequest(pubkey, hello) {
+        if (!this.#keyPair || !this.#announceDataKey) {
+            throw new Error("Peer is not started");
+        }
+        // Idempotency guard: if this friend was previously accepted (we have
+        // ever had a real session with them), skip the friend-request round
+        // trip entirely. Sending it again would be visible to iOS as a fresh
+        // friend request prompt — worst case the user dismisses it, best case
+        // it's silently ignored since iOS already has us. We still emit the
+        // last-dispatch summary (transport=cached) so the demo's retry loop
+        // recognizes "this counted as a successful dispatch" and proceeds to
+        // wait for connection events. The friend connection loop will pick up
+        // session establishment via DHT-PK on its own cadence.
+        const friendAddress = parseCarrierAddress(pubkey);
+        const friendId = carrierIdFromPublicKey(friendAddress.publicKey);
+        const existing = this.#friends.get(friendId);
+        if (existing?.acceptedAt) {
+            this.#debugLog(`friend request skipped — ${friendId} already accepted at ${new Date(existing.acceptedAt).toISOString()}`);
+            this.#lastFriendRequestDispatch = {
+                transport: "onion",
+                routes: 0,
+                targets: 0
+            };
+            // Kick the connection loop so we don't have to wait for the next
+            // 2s tick. Best-effort — failures here are non-fatal because the
+            // periodic loop will keep retrying.
+            void this.#initiateSession(friendId).catch(() => { });
+            return;
+        }
+        const resumeSelfAnnounce = this.#pauseSelfAnnounce();
+        try {
+            if (this.#selfAnnouncePromise) {
+                await this.#selfAnnouncePromise.catch(() => { });
+            }
+            await this.#announceSelfBestEffort(false, Date.now() + 4000);
+            const appPayload = encodeFriendRequestPacket({
+                name: PEER_NICKNAME,
+                descr: PEER_STATUS_MESSAGE || "decent peer",
+                hello: hello ?? ""
+            });
+            const friendReqPayload = concatBytes([
+                uint32ToLe(friendAddress.nospam),
+                appPayload
+            ]);
+            const routes = await this.#discoverFriendRoutes(friendAddress.publicKey);
+            this.#debugLog(`friend route discovery done routes=${routes.length}`);
+            if (routes.length === 0) {
+                await this.#sendDirectCryptoFriendRequest(friendAddress.publicKey, friendReqPayload);
+                this.#lastFriendRequestDispatch = {
+                    transport: "direct",
+                    routes: 0,
+                    targets: this.#knownNodes.length > 0 ? this.#knownNodes.length : this.#opts.bootstrapNodes.length
+                };
+                this.#recordOutgoingFriendRequest(friendId, pubkey, friendAddress.nospam, hello);
+                if (this.#express?.hasNodes()) {
+                    void this.#express.sendOfflineFriendRequest(pubkey, appPayload)
+                        .then(() => {
+                        this.#debugLog(`offline_fr_post ok to ${pubkey}`);
+                    })
+                        .catch((error) => {
+                        this.#debugLog(`offline friend request dispatch failed: ${error.message}`);
+                    });
+                }
+                return;
+            }
+            let sent = 0;
+            const errors = [];
+            for (const route of routes) {
+                try {
+                    const nonce = randomBytes(24);
+                    const onionData = createOnionDataPacket({
+                        senderPublicKey: this.#keyPair.publicKey,
+                        senderSecretKey: this.#keyPair.secretKey,
+                        receiverPublicKey: friendAddress.publicKey,
+                        nonce,
+                        innerPacketId: ONION_FRIEND_REQUEST_ID,
+                        innerPayload: friendReqPayload
+                    });
+                    const dataRequest = createOnionDataRequest({
+                        destinationPublicKey: friendAddress.publicKey,
+                        routePublicKey: route.routePublicKey,
+                        nonce,
+                        onionDataPacket: onionData
+                    });
+                    for (let attempt = 0; attempt < ONION_DATA_ATTEMPTS; attempt++) {
+                        await this.#sendThroughOnionPath(dataRequest, route.node, attempt);
+                        sent += 1;
+                        await sleep(150);
+                    }
+                }
+                catch (error) {
+                    errors.push(`${route.node.host}:${route.node.port} ${error.message}`);
+                }
+            }
+            if (sent === 0) {
+                throw new Error(`friend request dispatch failed: ${errors.join("; ")}`);
+            }
+            this.#lastFriendRequestDispatch = {
+                transport: "onion",
+                routes: routes.length,
+                targets: sent
+            };
+            this.#recordOutgoingFriendRequest(friendId, pubkey, friendAddress.nospam, hello);
+            if (this.#express?.hasNodes()) {
+                void this.#express.sendOfflineFriendRequest(pubkey, appPayload).catch((error) => {
+                    this.#debugLog(`offline friend request dispatch failed: ${error.message}`);
+                });
+            }
+        }
+        finally {
+            resumeSelfAnnounce();
+        }
+    }
+    lastFriendRequestDispatch() {
+        return this.#lastFriendRequestDispatch;
+    }
+    async acceptFriendRequest(pubkey) {
+        const request = this.#pendingFriendRequests.get(pubkey);
+        if (!request) {
+            throw new Error("No pending friend request from this peer");
+        }
+        this.#pendingFriendRequests.delete(pubkey);
+        this.#friends.set(pubkey, {
+            pubkey,
+            userid: request.userid,
+            address: request.address,
+            nospam: request.nospam,
+            name: request.name,
+            description: request.description,
+            hello: request.hello,
+            status: "offline",
+            acceptedAt: Date.now()
+        });
+        this.#persistFriends();
+        this.#events.emit("friendConnection", {
+            pubkey,
+            status: "disconnected"
+        });
+        // Pre-route on TCP relays so the relay starts watching for them.
+        if (this.#tcpRelays) {
+            try {
+                const pk = base58ToBytes(pubkey);
+                if (pk.length === 32)
+                    this.#tcpRelays.requestRoute(pk);
+            }
+            catch { /* skip malformed */ }
+        }
+        // Attempt to start net_crypto session immediately. If we don't have a
+        // remote endpoint cached yet, the friend connection loop will retry
+        // periodically. The peer side will also attempt to initiate, so even if
+        // our initiation fails, the responder path can still complete the session.
+        void this.#initiateSession(pubkey).catch((error) => {
+            this.#debugLog(`accept friend: initiate session failed for ${pubkey}: ${error.message}`);
+        });
+    }
+    rejectFriendRequest(pubkey) {
+        this.#pendingFriendRequests.delete(pubkey);
+    }
+    /**
+     * Drop a friend entirely: tear down any active net_crypto session, forget
+     * their cached endpoint, clear retry/backoff bookkeeping, and persist the
+     * shrunk friend list to disk. Use this to remove stale persisted entries
+     * (e.g. an old simulator pubkey) that are still hogging the friend
+     * connection loop with cookie requests no peer is going to answer.
+     *
+     * `pubkey` accepts either the friend's userid (base58 of the real public
+     * key) or full Carrier address — both resolve to the same friendId.
+     */
+    removeFriend(pubkey) {
+        let friendId = pubkey;
+        try {
+            friendId = carrierIdFromAddress(pubkey);
+        }
+        catch {
+            // Not an address; assume already a userid / pubkey form.
+        }
+        const existed = this.#friends.delete(friendId);
+        this.#friendSessions.delete(friendId);
+        this.#pendingFriendRequests.delete(friendId);
+        this.#cookieRetryCount.delete(friendId);
+        this.#lastCookieSentKey.delete(friendId);
+        this.#lastEndpointSelectedKey.delete(friendId);
+        this.#lastLoggedRoutesForFriend.delete(friendId);
+        this.#dhtPkSendCooldown.delete(friendId);
+        this.#dhtPkConsecutiveFailures.delete(friendId);
+        this.#tcpOnlyWarningShown.delete(friendId);
+        this.#noEndpointWarned.delete(friendId);
+        this.#profileSentTo.delete(friendId);
+        this.#greetingSentTo.delete(friendId);
+        if (existed) {
+            this.#persistFriends();
+            this.#debugLog(`removed friend ${friendId}`);
+        }
+        return existed;
+    }
+    #recordOutgoingFriendRequest(friendId, address, nospam, hello) {
+        const existing = this.#friends.get(friendId);
+        if (existing?.status === "online" || existing?.acceptedAt) {
+            return;
+        }
+        this.#friends.set(friendId, {
+            ...existing,
+            pubkey: friendId,
+            userid: friendId,
+            address,
+            nospam,
+            hello: hello ?? existing?.hello,
+            status: existing?.status ?? "requested"
+        });
+        this.#persistFriends();
+        // Tell every connected TCP relay we want this friend routed; the
+        // moment they're also connected, the relay sends us a CONNECTION_
+        // NOTIFICATION and we can establish a session over TCP even if UDP
+        // doesn't work (which is iOS's normal case).
+        if (this.#tcpRelays) {
+            try {
+                const pk = parseCarrierAddress(address).publicKey;
+                this.#tcpRelays.requestRoute(pk);
+            }
+            catch { /* address parse failure already logged elsewhere */ }
+        }
+    }
+    async sendText(pubkey, text) {
+        const friend = this.#friends.get(pubkey);
+        if (!friend) {
+            throw new Error(`Not a friend: ${pubkey}`);
+        }
+        let session = this.#friendSessions.get(pubkey);
+        if (!session?.established) {
+            // Try to bring up the session if we know the friend's endpoint
+            await this.#initiateSession(pubkey).catch(() => { });
+            const established = await this.#waitForFriendConnected(pubkey, 5000).catch(() => false);
+            if (established) {
+                session = this.#friendSessions.get(pubkey);
+            }
+        }
+        const packet = encodeFriendMessagePacket(text);
+        // Try the live in-session path first when any transport is up
+        // (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.
+        const liveSession = session?.established
+            && session.sessionSharedKey
+            && session.ourBaseNonce
+            && (session.remote || session.hasTcpRoute);
+        if (liveSession) {
+            try {
+                await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, packet);
+                return;
+            }
+            catch (error) {
+                // Mirrors Carrier C SDK behavior: when an in-session send fails
+                // (no transport accepted the encrypted packet), fall through to
+                // the express offline relay rather than dropping the message
+                // on the floor. The receiver will pick it up on their next
+                // express pull. Without this the message is just lost when the
+                // friend's NAT briefly forgets us — observed when iPad rebinds
+                // its TCP relay slot, or when UDP and TCP relay both blip.
+                this.#debugLog(`sendText: in-session send failed for ${pubkey}, falling back to express: ${error.message}`);
+            }
+        }
+        // Offline / fallback path via Carrier express HTTP store-and-forward.
+        if (this.#express?.hasNodes()) {
+            await this.#express.sendOfflineText(pubkey, packet);
+            this.#debugLog(`sendText: queued via express for ${pubkey}`);
+            return;
+        }
+        throw new Error("friend is offline and no express node is configured");
+    }
+    waitForFriendConnected(pubkey, timeoutMs = 30000) {
+        return this.#waitForFriendConnected(pubkey, timeoutMs);
+    }
+    #waitForFriendConnected(pubkey, timeoutMs) {
+        const session = this.#friendSessions.get(pubkey);
+        if (session?.established) {
+            return Promise.resolve(true);
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#events.off("friendConnection", onConnection);
+                resolve(false);
+            }, timeoutMs);
+            const onConnection = (ev) => {
+                if (ev.pubkey === pubkey && ev.status === "connected") {
+                    clearTimeout(timer);
+                    this.#events.off("friendConnection", onConnection);
+                    resolve(true);
+                }
+            };
+            this.#events.on("friendConnection", onConnection);
+        });
+    }
+    onFriendRequest(cb) {
+        this.#events.on("friendRequest", cb);
+    }
+    onText(cb) {
+        this.#events.on("text", cb);
+    }
+    onFriendConnection(cb) {
+        this.#events.on("friendConnection", cb);
+    }
+    onFriendInfo(cb) {
+        this.#events.on("friendInfo", cb);
+    }
+    friends() {
+        return [...this.#friends.values()];
+    }
+    waitForFriendRequest(timeoutMs = 30000) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error(`timed out waiting for friend request after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const onRequest = (request) => {
+                cleanup();
+                resolve(request);
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                this.#events.off("friendRequest", onRequest);
+            };
+            this.#events.on("friendRequest", onRequest);
+        });
+    }
+    /**
+     * Bridge for inbound TCP-relayed packets. The relay forwards the
+     * exact bytes the friend sent (cookie request/response, handshake,
+     * crypto data) — same wire format as UDP minus the iveg magic
+     * prefix (the relay strips its own framing). We re-use the existing
+     * UDP datagram dispatch by synthesizing a remote whose `address`
+     * starts with `tcp:` so downstream code can recognize the origin
+     * and avoid setting `session.remote` to a UDP-shaped value.
+     */
+    #handleTcpDatagram(friendKey, payload) {
+        const friendId = carrierIdFromPublicKey(friendKey);
+        // Mark the session as TCP-routed if we don't have it yet.
+        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.
+        this.#onDatagram({
+            data: Buffer.from(payload),
+            remote: { address: `tcp:${friendId}`, port: 0 }
+        });
+    }
+    /** True when the synthetic remote was constructed by #handleTcpDatagram. */
+    #remoteIsTcp(remote) {
+        return remote.address.startsWith("tcp:");
+    }
+    #onDatagram = ({ data, remote }) => {
+        if (!this.#keyPair) {
+            return;
+        }
+        const packet = stripCarrierMagic(data);
+        if (packet.length === 0) {
+            return;
+        }
+        this.#tracePacket("rx", packet, { host: remote.address, port: remote.port });
+        if (packet[0] === NET_PACKET_CRYPTO) {
+            const opened = openToxDhtCryptoRequest(packet, this.#keyPair);
+            if (!opened) {
+                return;
+            }
+            if (opened.requestId === CRYPTO_PACKET_DHTPK) {
+                this.#handleOnionDhtPk(opened.senderPublicKey, opened.data);
+                return;
+            }
+            if (opened.requestId !== CRYPTO_PACKET_FRIEND_REQ) {
+                return;
+            }
+            const friendRequest = splitFriendRequestPayload(opened.data);
+            if (!friendRequest) {
+                this.#debugLog(`direct friend request payload decode failed from ${remote.address}:${remote.port}`);
+                return;
+            }
+            this.#emitFriendRequest(opened.senderPublicKey, friendRequest.carrierPacket, friendRequest.nospam);
+            return;
+        }
+        if (packet[0] === NET_PACKET_COOKIE_REQUEST && this.#cookieSymmetricKey) {
+            const request = openCookieRequest(packet, {
+                receiverDhtSecretKey: this.#keyPair.secretKey
+            });
+            if (!request) {
+                this.#debugLog(`cookie request parse failed from ${remote.address}:${remote.port}`);
+                return;
+            }
+            const senderId = carrierIdFromPublicKey(request.senderRealPublicKey);
+            const fromTcp = this.#remoteIsTcp(remote);
+            this.#debugLog(`cookie request received from ${senderId} via ${remote.address}:${remote.port}${fromTcp ? " (tcp)" : ""}`);
+            // Cache friend's known UDP endpoint only when this came over UDP.
+            // For TCP-routed cookie requests the synthetic "tcp:<id>:0" remote
+            // would otherwise poison the UDP send-back path.
+            if (!fromTcp) {
+                this.#cacheFriendRemote(senderId, remote.address, remote.port, request.senderRealPublicKey, request.senderDhtPublicKey);
+            }
+            const response = createCookieResponse({
+                request,
+                receiverDhtSecretKey: this.#keyPair.secretKey,
+                receiverCookieSymmetricKey: this.#cookieSymmetricKey
+            });
+            if (fromTcp) {
+                // Reply via TCP relay OOB_SEND. The relay forwards as OOB_RECV
+                // to the destination. **Critical**: the relay routes OOB by
+                // the destination's DHT pubkey (= the pubkey they handshook
+                // the relay with), NOT by their real pubkey. iOS Beagle peers
+                // use a different DHT pk than real pk (real "7se1FY..." vs
+                // DHT "GgAxwFFP..."). If we send OOB to the real pk the
+                // relay's lookup table misses and the response is silently
+                // dropped — iOS then keeps re-sending the cookie request
+                // forever (observed in real testing as 6+ duplicate
+                // tcp_oob_recv lines with no hs_recv follow-up).
+                const sent = this.#tcpRelays?.sendOobToFriend(request.senderDhtPublicKey, response) ?? 0;
+                if (sent > 0) {
+                    this.#debugLog(`cookie response sent via tcp_oob to ${senderId} dhtpk=${carrierIdFromPublicKey(request.senderDhtPublicKey)} (relays=${sent})`);
+                }
+                else {
+                    this.#debugLog(`cookie response: no tcp relay accepted oob send for ${senderId}`);
+                }
+            }
+            else {
+                void this.#sendPacket(response, { host: remote.address, port: remote.port })
+                    .then(() => {
+                    this.#debugLog(`cookie response sent to ${remote.address}:${remote.port}`);
+                })
+                    .catch((error) => {
+                    this.#debugLog(`cookie response send failed: ${error.message}`);
+                });
+            }
+            return;
+        }
+        if (packet[0] === NET_PACKET_COOKIE_RESPONSE) {
+            // Match cookie response by successful decrypt + echo, not by guessed
+            // endpoint. Friends may reply from a different port than we targeted.
+            let matchedFriendId;
+            let matchedSession;
+            let opened;
+            for (const [friendId, session] of this.#friendSessions) {
+                if (!session.friendRealPublicKey) {
+                    continue;
+                }
+                // Allow currently-pending echo OR any echo from the recent history
+                // (last 30s). This prevents losing legitimate cookie responses when
+                // the friend connection loop rotated to a new echo while a LAN
+                // sweep response was in flight from the old echo.
+                const hasPending = session.pendingEcho !== undefined;
+                const recent = session.recentEchoes;
+                if (!hasPending && (!recent || recent.size === 0)) {
+                    continue;
+                }
+                const responsePeerDhtKey = session.pendingCookiePeerDhtPublicKey ?? session.friendDhtPublicKey;
+                if (!responsePeerDhtKey) {
+                    continue;
+                }
+                const candidate = openCookieResponse(packet, {
+                    receiverDhtPublicKey: responsePeerDhtKey,
+                    senderDhtSecretKey: this.#keyPair.secretKey
+                });
+                if (!candidate) {
+                    continue;
+                }
+                const echoMatches = (hasPending && candidate.echo === session.pendingEcho) ||
+                    (recent !== undefined && recent.has(candidate.echo));
+                if (!echoMatches) {
+                    continue;
+                }
+                matchedFriendId = friendId;
+                matchedSession = session;
+                opened = candidate;
+                break;
+            }
+            if (!matchedFriendId || !matchedSession || !opened) {
+                this.#debugLog(`cookie response from ${remote.address}:${remote.port} ignored — no echo/key match`);
+                return;
+            }
+            if (!matchedSession.friendRealPublicKey) {
+                this.#debugLog(`cookie response from ${remote.address}:${remote.port} ignored — missing friend real key`);
+                return;
+            }
+            this.#debugLog(`cookie_recv friend=${matchedFriendId} from=${remote.address}:${remote.port} sending_handshake=1`);
+            // Successful cookie round-trip — drop backoff so any subsequent reconnect
+            // returns to the snappy 8s base cooldown instead of carrying forward
+            // however many unmatched attempts we accumulated while reaching this
+            // friend.
+            this.#cookieRetryCount.delete(matchedFriendId);
+            // Send our 0x1a CRYPTO_HS using the cookie peer just gave us
+            const handshake = createCryptoHandshake({
+                recipientCookie: opened.cookie,
+                baseNonce: matchedSession.ourBaseNonce,
+                sessionPublicKey: matchedSession.ourSessionKeyPair.publicKey,
+                senderRealSecretKey: this.#keyPair.secretKey,
+                senderRealPublicKey: this.#keyPair.publicKey,
+                senderDhtPublicKey: this.#keyPair.publicKey,
+                receiverRealPublicKey: matchedSession.friendRealPublicKey,
+                receiverDhtPublicKey: matchedSession.friendDhtPublicKey ?? matchedSession.friendRealPublicKey,
+                localCookieSymmetricKey: this.#cookieSymmetricKey
+            });
+            matchedSession.handshakeSentMs = Date.now();
+            matchedSession.pendingEcho = undefined;
+            matchedSession.pendingCookiePeerDhtPublicKey = undefined;
+            // Only update session.remote (a UDP endpoint) when the cookie
+            // response actually arrived via UDP. TCP-routed responses come
+            // with a synthetic remote like `tcp:<friendId>:0` and must not
+            // poison the UDP send-back path.
+            const fromTcp = this.#remoteIsTcp(remote);
+            if (!fromTcp) {
+                matchedSession.remote = { host: remote.address, port: remote.port };
+            }
+            else {
+                matchedSession.hasTcpRoute = true;
+            }
+            // Send the handshake reply via whichever transport the cookie
+            // response arrived on.
+            // For TCP: send via BOTH the routed DATA frame AND the OOB path.
+            // The DATA frame is the canonical channel but requires the relay's
+            // cid (CONNECTION_NOTIFICATION) to already be established. During
+            // simultaneous mutual initiation, the cid setup races against the
+            // handshake send — when it loses the race, the DATA frame is dropped
+            // and the session stalls. Sending OOB in parallel guarantees delivery
+            // even in that race, since handshake (0x1a) is a permitted OOB kind.
+            const sendHandshake = async () => {
+                if (fromTcp) {
+                    let dataOk = false;
+                    try {
+                        await this.#sendToFriend(matchedFriendId, handshake);
+                        dataOk = true;
+                    }
+                    catch {
+                        // ignore — fall through to OOB
+                    }
+                    let oobSent = 0;
+                    if (this.#tcpRelays && matchedSession.friendDhtPublicKey) {
+                        oobSent = this.#tcpRelays.sendOobToFriend(matchedSession.friendDhtPublicKey, handshake);
+                    }
+                    if (!dataOk && oobSent === 0) {
+                        throw new Error("handshake send failed via both data and oob paths");
+                    }
+                    return `tcp:${matchedFriendId}${dataOk ? " (data)" : ""}${oobSent > 0 ? ` (oob×${oobSent})` : ""}`;
+                }
+                await this.#sendPacket(handshake, matchedSession.remote);
+                return `${matchedSession.remote.host}:${matchedSession.remote.port}`;
+            };
+            void sendHandshake()
+                .then((dest) => {
+                this.#debugLog(`hs_sent friend=${matchedFriendId} to=${dest}`);
+            })
+                .catch((error) => {
+                this.#debugLog(`crypto handshake send failed: ${error.message}`);
+            });
+            return;
+        }
+        if (packet[0] === NET_PACKET_CRYPTO_HS && this.#cookieSymmetricKey) {
+            const hs = openCryptoHandshake(packet, {
+                receiverRealSecretKey: this.#keyPair.secretKey,
+                receiverCookieSymmetricKey: this.#cookieSymmetricKey
+            });
+            if (!hs) {
+                this.#debugLog(`crypto handshake parse failed from ${remote.address}:${remote.port}`);
+                return;
+            }
+            const friendId = carrierIdFromPublicKey(hs.senderRealPublicKey);
+            let state = this.#friendSessions.get(friendId);
+            // Detect whether we initiated: if we have a session in cookie_requested or handshake_sent state
+            const weInitiated = state !== undefined && state.handshakeSentMs !== undefined;
+            // Duplicate handshake fast path: if we already have an established
+            // session with this peer AND the new handshake carries the same
+            // peer session public key as the one we already accepted, this is
+            // an in-flight retransmission from the peer (UDP loss). Refresh
+            // the remote endpoint and lastPingRecvMs but DO NOT reset session
+            // keys, base nonces, or packet counters — doing so would discard
+            // any net_crypto state we built up after the first handshake and
+            // make subsequent crypto data fail to decrypt on either side.
+            if (state &&
+                state.established &&
+                state.peerSessionPublicKey &&
+                bytesEqual(state.peerSessionPublicKey, hs.sessionPublicKey)) {
+                if (this.#remoteIsTcp(remote)) {
+                    state.hasTcpRoute = true;
+                }
+                else {
+                    state.remote = { host: remote.address, port: remote.port };
+                }
+                state.lastPingRecvMs = Date.now();
+                this.#debugVerboseLog(`hs_recv duplicate friend=${friendId} remote=${remote.address}:${remote.port} (session preserved)`);
+                return;
+            }
+            if (!state) {
+                state = {
+                    ourSessionKeyPair: createEphemeralKeyPair(),
+                    ourBaseNonce: randomBytes(24),
+                    friendRealPublicKey: hs.senderRealPublicKey,
+                    friendDhtPublicKey: hs.senderDhtPublicKey
+                };
+                this.#friendSessions.set(friendId, state);
+            }
+            else {
+                if (!state.friendRealPublicKey)
+                    state.friendRealPublicKey = hs.senderRealPublicKey;
+                if (!state.friendDhtPublicKey)
+                    state.friendDhtPublicKey = 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
+            // that happens, BOTH sides start their packet-number counter
+            // back at 0 — the encryption ties packet_number into the nonce
+            // (sentNonce ⊕ packet_number low bytes), so if we keep our
+            // counter from the previous session, our crypto data packets
+            // arrive at iPad with a packet_number iPad's reset state
+            // doesn't expect, and iPad drops them as out-of-window.
+            // Observed in real iPad testing as "I see your `got: Hi` and
+            // `got: Offline` but not your reply to my next message." —
+            // the in-session sends after a session refresh were silently
+            // rejected by iPad's net_crypto sliding-ack-window check.
+            const prevPeerSessionPk = state.peerSessionPublicKey;
+            const isNewSession = !prevPeerSessionPk || !bytesEqual(prevPeerSessionPk, hs.sessionPublicKey);
+            // Reject handshakes proposing a different session pubkey while we
+            // already have an established session. The cookie embedded in
+            // every handshake is freshly issued (it's a response to that very
+            // exchange's cookie REQUEST), so it isn't a reliable freshness
+            // signal — and toxcore explicitly *doesn't* accept new keys while
+            // ACCEPTED. The path back to a legitimate reinitiation is:
+            // peer→stops sending ALIVE→we time out at 32s→delete session→next
+            // handshake creates a fresh shell. That's slow but correct; the
+            // alternative (blindly accepting) corrupts the current session
+            // and silently breaks CRYPTO_DATA decryption (observed in
+            // stability test as oscillating peerSessionPub and continuous
+            // "crypto data received but no session matched").
+            //
+            // The retained `sessionEstablishedAtMs` is still useful for the
+            // 1s grace below: very-fresh sessions can accept an in-flight
+            // late handshake from a parallel cookie chain, since that's part
+            // of normal symmetric-initiation convergence rather than a stale
+            // replay.
+            if (state.established &&
+                isNewSession &&
+                state.sessionEstablishedAtMs !== undefined) {
+                const sinceEstablished = Date.now() - state.sessionEstablishedAtMs;
+                if (sinceEstablished > 1000) {
+                    // Verbose only — peers retransmit handshakes aggressively, so
+                    // this line fires dozens of times per minute on a stuck pair
+                    // and drowns out signal. Visible with DECENT_DEBUG_VERBOSE=1.
+                    this.#debugVerboseLog(`hs_recv ignored friend=${friendId} (new session pubkey on established session, ${sinceEstablished}ms after establish)`);
+                    return;
+                }
+            }
+            state.peerSessionPublicKey = hs.sessionPublicKey;
+            state.peerBaseNonce = hs.baseNonce.slice();
+            state.sessionSharedKey = nacl.box.before(hs.sessionPublicKey, state.ourSessionKeyPair.secretKey);
+            state.established = true;
+            state.sessionEstablishedAtMs = Date.now();
+            if (this.#remoteIsTcp(remote)) {
+                state.hasTcpRoute = true;
+                // Don't set state.remote — there's no UDP endpoint for this peer.
+            }
+            else {
+                state.remote = { host: remote.address, port: remote.port };
+            }
+            if (isNewSession) {
+                state.sendPacketNumber = 0;
+                state.receiveBufferStart = 0;
+            }
+            else {
+                state.sendPacketNumber ??= 0;
+                state.receiveBufferStart ??= 0;
+            }
+            state.lastPingRecvMs = Date.now();
+            state.pendingEcho = undefined;
+            state.pendingCookiePeerDhtPublicKey = undefined;
+            this.#debugLog(`hs_recv friend=${friendId} initiated=${weInitiated ? 1 : 0} remote=${remote.address}:${remote.port}`);
+            if (!wasEstablished) {
+                this.#debugLog(`friend_connected friend=${friendId} remote=${remote.address}:${remote.port}`);
+            }
+            const friend = this.#friends.get(friendId);
+            if (friend) {
+                // Once we've established a real session with this peer, they are
+                // "accepted" forever — even if the session later drops. Without
+                // this `acceptedAt` mark, every restart of the demo with the same
+                // DECENT_FRIEND_ADDRESS would re-fire `sendFriendRequest`, since
+                // `#recordOutgoingFriendRequest` only suppresses dupes when the
+                // record has `status === "online"` (transient) OR `acceptedAt`
+                // (persistent). iOS would see the duplicate friend request as a
+                // "friend changed nospam" / re-add prompt; we want it silent.
+                this.#friends.set(friendId, {
+                    ...friend,
+                    status: "online",
+                    acceptedAt: friend.acceptedAt ?? Date.now(),
+                    remoteHost: remote.address,
+                    remotePort: remote.port
+                });
+                this.#persistFriends();
+            }
+            // Only emit the friendConnection: connected event on the first
+            // transition from disconnected -> connected. Re-firing it on each
+            // retransmitted handshake produces noisy "friend connection ...
+            // connected" lines in the user's app callbacks.
+            if (!wasEstablished) {
+                this.#events.emit("friendConnection", {
+                    pubkey: friendId,
+                    status: "connected"
+                });
+            }
+            // Only send a reply handshake when the peer initiated.
+            // Otherwise we already sent ours during the cookie response handler.
+            if (!weInitiated) {
+                const reply = createCryptoHandshake({
+                    recipientCookie: hs.embeddedCookie,
+                    baseNonce: state.ourBaseNonce,
+                    sessionPublicKey: state.ourSessionKeyPair.publicKey,
+                    senderRealSecretKey: this.#keyPair.secretKey,
+                    senderRealPublicKey: this.#keyPair.publicKey,
+                    senderDhtPublicKey: this.#keyPair.publicKey,
+                    receiverRealPublicKey: hs.senderRealPublicKey,
+                    receiverDhtPublicKey: hs.senderDhtPublicKey,
+                    localCookieSymmetricKey: this.#cookieSymmetricKey
+                });
+                const replyFromTcp = this.#remoteIsTcp(remote);
+                const sendReply = () => {
+                    if (replyFromTcp) {
+                        // OOB reply must go to the DHT pubkey (relay routing key),
+                        // not the real pubkey — see the cookie response handler
+                        // above for the full explanation.
+                        const sent = this.#tcpRelays?.sendOobToFriend(hs.senderDhtPublicKey, reply) ?? 0;
+                        return Promise.resolve(sent);
+                    }
+                    return this.#sendPacket(reply, { host: remote.address, port: remote.port });
+                };
+                void sendReply()
+                    .then(() => {
+                    this.#debugLog(`crypto handshake reply sent to ${friendId}${replyFromTcp ? " (tcp)" : ""}`);
+                    void this.#sendMessengerPacket(friendId, PACKET_ID_ONLINE, new Uint8Array()).catch((error) => {
+                        this.#debugLog(`send online packet failed: ${error.message}`);
+                    });
+                })
+                    .catch((error) => {
+                    this.#debugLog(`crypto handshake reply failed: ${error.message}`);
+                });
+            }
+            else {
+                // We initiated and just received the peer's reply. Send PACKET_ID_ONLINE now.
+                void this.#sendMessengerPacket(friendId, PACKET_ID_ONLINE, new Uint8Array()).catch((error) => {
+                    this.#debugLog(`send online packet failed: ${error.message}`);
+                });
+            }
+            return;
+        }
+        if (packet[0] === NET_PACKET_CRYPTO_DATA) {
+            for (const [friendId, state] of this.#friendSessions.entries()) {
+                if (!state.sessionSharedKey || !state.peerBaseNonce) {
+                    continue;
+                }
+                const opened = openCryptoDataPacket(packet, {
+                    sessionSharedKey: state.sessionSharedKey,
+                    recvBaseNonce: state.peerBaseNonce
+                });
+                if (!opened) {
+                    continue;
+                }
+                state.peerBaseNonce[state.peerBaseNonce.length - 2] = packet[1];
+                state.peerBaseNonce[state.peerBaseNonce.length - 1] = packet[2];
+                incrementNonce(state.peerBaseNonce);
+                state.lastPingRecvMs = Date.now();
+                // Same TCP-vs-UDP rule as the handshake handlers: don't poison
+                // the UDP send-back endpoint when this packet came in via TCP.
+                if (this.#remoteIsTcp(remote)) {
+                    state.hasTcpRoute = true;
+                }
+                else {
+                    state.remote = { host: remote.address, port: remote.port };
+                }
+                state.receiveBufferStart = Math.max(state.receiveBufferStart ?? 0, (opened.packetNumber + 1) >>> 0);
+                const kind = opened.payload[0];
+                const inner = opened.payload.slice(1);
+                if (kind === PACKET_ID_ONLINE) {
+                    this.#setFriendOnline(friendId, remote.address, remote.port);
+                    this.#debugLog(`crypto online packet received from ${friendId}`);
+                    // First time the friend signals ONLINE, push our profile
+                    // (nickname + status message) and any configured greeting so the
+                    // other side updates "unknown" to a real name. Toxcore semantics:
+                    // these are sent on every reconnect by the friend_connection layer.
+                    this.#sendProfileAndGreeting(friendId);
+                    return;
+                }
+                if (kind === PACKET_ID_OFFLINE) {
+                    this.#setFriendOffline(friendId);
+                    this.#debugLog(`crypto offline packet received from ${friendId}`);
+                    return;
+                }
+                if (kind === PACKET_ID_KILL) {
+                    this.#friendSessions.delete(friendId);
+                    this.#setFriendOffline(friendId);
+                    this.#debugLog(`crypto kill received from ${friendId}, session torn down`);
+                    return;
+                }
+                if (kind === PACKET_ID_ALIVE) {
+                    // Pure liveness signal; lastPingRecvMs already updated above.
+                    this.#debugVerboseLog(`crypto alive (keepalive) received from ${friendId}`);
+                    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)`);
+                    return;
+                }
+                if (kind === PACKET_ID_SHARE_RELAYS) {
+                    // Peer is sharing TCP relay endpoints they're connected to. We
+                    // don't have a TCP relay client yet, so cache nothing — just log.
+                    this.#debugVerboseLog(`crypto share-relays from ${friendId} (TCP relay client not implemented)`);
+                    return;
+                }
+                if (kind === PACKET_ID_NICKNAME) {
+                    const name = decodeUtf8Best(inner);
+                    const friend = this.#friends.get(friendId);
+                    if (friend && name && friend.name !== name) {
+                        this.#friends.set(friendId, { ...friend, name });
+                        this.#persistFriends();
+                        this.#events.emit("friendInfo", {
+                            pubkey: friendId,
+                            userid: friend.userid ?? friendId,
+                            name,
+                            description: friend.description
+                        });
+                    }
+                    this.#debugLog(`crypto nickname received from ${friendId}: "${name}"`);
+                    return;
+                }
+                if (kind === PACKET_ID_STATUSMESSAGE) {
+                    // Carrier C SDK wraps the user-profile in a FlatBuffers
+                    // PACKET_TYPE_USERINFO packet here (name + descr + gender + phone
+                    // + email + region + has_avatar). Some non-Carrier toxcore peers
+                    // may still send raw UTF-8, so try the FB decode first and fall
+                    // back to plain UTF-8 for compatibility.
+                    let userInfoName;
+                    let userInfoDescr;
+                    try {
+                        const decoded = decodeCarrierPacket(inner);
+                        if (decoded.type === PACKET_TYPE_USERINFO) {
+                            userInfoName = decoded.name;
+                            userInfoDescr = decoded.descr;
+                        }
+                    }
+                    catch {
+                        // Not a Carrier userinfo packet — fall through.
+                    }
+                    if (userInfoName !== undefined || userInfoDescr !== undefined) {
+                        const friend = this.#friends.get(friendId);
+                        const newName = userInfoName && userInfoName.length > 0 ? userInfoName : friend?.name;
+                        const newDescr = userInfoDescr ?? friend?.description;
+                        if (friend && (friend.name !== newName || friend.description !== newDescr)) {
+                            this.#friends.set(friendId, { ...friend, name: newName, description: newDescr });
+                            this.#persistFriends();
+                            this.#events.emit("friendInfo", {
+                                pubkey: friendId,
+                                userid: friend.userid ?? friendId,
+                                name: newName,
+                                description: newDescr
+                            });
+                        }
+                        this.#debugLog(`crypto userinfo received from ${friendId}: name="${userInfoName ?? ""}" descr="${userInfoDescr ?? ""}"`);
+                    }
+                    else {
+                        const status = decodeUtf8Best(inner);
+                        const friend = this.#friends.get(friendId);
+                        if (friend && status && friend.description !== status) {
+                            this.#friends.set(friendId, { ...friend, description: status });
+                            this.#persistFriends();
+                        }
+                        this.#debugVerboseLog(`crypto status message (raw) received from ${friendId}: "${status}"`);
+                    }
+                    return;
+                }
+                if (kind === PACKET_ID_USERSTATUS) {
+                    this.#debugVerboseLog(`crypto user-status received from ${friendId} (${inner[0] ?? "?"})`);
+                    return;
+                }
+                if (kind === PACKET_ID_TYPING) {
+                    this.#debugVerboseLog(`crypto typing received from ${friendId} (${inner[0] ?? "?"})`);
+                    return;
+                }
+                if (kind === PACKET_ID_MESSAGE || kind === PACKET_ID_ACTION) {
+                    // Plain text inside (no Carrier FlatBuffers wrapper). Some peers
+                    // send raw UTF-8, others send a Carrier message packet — try both.
+                    let text = tryDecodeCarrierMessagePacket(inner) ?? decodeUtf8Best(inner);
+                    if (!text) {
+                        this.#debugLog(`crypto message packet decode failed from ${friendId}`);
+                        return;
+                    }
+                    this.#setFriendOnline(friendId, remote.address, remote.port);
+                    this.#events.emit("text", {
+                        pubkey: friendId,
+                        text
+                    });
+                    this.#debugLog(`crypto ${kind === PACKET_ID_ACTION ? "action" : "message"} from ${friendId}: "${text}"`);
+                    return;
+                }
+                this.#debugVerboseLog(`unknown messenger packet kind ${kind} from ${friendId}`);
+                return;
+            }
+            this.#debugLog(`crypto data received from ${remote.address}:${remote.port} but no session matched`);
+            return;
+        }
+        if (packet[0] === NET_PACKET_ONION_DATA_RESPONSE && this.#announceDataKey) {
+            this.#debugLog("onion data response received");
+            const routed = openOnionDataResponse(packet, {
+                dataSecretKey: this.#announceDataKey.secretKey
+            });
+            if (!routed) {
+                this.#debugLog("onion data response decrypt failed");
+                return;
+            }
+            const onionData = openOnionDataPacket(routed.payload, {
+                receiverSecretKey: this.#keyPair.secretKey,
+                nonce: routed.nonce
+            });
+            if (!onionData) {
+                this.#debugLog("onion friend request payload decrypt failed");
+                return;
+            }
+            if (onionData.innerPacketId !== ONION_FRIEND_REQUEST_ID) {
+                if (onionData.innerPacketId === CRYPTO_PACKET_DHTPK) {
+                    this.#handleOnionDhtPk(onionData.senderPublicKey, onionData.innerPayload);
+                    return;
+                }
+                const previewLen = Math.min(48, onionData.innerPayload.length);
+                const previewHex = Buffer.from(onionData.innerPayload.slice(0, previewLen)).toString("hex");
+                const senderId = carrierIdFromPublicKey(onionData.senderPublicKey);
+                this.#debugLog(`onion data response ignored innerPacketId=${onionData.innerPacketId} ` +
+                    `sender=${senderId} payloadLen=${onionData.innerPayload.length} ` +
+                    `payloadPreviewHex=${previewHex}`);
+                return;
+            }
+            const friendRequest = splitFriendRequestPayload(onionData.innerPayload);
+            if (!friendRequest) {
+                this.#debugLog("onion friend request payload decode failed");
+                return;
+            }
+            this.#emitFriendRequest(onionData.senderPublicKey, friendRequest.carrierPacket, friendRequest.nospam);
+        }
+    };
+    #handleOnionDhtPk(senderPublicKey, payload) {
+        const senderId = carrierIdFromPublicKey(senderPublicKey);
+        if (payload.length < 8 + 32) {
+            this.#debugLog(`onion dhtpk payload too short from ${senderId}: len=${payload.length}`);
+            return;
+        }
+        const noReplay = readUint64BE(payload, 0);
+        const friendDhtPublicKey = payload.slice(8, 40);
+        const extra = payload.slice(40);
+        const extraPreview = Buffer.from(extra.slice(0, Math.min(48, extra.length))).toString("hex");
+        let extraNodes = parsePackedNodes(extra);
+        // Some tox-compatible peers include encrypted endpoint hints in the DHTPK
+        // payload tail: nonce (24 bytes) + crypto_box ciphertext.
+        if (extraNodes.length === 0 && this.#keyPair && extra.length > 24 + 16) {
+            const nonce = extra.slice(0, 24);
+            const encrypted = extra.slice(24);
+            const openedBySender = nacl.box.open(encrypted, nonce, senderPublicKey, this.#keyPair.secretKey);
+            if (openedBySender) {
+                const decryptedNodes = parsePackedNodes(openedBySender);
+                if (decryptedNodes.length > 0) {
+                    extraNodes = decryptedNodes;
+                    this.#debugLog(`onion dhtpk decrypted extra using sender key; nodes=${decryptedNodes.length}`);
+                }
+            }
+            if (extraNodes.length === 0) {
+                const openedByDhtPk = nacl.box.open(encrypted, nonce, friendDhtPublicKey, this.#keyPair.secretKey);
+                if (openedByDhtPk) {
+                    const decryptedNodes = parsePackedNodes(openedByDhtPk);
+                    if (decryptedNodes.length > 0) {
+                        extraNodes = decryptedNodes;
+                        this.#debugLog(`onion dhtpk decrypted extra using dht key; nodes=${decryptedNodes.length}`);
+                    }
+                }
+            }
+        }
+        // Treat DHTPK as a liveness/accept signal from existing friend and use any
+        // endpoint hints in the payload to attempt net_crypto session bring-up.
+        const friend = this.#friends.get(senderId);
+        if (!friend) {
+            return;
+        }
+        let session = this.#friendSessions.get(senderId);
+        if (!session) {
+            session = {
+                ourSessionKeyPair: createEphemeralKeyPair(),
+                ourBaseNonce: randomBytes(24)
+            };
+            this.#friendSessions.set(senderId, session);
+        }
+        if (session.lastDhtPkNoReplay !== undefined && noReplay <= session.lastDhtPkNoReplay) {
+            this.#debugLog(`onion dhtpk replay/old packet ignored from ${senderId} noReplay=${noReplay.toString()}`);
+            return;
+        }
+        session.lastDhtPkNoReplay = noReplay;
+        session.friendRealPublicKey ??= senderPublicKey;
+        session.friendDhtPublicKey = 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
+        // are no-ops (otherwise the demo's retry loop keeps re-POSTing the
+        // request to express, which iOS Beagle re-displays as a new
+        // "pending" notification each time, even though the user has
+        // already accepted on their device).
+        if (friend.status === "requested" && !friend.acceptedAt) {
+            this.#friends.set(senderId, {
+                ...friend,
+                status: "offline",
+                acceptedAt: Date.now()
+            });
+            this.#persistFriends();
+            this.#debugLog(`friend ${senderId} accepted (proof: dhtpk_update); will stop re-sending friend request`);
+        }
+        const friendDhtId = carrierIdFromPublicKey(friendDhtPublicKey);
+        const knownMatch = this.#knownNodes.find((node) => node.pk === friendDhtId || node.pk === senderId);
+        if (knownMatch) {
+            this.#cacheFriendRemote(senderId, knownMatch.host, knownMatch.port, senderPublicKey, friendDhtPublicKey);
+            this.#debugLog(`onion dhtpk matched known node for ${senderId} at ${knownMatch.host}:${knownMatch.port}`);
+        }
+        this.#debugLog(`dhtpk_update friend=${senderId} noReplay=${noReplay.toString()} ` +
+            `dhtpk=${carrierIdFromPublicKey(friendDhtPublicKey)} extraLen=${extra.length} ` +
+            `extraNodes=${extraNodes.length} extraPreviewHex=${extraPreview}`);
+        if (extraNodes.length > 0) {
+            for (const candidate of extraNodes) {
+                if (candidate.isTcp) {
+                    // iPad/iOS Beagle peers advertise their reachable TCP relays
+                    // here (every entry has family = 0x82). Add each to our pool
+                    // so we end up on shared relays — without this, even though
+                    // both sides are willing to use TCP, we'd never overlap and
+                    // sessions would never come up via the relay path.
+                    if (this.#tcpRelays) {
+                        this.#tcpRelays.addRelay(candidate);
+                        // ROUTING_REQUEST must use the friend's DHT pubkey (= the
+                        // pubkey they handshook the relay with), NOT their real
+                        // friend identity pubkey. The relay's connection table is
+                        // keyed by handshake pubkey. iOS Beagle uses different
+                        // keys for DHT vs friend identity (real "7se1FY..." vs
+                        // DHT "GgAxwFFP...") so requesting route for the real
+                        // pubkey would silently mismatch and the relay would never
+                        // link us. Friend's DHT pubkey is in the inbound announce
+                        // payload (already parsed above as friendDhtPublicKey).
+                        this.#tcpRelays.requestRoute(friendDhtPublicKey);
+                    }
+                }
+                else {
+                    this.#cacheFriendRemote(senderId, candidate.host, candidate.port, senderPublicKey, friendDhtPublicKey);
+                }
+            }
+        }
+        void this.#initiateSession(senderId).catch((error) => {
+            this.#debugLog(`onion dhtpk initiate session failed for ${senderId}: ${error.message}`);
+        });
+        void this.#discoverAndCacheFriendEndpoint(senderId, friendDhtPublicKey).then((found) => {
+            if (!found) {
+                return this.#discoverAndCacheFriendEndpoint(senderId, senderPublicKey);
+            }
+            return Promise.resolve(true);
+        }).then((found) => {
+            if (!found) {
+                return;
+            }
+            void this.#initiateSession(senderId).catch((error) => {
+                this.#debugLog(`friend endpoint discovery initiate failed for ${senderId}: ${error.message}`);
+            });
+        }).catch((error) => {
+            this.#debugLog(`friend endpoint discovery failed for ${senderId}: ${error.message}`);
+        });
+    }
+    #emitFriendRequest(senderPublicKey, carrierPacket, nospam) {
+        let hello = "";
+        let name = "";
+        let description = "";
+        try {
+            const decoded = decodeCarrierPacket(carrierPacket);
+            if (decoded.type !== PACKET_TYPE_FRIEND_REQUEST) {
+                return;
+            }
+            hello = decoded.hello;
+            name = decoded.name;
+            description = decoded.descr;
+        }
+        catch {
+            return;
+        }
+        const userid = carrierIdFromPublicKey(senderPublicKey);
+        // If we already have this peer as a friend, do not re-emit a friend
+        // request to the UI. Instead, treat the packet as a reconnection signal
+        // and ensure we attempt to re-establish a net_crypto session.
+        if (this.#friends.has(userid)) {
+            this.#debugLog(`friend request from existing friend ${userid} treated as reconnection signal`);
+            void this.#initiateSession(userid).catch((error) => {
+                this.#debugLog(`reconnect initiate session failed for ${userid}: ${error.message}`);
+            });
+            return;
+        }
+        if (this.#pendingFriendRequests.has(userid)) {
+            return;
+        }
+        const request = {
+            pubkey: userid,
+            userid,
+            nospam,
+            address: carrierAddressFromPublicKey(senderPublicKey, nospam),
+            name,
+            description,
+            hello
+        };
+        this.#pendingFriendRequests.set(userid, request);
+        this.#events.emit("friendInfo", {
+            pubkey: userid,
+            userid,
+            name,
+            description
+        });
+        this.#events.emit("friendRequest", request);
+    }
+    #emitOfflineFriendRequest(fromUserId, packet) {
+        let helloText = "";
+        let name = "";
+        let description = "";
+        try {
+            const decoded = decodeCarrierPacket(packet);
+            if (decoded.type !== PACKET_TYPE_FRIEND_REQUEST) {
+                return;
+            }
+            helloText = decoded.hello;
+            name = decoded.name;
+            description = decoded.descr;
+        }
+        catch {
+            return;
+        }
+        if (this.#pendingFriendRequests.has(fromUserId)) {
+            return;
+        }
+        const request = {
+            pubkey: fromUserId,
+            userid: fromUserId,
+            name,
+            description,
+            hello: helloText
+        };
+        this.#pendingFriendRequests.set(fromUserId, request);
+        this.#events.emit("friendInfo", {
+            pubkey: fromUserId,
+            userid: fromUserId,
+            name,
+            description
+        });
+        this.#events.emit("friendRequest", request);
+    }
+    #emitOfflineFriendMessage(fromUserId, packet) {
+        try {
+            const decoded = decodeCarrierPacket(packet);
+            if (decoded.type !== PACKET_TYPE_MESSAGE) {
+                return;
+            }
+            const text = new TextDecoder().decode(decoded.data);
+            // Implicit-acceptance handling: in toxcore there's no explicit
+            // "friend accept" packet. When peer A sends a friend request to
+            // peer B and B accepts, B silently adds A as a friend and tries to
+            // bring up a net_crypto session. If A is offline at that moment,
+            // B's first messages are queued by B's client and routed through
+            // the express offline relay. The first such message arriving at A
+            // *is* the proof that B accepted.
+            //
+            // Treat any offline message from a friend currently in "requested"
+            // state as implicit acceptance: stamp acceptedAt so we won't
+            // re-issue the friend request next run, demote to "offline" so
+            // the friend connection loop will start trying to establish a
+            // direct session, and immediately kick #sendOnionDhtPk so B
+            // learns our current endpoint.
+            const friend = this.#friends.get(fromUserId);
+            if (friend && friend.status === "requested" && !friend.acceptedAt) {
+                this.#friends.set(fromUserId, {
+                    ...friend,
+                    status: "offline",
+                    acceptedAt: Date.now()
+                });
+                this.#persistFriends();
+                this.#debugLog(`offline message from ${fromUserId} treated as implicit accept of our friend request; ` +
+                    `friend is now accepted, queueing DHT-PK announce`);
+                // Best-effort: try to send our DHT-PK to B so they can find our
+                // current UDP endpoint and switch from express to direct.
+                try {
+                    const realPk = base58ToBytes(fromUserId);
+                    if (realPk.length === 32) {
+                        this.#dhtPkSendCooldown.delete(fromUserId);
+                        void this.#sendOnionDhtPk(realPk).catch(() => { });
+                    }
+                }
+                catch {
+                    // Malformed pubkey, fall through.
+                }
+            }
+            this.#events.emit("text", { pubkey: fromUserId, text });
+        }
+        catch {
+            // Ignore invalid offline payloads.
+        }
+    }
+    async #discoverFriendRoutes(friendPublicKey) {
+        if (!this.#keyPair) {
+            throw new Error("Peer is not started");
+        }
+        const searchKey = createEphemeralKeyPair();
+        const routes = [];
+        const routeSeen = new Set();
+        const queue = dedupeNodes(this.#knownNodes.length > 0 ? this.#knownNodes : this.#opts.bootstrapNodes)
+            .filter((n) => !this.#isNodeBlacklisted(`${n.host}:${n.port}`))
+            .sort((a, b) => this.#nodeScore(`${b.host}:${b.port}`) - this.#nodeScore(`${a.host}:${a.port}`));
+        const friendId = carrierIdFromPublicKey(friendPublicKey);
+        const visited = new Set();
+        let attempts = 0;
+        const maxAttempts = MAX_FRIEND_ROUTE_ATTEMPTS;
+        // Drive the walk in waves: pick up to FRIEND_ROUTE_BATCH_SIZE candidates
+        // from the queue, fire announce step1 to all of them in parallel, then
+        // process the responses together (extracting routes + new candidates
+        // for the next wave). Mirrors toxcore's onion_client.c which keeps up
+        // to MAX_ONION_CLIENTS=8 in-flight requests at once instead of a
+        // strict sequential walk. Net effect on a typical ISP: full discovery
+        // drops from ~60s (12 × 5s sequential timeouts) to ~10s (one or two
+        // 4-10s parallel waves).
+        while (queue.length > 0 && attempts < maxAttempts && routes.length < 8) {
+            const batch = [];
+            while (queue.length > 0 && batch.length < FRIEND_ROUTE_BATCH_SIZE && attempts < maxAttempts) {
+                const node = queue.shift();
+                const nodeId = `${node.host}:${node.port}`;
+                if (visited.has(nodeId) || !node.pk) {
+                    continue;
+                }
+                visited.add(nodeId);
+                let nodePk;
+                try {
+                    nodePk = base58ToBytes(node.pk);
+                }
+                catch {
+                    continue;
+                }
+                if (nodePk.length !== 32) {
+                    continue;
+                }
+                attempts += 1;
+                batch.push({ node, nodePk, sendBack: randomBytes(8) });
+            }
+            if (batch.length === 0) {
+                break;
+            }
+            const zeroPing = new Uint8Array(32);
+            const settled = await Promise.allSettled(batch.map((c) => this.#sendAnnounceAndWait({
+                node: c.node,
+                nodePublicKey: c.nodePk,
+                senderPublicKey: searchKey.publicKey,
+                senderSecretKey: searchKey.secretKey,
+                pingId: zeroPing,
+                searchPublicKey: friendPublicKey,
+                dataPublicKey: new Uint8Array(32),
+                sendBack: c.sendBack,
+                allowDirectFallback: true,
+                attempts: FRIEND_ANNOUNCE_ATTEMPTS
+            })));
+            for (let i = 0; i < batch.length; i++) {
+                const candidate = batch[i];
+                const result = settled[i];
+                const nodeId = `${candidate.node.host}:${candidate.node.port}`;
+                const response1 = result.status === "fulfilled" ? result.value : undefined;
+                if (!response1) {
+                    this.#debugLog(`announce step1 no response from ${nodeId}`);
+                    continue;
+                }
+                this.#debugLog(`announce step1 response from ${nodeId} isStored=${response1.isStored}`);
+                if (response1.isStored === 1) {
+                    const routeKey = `${nodeId}:${Buffer.from(response1.pingOrDataPublicKey).toString("hex")}`;
+                    if (!routeSeen.has(routeKey)) {
+                        routeSeen.add(routeKey);
+                        routes.push({
+                            node: candidate.node,
+                            routePublicKey: response1.pingOrDataPublicKey
+                        });
+                        this.#debugLog(`route discovered via ${nodeId}`);
+                    }
+                }
+                const discovered = parsePackedNodes(response1.nodes);
+                if (discovered.length > 0) {
+                    this.#knownNodes = dedupeNodes([...this.#knownNodes, ...discovered]);
+                    for (const discoveredNode of discovered) {
+                        if (discoveredNode.pk === friendId) {
+                            this.#cacheFriendRemote(friendId, discoveredNode.host, discoveredNode.port, friendPublicKey, friendPublicKey);
+                        }
+                        const discoveredId = `${discoveredNode.host}:${discoveredNode.port}`;
+                        if (!visited.has(discoveredId) && !this.#isNodeBlacklisted(discoveredId)) {
+                            queue.push(discoveredNode);
+                        }
+                    }
+                }
+            }
+        }
+        return routes;
+    }
+    async #discoverAndCacheFriendEndpoint(friendId, searchPublicKey) {
+        if (!this.#keyPair) {
+            return false;
+        }
+        const targetId = carrierIdFromPublicKey(searchPublicKey);
+        const queue = dedupeNodes(this.#knownNodes.length > 0 ? this.#knownNodes : this.#opts.bootstrapNodes)
+            .filter((n) => !this.#isNodeBlacklisted(`${n.host}:${n.port}`))
+            .sort((a, b) => this.#nodeScore(`${b.host}:${b.port}`) - this.#nodeScore(`${a.host}:${a.port}`))
+            .slice(0, Math.max(8, Math.min(24, MAX_FRIEND_ROUTE_ATTEMPTS)));
+        const directKnown = queue.find((node) => node.pk === targetId);
+        if (directKnown) {
+            this.#cacheFriendRemote(friendId, directKnown.host, directKnown.port);
+            this.#debugLog(`friend endpoint matched known node for ${friendId} at ${directKnown.host}:${directKnown.port}`);
+            return true;
+        }
+        const visited = new Set();
+        for (const node of queue) {
+            const nodeId = `${node.host}:${node.port}`;
+            if (visited.has(nodeId) || !node.pk) {
+                continue;
+            }
+            visited.add(nodeId);
+            let nodePk;
+            try {
+                nodePk = base58ToBytes(node.pk);
+            }
+            catch {
+                continue;
+            }
+            if (nodePk.length !== 32) {
+                continue;
+            }
+            const sendBack = randomBytes(8);
+            const response1 = await this.#sendAnnounceAndWait({
+                node,
+                nodePublicKey: nodePk,
+                senderPublicKey: this.#keyPair.publicKey,
+                senderSecretKey: this.#keyPair.secretKey,
+                pingId: new Uint8Array(32),
+                searchPublicKey,
+                dataPublicKey: new Uint8Array(32),
+                sendBack,
+                allowDirectFallback: true,
+                attempts: 1
+            });
+            if (!response1) {
+                continue;
+            }
+            const response2 = await this.#sendAnnounceAndWait({
+                node,
+                nodePublicKey: nodePk,
+                senderPublicKey: this.#keyPair.publicKey,
+                senderSecretKey: this.#keyPair.secretKey,
+                pingId: response1.pingOrDataPublicKey,
+                searchPublicKey,
+                dataPublicKey: new Uint8Array(32),
+                sendBack,
+                allowDirectFallback: true,
+                attempts: 1
+            });
+            const responses = response2 ? [response1, response2] : [response1];
+            const discovered = responses.flatMap((resp) => parsePackedNodes(resp.nodes));
+            if (discovered.length > 0) {
+                this.#knownNodes = dedupeNodes([...this.#knownNodes, ...discovered]);
+            }
+            const exact = discovered.find((n) => n.pk === targetId);
+            if (exact) {
+                this.#cacheFriendRemote(friendId, exact.host, exact.port);
+                this.#debugLog(`friend endpoint discovered for ${friendId} at ${exact.host}:${exact.port}`);
+                return true;
+            }
+        }
+        return false;
+    }
+    async #announceSelfBestEffort(force = false, deadlineMs = Number.POSITIVE_INFINITY) {
+        if (!this.#keyPair || !this.#announceDataKey) {
+            return [];
+        }
+        const now = Date.now();
+        if (!force && now - this.#lastSelfAnnounceMs < 12000) {
+            return [];
+        }
+        this.#lastSelfAnnounceMs = now;
+        const storedNodes = [];
+        const targets = dedupeNodes(this.#knownNodes.length > 0 ? this.#knownNodes : this.#opts.bootstrapNodes)
+            .filter((n) => !this.#isNodeBlacklisted(`${n.host}:${n.port}`))
+            .sort((a, b) => this.#nodeScore(`${b.host}:${b.port}`) - this.#nodeScore(`${a.host}:${a.port}`))
+            .slice(0, MAX_SELF_ANNOUNCE_TARGETS);
+        const zeroPing = new Uint8Array(32);
+        const candidates = [];
+        for (const node of targets) {
+            if (!node.pk)
+                continue;
+            let nodePk;
+            try {
+                nodePk = base58ToBytes(node.pk);
+            }
+            catch {
+                continue;
+            }
+            if (nodePk.length !== 32)
+                continue;
+            candidates.push({ node, nodePk, sendBack: randomBytes(8) });
+        }
+        // Walk in waves — fire SELF_ANNOUNCE_BATCH_SIZE step1+step2 sequences
+        // in parallel per wave, then process. Toxcore's onion_client.c does
+        // up to MAX_ONION_CLIENTS_ANNOUNCE = 12 simultaneously, which lets it
+        // stabilize self-announce in ~10s on a healthy network. Old serial
+        // walk took (per-node-timeout × N targets × 2 steps) ≈ 16 × 5s × 2
+        // = 160s worst case before a single isStored=2 response.
+        for (let i = 0; i < candidates.length; i += SELF_ANNOUNCE_BATCH_SIZE) {
+            if (Date.now() >= deadlineMs) {
+                this.#debugLog("self announce stopped at deadline");
+                return storedNodes;
+            }
+            const wave = candidates.slice(i, i + SELF_ANNOUNCE_BATCH_SIZE);
+            // Fire all step1 requests in parallel.
+            const step1Settled = await Promise.allSettled(wave.map((c) => this.#sendAnnounceAndWait({
+                node: c.node,
+                nodePublicKey: c.nodePk,
+                senderPublicKey: this.#keyPair.publicKey,
+                senderSecretKey: this.#keyPair.secretKey,
+                pingId: zeroPing,
+                searchPublicKey: this.#keyPair.publicKey,
+                dataPublicKey: this.#announceDataKey.publicKey,
+                sendBack: c.sendBack,
+                allowDirectFallback: true,
+                attempts: SELF_ANNOUNCE_ATTEMPTS
+            })));
+            const step1Hits = [];
+            for (let j = 0; j < wave.length; j++) {
+                const r = step1Settled[j];
+                const c = wave[j];
+                const resp1 = r.status === "fulfilled" ? r.value : undefined;
+                if (!resp1) {
+                    this.#debugLog(`self announce step1 no response from ${c.node.host}:${c.node.port}`);
+                    continue;
+                }
+                this.#debugLog(`self announce step1 response from ${c.node.host}:${c.node.port} isStored=${resp1.isStored}`);
+                step1Hits.push({ c, resp1 });
+            }
+            const step2Settled = await Promise.allSettled(step1Hits.map(({ c, resp1 }) => this.#sendAnnounceAndWait({
+                node: c.node,
+                nodePublicKey: c.nodePk,
+                senderPublicKey: this.#keyPair.publicKey,
+                senderSecretKey: this.#keyPair.secretKey,
+                pingId: resp1.pingOrDataPublicKey,
+                searchPublicKey: this.#keyPair.publicKey,
+                dataPublicKey: this.#announceDataKey.publicKey,
+                sendBack: c.sendBack,
+                allowDirectFallback: true,
+                attempts: SELF_ANNOUNCE_ATTEMPTS
+            })));
+            for (let j = 0; j < step1Hits.length; j++) {
+                const { c, resp1 } = step1Hits[j];
+                const r2 = step2Settled[j];
+                const resp2 = r2.status === "fulfilled" ? r2.value : undefined;
+                const final = resp2 ?? resp1;
+                if (resp2) {
+                    this.#debugLog(`self announce step2 response from ${c.node.host}:${c.node.port} isStored=${resp2.isStored}`);
+                }
+                if (final.isStored === 2) {
+                    storedNodes.push(c.node);
+                }
+                const discovered = parsePackedNodes(final.nodes);
+                if (discovered.length > 0) {
+                    this.#knownNodes = dedupeNodes([...this.#knownNodes, ...discovered]);
+                }
+            }
+        }
+        return storedNodes;
+    }
+    #ensureSelfAnnounceLoop() {
+        if (this.#selfAnnounceTimer || SELF_ANNOUNCE_INTERVAL_MS <= 0) {
+            return;
+        }
+        this.#selfAnnounceTimer = setInterval(() => {
+            if (this.#selfAnnouncePauseDepth > 0) {
+                return;
+            }
+            if (this.#selfAnnouncePromise) {
+                return;
+            }
+            void this.#runSelfAnnounce(false, Date.now() + JOIN_ANNOUNCE_TIMEOUT_MS).catch((error) => {
+                this.#debugLog(`background self announce failed: ${error.message}`);
+            });
+        }, SELF_ANNOUNCE_INTERVAL_MS);
+        this.#selfAnnounceTimer.unref?.();
+    }
+    #ensureExpressPullLoop() {
+        if (!this.#express?.hasNodes() || this.#expressPollTimer || EXPRESS_PULL_INTERVAL_MS <= 0) {
+            return;
+        }
+        const pull = () => {
+            void this.#express?.pullOnce().catch((error) => {
+                this.#debugLog(`express pull failed: ${error.message}`);
+            });
+        };
+        pull();
+        this.#expressPollTimer = setInterval(pull, EXPRESS_PULL_INTERVAL_MS);
+        this.#expressPollTimer.unref?.();
+    }
+    #ensureFriendConnectionLoop() {
+        if (this.#friendConnectionTimer) {
+            return;
+        }
+        // FRIEND_CONNECTION_LOOP_MS default 250ms (was 2000ms). Toxcore's
+        // reactive 50-1000ms tick is what makes iOS Beagle feel snappy —
+        // every "do this when X arrives" path (DHT-PK reply, cookie request
+        // scheduling, ROUTING_REQUEST after seeing a new relay) snaps to the
+        // tick. With 250ms we're 8× faster than before and within ~5× of
+        // toxcore's ideal. Configurable via DECENT_FRIEND_CONNECTION_LOOP_MS.
+        this.#friendConnectionTimer = setInterval(() => {
+            void this.#doFriendConnections().catch((error) => {
+                this.#debugLog(`friend connection loop failed: ${error.message}`);
+            });
+        }, FRIEND_CONNECTION_LOOP_MS);
+        this.#friendConnectionTimer.unref?.();
+    }
+    async #doFriendConnections() {
+        const now = Date.now();
+        for (const [friendId, friend] of this.#friends.entries()) {
+            const session = this.#friendSessions.get(friendId);
+            // Established session: keepalive + timeout monitoring
+            if (session?.established) {
+                if (session.lastPingRecvMs && now - session.lastPingRecvMs > FRIEND_TIMEOUT_MS) {
+                    this.#debugLog(`session timeout for ${friendId} (no ping in ${FRIEND_TIMEOUT_MS}ms)`);
+                    this.#friendSessions.delete(friendId);
+                    this.#setFriendOffline(friendId);
+                    continue;
+                }
+                if (!session.lastPingSentMs || now - session.lastPingSentMs > FRIEND_PING_INTERVAL_MS) {
+                    // Toxcore friend_connection.c::send_ping uses PACKET_ID_ALIVE (16),
+                    // not PACKET_ID_ONLINE (24). The peer's `ping_lastrecv` is only
+                    // updated by ALIVE packets; sending ONLINE repeatedly does not
+                    // refresh it, which is why iOS Beagle was timing out our session
+                    // after ~32 seconds even though our keepalive timer was firing.
+                    await this.#sendMessengerPacket(friendId, PACKET_ID_ALIVE, new Uint8Array()).catch(() => { });
+                }
+                if (session.remote && friend.status !== "online") {
+                    this.#setFriendOnline(friendId, session.remote.host, session.remote.port);
+                }
+                continue;
+            }
+            // No active session: tell the friend our DHT public key so they can
+            // find our UDP endpoint and initiate net_crypto from their side. This
+            // is the bidirectional partner of the inbound dhtpk_update flow — the
+            // toxcore Messenger.c::send_dht_public_key_to_friend periodic in C SDK.
+            // Without this, an iOS peer who just accepted our friend request has no
+            // way to learn our endpoint (their own DHT lookup against us only works
+            // if our self-announce stored, which is unreliable against the public
+            // bootstrap nodes). Per-friend cooldown via #dhtPkSendCooldown so we
+            // don't flood onion data requests every 5s loop tick.
+            const lastDhtPkSent = this.#dhtPkSendCooldown.get(friendId) ?? 0;
+            const dhtPkInterval = 25_000;
+            if (now - lastDhtPkSent > dhtPkInterval) {
+                let friendRealPk = session?.friendRealPublicKey;
+                if (!friendRealPk && friend.address) {
+                    try {
+                        friendRealPk = parseCarrierAddress(friend.address).publicKey;
+                    }
+                    catch {
+                        // Fall through; we'll try the userid form below.
+                    }
+                }
+                if (!friendRealPk && friend.pubkey) {
+                    try {
+                        friendRealPk = base58ToBytes(friend.pubkey);
+                    }
+                    catch {
+                        // Ignore malformed pubkey
+                    }
+                }
+                if (friendRealPk && friendRealPk.length === 32) {
+                    this.#dhtPkSendCooldown.set(friendId, now);
+                    void this.#sendOnionDhtPk(friendRealPk).catch((error) => {
+                        this.#debugLog(`dhtpk_send for ${friendId} failed: ${error.message}`);
+                    });
+                }
+            }
+            // No active session: try to establish one if we know the friend's endpoint.
+            // If we don't, the C++-initiated path can still bring up the session
+            // when peer reaches us — so this is only one of two ways to recover.
+            const haveEndpoint = (friend.remoteHost && friend.remotePort) || session?.remote;
+            if (!haveEndpoint) {
+                const dhtPk = session?.friendDhtPublicKey;
+                if (dhtPk) {
+                    const found = await this.#discoverAndCacheFriendEndpoint(friendId, dhtPk).catch(() => false);
+                    if (found) {
+                        void this.#initiateSession(friendId).catch((error) => {
+                            this.#debugLog(`friend connection loop: initiate after discovery failed for ${friendId}: ${error.message}`);
+                        });
+                    }
+                }
+                continue;
+            }
+            // Cooldown to avoid flooding cookie requests. Base is 8s; we apply
+            // exponential backoff per consecutive failure so unreachable persisted
+            // friends (e.g. an old simulator that's no longer running) don't keep
+            // hogging loop cycles. Capped so reachable friends still recover within
+            // a minute or two when the network is just slow.
+            const lastAttempt = session?.cookieRequestSentMs ?? session?.handshakeSentMs ?? 0;
+            const failures = this.#cookieRetryCount.get(friendId) ?? 0;
+            const baseCooldownMs = 8000;
+            const maxCooldownMs = 120_000;
+            const cooldownMs = Math.min(maxCooldownMs, baseCooldownMs * Math.pow(1.5, failures));
+            if (now - lastAttempt < cooldownMs) {
+                continue;
+            }
+            // Cookie has been pending without a response for a while: try a LAN
+            // sweep as a last resort. Covers iOS Simulator (loopback) and same-
+            // LAN peers whose actual address isn't in their DHT-PK extras.
+            //
+            // The sweep produces ~250 cookie-request probes per /24, which is
+            // expensive UDP traffic — we only want to fire it for friends that
+            // could plausibly be reachable on the LAN. After a few consecutive
+            // failures (cookie retry count, same metric used above for the
+            // request cooldown), we stop sweeping for the friend altogether so a
+            // long-dead persisted simulator entry doesn't burst 1000 probes/min
+            // into the local subnet forever.
+            const sweepBaseMs = 30_000;
+            const sweepMaxMs = 300_000;
+            const sweepCooldownMs = Math.min(sweepMaxMs, sweepBaseMs * Math.pow(1.5, Math.max(0, failures - 1)));
+            if (LAN_SWEEP_AFTER_MS > 0 &&
+                failures < 8 &&
+                session?.pendingEcho !== undefined &&
+                session.cookieRequestSentMs &&
+                now - session.cookieRequestSentMs > LAN_SWEEP_AFTER_MS &&
+                (session.lastLanSweepMs === undefined || now - session.lastLanSweepMs > sweepCooldownMs)) {
+                session.lastLanSweepMs = now;
+                void this.#sweepLanForCookieResponse(friendId).catch((error) => {
+                    this.#debugLog(`lan sweep failed for ${friendId}: ${error.message}`);
+                });
+                continue;
+            }
+            // Reset stale session state and re-initiate
+            if (session && !session.established) {
+                session.pendingEcho = undefined;
+                session.handshakeSentMs = undefined;
+            }
+            void this.#initiateSession(friendId).catch((error) => {
+                this.#debugLog(`friend connection loop: initiate failed for ${friendId}: ${error.message}`);
+            });
+        }
+    }
+    async #sendMessengerPacket(friendId, kind, data) {
+        const session = this.#friendSessions.get(friendId);
+        if (!session?.established || !session.sessionSharedKey || !session.ourBaseNonce) {
+            throw new Error(`friend session unavailable for ${friendId}`);
+        }
+        if (!session.remote && !session.hasTcpRoute) {
+            throw new Error(`friend session has no transport for ${friendId}`);
+        }
+        const payload = concatBytes([Uint8Array.of(kind & 0xff), data]);
+        const packetNumber = session.sendPacketNumber ?? 0;
+        const encrypted = createCryptoDataPacket({
+            sessionSharedKey: session.sessionSharedKey,
+            sentNonce: session.ourBaseNonce,
+            bufferStart: session.receiveBufferStart ?? 0,
+            packetNumber,
+            payload
+        });
+        incrementNonce(session.ourBaseNonce);
+        session.sendPacketNumber = (packetNumber + 1) >>> 0;
+        session.lastPingSentMs = Date.now();
+        await this.#sendToFriend(friendId, encrypted, session);
+    }
+    /**
+     * Send `packet` to `friendId` over whichever transport(s) are
+     * available. Tries UDP first when `session.remote` is set, then TCP
+     * relay if `session.hasTcpRoute` is true. Sending over both is fine
+     * — net_crypto's packet number / buffer_start logic dedups on the
+     * receiving end (toxcore does the same when both transports are up).
+     * Throws only if zero transports succeeded.
+     */
+    async #sendToFriend(friendId, packet, session) {
+        const s = session ?? this.#friendSessions.get(friendId);
+        let udpOk = false;
+        let tcpOk = false;
+        let firstError;
+        if (s?.remote) {
+            try {
+                await this.#sendPacket(packet, s.remote);
+                udpOk = true;
+            }
+            catch (error) {
+                firstError = error;
+            }
+        }
+        if (this.#tcpRelays) {
+            // The TCP relay routes by the friend's DHT pubkey (= the pubkey
+            // they handshook the relay with), not by the friend's real
+            // identity pubkey. iOS Beagle uses different keys for the two,
+            // and our cid table is populated against the DHT pubkey from
+            // ROUTING_REQUEST. Prefer DHT pk when available; fall back to
+            // real pk for peers where they match (older toxcore clients).
+            const tcpKey = s?.friendDhtPublicKey ?? s?.friendRealPublicKey;
+            if (tcpKey) {
+                // Routed DATA only — toxcore's tcp_oob_callback rejects
+                // CRYPTO_DATA (only handles 0x18 / 0x1a), so OOB fallback
+                // would silently drop on iPad's side and leave the session
+                // looking healthy on our side while iPad never sees the
+                // packets.
+                const sent = this.#tcpRelays.sendToFriend(tcpKey, packet);
+                if (sent > 0) {
+                    tcpOk = true;
+                }
+            }
+        }
+        if (!udpOk && !tcpOk) {
+            throw firstError ?? new Error(`no transport accepted send for ${friendId}`);
+        }
+    }
+    /**
+     * After a friend sends us PACKET_ID_ONLINE, push our nickname + status
+     * message so their UI replaces "unknown" with our actual display name,
+     * and optionally fire off a configured greeting message. Idempotent —
+     * tracked per friend so we don't spam every keepalive cycle.
+     *
+     * Sends are sequenced with small delays so the receiving peer's UI layer
+     * doesn't process three messenger packets in the same render frame —
+     * iOS Beagle 1.8.6 has a SwiftUI use-after-free in
+     * `_UIHostingView.beginTransaction()` when nickname / status / message
+     * arrive in rapid succession at session establishment, observed as
+     * EXC_BAD_ACCESS in the iOS app's main thread.
+     */
+    #sendProfileAndGreeting(friendId) {
+        if (!this.#profileSentTo.has(friendId)) {
+            this.#profileSentTo.add(friendId);
+            void (async () => {
+                try {
+                    // Toxcore PACKET_ID_NICKNAME (48) carries a raw UTF-8 nickname.
+                    // Carrier C SDK happens to also call tox_self_set_name, so we
+                    // mirror that behaviour for clients that rely on the toxcore
+                    // callback. Most Carrier UIs read the displayed name from the
+                    // userinfo flatbuffers payload below, but this keeps both paths
+                    // consistent.
+                    const nameBytes = new TextEncoder().encode(PEER_NICKNAME);
+                    await this.#sendMessengerPacket(friendId, PACKET_ID_NICKNAME, nameBytes);
+                    this.#debugLog(`nickname "${PEER_NICKNAME}" sent to ${friendId}`);
+                    // Carrier C SDK transports its full user-profile (name, descr,
+                    // gender, phone, email, region, has_avatar) as a FlatBuffers
+                    // PACKET_TYPE_USERINFO (3) payload sent via toxcore's
+                    // PACKET_ID_STATUSMESSAGE (49). iOS Beagle's
+                    // notify_friend_status_message_cb -> unpack_user_descr ->
+                    // packet_decode pipeline expects this exact wrapping. Sending
+                    // raw UTF-8 here causes flatbuffers to read random offsets and
+                    // crash the app with EXC_BAD_ACCESS in
+                    // __flatbuffers_soffset_read_from_pe (observed in Beagle 1.8.6).
+                    await sleep(250);
+                    const userInfo = encodeUserInfoPacket({
+                        name: PEER_NICKNAME,
+                        descr: PEER_STATUS_MESSAGE
+                    });
+                    await this.#sendMessengerPacket(friendId, PACKET_ID_STATUSMESSAGE, userInfo);
+                    this.#debugLog(`userinfo sent to ${friendId} (name="${PEER_NICKNAME}", descr="${PEER_STATUS_MESSAGE}")`);
+                }
+                catch (error) {
+                    this.#debugLog(`send profile failed for ${friendId}: ${error.message}`);
+                }
+            })();
+        }
+        if (GREETING_TEXT && !this.#greetingSentTo.has(friendId)) {
+            this.#greetingSentTo.add(friendId);
+            void (async () => {
+                try {
+                    // Wait so the greeting arrives after the profile pair, giving
+                    // the friend's UI time to render the nickname update first.
+                    await sleep(700);
+                    const carrierMsg = encodeFriendMessagePacket(GREETING_TEXT);
+                    await this.#sendMessengerPacket(friendId, PACKET_ID_MESSAGE, carrierMsg);
+                    this.#debugLog(`greeting "${GREETING_TEXT}" sent to ${friendId}`);
+                }
+                catch (error) {
+                    this.#debugLog(`send greeting failed for ${friendId}: ${error.message}`);
+                }
+            })();
+        }
+    }
+    #cacheFriendRemote(friendId, host, port, realPublicKey, dhtPublicKey) {
+        const friend = this.#friends.get(friendId);
+        if (!friend) {
+            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
+        // current UDP endpoint. Persisting them then loading on restart causes
+        // the friend connection loop to spam cookie requests to dead addresses
+        // and never recover. Instead we update the in-memory record so the
+        // *current* session's connection loop has somewhere to try, and only
+        // persist remoteHost from #setFriendOnline (which fires after a real
+        // handshake completes — that endpoint is verified working).
+        if (friend.remoteHost !== host || friend.remotePort !== port) {
+            this.#friends.set(friendId, {
+                ...friend,
+                remoteHost: host,
+                remotePort: port
+            });
+            // Intentionally NO #persistFriends() here.
+        }
+        let session = this.#friendSessions.get(friendId);
+        if (!session) {
+            session = {
+                ourSessionKeyPair: createEphemeralKeyPair(),
+                ourBaseNonce: randomBytes(24)
+            };
+            this.#friendSessions.set(friendId, session);
+        }
+        session.remote = { host, port };
+        this.#rememberEndpointCandidate(session, host, port);
+        if (realPublicKey && !session.friendRealPublicKey) {
+            session.friendRealPublicKey = realPublicKey;
+        }
+        if (dhtPublicKey) {
+            session.friendDhtPublicKey = dhtPublicKey;
+        }
+    }
+    #rememberEndpointCandidate(session, host, port) {
+        const now = Date.now();
+        const next = (session.endpointCandidates ?? []).filter((candidate) => !(candidate.host === host && candidate.port === port));
+        next.unshift({ host, port, updatedMs: now });
+        session.endpointCandidates = next
+            .sort((a, b) => b.updatedMs - a.updatedMs)
+            .slice(0, 12);
+    }
+    #collectSessionEndpointCandidates(friendId, friend, session) {
+        // Three buckets: same-LAN private (highest priority for direct UDP),
+        // public/routable, and other private (different LAN, last-resort).
+        // When the local machine has any non-loopback private interface, we
+        // are likely behind NAT and any candidate that matches our subnet is
+        // the only reliable direct-UDP path to the peer; routing to a public
+        // address requires the peer's NAT to allow our incoming packet, which
+        // only succeeds with hole-punching that we don't implement.
+        const sameLan = [];
+        const publicCandidates = [];
+        const otherPrivate = [];
+        const localSubnets = getLocalIpv4Subnets();
+        // Exclude our own IPv4 + UDP port: some toxcore peers include observed
+        // sender addresses in their DHT-PK extras, and we'd otherwise send a
+        // cookie request to ourselves.
+        const ourLocalIps = getLocalIpv4Addresses();
+        const ourLocalPort = this.#udp.localPort();
+        const seen = new Set();
+        const totalCount = () => sameLan.length + publicCandidates.length + otherPrivate.length;
+        const push = (host, port) => {
+            if (!host || !port) {
+                return;
+            }
+            if (ourLocalPort === port && ourLocalIps.includes(host)) {
+                return;
+            }
+            const key = `${host}:${port}`;
+            if (seen.has(key)) {
+                return;
+            }
+            seen.add(key);
+            if (isPrivateAddress(host)) {
+                if (localSubnets.some((subnet) => isInIpv4Subnet(host, subnet))) {
+                    sameLan.push({ host, port });
+                }
+                else {
+                    otherPrivate.push({ host, port });
+                }
+            }
+            else {
+                publicCandidates.push({ host, port });
+            }
+        };
+        push(session?.remote?.host, session?.remote?.port);
+        push(friend.remoteHost, friend.remotePort);
+        // Operator-supplied extra hosts (DECENT_LAN_SWEEP_EXTRA_HOSTS) are
+        // pushed straight into the same-LAN bucket so e.g. the iOS Simulator
+        // on 127.0.0.1 gets a cookie request on the very first initiateSession
+        // instead of waiting for the 6-second LAN sweep timer. Loopback is not
+        // in the local IPv4 subnet list (getLocalIpv4Subnets excludes internal
+        // interfaces) so it would otherwise land in the "other private"
+        // last-resort bucket and connect noticeably slower.
+        for (const host of LAN_SWEEP_EXTRA_HOSTS) {
+            for (const port of LAN_SWEEP_PORTS) {
+                const key = `${host}:${port}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                sameLan.push({ host, port });
+            }
+        }
+        for (const candidate of session?.endpointCandidates ?? []) {
+            push(candidate.host, candidate.port);
+            if (totalCount() >= 8) {
+                return [...sameLan, ...publicCandidates, ...otherPrivate].slice(0, 8);
+            }
+        }
+        const dhtId = session?.friendDhtPublicKey ? carrierIdFromPublicKey(session.friendDhtPublicKey) : undefined;
+        for (const node of this.#knownNodes) {
+            if (node.pk !== friendId && (!dhtId || node.pk !== dhtId)) {
+                continue;
+            }
+            push(node.host, node.port);
+            if (totalCount() >= 8) {
+                break;
+            }
+        }
+        // Same-LAN candidates first (most reliable when both peers are behind
+        // the same NAT), then public addresses, then other private addresses.
+        return [...sameLan, ...publicCandidates, ...otherPrivate].slice(0, 8);
+    }
+    async #initiateSession(friendId) {
+        if (!this.#keyPair || !this.#cookieSymmetricKey) {
+            return false;
+        }
+        const friend = this.#friends.get(friendId);
+        if (!friend) {
+            return false;
+        }
+        let session = this.#friendSessions.get(friendId);
+        if (session?.established) {
+            return true;
+        }
+        if (session && session.pendingEcho !== undefined) {
+            // Already waiting on a cookie response — do not flood
+            return false;
+        }
+        if (session && session.handshakeSentMs && Date.now() - session.handshakeSentMs < 6000) {
+            // Recently sent handshake; wait for peer reply
+            return false;
+        }
+        // Resolve friend's real public key
+        let friendRealPk = session?.friendRealPublicKey;
+        if (!friendRealPk && friend.address) {
+            try {
+                friendRealPk = parseCarrierAddress(friend.address).publicKey;
+            }
+            catch (error) {
+                this.#debugLog(`initiate session: parse address failed for ${friendId}: ${error.message}`);
+                return false;
+            }
+        }
+        if (!friendRealPk && friend.pubkey) {
+            try {
+                friendRealPk = base58ToBytes(friend.pubkey);
+            }
+            catch {
+                // Ignore decode errors and bail below
+            }
+        }
+        if (!friendRealPk || friendRealPk.length !== 32) {
+            this.#debugLog(`initiate session: cannot resolve pubkey for ${friendId}`);
+            return false;
+        }
+        // Tie-break who initiates. When both peers send COOKIE_REQUEST in
+        // parallel, each creates an independent local session shell with
+        // ephemeral keys, then computes a shared key from the OTHER side's
+        // handshake. Even though ECDH is commutative, the keys diverge as
+        // soon as one side's shell rotates (which happens on session
+        // timeout, friend-online flap, etc.). Result: chronic decrypt
+        // failures, observed as "crypto data received but no session
+        // matched" cycling every 32s.
+        //
+        // Mirror toxcore: lower-pubkey side stays pure responder. Only the
+        // higher-pubkey side initiates a cookie chain. Peer comparison is
+        // lexicographic on the 32-byte real public key.
+        let pkCmp = 0;
+        for (let i = 0; i < 32; i++) {
+            const a = this.#keyPair.publicKey[i];
+            const b = friendRealPk[i];
+            if (a !== b) {
+                pkCmp = a - b;
+                break;
+            }
+        }
+        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}`);
+            }
+            return false;
+        }
+        // Prefer DHT key learned from DHTPK updates; fallback to real key.
+        const friendDhtPk = session?.friendDhtPublicKey ?? friendRealPk;
+        const connectCandidates = this.#collectSessionEndpointCandidates(friendId, friend, session);
+        const tcpAvailable = !!this.#tcpRelays?.isFriendOnline(friendRealPk);
+        if (connectCandidates.length === 0 && !tcpAvailable) {
+            this.#debugLog(`initiate session: no known endpoint for ${friendId} yet`);
+            return false;
+        }
+        if (!session) {
+            session = {
+                ourSessionKeyPair: createEphemeralKeyPair(),
+                ourBaseNonce: randomBytes(24)
+            };
+            this.#friendSessions.set(friendId, session);
+        }
+        session.friendRealPublicKey = friendRealPk;
+        session.friendDhtPublicKey = friendDhtPk;
+        if (tcpAvailable)
+            session.hasTcpRoute = true;
+        if (connectCandidates.length > 0) {
+            session.remote = connectCandidates[0];
+            const endpointKey = `${connectCandidates[0].host}:${connectCandidates[0].port}`;
+            if (this.#lastEndpointSelectedKey.get(friendId) !== endpointKey) {
+                this.#debugLog(`endpoint_selected friend=${friendId} endpoint=${endpointKey}`);
+                this.#lastEndpointSelectedKey.set(friendId, endpointKey);
+            }
+            else {
+                this.#debugVerboseLog(`endpoint_selected friend=${friendId} endpoint=${endpointKey} (unchanged)`);
+            }
+            this.#rememberEndpointCandidate(session, connectCandidates[0].host, connectCandidates[0].port);
+        }
+        else if (tcpAvailable) {
+            this.#debugLog(`endpoint_selected friend=${friendId} endpoint=tcp-relay (no UDP path)`);
+        }
+        const echo = randomBigUint64();
+        session.pendingEcho = echo;
+        session.pendingCookiePeerDhtPublicKey = friendDhtPk;
+        session.cookieRequestSentMs = Date.now();
+        if (!session.recentEchoes)
+            session.recentEchoes = new Map();
+        session.recentEchoes.set(echo, Date.now());
+        // Prune entries older than 30s.
+        const cutoff = Date.now() - 30_000;
+        for (const [k, t] of session.recentEchoes) {
+            if (t < cutoff)
+                session.recentEchoes.delete(k);
+        }
+        const packet = createCookieRequest({
+            senderRealPublicKey: this.#keyPair.publicKey,
+            senderDhtPublicKey: this.#keyPair.publicKey,
+            senderDhtSecretKey: this.#keyPair.secretKey,
+            receiverDhtPublicKey: friendDhtPk,
+            echo
+        });
+        try {
+            let sent = 0;
+            let tcpSent = 0;
+            for (const candidate of connectCandidates) {
+                try {
+                    await this.#sendPacket(packet, candidate);
+                    sent += 1;
+                }
+                catch {
+                    // Keep best-effort behavior.
+                }
+            }
+            // 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) {
+                throw new Error("no cookie request packet was sent");
+            }
+            // Each unmatched attempt grows the per-friend backoff. Resets when a
+            // cookie response actually matches (see NET_PACKET_COOKIE_RESPONSE
+            // handler) or when the friend is removed.
+            this.#cookieRetryCount.set(friendId, (this.#cookieRetryCount.get(friendId) ?? 0) + 1);
+            const primaryDesc = connectCandidates.length > 0
+                ? `${connectCandidates[0].host}:${connectCandidates[0].port}`
+                : `tcp-relay`;
+            const cookieKey = `${primaryDesc}|udp=${sent}|tcp=${tcpSent}`;
+            if (this.#lastCookieSentKey.get(friendId) !== cookieKey) {
+                this.#debugLog(`cookie_sent friend=${friendId} udp=${sent} tcp=${tcpSent} 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)})`);
+            }
+            return true;
+        }
+        catch (error) {
+            this.#debugLog(`cookie request send failed for ${friendId}: ${error.message}`);
+            session.pendingEcho = undefined;
+            session.pendingCookiePeerDhtPublicKey = undefined;
+            session.cookieRequestSentMs = undefined;
+            return false;
+        }
+    }
+    /**
+     * Last-resort same-LAN discovery: when we've sent cookie requests to all
+     * known candidates for a friend and haven't heard back, broadcast cookie
+     * requests to every host in our local /24 subnets at toxcore's standard
+     * UDP ports. Whichever host is the friend will receive, decrypt with its
+     * DHT secret key, and respond — the existing cookie response handler
+     * matches by echo, so the right reply wins automatically.
+     *
+     * Useful in the iOS Beagle case where the peer's DHT-PK extras don't
+     * include the peer's own LAN IP and platform sandboxing prevents normal
+     * LAN discovery broadcasts from arriving.
+     */
+    async #sweepLanForCookieResponse(friendId) {
+        if (!this.#keyPair)
+            return;
+        const session = this.#friendSessions.get(friendId);
+        if (!session?.pendingEcho || !session.friendDhtPublicKey)
+            return;
+        if (LAN_SWEEP_AFTER_MS <= 0)
+            return;
+        // Build the same cookie request packet but reuse the pending echo so
+        // the existing cookie response handler matches it.
+        const packet = createCookieRequest({
+            senderRealPublicKey: this.#keyPair.publicKey,
+            senderDhtPublicKey: this.#keyPair.publicKey,
+            senderDhtSecretKey: this.#keyPair.secretKey,
+            receiverDhtPublicKey: session.friendDhtPublicKey,
+            echo: session.pendingEcho
+        });
+        const subnets = getLocalIpv4Subnets();
+        const ourLocalIps = getLocalIpv4Addresses();
+        const ourLocalPort = this.#udp.localPort();
+        let probes = 0;
+        // Optional explicit hosts (DECENT_LAN_SWEEP_EXTRA_HOSTS). Empty by
+        // 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) {
+                if (port === ourLocalPort && ourLocalIps.includes(host))
+                    continue;
+                try {
+                    await this.#sendPacket(packet, { host, port });
+                    probes += 1;
+                }
+                catch {
+                    // best-effort
+                }
+            }
+        }
+        for (const subnet of subnets) {
+            const network = subnet.networkBits;
+            const mask = subnet.maskBits;
+            const broadcast = (network | (~mask >>> 0)) >>> 0;
+            // Only sweep /23 or smaller (≤512 hosts) to keep the burst bounded.
+            if (((~mask >>> 0) & 0xffffffff) > 0x1ff)
+                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) {
+                    if (ourLocalPort === port && ourLocalIps.includes(host))
+                        continue;
+                    try {
+                        await this.#sendPacket(packet, { host, port });
+                        probes += 1;
+                    }
+                    catch {
+                        // best-effort
+                    }
+                }
+            }
+        }
+        if (probes > 0) {
+            this.#debugLog(`lan_sweep friend=${friendId} probes=${probes}`);
+        }
+    }
+    /**
+     * Send an onion DHT-PK announcement to a friend so they learn our DHT
+     * public key + endpoint hints. This is the bidirectional partner of the
+     * inbound dhtpk_update flow: without this, a peer who accepted our friend
+     * request has no way to find our UDP endpoint and net_crypto cannot start
+     * from their side.
+     *
+     * Packet layout matches toxcore Messenger.c:send_dht_public_key_to_friend
+     * — onion data with innerPacketId = CRYPTO_PACKET_DHTPK (156), payload =
+     *   noReplay (8 BE) || dhtPublicKey (32) || extra (packed nodes).
+     */
+    async #sendOnionDhtPk(friendRealPublicKey) {
+        if (!this.#keyPair)
+            return false;
+        const friendId = carrierIdFromPublicKey(friendRealPublicKey);
+        const routes = await this.#discoverFriendRoutes(friendRealPublicKey).catch(() => []);
+        if (routes.length === 0) {
+            const failures = (this.#dhtPkConsecutiveFailures.get(friendId) ?? 0) + 1;
+            this.#dhtPkConsecutiveFailures.set(friendId, failures);
+            // Only log first failure at debug level; subsequent retries go to verbose
+            // since a stale persisted friend can hit this repeatedly (with backoff).
+            if (failures === 1) {
+                this.#debugLog(`dhtpk_send no routes available for ${friendId} (consecutive_failures=1)`);
+            }
+            else {
+                this.#debugVerboseLog(`dhtpk_send no routes available for ${friendId} (consecutive_failures=${failures})`);
+            }
+            return false;
+        }
+        // Reset failure counter on first success at finding any route.
+        this.#dhtPkConsecutiveFailures.delete(friendId);
+        // Build inner DHTPK payload.
+        const noReplay = BigInt(Math.floor(Date.now() / 1000));
+        const noReplayBytes = new Uint8Array(8);
+        {
+            let v = noReplay;
+            for (let i = 7; i >= 0; i--) {
+                noReplayBytes[i] = Number(v & 0xffn);
+                v >>= 8n;
+            }
+        }
+        // Pack our currently-connected TCP relays as DHT-PK extras. iOS
+        // Beagle's friend_connection layer reads these to populate its
+        // tcp_relays list for us, then issues OOB_SEND with cookie request
+        // on each — without this hint, iPad has no idea which relays might
+        // reach us, and iPad's friend_connection stalls at CONNECTING when
+        // its own DHT search for our pubkey fails (the common case on
+        // residential ISPs where self-announce doesn't propagate).
+        // Mirrors toxcore's send_dht_pk_packet which calls
+        // tcp_copy_connected_relays to fill extras.
+        let extras = new Uint8Array(0);
+        if (this.#tcpRelays) {
+            const relays = this.#tcpRelays.connectedRelays(3); // MAX_SHARED_RELAYS
+            const packed = [];
+            for (const r of relays) {
+                // Only IPv4 TCP entries supported here; matches what we parse.
+                // Format per packed-nodes spec: family(1) + ipv4(4) + port(2 BE) + pk(32)
+                const parts = r.host.split(".").map((p) => Number.parseInt(p, 10));
+                if (parts.length !== 4 || parts.some((n) => !(n >= 0 && n <= 255)))
+                    continue;
+                const entry = new Uint8Array(1 + 4 + 2 + 32);
+                entry[0] = 130; // 0x82 = TCP_FAMILY_IPV4
+                entry[1] = parts[0];
+                entry[2] = parts[1];
+                entry[3] = parts[2];
+                entry[4] = parts[3];
+                entry[5] = (r.port >> 8) & 0xff;
+                entry[6] = r.port & 0xff;
+                entry.set(r.serverPublicKey, 7);
+                packed.push(entry);
+            }
+            if (packed.length > 0) {
+                extras = concatBytes(packed);
+            }
+        }
+        const innerPayload = concatBytes([
+            noReplayBytes,
+            this.#keyPair.publicKey,
+            extras
+        ]);
+        let sent = 0;
+        for (const route of routes) {
+            try {
+                const nonce = randomBytes(24);
+                const onionData = createOnionDataPacket({
+                    senderPublicKey: this.#keyPair.publicKey,
+                    senderSecretKey: this.#keyPair.secretKey,
+                    receiverPublicKey: friendRealPublicKey,
+                    nonce,
+                    innerPacketId: CRYPTO_PACKET_DHTPK,
+                    innerPayload
+                });
+                const dataRequest = createOnionDataRequest({
+                    destinationPublicKey: friendRealPublicKey,
+                    routePublicKey: route.routePublicKey,
+                    nonce,
+                    onionDataPacket: onionData
+                });
+                await this.#sendThroughOnionPath(dataRequest, route.node, sent);
+                sent += 1;
+                if (sent >= 4)
+                    break; // a few routes is enough
+            }
+            catch (error) {
+                this.#debugLog(`dhtpk_send route failed via ${route.node.host}:${route.node.port}: ${error.message}`);
+            }
+        }
+        if (sent > 0) {
+            this.#debugLog(`dhtpk_sent friend=${friendId} routes=${sent} noReplay=${noReplay.toString()}`);
+        }
+        return sent > 0;
+    }
+    #setFriendOnline(friendId, remoteHost, remotePort) {
+        const friend = this.#friends.get(friendId);
+        if (!friend) {
+            return;
+        }
+        // Don't persist a synthetic TCP-relay-routed remote ("tcp:<dhtpk>:0").
+        // The friend connection loop reading it next run would try to UDP-send
+        // to that host and silently drop. Keep status=online + acceptedAt
+        // updated, but only persist remoteHost when it's a real UDP endpoint.
+        const isSynthetic = remoteHost.startsWith("tcp:") || remotePort === 0;
+        const persistedHost = isSynthetic ? friend.remoteHost : remoteHost;
+        const persistedPort = isSynthetic ? friend.remotePort : remotePort;
+        const changed = friend.status !== "online" || friend.remoteHost !== persistedHost || friend.remotePort !== persistedPort;
+        this.#friends.set(friendId, {
+            ...friend,
+            status: "online",
+            remoteHost: persistedHost,
+            remotePort: persistedPort
+        });
+        if (changed) {
+            this.#persistFriends();
+            this.#events.emit("friendConnection", {
+                pubkey: friendId,
+                status: "connected"
+            });
+        }
+    }
+    #setFriendOffline(friendId) {
+        // Re-arm the profile (nickname + userinfo) flag so the next reconnect
+        // pushes it again — toxcore peers persist nicknames across reconnects
+        // but it's the responsible thing to refresh once per session in case
+        // the peer's UI dropped state.
+        //
+        // Greeting flag is intentionally NOT reset: the configured greeting is
+        // a one-time "Hi from JS" intended to fire once per process startup,
+        // not on every reconnect. Keeping #greetingSentTo set across offline
+        // transitions prevents the user from seeing the same greeting message
+        // repeated each time the session bounces.
+        this.#profileSentTo.delete(friendId);
+        const friend = this.#friends.get(friendId);
+        if (!friend) {
+            return;
+        }
+        if (friend.status === "offline") {
+            return;
+        }
+        this.#friends.set(friendId, {
+            ...friend,
+            status: "offline"
+        });
+        this.#persistFriends();
+        this.#events.emit("friendConnection", {
+            pubkey: friendId,
+            status: "disconnected"
+        });
+    }
+    async #sendAnnounceAndWait(opts) {
+        this.#debugLog(`announce request target=${opts.node.host}:${opts.node.port} ` +
+            `searchEqSender=${bytesEqual(opts.searchPublicKey, opts.senderPublicKey)} ` +
+            `dataKeyZero=${isAllZero(opts.dataPublicKey)}`);
+        const request = createOnionAnnounceRequest({
+            senderPublicKey: opts.senderPublicKey,
+            senderSecretKey: opts.senderSecretKey,
+            nodePublicKey: opts.nodePublicKey,
+            pingId: opts.pingId,
+            searchPublicKey: opts.searchPublicKey,
+            dataPublicKey: opts.dataPublicKey,
+            sendBack: opts.sendBack
+        });
+        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.#sendThroughOnionPath(request, opts.node, attempt);
+            const response = await waiter;
+            if (response) {
+                this.#recordNodeSuccess(`${opts.node.host}:${opts.node.port}`);
+                return response;
+            }
+            this.#recordNodeFailure(`${opts.node.host}:${opts.node.port}`);
+        }
+        if (opts.allowDirectFallback) {
+            const waiter = this.#waitForAnnounceResponse(opts.node, opts.sendBack, {
+                requesterSecretKey: opts.senderSecretKey,
+                nodePublicKey: opts.nodePublicKey
+            });
+            await this.#sendPacket(request, opts.node);
+            const response = await waiter;
+            if (response) {
+                this.#recordNodeSuccess(`${opts.node.host}:${opts.node.port}`);
+                return response;
+            }
+            this.#recordNodeFailure(`${opts.node.host}:${opts.node.port}`);
+        }
+        return undefined;
+    }
+    async #waitForAnnounceResponse(node, sendBack, openOpts) {
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                cleanup();
+                resolve(undefined);
+            }, ANNOUNCE_WAIT_TIMEOUT_MS);
+            const onDatagram = ({ data, remote }) => {
+                const source = `${remote.address}:${remote.port}`;
+                const packet = stripCarrierMagic(data);
+                if (packet.length === 0 || packet[0] !== NET_PACKET_ONION_ANNOUNCE_RESPONSE) {
+                    return;
+                }
+                // Pre-filter by sendBack BEFORE attempting decrypt. With parallel
+                // batches (8-12 in-flight requests), every inbound response is
+                // delivered to all listeners — only the one with the matching
+                // sendBack should attempt decrypt. Without this guard, the other
+                // 11 listeners would all run nacl.box.open with their own
+                // requesterSecretKey + nodePublicKey, fail (because the response
+                // was for a different listener), and log "decrypt failed from
+                // <source>" — which makes it look like the bootstrap is broken
+                // when it's actually fine. The sendBack token is in plaintext at
+                // a fixed offset (1..1+SEND_BACK_SIZE), so we can match it
+                // without decrypting.
+                const SEND_BACK_OFFSET = 1;
+                const SEND_BACK_LEN = 8;
+                if (packet.length < SEND_BACK_OFFSET + SEND_BACK_LEN) {
+                    return;
+                }
+                const incoming = packet.subarray(SEND_BACK_OFFSET, SEND_BACK_OFFSET + SEND_BACK_LEN);
+                if (!bytesEqual(incoming, sendBack)) {
+                    return; // not for this listener — silent
+                }
+                // Now this packet IS for us. A decrypt failure here is real.
+                const opened = openOnionAnnounceResponse(packet, openOpts);
+                if (!opened) {
+                    this.#debugLog(`announce response decrypt failed from ${source}`);
+                    return;
+                }
+                this.#recordNodeSuccess(source);
+                this.#debugLog(`announce response accepted from ${source}`);
+                cleanup();
+                resolve(opened);
+            };
+            const cleanup = () => {
+                clearTimeout(timeout);
+                this.#udp.off("datagram", onDatagram);
+            };
+            this.#udp.on("datagram", onDatagram);
+        });
+    }
+    async #sendPacket(packet, node) {
+        this.#tracePacket("tx", packet, node);
+        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);
+        if (!path) {
+            this.#debugLog(`no onion path for ${nodeD.host}:${nodeD.port}, sending direct`);
+            await this.#sendPacket(payloadForNodeD, nodeD);
+            return;
+        }
+        this.#debugLog(`sending onion initial via ${path.nodeA.node.host}:${path.nodeA.node.port} to ${nodeD.host}:${nodeD.port}`);
+        const packet = createOnionRequest0({
+            nodeAPublicKey: path.nodeA.publicKey,
+            nodeBHost: path.nodeB.host,
+            nodeBPort: path.nodeB.port,
+            nodeBPublicKey: path.nodeB.publicKey,
+            nodeCHost: path.nodeC.host,
+            nodeCPort: path.nodeC.port,
+            nodeCPublicKey: path.nodeC.publicKey,
+            nodeDHost: nodeD.host,
+            nodeDPort: nodeD.port,
+            payloadForNodeD
+        });
+        await this.#sendPacket(packet, path.nodeA.node);
+    }
+    #selectOnionPath(nodeD, pathOffset = 0) {
+        const nodeDId = `${nodeD.host}:${nodeD.port}`;
+        const candidates = [];
+        const bootstrapIds = new Set(this.#opts.bootstrapNodes.map((node) => `${node.host}:${node.port}`));
+        const seenHosts = new Set();
+        const seenPublicKeys = new Set();
+        for (const node of this.#knownNodes) {
+            if (!node.pk) {
+                continue;
+            }
+            const id = `${node.host}:${node.port}`;
+            if (id === nodeDId || node.host === nodeD.host || seenHosts.has(node.host)) {
+                continue;
+            }
+            // Skip blacklisted relays — onion paths through dead nodes
+            // silently swallow the request and the announce times out.
+            if (this.#isNodeBlacklisted(id)) {
+                continue;
+            }
+            try {
+                const pk = base58ToBytes(node.pk);
+                const pkHex = Buffer.from(pk).toString("hex");
+                if (pk.length === 32 && !seenPublicKeys.has(pkHex)) {
+                    seenHosts.add(node.host);
+                    seenPublicKeys.add(pkHex);
+                    candidates.push({
+                        node,
+                        publicKey: pk,
+                        score: this.#nodeScore(id) + relayPortScore(node.port) + (bootstrapIds.has(id) ? 4 : 0)
+                    });
+                }
+            }
+            catch {
+                // Ignore bad keys.
+            }
+        }
+        if (candidates.length < 3) {
+            return undefined;
+        }
+        candidates.sort((a, b) => b.score - a.score);
+        const preferredRelays = candidates.filter((item) => isLikelyStableRelayPort(item.node.port));
+        const healthy = preferredRelays.filter((item) => item.score > -2);
+        const pool = healthy.length >= 3 ? healthy : preferredRelays.length >= 3 ? preferredRelays : candidates;
+        const count = pool.length;
+        const i0 = pathOffset % count;
+        const i1 = (pathOffset + 1) % count;
+        const i2 = (pathOffset + 2) % count;
+        return {
+            nodeA: pool[i0],
+            nodeB: {
+                node: pool[i1].node,
+                host: pool[i1].node.host,
+                port: pool[i1].node.port,
+                publicKey: pool[i1].publicKey
+            },
+            nodeC: {
+                node: pool[i2].node,
+                host: pool[i2].node.host,
+                port: pool[i2].node.port,
+                publicKey: pool[i2].publicKey
+            }
+        };
+    }
+    async #sendDirectCryptoFriendRequest(friendPublicKey, friendReqPayload) {
+        if (!this.#keyPair) {
+            throw new Error("Peer is not started");
+        }
+        const cryptoPacket = createToxDhtCryptoRequest({
+            sender: this.#keyPair,
+            receiverPublicKey: friendPublicKey,
+            requestId: CRYPTO_PACKET_FRIEND_REQ,
+            data: friendReqPayload
+        });
+        const targets = dedupeNodes(this.#knownNodes.length > 0 ? this.#knownNodes : this.#opts.bootstrapNodes);
+        let sent = 0;
+        for (const node of targets) {
+            try {
+                await this.#sendPacket(cryptoPacket, node);
+                sent += 1;
+            }
+            catch {
+                // Keep best-effort semantics while trying multiple nodes.
+            }
+        }
+        if (sent === 0) {
+            throw new Error("friend request dispatch failed: no packet was sent");
+        }
+        this.#debugLog(`direct friend request sent via ${sent} targets`);
+    }
+    #debugLog(message) {
+        if (!this.#debug) {
+            return;
+        }
+        const label = this.#opts.debugLabel ? `:${this.#opts.debugLabel}` : "";
+        console.log(`[peer-debug${label}] ${message}`);
+    }
+    /**
+     * Verbose debug log — DHT plumbing chatter (per-onion-hop sends, decrypt
+     * failures from in-flight stale responses, isStored=0 announce results,
+     * etc.). Off by default even with DECENT_DEBUG=1; only emitted when
+     * DECENT_DEBUG_VERBOSE=1 is also set.
+     */
+    #debugVerboseLog(message) {
+        if (!this.#debugVerbose) {
+            return;
+        }
+        const label = this.#opts.debugLabel ? `:${this.#opts.debugLabel}` : "";
+        console.log(`[peer-debug${label}] ${message}`);
+    }
+    #tracePacket(direction, packet, remote) {
+        if (!this.#packetTrace || packet.length === 0) {
+            return;
+        }
+        const type = packet[0];
+        const label = this.#opts.debugLabel ? `:${this.#opts.debugLabel}` : "";
+        console.log(`[peer-packet${label}] ${direction} type=0x${type.toString(16).padStart(2, "0")} ` +
+            `len=${packet.length} peer=${remote.host}:${remote.port}`);
+    }
+    #recordNodeSuccess(nodeId) {
+        const prev = this.#nodeHealth.get(nodeId) ?? { ok: 0, fail: 0, lastOkMs: 0 };
+        this.#nodeHealth.set(nodeId, {
+            ok: prev.ok + 1,
+            fail: prev.fail,
+            lastOkMs: Date.now()
+        });
+        // Any success clears the blacklist — the node is alive again.
+        this.#nodeBlacklist.delete(nodeId);
+    }
+    #recordNodeFailure(nodeId) {
+        const prev = this.#nodeHealth.get(nodeId) ?? { ok: 0, fail: 0, lastOkMs: 0 };
+        const next = {
+            ok: prev.ok,
+            fail: prev.fail + 1,
+            lastOkMs: prev.lastOkMs
+        };
+        this.#nodeHealth.set(nodeId, next);
+        // Soft blacklist: a node that has accumulated NODE_BLACKLIST_THRESHOLD
+        // consecutive failures (no successful response in between resets it
+        // via #recordNodeSuccess) goes onto the blacklist with a 5-minute
+        // TTL. This stops the parallel announce batches from spending half
+        // their slots on a known-dead bootstrap; the surviving healthy nodes
+        // pick up the slack. The blacklist self-heals after the TTL so a
+        // temporarily-flapping node gets re-tried later.
+        const consecutive = next.fail - next.ok;
+        if (consecutive >= NODE_BLACKLIST_THRESHOLD) {
+            const ttl = Math.min(NODE_BLACKLIST_MAX_TTL_MS, NODE_BLACKLIST_BASE_TTL_MS * Math.pow(1.5, consecutive - NODE_BLACKLIST_THRESHOLD));
+            this.#nodeBlacklist.set(nodeId, Date.now() + ttl);
+            this.#debugVerboseLog(`node ${nodeId} blacklisted for ${Math.round(ttl / 1000)}s after ${consecutive} consecutive fails`);
+        }
+    }
+    /**
+     * True if this node is currently shadowbanned for repeated failures.
+     * Self-expires after the TTL set in #recordNodeFailure. Used by every
+     * candidate-selection site to skip dead bootstraps without needing to
+     * remove them from #knownNodes (which would lose neighbor info on
+     * restart).
+     */
+    #isNodeBlacklisted(nodeId) {
+        const expiry = this.#nodeBlacklist.get(nodeId);
+        if (expiry === undefined)
+            return false;
+        if (Date.now() > expiry) {
+            this.#nodeBlacklist.delete(nodeId);
+            return false;
+        }
+        return true;
+    }
+    #nodeScore(nodeId) {
+        const h = this.#nodeHealth.get(nodeId);
+        if (!h) {
+            return 0;
+        }
+        const recentBonus = Date.now() - h.lastOkMs < 60_000 ? 2 : 0;
+        return (h.ok * 2) - h.fail + recentBonus;
+    }
+    #pauseSelfAnnounce() {
+        this.#selfAnnouncePauseDepth += 1;
+        return () => {
+            this.#selfAnnouncePauseDepth = Math.max(0, this.#selfAnnouncePauseDepth - 1);
+        };
+    }
+    async #runSelfAnnounce(force, deadlineMs) {
+        if (this.#selfAnnouncePromise) {
+            await this.#selfAnnouncePromise.catch(() => { });
+        }
+        this.#selfAnnouncePromise = this.#announceSelfBestEffort(force, deadlineMs);
+        try {
+            const result = await this.#selfAnnouncePromise;
+            return result ?? [];
+        }
+        finally {
+            this.#selfAnnouncePromise = undefined;
+        }
+    }
+    async #loadPersistedFriends() {
+        if (!this.#friendStoreFile) {
+            return;
+        }
+        try {
+            const raw = await readFile(this.#friendStoreFile, "utf8");
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed)) {
+                return;
+            }
+            for (const record of parsed) {
+                if (!record || typeof record.pubkey !== "string" || !record.pubkey) {
+                    continue;
+                }
+                // If the persisted record has no acceptedAt, the saved
+                // remoteHost/remotePort may be stale (older builds persisted
+                // speculative DHT-PK extras). Drop them so the connection loop
+                // does fresh discovery via DHT-PK rather than spamming cookie
+                // requests to a dead bootstrap relay address.
+                const trusted = record.acceptedAt ? record : {
+                    ...record,
+                    remoteHost: undefined,
+                    remotePort: undefined,
+                    status: record.status === "online" ? "offline" : record.status
+                };
+                this.#friends.set(record.pubkey, trusted);
+            }
+            this.#debugLog(`loaded ${this.#friends.size} persisted friends`);
+        }
+        catch {
+            // Ignore missing/invalid friend store on startup.
+        }
+    }
+    #persistFriends() {
+        if (!this.#friendStoreFile) {
+            return;
+        }
+        const payload = JSON.stringify([...this.#friends.values()], null, 2);
+        void mkdir(dirname(this.#friendStoreFile), { recursive: true })
+            .then(() => writeFile(this.#friendStoreFile, payload, "utf8"))
+            .catch((error) => {
+            this.#debugLog(`persist friends failed: ${error.message}`);
+        });
+    }
+}
+function decodeUtf8Best(payload) {
+    if (payload.length === 0)
+        return "";
+    try {
+        return new TextDecoder("utf-8", { fatal: false }).decode(payload);
+    }
+    catch {
+        return "";
+    }
+}
+function tryDecodeCarrierMessagePacket(payload) {
+    try {
+        const decoded = decodeCarrierPacket(payload);
+        if (decoded.type !== PACKET_TYPE_MESSAGE) {
+            return undefined;
+        }
+        return new TextDecoder().decode(decoded.data);
+    }
+    catch {
+        return undefined;
+    }
+}
+function splitFriendRequestPayload(payload) {
+    if (payload.length >= 4) {
+        const withPrefix = payload.slice(4);
+        try {
+            const decoded = decodeCarrierPacket(withPrefix);
+            if (decoded.type === PACKET_TYPE_FRIEND_REQUEST) {
+                return {
+                    nospam: readUint32LE(payload, 0),
+                    carrierPacket: withPrefix
+                };
+            }
+        }
+        catch {
+            // Fall through and try payload without a nospam prefix.
+        }
+    }
+    try {
+        const decoded = decodeCarrierPacket(payload);
+        if (decoded.type === PACKET_TYPE_FRIEND_REQUEST) {
+            return {
+                nospam: 0,
+                carrierPacket: payload
+            };
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function dedupeNodes(nodes) {
+    const byAddress = new Map();
+    for (const node of nodes) {
+        byAddress.set(`${node.host}:${node.port}`, node);
+    }
+    return [...byAddress.values()];
+}
+function uint32ToLe(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+        throw new Error("friend nospam must be uint32");
+    }
+    return new Uint8Array([
+        value & 0xff,
+        (value >>> 8) & 0xff,
+        (value >>> 16) & 0xff,
+        (value >>> 24) & 0xff
+    ]);
+}
+function readUint32LE(bytes, offset) {
+    return (bytes[offset] |
+        (bytes[offset + 1] << 8) |
+        (bytes[offset + 2] << 16) |
+        (bytes[offset + 3] << 24)) >>> 0;
+}
+function readUint64BE(bytes, offset) {
+    let v = 0n;
+    for (let i = 0; i < 8; i++) {
+        v = (v << 8n) | BigInt(bytes[offset + i] ?? 0);
+    }
+    return v;
+}
+function stripCarrierMagic(data) {
+    if (data.length >= 5 &&
+        data[0] === 0x69 &&
+        data[1] === 0x76 &&
+        data[2] === 0x65 &&
+        data[3] === 0x67) {
+        return data.slice(4);
+    }
+    return data;
+}
+function parsePackedNodes(data) {
+    const nodes = [];
+    let offset = 0;
+    while (offset + 1 <= data.length) {
+        const family = data[offset];
+        offset += 1;
+        let host = "";
+        let isTcp = false;
+        if (family === 2 || family === 130) {
+            if (offset + 4 + 2 + 32 > data.length) {
+                break;
+            }
+            host = [...data.slice(offset, offset + 4)].join(".");
+            offset += 4;
+            isTcp = family === 130; // TCP_FAMILY_IPV4
+        }
+        else if (family === 10 || family === 138) {
+            if (offset + 16 + 2 + 32 > data.length) {
+                break;
+            }
+            const parts = [];
+            for (let i = 0; i < 8; i++) {
+                parts.push(((data[offset + i * 2] << 8) | data[offset + i * 2 + 1]).toString(16));
+            }
+            host = parts.join(":");
+            offset += 16;
+            isTcp = family === 138; // TCP_FAMILY_IPV6
+        }
+        else {
+            break;
+        }
+        const port = (data[offset] << 8) | data[offset + 1];
+        offset += 2;
+        const pk = carrierIdFromPublicKey(data.slice(offset, offset + 32));
+        offset += 32;
+        nodes.push({ host, port, pk, isTcp });
+    }
+    return nodes;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}
+function createEphemeralKeyPair() {
+    return nacl.box.keyPair();
+}
+function isAllZero(bytes) {
+    for (let i = 0; i < bytes.length; i++) {
+        if (bytes[i] !== 0) {
+            return false;
+        }
+    }
+    return true;
+}
+function isLikelyStableRelayPort(port) {
+    return port >= 33445 && port <= 33449;
+}
+function relayPortScore(port) {
+    return isLikelyStableRelayPort(port) ? 3 : 0;
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, Math.max(0, ms));
+    });
+}
+function randomBigUint64() {
+    const bytes = randomBytes(8);
+    let v = 0n;
+    for (let i = 7; i >= 0; i--) {
+        v = (v << 8n) | BigInt(bytes[i]);
+    }
+    return v;
+}
+function computeIpv4Broadcast(address, netmask) {
+    const a = address.split(".").map((p) => Number.parseInt(p, 10));
+    const m = netmask.split(".").map((p) => Number.parseInt(p, 10));
+    if (a.length !== 4 || m.length !== 4 || a.some((n) => !Number.isInteger(n)) || m.some((n) => !Number.isInteger(n))) {
+        return undefined;
+    }
+    const out = a.map((octet, i) => (octet & m[i]) | (~m[i] & 0xff));
+    return out.join(".");
+}
+function ipv4ToInt(host) {
+    const parts = host.split(".");
+    if (parts.length !== 4)
+        return undefined;
+    const oct = parts.map((p) => Number.parseInt(p, 10));
+    if (oct.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return undefined;
+    return ((oct[0] << 24) | (oct[1] << 16) | (oct[2] << 8) | oct[3]) >>> 0;
+}
+function netmaskToInt(mask) {
+    return ipv4ToInt(mask);
+}
+/**
+ * Enumerate non-loopback IPv4 addresses bound to this host.
+ */
+function getLocalIpv4Addresses() {
+    const out = [];
+    try {
+        const ifaces = networkInterfaces();
+        for (const list of Object.values(ifaces)) {
+            if (!list)
+                continue;
+            for (const info of list) {
+                if (info.family !== "IPv4" || info.internal)
+                    continue;
+                out.push(info.address);
+            }
+        }
+    }
+    catch {
+        // best-effort
+    }
+    return out;
+}
+/**
+ * Enumerate non-loopback IPv4 subnets the local machine is attached to.
+ * Used to detect "same-LAN" candidates so we can prefer direct same-subnet
+ * UDP over public addresses that would require NAT hole-punching.
+ */
+function getLocalIpv4Subnets() {
+    const out = [];
+    try {
+        const ifaces = networkInterfaces();
+        for (const list of Object.values(ifaces)) {
+            if (!list)
+                continue;
+            for (const info of list) {
+                if (info.family !== "IPv4" || info.internal)
+                    continue;
+                const addr = ipv4ToInt(info.address);
+                const mask = netmaskToInt(info.netmask);
+                if (addr === undefined || mask === undefined || mask === 0)
+                    continue;
+                out.push({ networkBits: (addr & mask) >>> 0, maskBits: mask });
+            }
+        }
+    }
+    catch {
+        // best-effort; no LAN-prefer hint when interface introspection fails
+    }
+    return out;
+}
+function isInIpv4Subnet(host, subnet) {
+    const ip = ipv4ToInt(host);
+    if (ip === undefined)
+        return false;
+    return ((ip & subnet.maskBits) >>> 0) === subnet.networkBits;
+}
+function isPrivateAddress(host) {
+    // RFC1918 IPv4: 10/8, 172.16/12, 192.168/16; loopback 127/8;
+    // link-local 169.254/16; carrier-grade NAT 100.64/10. IPv6 link-local fe80::/10
+    // and unique-local fc00::/7.
+    if (!host)
+        return false;
+    if (host === "localhost")
+        return true;
+    // IPv6 quick check
+    if (host.includes(":")) {
+        const lower = host.toLowerCase();
+        if (lower === "::1")
+            return true;
+        if (lower.startsWith("fe80:"))
+            return true;
+        if (lower.startsWith("fc") || lower.startsWith("fd"))
+            return true;
+        return false;
+    }
+    // IPv4 dotted quad
+    const parts = host.split(".");
+    if (parts.length !== 4)
+        return false;
+    const oct = parts.map((p) => Number.parseInt(p, 10));
+    if (oct.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return false;
+    if (oct[0] === 10)
+        return true;
+    if (oct[0] === 127)
+        return true;
+    if (oct[0] === 169 && oct[1] === 254)
+        return true;
+    if (oct[0] === 172 && oct[1] >= 16 && oct[1] <= 31)
+        return true;
+    if (oct[0] === 192 && oct[1] === 168)
+        return true;
+    if (oct[0] === 100 && oct[1] >= 64 && oct[1] <= 127)
+        return true;
+    return false;
+}
+function readEnvInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}