@decentnetwork/peer 0.1.0

package/dist/compat/tcp-relay.d.ts

@@ -0,0 +1,96 @@
+import { EventEmitter } from "node:events";
+import type { KeyPair } from "../crypto/keypair.js";
+export declare const TCP_PACKET_ROUTING_REQUEST = 0;
+export declare const TCP_PACKET_ROUTING_RESPONSE = 1;
+export declare const TCP_PACKET_CONNECTION_NOTIFICATION = 2;
+export declare const TCP_PACKET_DISCONNECT_NOTIFICATION = 3;
+export declare const TCP_PACKET_PING = 4;
+export declare const TCP_PACKET_PONG = 5;
+export declare const TCP_PACKET_OOB_SEND = 6;
+export declare const TCP_PACKET_OOB_RECV = 7;
+export declare const TCP_PACKET_ONION_REQUEST = 8;
+export declare const TCP_PACKET_ONION_RESPONSE = 9;
+export type TcpRelayState = "disconnected" | "connecting" | "handshake-sent" | "connected" | "closed";
+export type TcpRelayOptions = {
+    /** Hostname or IPv4 of the relay server. */
+    host: string;
+    /** TCP port. Carrier bootstraps typically run on 443, 3389, or 33445. */
+    port: number;
+    /** Server's DHT public key (the same `pk` field used for the UDP DHT). */
+    serverPublicKey: Uint8Array;
+    /** Our DHT keypair (= our real keypair in this codebase). */
+    selfKeyPair: KeyPair;
+    /** Optional debug label (operator-supplied) for log lines. */
+    label?: string;
+};
+/** Inbound traffic surfaced to the owner. */
+export type TcpRelayEvents = {
+    /** Handshake completed; the relay is now usable. */
+    open: () => void;
+    /** Connection terminated, either by us or by remote. */
+    close: (reason: string) => void;
+    /**
+     * The relay accepted our ROUTING_REQUEST and assigned a connection_id.
+     * Surfaced for diagnostics; for actual messaging use the `friendOnline`
+     * / `peerData` events which key by the friend's real public key.
+     */
+    routing: (connectionId: number, friendKey: Uint8Array) => void;
+    /**
+     * Friend (identified by their real pubkey) is now actively connected
+     * to this relay and routing is up. Both sides asked the relay about
+     * each other; we and they can now exchange DATA.
+     */
+    friendOnline: (friendPublicKey: Uint8Array) => void;
+    /** Friend dropped from the relay. */
+    friendOffline: (friendPublicKey: Uint8Array) => void;
+    /**
+     * Inbound DATA from a connected friend, already mapped by the client's
+     * internal connection_id → pubkey table. Treat the payload as you
+     * would a UDP datagram from that friend (cookie request / response /
+     * handshake / crypto_data, with the same iveg magic prefix as UDP).
+     */
+    peerData: (friendPublicKey: Uint8Array, payload: Uint8Array) => void;
+    /** Inbound OOB_RECV — friend's pubkey + payload (used for friend requests). */
+    oob: (senderPublicKey: Uint8Array, payload: Uint8Array) => void;
+    /** Pong (response to our ping). */
+    pong: (pingId: bigint) => void;
+};
+export declare class TcpRelayClient extends EventEmitter {
+    #private;
+    constructor(opts: TcpRelayOptions);
+    state(): TcpRelayState;
+    /**
+     * Open the TCP connection and perform the handshake. Resolves once the
+     * relay is in "connected" state (handshake response decrypted, session
+     * keys derived). Rejects on any failure during connect or handshake.
+     */
+    connect(timeoutMs?: number): Promise<void>;
+    /**
+     * Send ROUTING_REQUEST so the relay starts watching for `friendPublicKey`.
+     * Idempotent — calling twice with the same key is a no-op (the relay
+     * would otherwise allocate a duplicate cid). Use `forgetRoute` to
+     * forcibly re-request.
+     */
+    requestRoute(friendPublicKey: Uint8Array): boolean;
+    /** Returns true if we've received a CONNECTION_NOTIFICATION for this friend. */
+    hasFriendOnline(friendPublicKey: Uint8Array): boolean;
+    /** Returns true if we've sent a ROUTING_REQUEST for this friend (regardless of online state). */
+    hasRequestedRoute(friendPublicKey: Uint8Array): boolean;
+    /**
+     * Send a DATA payload to `friendPublicKey` over this relay. Returns
+     * false if the friend hasn't been routed (no ROUTING_RESPONSE yet) or
+     * if the relay says they're offline. Caller should treat false as
+     * "try another transport".
+     */
+    sendToFriend(friendPublicKey: Uint8Array, payload: Uint8Array): boolean;
+    /** Send a PING; relay echoes it as PONG. ping_id is opaque 8 bytes. */
+    sendPing(): boolean;
+    /** Send DATA payload to the friend at `connectionId`. */
+    sendData(connectionId: number, payload: Uint8Array): boolean;
+    /** Send OOB_SEND (used for delivering friend requests via TCP relay). */
+    sendOob(receiverPublicKey: Uint8Array, payload: Uint8Array): boolean;
+    close(reason?: string): void;
+    on<E extends keyof TcpRelayEvents>(event: E, listener: TcpRelayEvents[E]): this;
+    once<E extends keyof TcpRelayEvents>(event: E, listener: TcpRelayEvents[E]): this;
+    off<E extends keyof TcpRelayEvents>(event: E, listener: TcpRelayEvents[E]): this;
+}

