@decentnetwork/peer 0.1.16 → 0.1.18

package/dist/turn.js

@@ -0,0 +1,275 @@
+/**
+ * Minimal TURN client (RFC 5766 subset) for the Carrier bootnode TURN
+ * servers running on UDP/3478. Covers:
+ *
+ *  - ALLOCATE (with the long-term cred dance: 401 → echo realm/nonce → success)
+ *  - REFRESH  (keeps the allocation alive past `lifetime`)
+ *  - CREATE-PERMISSION (one per peer address we want to send to)
+ *  - SEND-INDICATION   (wraps app data going out via the relay)
+ *  - DATA-INDICATION   (unwraps app data coming in via the relay)
+ *
+ * Deliberately skipped to keep this small:
+ *  - ChannelBind / ChannelData framing — minor bandwidth win, more state
+ *  - TCP TURN, TURN-over-TLS
+ *  - DontFragment, Even-port, reservation tokens
+ *
+ * Owns its UDP socket exclusively while a request is in flight. The
+ * caller can multiplex by using a separate TurnClient per allocation
+ * (one per bootnode), which is what ICE will do.
+ */
+import { buildBindingRequest, // re-used as a NAT-probe before TURN allocation
+decodeStun, decodeXorMappedAddress, encodeStun, encodeXorMappedAddress, findAttr, longTermIntegrityKey, newTransactionId, STUN_ATTR_DATA, STUN_ATTR_ERROR_CODE, STUN_ATTR_LIFETIME, STUN_ATTR_NONCE, STUN_ATTR_REALM, STUN_ATTR_REQUESTED_TRANSPORT, STUN_ATTR_SOFTWARE, STUN_ATTR_USERNAME, STUN_ATTR_XOR_PEER_ADDRESS, STUN_ATTR_XOR_RELAYED_ADDRESS, TURN_ALLOCATE_ERROR, TURN_ALLOCATE_REQUEST, TURN_ALLOCATE_SUCCESS, TURN_CREATE_PERMISSION_REQUEST, TURN_CREATE_PERMISSION_SUCCESS, TURN_DATA_INDICATION, TURN_REFRESH_REQUEST, TURN_REFRESH_SUCCESS, TURN_SEND_INDICATION, decodeErrorCode } from "./stun.js";
+const REQUEST_TIMEOUT_MS = 3000;
+const REQUEST_RETRIES = 3;
+const SOFTWARE_NAME = "decentnet-peer/0.1";
+export class TurnClient {
+    creds;
+    #sock;
+    #realm;
+    #nonce;
+    #integrityKey;
+    #allocation;
+    #pending = new Map();
+    #onData;
+    #refreshTimer;
+    #closed = false;
+    /**
+     * The TURN server's resolved IP. We filter inbound datagrams by source
+     * so a shared socket doesn't feed us unrelated traffic — but inbound
+     * `rinfo.address` is always an IP, while `creds.host` may be a
+     * hostname (e.g. "tokyo.fi.chat"). Resolve once and compare against
+     * the IP. Until resolved, we fall back to txn-matching only.
+     */
+    #serverIp;
+    constructor(opts) {
+        this.#sock = opts.sock;
+        this.creds = opts.creds;
+        this.#realm = opts.creds.realm;
+        // If creds.host is already a dotted-quad, use it directly.
+        if (/^\d+\.\d+\.\d+\.\d+$/.test(opts.creds.host)) {
+            this.#serverIp = opts.creds.host;
+        }
+        this.#sock.on("message", this.#onMessage);
+    }
+    /**
+     * Perform the long-term-credential ALLOCATE dance. Returns the
+     * server-reflexive (mapped) and relay-allocated addresses, plus the
+     * allocation lifetime.
+     */
+    async allocate() {
+        // Resolve the TURN server host to an IP so inbound-source filtering
+        // works when creds.host is a hostname.
+        if (!this.#serverIp) {
+            try {
+                const { lookup } = await import("dns/promises");
+                const { address } = await lookup(this.creds.host, { family: 4 });
+                this.#serverIp = address;
+            }
+            catch {
+                // best-effort; #onMessage falls back to txn-only matching
+            }
+        }
+        // Step 1: send a bare ALLOCATE — server replies 401 with realm/nonce
+        const initialAttrs = [
+            { type: STUN_ATTR_REQUESTED_TRANSPORT, value: Uint8Array.of(17, 0, 0, 0) }, // 17 = UDP
+            { type: STUN_ATTR_SOFTWARE, value: Buffer.from(SOFTWARE_NAME, "utf8") }
+        ];
+        const first = await this.#request(TURN_ALLOCATE_REQUEST, initialAttrs);
+        if (first.type === TURN_ALLOCATE_SUCCESS) {
+            return this.#parseAllocateSuccess(first);
+        }
+        if (first.type !== TURN_ALLOCATE_ERROR) {
+            throw new Error(`unexpected ALLOCATE response type 0x${first.type.toString(16)}`);
+        }
+        const realmAttr = findAttr(first, STUN_ATTR_REALM);
+        const nonceAttr = findAttr(first, STUN_ATTR_NONCE);
+        if (!realmAttr || !nonceAttr) {
+            const err = findAttr(first, STUN_ATTR_ERROR_CODE);
+            const decoded = err ? decodeErrorCode(err) : undefined;
+            throw new Error(`ALLOCATE 401 missing realm/nonce (code=${decoded?.code} reason=${decoded?.reason})`);
+        }
+        this.#realm = Buffer.from(realmAttr).toString("utf8");
+        this.#nonce = nonceAttr;
+        this.#integrityKey = longTermIntegrityKey(this.creds.username, this.#realm, this.creds.password);
+        // Step 2: re-send ALLOCATE authenticated
+        const authed = await this.#request(TURN_ALLOCATE_REQUEST, [
+            { type: STUN_ATTR_REQUESTED_TRANSPORT, value: Uint8Array.of(17, 0, 0, 0) },
+            { type: STUN_ATTR_SOFTWARE, value: Buffer.from(SOFTWARE_NAME, "utf8") },
+            { type: STUN_ATTR_USERNAME, value: Buffer.from(this.creds.username, "utf8") },
+            { type: STUN_ATTR_REALM, value: Buffer.from(this.#realm, "utf8") },
+            { type: STUN_ATTR_NONCE, value: this.#nonce }
+        ]);
+        if (authed.type !== TURN_ALLOCATE_SUCCESS) {
+            const err = findAttr(authed, STUN_ATTR_ERROR_CODE);
+            const decoded = err ? decodeErrorCode(err) : undefined;
+            throw new Error(`ALLOCATE failed code=${decoded?.code} reason=${decoded?.reason}`);
+        }
+        const allocation = this.#parseAllocateSuccess(authed);
+        this.#allocation = allocation;
+        this.#scheduleRefresh(allocation.lifetime);
+        return allocation;
+    }
+    /**
+     * Tell the TURN server we want to send to / receive from `peer`.
+     * Required before SEND-INDICATION will actually relay.
+     */
+    async createPermission(peer) {
+        if (!this.#integrityKey || !this.#nonce) {
+            throw new Error("createPermission called before allocate()");
+        }
+        const resp = await this.#request(TURN_CREATE_PERMISSION_REQUEST, [
+            { type: STUN_ATTR_XOR_PEER_ADDRESS, value: encodeXorMappedAddress(peer, newTransactionId()) },
+            { type: STUN_ATTR_USERNAME, value: Buffer.from(this.creds.username, "utf8") },
+            { type: STUN_ATTR_REALM, value: Buffer.from(this.#realm, "utf8") },
+            { type: STUN_ATTR_NONCE, value: this.#nonce }
+        ]);
+        if (resp.type !== TURN_CREATE_PERMISSION_SUCCESS) {
+            const err = findAttr(resp, STUN_ATTR_ERROR_CODE);
+            const decoded = err ? decodeErrorCode(err) : undefined;
+            throw new Error(`CREATE-PERMISSION failed code=${decoded?.code} reason=${decoded?.reason}`);
+        }
+    }
+    /**
+     * Wrap `data` in a SEND-INDICATION and ship it to the TURN server.
+     * Fire-and-forget — TURN indications never get a response.
+     */
+    sendTo(peer, data) {
+        const txn = newTransactionId();
+        const pkt = encodeStun({
+            type: TURN_SEND_INDICATION,
+            transactionId: txn,
+            attributes: [
+                { type: STUN_ATTR_XOR_PEER_ADDRESS, value: encodeXorMappedAddress(peer, txn) },
+                { type: STUN_ATTR_DATA, value: data }
+            ]
+        });
+        this.#sock.send(Buffer.from(pkt), this.creds.port, this.creds.host);
+    }
+    onData(cb) {
+        this.#onData = cb;
+    }
+    async refresh() {
+        if (!this.#integrityKey || !this.#nonce) {
+            throw new Error("refresh called before allocate()");
+        }
+        const resp = await this.#request(TURN_REFRESH_REQUEST, [
+            { type: STUN_ATTR_LIFETIME, value: u32Bytes(600) },
+            { type: STUN_ATTR_USERNAME, value: Buffer.from(this.creds.username, "utf8") },
+            { type: STUN_ATTR_REALM, value: Buffer.from(this.#realm, "utf8") },
+            { type: STUN_ATTR_NONCE, value: this.#nonce }
+        ]);
+        if (resp.type !== TURN_REFRESH_SUCCESS) {
+            // Stale nonce — server may have rotated. Re-allocate on next call.
+            this.#allocation = undefined;
+            const err = findAttr(resp, STUN_ATTR_ERROR_CODE);
+            const decoded = err ? decodeErrorCode(err) : undefined;
+            throw new Error(`REFRESH failed code=${decoded?.code} reason=${decoded?.reason}`);
+        }
+        const lifetimeAttr = findAttr(resp, STUN_ATTR_LIFETIME);
+        const lifetime = lifetimeAttr ? readU32(lifetimeAttr) : 600;
+        if (this.#allocation)
+            this.#allocation.lifetime = lifetime;
+        this.#scheduleRefresh(lifetime);
+    }
+    close() {
+        this.#closed = true;
+        if (this.#refreshTimer)
+            clearTimeout(this.#refreshTimer);
+        this.#sock.off("message", this.#onMessage);
+    }
+    // -- internal helpers -----------------------------------------------------
+    #onMessage = (data, rinfo) => {
+        // Filter to our TURN server. Compare against the resolved IP (rinfo
+        // is always an IP; creds.host may be a hostname). Wrong port is
+        // never ours; wrong IP only filters once resolved.
+        if (rinfo.port !== this.creds.port)
+            return;
+        if (this.#serverIp && rinfo.address !== this.#serverIp)
+            return;
+        const msg = decodeStun(data);
+        if (!msg)
+            return;
+        if (msg.type === TURN_DATA_INDICATION) {
+            const peerAttr = findAttr(msg, STUN_ATTR_XOR_PEER_ADDRESS);
+            const dataAttr = findAttr(msg, STUN_ATTR_DATA);
+            if (peerAttr && dataAttr && this.#onData) {
+                const peer = decodeXorMappedAddress(peerAttr, msg.transactionId);
+                if (peer)
+                    this.#onData(peer, dataAttr);
+            }
+            return;
+        }
+        const key = Buffer.from(msg.transactionId).toString("hex");
+        const resolve = this.#pending.get(key);
+        if (resolve) {
+            this.#pending.delete(key);
+            resolve(msg);
+        }
+    };
+    async #request(type, attrs) {
+        const txn = newTransactionId();
+        const key = Buffer.from(txn).toString("hex");
+        const integrity = type !== TURN_ALLOCATE_REQUEST || this.#integrityKey ? this.#integrityKey : undefined;
+        const pkt = encodeStun({ type, transactionId: txn, attributes: attrs }, integrity
+            ? { integrityKey: integrity, fingerprint: false }
+            : { fingerprint: false });
+        let lastError;
+        for (let attempt = 0; attempt < REQUEST_RETRIES; attempt++) {
+            const result = await new Promise((resolve) => {
+                const timeout = setTimeout(() => {
+                    this.#pending.delete(key);
+                    resolve(undefined);
+                }, REQUEST_TIMEOUT_MS);
+                this.#pending.set(key, (msg) => {
+                    clearTimeout(timeout);
+                    resolve(msg);
+                });
+                this.#sock.send(Buffer.from(pkt), this.creds.port, this.creds.host, (err) => {
+                    if (err) {
+                        clearTimeout(timeout);
+                        this.#pending.delete(key);
+                        lastError = err;
+                        resolve(undefined);
+                    }
+                });
+            });
+            if (result)
+                return result;
+        }
+        throw new Error(`TURN request (type=0x${type.toString(16)}) timed out: ${lastError?.message ?? "no response"}`);
+    }
+    #parseAllocateSuccess(msg) {
+        const relayAttr = findAttr(msg, STUN_ATTR_XOR_RELAYED_ADDRESS);
+        if (!relayAttr)
+            throw new Error("ALLOCATE success missing XOR-RELAYED-ADDRESS");
+        const relayed = decodeXorMappedAddress(relayAttr, msg.transactionId);
+        if (!relayed)
+            throw new Error("ALLOCATE success has malformed XOR-RELAYED-ADDRESS");
+        const mappedAttr = findAttr(msg, 0x0020 /* XOR-MAPPED-ADDRESS */);
+        const mapped = mappedAttr ? decodeXorMappedAddress(mappedAttr, msg.transactionId) : undefined;
+        const lifetimeAttr = findAttr(msg, STUN_ATTR_LIFETIME);
+        const lifetime = lifetimeAttr ? readU32(lifetimeAttr) : 600;
+        return { relayedAddress: relayed, mappedAddress: mapped, lifetime };
+    }
+    #scheduleRefresh(lifetime) {
+        if (this.#refreshTimer)
+            clearTimeout(this.#refreshTimer);
+        if (this.#closed)
+            return;
+        const ms = Math.max(15_000, (lifetime * 1000) / 2);
+        this.#refreshTimer = setTimeout(() => {
+            this.refresh().catch((err) => {
+                // Log only — next sendTo() may re-trigger allocate via caller.
+                console.error("[turn] refresh failed:", err.message);
+            });
+        }, ms);
+    }
+}
+function u32Bytes(n) {
+    return Uint8Array.of((n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff);
+}
+function readU32(b) {
+    return ((b[0] << 24) >>> 0) + ((b[1] << 16) >>> 0) + ((b[2] << 8) >>> 0) + b[3];
+}
+// Re-export so callers can use the binding-request bootstrap probe.
+export { buildBindingRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",