package/dist/compat/tcp-relay.js

@@ -0,0 +1,489 @@
+// TCP relay client — port of toxcore's TCP_client.c.
+//
+// Carrier (= unmodified toxcore) has two transports for net_crypto traffic
+// between peers:
+//
+//   1. UDP/onion direct — fast, but blocked by hostile NATs and rate-
+//      limited by some ISPs.
+//   2. TCP relay — every Carrier bootstrap also runs a TCP relay server
+//      on ports 443/3389/33445. Each peer maintains 1-3 persistent TCP
+//      connections to relay servers. When two peers want to talk and at
+//      least one of them can't reach the other via UDP, they exchange
+//      packets through a relay they both happen to be connected to.
+//
+// iOS Beagle uses TCP relays as its *primary* path (its DHT-PK announces
+// only ever advertise TCP relay endpoints — `0x82 = TCP_FAMILY_IPV4` in
+// the packed-nodes extras). Without a TCP client on our side, an iPad/
+// iPhone Beagle peer will mark us offline forever even though everything
+// else is correctly configured.
+//
+// This module implements the client half of the toxcore TCP relay
+// protocol. The server side (TCP_server.c) is hosted by Carrier
+// bootstrap operators; we never run a server. Reference:
+//
+//   toxcore/TCP_client.{c,h}   — what this is a port of
+//   toxcore/TCP_connection.{c,h} — multi-relay coordinator (Phase 6)
+//   toxcore/TCP_server.h         — packet-type constants
+//
+// Threading / lifecycle: one TcpRelayClient = one persistent TCP
+// connection to one relay. Open it once at peer.start, keep it alive
+// with PING every ~10s, reconnect if the socket drops. The Peer class
+// will own a small pool (Phase 6).
+import nacl from "tweetnacl";
+import { connect as netConnect } from "node:net";
+import { EventEmitter } from "node:events";
+import { concatBytes, randomBytes } from "../utils/bytes.js";
+import { incrementNonce } from "./net-crypto.js";
+const KEY_SIZE = 32;
+const NONCE_SIZE = 24;
+const MAC_SIZE = 16;
+/** TCP_HANDSHAKE_PLAIN_SIZE in toxcore — temp pubkey + initial nonce. */
+const TCP_HANDSHAKE_PLAIN_SIZE = KEY_SIZE + NONCE_SIZE;
+/** Outbound handshake: self_dht_pk(32) + nonce(24) + box(plain)(KEY_SIZE+NONCE_SIZE+MAC_SIZE = 72) = 128. */
+const TCP_CLIENT_HANDSHAKE_SIZE = KEY_SIZE + NONCE_SIZE + TCP_HANDSHAKE_PLAIN_SIZE + MAC_SIZE;
+/** Inbound handshake response: nonce(24) + box(plain)(KEY_SIZE+NONCE_SIZE+MAC_SIZE = 72) = 96. */
+const TCP_SERVER_HANDSHAKE_SIZE = NONCE_SIZE + TCP_HANDSHAKE_PLAIN_SIZE + MAC_SIZE;
+// TCP_PACKET_* constants — see toxcore/TCP_server.h. Packet type 16+ is
+// data forwarded to/from a routed friend (the type byte is the
+// connection_id; payload is whatever the friend sent us).
+export const TCP_PACKET_ROUTING_REQUEST = 0;
+export const TCP_PACKET_ROUTING_RESPONSE = 1;
+export const TCP_PACKET_CONNECTION_NOTIFICATION = 2;
+export const TCP_PACKET_DISCONNECT_NOTIFICATION = 3;
+export const TCP_PACKET_PING = 4;
+export const TCP_PACKET_PONG = 5;
+export const TCP_PACKET_OOB_SEND = 6;
+export const TCP_PACKET_OOB_RECV = 7;
+export const TCP_PACKET_ONION_REQUEST = 8;
+export const TCP_PACKET_ONION_RESPONSE = 9;
+/** Max payload of a single framed packet (toxcore: MAX_PACKET_SIZE = 2048). */
+const MAX_PACKET_SIZE = 2048;
+/**
+ * Carrier-only TCP frame magic. Handshake packets (in either direction)
+ * are sent raw, but every encrypted frame *after* the handshake is
+ * prefixed with these 4 bytes. The server (TCP_server.c::read_TCP_length)
+ * reads the magic before reading the 2-byte length and rejects frames
+ * without it. Same convention as the iveg prefix on UDP datagrams,
+ * applied at the TCP layer in TCP_client.c::write_packet_TCP_secure_connection.
+ */
+const CARRIER_TCP_MAGIC = Uint8Array.of(0x69, 0x76, 0x65, 0x67);
+export class TcpRelayClient extends EventEmitter {
+    #opts;
+    #socket;
+    #state = "disconnected";
+    #debug = process.env.DECENT_DEBUG === "1";
+    // Crypto state derived during handshake.
+    #tempKeyPair;
+    #sentNonce; // TX nonce — increments per outbound encrypted frame
+    #recvNonce; // RX nonce — increments per inbound encrypted frame
+    #sessionKey; // box.before(server_temp_pk, our_temp_sk), used as secretbox key
+    // RX buffer for the framed encrypted stream.
+    #rxBuf = Buffer.alloc(0);
+    // Routing state — the relay assigns one connection_id per friend we
+    // requested routing for, in [16, 255]. Map both ways so we can:
+    //   - resolve inbound DATA(connection_id) to friend pubkey
+    //   - resolve outbound sendToFriend(pubkey) to a connection_id
+    #cidByFriend = new Map(); // hex(friend pubkey) -> cid
+    #friendByCid = new Map(); // cid -> raw friend pubkey
+    // Friends whose routing we've requested but the relay hasn't yet
+    // sent CONNECTION_NOTIFICATION for. We dedupe re-requests via this set.
+    #routesRequested = new Set(); // hex(friend pubkey)
+    constructor(opts) {
+        super();
+        if (opts.serverPublicKey.length !== KEY_SIZE) {
+            throw new Error(`relay server public key must be ${KEY_SIZE} bytes`);
+        }
+        this.#opts = opts;
+    }
+    state() {
+        return this.#state;
+    }
+    /**
+     * Open the TCP connection and perform the handshake. Resolves once the
+     * relay is in "connected" state (handshake response decrypted, session
+     * keys derived). Rejects on any failure during connect or handshake.
+     */
+    async connect(timeoutMs = 10_000) {
+        if (this.#state !== "disconnected" && this.#state !== "closed") {
+            throw new Error(`relay already ${this.#state}`);
+        }
+        this.#state = "connecting";
+        this.#log(`connecting to ${this.#opts.host}:${this.#opts.port}`);
+        return new Promise((resolve, reject) => {
+            const sock = netConnect({ host: this.#opts.host, port: this.#opts.port });
+            this.#socket = sock;
+            let settled = false;
+            const fail = (reason) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.#close(reason);
+                reject(new Error(reason));
+            };
+            const ok = () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve();
+            };
+            const connectTimer = setTimeout(() => fail(`connect timeout after ${timeoutMs}ms`), timeoutMs);
+            sock.once("error", (err) => {
+                clearTimeout(connectTimer);
+                fail(`socket error: ${err.message}`);
+            });
+            sock.once("close", () => {
+                clearTimeout(connectTimer);
+                if (!settled)
+                    fail("socket closed before handshake completed");
+                else
+                    this.#close("socket closed");
+            });
+            sock.once("connect", () => {
+                clearTimeout(connectTimer);
+                try {
+                    const handshake = this.#buildHandshake();
+                    sock.write(handshake);
+                    this.#state = "handshake-sent";
+                    this.#log(`handshake sent (${handshake.length} bytes), waiting for server response`);
+                }
+                catch (err) {
+                    fail(`handshake build failed: ${err.message}`);
+                    return;
+                }
+                // Wait specifically for the 96-byte handshake response.
+                let handshakeBuf = Buffer.alloc(0);
+                const onHandshakeData = (chunk) => {
+                    handshakeBuf = Buffer.concat([handshakeBuf, chunk]);
+                    if (handshakeBuf.length < TCP_SERVER_HANDSHAKE_SIZE) {
+                        return;
+                    }
+                    const hs = handshakeBuf.subarray(0, TCP_SERVER_HANDSHAKE_SIZE);
+                    const remainder = handshakeBuf.subarray(TCP_SERVER_HANDSHAKE_SIZE);
+                    sock.removeListener("data", onHandshakeData);
+                    try {
+                        this.#processHandshakeResponse(hs);
+                    }
+                    catch (err) {
+                        fail(`handshake response decrypt failed: ${err.message}`);
+                        return;
+                    }
+                    this.#state = "connected";
+                    this.#log(`handshake complete; session ready`);
+                    // Switch to the framed-data parser for everything after.
+                    sock.on("data", (next) => this.#onData(next));
+                    // If the handshake response chunk also carried framed data, feed it.
+                    if (remainder.length > 0) {
+                        this.#onData(remainder);
+                    }
+                    this.emit("open");
+                    ok();
+                };
+                sock.on("data", onHandshakeData);
+            });
+        });
+    }
+    /**
+     * Construct the 128-byte client handshake (toxcore TCP_client.c::generate_handshake).
+     * Layout:
+     *   [self_dht_pubkey (32)] [nonce (24)] [box(plain) (72)]
+     * where plain = [temp_pubkey (32)] [sent_nonce (24)] encrypted with
+     * shared(serverPublicKey, selfSecretKey) using the random nonce.
+     */
+    #buildHandshake() {
+        this.#tempKeyPair = (() => {
+            const kp = nacl.box.keyPair();
+            return { publicKey: kp.publicKey, secretKey: kp.secretKey };
+        })();
+        this.#sentNonce = randomBytes(NONCE_SIZE);
+        const plain = concatBytes([this.#tempKeyPair.publicKey, this.#sentNonce]);
+        const handshakeNonce = randomBytes(NONCE_SIZE);
+        const sharedKey = nacl.box.before(this.#opts.serverPublicKey, this.#opts.selfKeyPair.secretKey);
+        const encrypted = nacl.box.after(plain, handshakeNonce, sharedKey);
+        return concatBytes([this.#opts.selfKeyPair.publicKey, handshakeNonce, encrypted]);
+    }
+    /**
+     * Decrypt the 96-byte server handshake response (toxcore TCP_client.c::handle_handshake).
+     * Layout:
+     *   [nonce (24)] [box(plain) (72)]
+     * plain = [server_temp_pubkey (32)] [recv_nonce (24)]
+     * Sets #recvNonce and derives the session key for the encrypted stream.
+     */
+    #processHandshakeResponse(hs) {
+        if (hs.length !== TCP_SERVER_HANDSHAKE_SIZE) {
+            throw new Error(`handshake response must be ${TCP_SERVER_HANDSHAKE_SIZE} bytes`);
+        }
+        const nonce = hs.subarray(0, NONCE_SIZE);
+        const cipher = hs.subarray(NONCE_SIZE);
+        const sharedKey = nacl.box.before(this.#opts.serverPublicKey, this.#opts.selfKeyPair.secretKey);
+        const plain = nacl.box.open.after(cipher, nonce, sharedKey);
+        if (!plain || plain.length !== TCP_HANDSHAKE_PLAIN_SIZE) {
+            throw new Error("handshake response decrypt failed");
+        }
+        const serverTempPub = plain.subarray(0, KEY_SIZE);
+        const recvNonce = plain.subarray(KEY_SIZE, KEY_SIZE + NONCE_SIZE);
+        if (!this.#tempKeyPair) {
+            throw new Error("no temp keypair set");
+        }
+        // Derive the session key used for all subsequent secretbox frames.
+        this.#sessionKey = nacl.box.before(serverTempPub, this.#tempKeyPair.secretKey);
+        this.#recvNonce = new Uint8Array(recvNonce);
+        // Wipe the temp secret key — toxcore does crypto_memzero here.
+        this.#tempKeyPair.secretKey.fill(0);
+    }
+    /**
+     * Frame parser for everything after the handshake. Each frame is
+     *   [4-byte 'iveg' magic][2-byte BE length][secretbox-encrypted body]
+     * Bodies may straddle TCP read chunks — buffer until a complete frame
+     * is available, then dispatch.
+     */
+    #onData(chunk) {
+        this.#rxBuf = this.#rxBuf.length === 0 ? chunk : Buffer.concat([this.#rxBuf, chunk]);
+        while (this.#rxBuf.length >= 4 + 2) {
+            // Verify the iveg prefix before reading the length.
+            if (this.#rxBuf[0] !== CARRIER_TCP_MAGIC[0] ||
+                this.#rxBuf[1] !== CARRIER_TCP_MAGIC[1] ||
+                this.#rxBuf[2] !== CARRIER_TCP_MAGIC[2] ||
+                this.#rxBuf[3] !== CARRIER_TCP_MAGIC[3]) {
+                this.#close("missing/invalid iveg magic on TCP frame");
+                return;
+            }
+            const frameLen = this.#rxBuf.readUInt16BE(4);
+            if (frameLen === 0 || frameLen > MAX_PACKET_SIZE) {
+                this.#close(`invalid frame length ${frameLen}`);
+                return;
+            }
+            if (this.#rxBuf.length < 4 + 2 + frameLen) {
+                return; // wait for more data
+            }
+            const cipher = this.#rxBuf.subarray(4 + 2, 4 + 2 + frameLen);
+            this.#rxBuf = this.#rxBuf.subarray(4 + 2 + frameLen);
+            const plain = this.#decryptFrame(cipher);
+            if (!plain) {
+                this.#close("frame decrypt failed");
+                return;
+            }
+            this.#dispatch(plain);
+        }
+    }
+    /** Decrypt one frame body using sessionKey + #recvNonce, then increment nonce. */
+    #decryptFrame(cipher) {
+        if (!this.#sessionKey || !this.#recvNonce)
+            return undefined;
+        const opened = nacl.secretbox.open(cipher, this.#recvNonce, this.#sessionKey);
+        if (!opened)
+            return undefined;
+        incrementNonce(this.#recvNonce);
+        return opened;
+    }
+    /** Encrypt a payload and write it as one framed packet. */
+    #sendFrame(payload) {
+        if (this.#state !== "connected" || !this.#sessionKey || !this.#sentNonce || !this.#socket) {
+            return false;
+        }
+        if (payload.length === 0 || payload.length > MAX_PACKET_SIZE - MAC_SIZE) {
+            return false;
+        }
+        const cipher = nacl.secretbox(payload, this.#sentNonce, this.#sessionKey);
+        incrementNonce(this.#sentNonce);
+        // Wire layout: [4-byte iveg][2-byte BE length][cipher].
+        const frame = Buffer.alloc(4 + 2 + cipher.length);
+        frame.set(CARRIER_TCP_MAGIC, 0);
+        frame.writeUInt16BE(cipher.length, 4);
+        frame.set(cipher, 4 + 2);
+        return this.#socket.write(frame);
+    }
+    /**
+     * Dispatch a decrypted packet by leading byte. The toxcore wire format
+     * uses the first byte as the packet type; values 0-9 are control
+     * packets (see TCP_PACKET_* constants), and values 16+ are data
+     * forwarded between routed peers — the byte itself is the connection_id.
+     */
+    #dispatch(plain) {
+        if (plain.length === 0)
+            return;
+        const type = plain[0];
+        const body = plain.subarray(1);
+        switch (type) {
+            case TCP_PACKET_ROUTING_RESPONSE: {
+                // [rpid (1)][friend_pubkey (32)] — rpid is the connection_id, or 0
+                // if the relay refused to allocate one (e.g. table full).
+                if (body.length < 1 + KEY_SIZE)
+                    return;
+                const connectionId = body[0];
+                const friendKey = body.subarray(1, 1 + KEY_SIZE);
+                if (connectionId !== 0) {
+                    const friendHex = Buffer.from(friendKey).toString("hex");
+                    this.#cidByFriend.set(friendHex, connectionId);
+                    this.#friendByCid.set(connectionId, new Uint8Array(friendKey));
+                }
+                this.emit("routing", connectionId, friendKey);
+                return;
+            }
+            case TCP_PACKET_CONNECTION_NOTIFICATION: {
+                if (body.length < 1)
+                    return;
+                const cid = body[0];
+                const friendKey = this.#friendByCid.get(cid);
+                if (friendKey) {
+                    this.emit("friendOnline", friendKey);
+                }
+                return;
+            }
+            case TCP_PACKET_DISCONNECT_NOTIFICATION: {
+                if (body.length < 1)
+                    return;
+                const cid = body[0];
+                const friendKey = this.#friendByCid.get(cid);
+                if (friendKey) {
+                    this.emit("friendOffline", friendKey);
+                }
+                return;
+            }
+            case TCP_PACKET_PING: {
+                // Server-initiated ping — respond with PONG echoing the ping_id.
+                if (body.length < 8)
+                    return;
+                const pingId = body.subarray(0, 8);
+                this.#sendFrame(concatBytes([Uint8Array.of(TCP_PACKET_PONG), pingId]));
+                return;
+            }
+            case TCP_PACKET_PONG: {
+                if (body.length < 8)
+                    return;
+                let v = 0n;
+                for (let i = 0; i < 8; i++)
+                    v = (v << 8n) | BigInt(body[i]);
+                this.emit("pong", v);
+                return;
+            }
+            case TCP_PACKET_OOB_RECV: {
+                // [sender_pubkey (32)][payload]
+                if (body.length < KEY_SIZE)
+                    return;
+                const sender = body.subarray(0, KEY_SIZE);
+                const payload = body.subarray(KEY_SIZE);
+                this.emit("oob", sender, payload);
+                return;
+            }
+            default: {
+                if (type >= 16) {
+                    // DATA forwarded by relay from a connected peer. Resolve
+                    // connection_id → friend pubkey and surface as peerData. If we
+                    // somehow haven't recorded the cid (race with a stale relay
+                    // entry), drop silently — owner can't act on a connection_id
+                    // they don't have a key for.
+                    const friendKey = this.#friendByCid.get(type);
+                    if (friendKey) {
+                        this.emit("peerData", friendKey, body);
+                    }
+                    return;
+                }
+                // Other types (ROUTING_REQUEST, OOB_SEND, ONION_REQUEST/RESPONSE)
+                // are server-bound or out of scope for this phase.
+            }
+        }
+    }
+    /**
+     * Send ROUTING_REQUEST so the relay starts watching for `friendPublicKey`.
+     * Idempotent — calling twice with the same key is a no-op (the relay
+     * would otherwise allocate a duplicate cid). Use `forgetRoute` to
+     * forcibly re-request.
+     */
+    requestRoute(friendPublicKey) {
+        if (friendPublicKey.length !== KEY_SIZE)
+            return false;
+        const friendHex = Buffer.from(friendPublicKey).toString("hex");
+        if (this.#routesRequested.has(friendHex) || this.#cidByFriend.has(friendHex)) {
+            return true; // already requested or established
+        }
+        this.#routesRequested.add(friendHex);
+        return this.#sendFrame(concatBytes([Uint8Array.of(TCP_PACKET_ROUTING_REQUEST), friendPublicKey]));
+    }
+    /** Returns true if we've received a CONNECTION_NOTIFICATION for this friend. */
+    hasFriendOnline(friendPublicKey) {
+        if (friendPublicKey.length !== KEY_SIZE)
+            return false;
+        return this.#cidByFriend.has(Buffer.from(friendPublicKey).toString("hex"));
+    }
+    /** Returns true if we've sent a ROUTING_REQUEST for this friend (regardless of online state). */
+    hasRequestedRoute(friendPublicKey) {
+        if (friendPublicKey.length !== KEY_SIZE)
+            return false;
+        const friendHex = Buffer.from(friendPublicKey).toString("hex");
+        return this.#routesRequested.has(friendHex) || this.#cidByFriend.has(friendHex);
+    }
+    /**
+     * Send a DATA payload to `friendPublicKey` over this relay. Returns
+     * false if the friend hasn't been routed (no ROUTING_RESPONSE yet) or
+     * if the relay says they're offline. Caller should treat false as
+     * "try another transport".
+     */
+    sendToFriend(friendPublicKey, payload) {
+        if (friendPublicKey.length !== KEY_SIZE)
+            return false;
+        const cid = this.#cidByFriend.get(Buffer.from(friendPublicKey).toString("hex"));
+        if (cid === undefined)
+            return false;
+        return this.sendData(cid, payload);
+    }
+    /** Send a PING; relay echoes it as PONG. ping_id is opaque 8 bytes. */
+    sendPing() {
+        const pingId = randomBytes(8);
+        return this.#sendFrame(concatBytes([Uint8Array.of(TCP_PACKET_PING), pingId]));
+    }
+    /** Send DATA payload to the friend at `connectionId`. */
+    sendData(connectionId, payload) {
+        if (connectionId < 16 || connectionId > 0xff)
+            return false;
+        if (payload.length === 0)
+            return false;
+        return this.#sendFrame(concatBytes([Uint8Array.of(connectionId), payload]));
+    }
+    /** Send OOB_SEND (used for delivering friend requests via TCP relay). */
+    sendOob(receiverPublicKey, payload) {
+        if (receiverPublicKey.length !== KEY_SIZE)
+            return false;
+        return this.#sendFrame(concatBytes([Uint8Array.of(TCP_PACKET_OOB_SEND), receiverPublicKey, payload]));
+    }
+    close(reason = "explicit close") {
+        this.#close(reason);
+    }
+    #close(reason) {
+        if (this.#state === "closed")
+            return;
+        this.#state = "closed";
+        this.#log(`closing: ${reason}`);
+        if (this.#socket) {
+            try {
+                this.#socket.destroy();
+            }
+            catch { /* ignore */ }
+            this.#socket = undefined;
+        }
+        if (this.#sentNonce)
+            this.#sentNonce.fill(0);
+        if (this.#sessionKey)
+            this.#sessionKey.fill(0);
+        this.#sentNonce = undefined;
+        this.#recvNonce = undefined;
+        this.#sessionKey = undefined;
+        this.#tempKeyPair = undefined;
+        this.emit("close", reason);
+    }
+    #log(message) {
+        if (!this.#debug)
+            return;
+        const label = this.#opts.label ? `:${this.#opts.label}` : "";
+        console.log(`[peer-debug:tcp-relay${label}] ${this.#opts.host}:${this.#opts.port} ${message}`);
+    }
+    // Strongly-typed event helpers so callers get autocompletion.
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+}

package/dist/compat/text.d.ts

@@ -0,0 +1,3 @@
+export declare class LegacyTextClient {
+    send(pubkey: string, text: string): Promise<never>;
+}

package/dist/compat/text.js

@@ -0,0 +1,8 @@
+import { LegacyProtocolNotImplementedError } from "../runtime/errors.js";
+export class LegacyTextClient {
+    async send(pubkey, text) {
+        void pubkey;
+        void text;
+        throw new LegacyProtocolNotImplementedError("Legacy online text");
+    }
+}

package/dist/compat/tox-dht-crypto.d.ts

@@ -0,0 +1,18 @@
+import type { KeyPair } from "../crypto/keypair.js";
+export declare const NET_PACKET_CRYPTO = 32;
+export declare const CRYPTO_PACKET_FRIEND_REQ = 32;
+export declare const CRYPTO_PACKET_DHTPK = 156;
+export declare const CRYPTO_PACKET_NAT_PING = 254;
+export type ToxDhtCryptoRequest = {
+    receiverPublicKey: Uint8Array;
+    senderPublicKey: Uint8Array;
+    requestId: number;
+    data: Uint8Array;
+};
+export declare function createToxDhtCryptoRequest(opts: {
+    sender: KeyPair;
+    receiverPublicKey: Uint8Array;
+    requestId: number;
+    data: Uint8Array;
+}): Uint8Array;
+export declare function openToxDhtCryptoRequest(packet: Uint8Array, self: KeyPair): ToxDhtCryptoRequest | undefined;