@decentnetwork/peer 0.1.17 → 0.1.19

package/dist/stun.d.ts

@@ -0,0 +1,117 @@
+/**
+ * STUN message codec (RFC 5389 + parts of 5766 for TURN integration).
+ *
+ * Supports the subset we need:
+ *  - Binding Request / Binding Success Response (RFC 5389) for SRFLX
+ *    discovery and ICE connectivity checks.
+ *  - Long-term credential MESSAGE-INTEGRITY (HMAC-SHA1) and FINGERPRINT,
+ *    needed by the bootnode TURN servers (coturn).
+ *  - XOR-MAPPED-ADDRESS decoding.
+ *  - USERNAME, REALM, NONCE, ERROR-CODE attributes (TURN auth dance).
+ *  - SOFTWARE / FINGERPRINT attributes for being polite.
+ *
+ * Wire format:
+ *
+ *   0                   1                   2                   3
+ *   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *  |0 0|     STUN Message Type     |         Message Length        |
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *  |                         Magic Cookie                          |
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *  |                                                               |
+ *  |                     Transaction ID (96 bits)                  |
+ *  |                                                               |
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *
+ * Attributes follow as { type: u16, length: u16, value: bytes, pad to 4 }.
+ *
+ * MESSAGE-INTEGRITY is HMAC-SHA1 over the entire message up to (not
+ * including) the MESSAGE-INTEGRITY attribute itself, with the message
+ * length pre-adjusted as if MESSAGE-INTEGRITY were present.
+ */
+export declare const STUN_MAGIC_COOKIE = 554869826;
+export declare const STUN_BINDING_REQUEST = 1;
+export declare const STUN_BINDING_SUCCESS = 257;
+export declare const STUN_BINDING_ERROR = 273;
+export declare const TURN_ALLOCATE_REQUEST = 3;
+export declare const TURN_ALLOCATE_SUCCESS = 259;
+export declare const TURN_ALLOCATE_ERROR = 275;
+export declare const TURN_REFRESH_REQUEST = 4;
+export declare const TURN_REFRESH_SUCCESS = 260;
+export declare const TURN_CREATE_PERMISSION_REQUEST = 8;
+export declare const TURN_CREATE_PERMISSION_SUCCESS = 264;
+export declare const TURN_SEND_INDICATION = 22;
+export declare const TURN_DATA_INDICATION = 23;
+export declare const STUN_ATTR_MAPPED_ADDRESS = 1;
+export declare const STUN_ATTR_USERNAME = 6;
+export declare const STUN_ATTR_MESSAGE_INTEGRITY = 8;
+export declare const STUN_ATTR_ERROR_CODE = 9;
+export declare const STUN_ATTR_REALM = 20;
+export declare const STUN_ATTR_NONCE = 21;
+export declare const STUN_ATTR_XOR_MAPPED_ADDRESS = 32;
+export declare const STUN_ATTR_SOFTWARE = 32802;
+export declare const STUN_ATTR_FINGERPRINT = 32808;
+export declare const STUN_ATTR_CHANNEL_NUMBER = 12;
+export declare const STUN_ATTR_LIFETIME = 13;
+export declare const STUN_ATTR_XOR_PEER_ADDRESS = 18;
+export declare const STUN_ATTR_DATA = 19;
+export declare const STUN_ATTR_XOR_RELAYED_ADDRESS = 22;
+export declare const STUN_ATTR_REQUESTED_TRANSPORT = 25;
+export declare const STUN_ATTR_DONT_FRAGMENT = 26;
+export interface StunAttribute {
+    type: number;
+    value: Uint8Array;
+}
+export interface StunMessage {
+    type: number;
+    transactionId: Uint8Array;
+    attributes: StunAttribute[];
+}
+export interface AddressValue {
+    family: 4 | 6;
+    address: string;
+    port: number;
+}
+export declare function newTransactionId(): Uint8Array;
+/**
+ * Encode a STUN message. If `integrityKey` is provided, a
+ * MESSAGE-INTEGRITY attribute (HMAC-SHA1) is appended. If `fingerprint`
+ * is true, a FINGERPRINT (CRC32 XOR 0x5354554e) is appended last.
+ *
+ * The order matters because MESSAGE-INTEGRITY must be computed over
+ * the message *as if* it were the last attribute (with length already
+ * adjusted), and FINGERPRINT must be computed over the message
+ * including MESSAGE-INTEGRITY.
+ */
+export declare function encodeStun(message: StunMessage, opts?: {
+    integrityKey?: Uint8Array;
+    fingerprint?: boolean;
+}): Uint8Array;
+export declare function decodeStun(data: Uint8Array): StunMessage | undefined;
+export declare function findAttr(message: StunMessage, type: number): Uint8Array | undefined;
+/**
+ * Decode XOR-MAPPED-ADDRESS (RFC 5389 §15.2). The high bits of the
+ * port and the address are XORed with the magic cookie + transactionId.
+ */
+export declare function decodeXorMappedAddress(value: Uint8Array, transactionId: Uint8Array): AddressValue | undefined;
+/** Encode XOR-MAPPED-ADDRESS for outgoing STUN responses (TURN, conn check). */
+export declare function encodeXorMappedAddress(addr: AddressValue, transactionId: Uint8Array): Uint8Array;
+export declare function encodeErrorCode(code: number, reason: string): Uint8Array;
+export declare function decodeErrorCode(value: Uint8Array): {
+    code: number;
+    reason: string;
+} | undefined;
+/**
+ * Long-term-credential integrity key: MD5("username:realm:password").
+ * RFC 5389 §15.4. coturn uses this.
+ */
+export declare function longTermIntegrityKey(username: string, realm: string, password: string): Uint8Array;
+/** Short-term-credential integrity key: just the password as UTF-8. */
+export declare function shortTermIntegrityKey(password: string): Uint8Array;
+export declare function buildBindingRequest(transactionId?: Uint8Array): Uint8Array;
+export declare function buildBindingRequestWithIntegrity(opts: {
+    username: string;
+    password: string;
+    transactionId?: Uint8Array;
+}): Uint8Array;

package/dist/stun.js

@@ -0,0 +1,304 @@
+/**
+ * STUN message codec (RFC 5389 + parts of 5766 for TURN integration).
+ *
+ * Supports the subset we need:
+ *  - Binding Request / Binding Success Response (RFC 5389) for SRFLX
+ *    discovery and ICE connectivity checks.
+ *  - Long-term credential MESSAGE-INTEGRITY (HMAC-SHA1) and FINGERPRINT,
+ *    needed by the bootnode TURN servers (coturn).
+ *  - XOR-MAPPED-ADDRESS decoding.
+ *  - USERNAME, REALM, NONCE, ERROR-CODE attributes (TURN auth dance).
+ *  - SOFTWARE / FINGERPRINT attributes for being polite.
+ *
+ * Wire format:
+ *
+ *   0                   1                   2                   3
+ *   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *  |0 0|     STUN Message Type     |         Message Length        |
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *  |                         Magic Cookie                          |
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *  |                                                               |
+ *  |                     Transaction ID (96 bits)                  |
+ *  |                                                               |
+ *  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ *
+ * Attributes follow as { type: u16, length: u16, value: bytes, pad to 4 }.
+ *
+ * MESSAGE-INTEGRITY is HMAC-SHA1 over the entire message up to (not
+ * including) the MESSAGE-INTEGRITY attribute itself, with the message
+ * length pre-adjusted as if MESSAGE-INTEGRITY were present.
+ */
+import { createHash, createHmac, randomBytes as nodeRandomBytes } from "crypto";
+import { concatBytes } from "./utils/bytes.js";
+export const STUN_MAGIC_COOKIE = 0x2112a442;
+export const STUN_BINDING_REQUEST = 0x0001;
+export const STUN_BINDING_SUCCESS = 0x0101;
+export const STUN_BINDING_ERROR = 0x0111;
+// TURN methods (RFC 5766) — declared here so turn.ts can share the codec.
+export const TURN_ALLOCATE_REQUEST = 0x0003;
+export const TURN_ALLOCATE_SUCCESS = 0x0103;
+export const TURN_ALLOCATE_ERROR = 0x0113;
+export const TURN_REFRESH_REQUEST = 0x0004;
+export const TURN_REFRESH_SUCCESS = 0x0104;
+export const TURN_CREATE_PERMISSION_REQUEST = 0x0008;
+export const TURN_CREATE_PERMISSION_SUCCESS = 0x0108;
+export const TURN_SEND_INDICATION = 0x0016;
+export const TURN_DATA_INDICATION = 0x0017;
+export const STUN_ATTR_MAPPED_ADDRESS = 0x0001;
+export const STUN_ATTR_USERNAME = 0x0006;
+export const STUN_ATTR_MESSAGE_INTEGRITY = 0x0008;
+export const STUN_ATTR_ERROR_CODE = 0x0009;
+export const STUN_ATTR_REALM = 0x0014;
+export const STUN_ATTR_NONCE = 0x0015;
+export const STUN_ATTR_XOR_MAPPED_ADDRESS = 0x0020;
+export const STUN_ATTR_SOFTWARE = 0x8022;
+export const STUN_ATTR_FINGERPRINT = 0x8028;
+// TURN attributes
+export const STUN_ATTR_CHANNEL_NUMBER = 0x000c;
+export const STUN_ATTR_LIFETIME = 0x000d;
+export const STUN_ATTR_XOR_PEER_ADDRESS = 0x0012;
+export const STUN_ATTR_DATA = 0x0013;
+export const STUN_ATTR_XOR_RELAYED_ADDRESS = 0x0016;
+export const STUN_ATTR_REQUESTED_TRANSPORT = 0x0019;
+export const STUN_ATTR_DONT_FRAGMENT = 0x001a;
+const FINGERPRINT_XOR = 0x5354554e; // "STUN" — RFC 5389 §15.5
+function u16(n) {
+    return Uint8Array.of((n >> 8) & 0xff, n & 0xff);
+}
+function u32(n) {
+    return Uint8Array.of((n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff);
+}
+function padTo4(n) {
+    return (4 - (n & 3)) & 3;
+}
+function readU16(b, off) {
+    return (b[off] << 8) | b[off + 1];
+}
+function readU32(b, off) {
+    return (((b[off] << 24) >>> 0) +
+        ((b[off + 1] << 16) >>> 0) +
+        ((b[off + 2] << 8) >>> 0) +
+        b[off + 3]);
+}
+export function newTransactionId() {
+    return Uint8Array.from(nodeRandomBytes(12));
+}
+function encodeAttributes(attrs) {
+    const parts = [];
+    for (const attr of attrs) {
+        parts.push(u16(attr.type));
+        parts.push(u16(attr.value.length));
+        parts.push(attr.value);
+        const pad = padTo4(attr.value.length);
+        if (pad > 0) {
+            parts.push(new Uint8Array(pad));
+        }
+    }
+    return concatBytes(parts);
+}
+/**
+ * Encode a STUN message. If `integrityKey` is provided, a
+ * MESSAGE-INTEGRITY attribute (HMAC-SHA1) is appended. If `fingerprint`
+ * is true, a FINGERPRINT (CRC32 XOR 0x5354554e) is appended last.
+ *
+ * The order matters because MESSAGE-INTEGRITY must be computed over
+ * the message *as if* it were the last attribute (with length already
+ * adjusted), and FINGERPRINT must be computed over the message
+ * including MESSAGE-INTEGRITY.
+ */
+export function encodeStun(message, opts = {}) {
+    let body = encodeAttributes(message.attributes);
+    if (opts.integrityKey) {
+        // Reserve 24 bytes (4-byte header + 20-byte HMAC-SHA1) for MESSAGE-INTEGRITY.
+        const reserved = 24;
+        const lengthWithIntegrity = body.length + reserved + (opts.fingerprint ? 8 : 0);
+        const headerForHmac = concatBytes([
+            u16(message.type),
+            u16(body.length + reserved),
+            u32(STUN_MAGIC_COOKIE),
+            message.transactionId
+        ]);
+        const hmacInput = concatBytes([headerForHmac, body]);
+        const hmac = createHmac("sha1", Buffer.from(opts.integrityKey)).update(hmacInput).digest();
+        body = concatBytes([
+            body,
+            u16(STUN_ATTR_MESSAGE_INTEGRITY),
+            u16(20),
+            Uint8Array.from(hmac)
+        ]);
+        void lengthWithIntegrity; // computed for clarity; final length set below
+    }
+    if (opts.fingerprint) {
+        const lengthWithFingerprint = body.length + 8;
+        const headerForCrc = concatBytes([
+            u16(message.type),
+            u16(lengthWithFingerprint),
+            u32(STUN_MAGIC_COOKIE),
+            message.transactionId
+        ]);
+        const crcInput = concatBytes([headerForCrc, body]);
+        const crc = crc32(crcInput) ^ FINGERPRINT_XOR;
+        body = concatBytes([
+            body,
+            u16(STUN_ATTR_FINGERPRINT),
+            u16(4),
+            u32(crc >>> 0)
+        ]);
+    }
+    const header = concatBytes([
+        u16(message.type),
+        u16(body.length),
+        u32(STUN_MAGIC_COOKIE),
+        message.transactionId
+    ]);
+    return concatBytes([header, body]);
+}
+export function decodeStun(data) {
+    if (data.length < 20)
+        return undefined;
+    if ((data[0] & 0xc0) !== 0)
+        return undefined; // top two bits must be zero
+    const type = readU16(data, 0);
+    const length = readU16(data, 2);
+    const cookie = readU32(data, 4);
+    if (cookie !== STUN_MAGIC_COOKIE)
+        return undefined;
+    if (data.length < 20 + length)
+        return undefined;
+    const transactionId = data.slice(8, 20);
+    const attributes = [];
+    let off = 20;
+    const end = 20 + length;
+    while (off + 4 <= end) {
+        const attrType = readU16(data, off);
+        const attrLen = readU16(data, off + 2);
+        off += 4;
+        if (off + attrLen > end)
+            return undefined;
+        attributes.push({ type: attrType, value: data.slice(off, off + attrLen) });
+        off += attrLen + padTo4(attrLen);
+    }
+    return { type, transactionId, attributes };
+}
+export function findAttr(message, type) {
+    for (const a of message.attributes) {
+        if (a.type === type)
+            return a.value;
+    }
+    return undefined;
+}
+/**
+ * Decode XOR-MAPPED-ADDRESS (RFC 5389 §15.2). The high bits of the
+ * port and the address are XORed with the magic cookie + transactionId.
+ */
+export function decodeXorMappedAddress(value, transactionId) {
+    if (value.length < 4)
+        return undefined;
+    const family = value[1];
+    const xPort = readU16(value, 2);
+    const port = xPort ^ ((STUN_MAGIC_COOKIE >>> 16) & 0xffff);
+    if (family === 0x01 && value.length >= 8) {
+        // IPv4
+        const xAddr = value.slice(4, 8);
+        const cookieBytes = u32(STUN_MAGIC_COOKIE);
+        const a = xAddr.map((b, i) => b ^ cookieBytes[i]);
+        return { family: 4, address: `${a[0]}.${a[1]}.${a[2]}.${a[3]}`, port };
+    }
+    if (family === 0x02 && value.length >= 20) {
+        // IPv6
+        const xAddr = value.slice(4, 20);
+        const xorKey = concatBytes([u32(STUN_MAGIC_COOKIE), transactionId]);
+        const a = xAddr.map((b, i) => b ^ xorKey[i]);
+        const parts = [];
+        for (let i = 0; i < 16; i += 2) {
+            parts.push(((a[i] << 8) | a[i + 1]).toString(16));
+        }
+        return { family: 6, address: parts.join(":"), port };
+    }
+    return undefined;
+}
+/** Encode XOR-MAPPED-ADDRESS for outgoing STUN responses (TURN, conn check). */
+export function encodeXorMappedAddress(addr, transactionId) {
+    if (addr.family === 4) {
+        const octets = addr.address.split(".").map((s) => parseInt(s, 10));
+        if (octets.length !== 4 || octets.some((o) => Number.isNaN(o))) {
+            throw new Error(`Invalid IPv4 address: ${addr.address}`);
+        }
+        const cookieBytes = u32(STUN_MAGIC_COOKIE);
+        const xAddr = Uint8Array.from(octets.map((b, i) => b ^ cookieBytes[i]));
+        const xPort = addr.port ^ ((STUN_MAGIC_COOKIE >>> 16) & 0xffff);
+        return concatBytes([Uint8Array.of(0x00, 0x01), u16(xPort), xAddr]);
+    }
+    throw new Error("IPv6 XOR-MAPPED-ADDRESS encode not implemented yet");
+}
+export function encodeErrorCode(code, reason) {
+    // RFC 5389 §15.6: 0x0000, class (top 3 bits of byte 2), number, reason text
+    const cls = Math.floor(code / 100);
+    const num = code % 100;
+    const reasonBytes = Buffer.from(reason, "utf8");
+    return concatBytes([Uint8Array.of(0, 0, cls, num), Uint8Array.from(reasonBytes)]);
+}
+export function decodeErrorCode(value) {
+    if (value.length < 4)
+        return undefined;
+    const code = value[2] * 100 + value[3];
+    const reason = Buffer.from(value.slice(4)).toString("utf8");
+    return { code, reason };
+}
+/**
+ * Long-term-credential integrity key: MD5("username:realm:password").
+ * RFC 5389 §15.4. coturn uses this.
+ */
+export function longTermIntegrityKey(username, realm, password) {
+    const md5 = createHash("md5");
+    md5.update(`${username}:${realm}:${password}`);
+    return Uint8Array.from(md5.digest());
+}
+/** Short-term-credential integrity key: just the password as UTF-8. */
+export function shortTermIntegrityKey(password) {
+    return Uint8Array.from(Buffer.from(password, "utf8"));
+}
+/**
+ * CRC32 (IEEE 802.3, polynomial 0xedb88320) — for STUN FINGERPRINT.
+ * Self-contained so we don't pull in zlib for one tiny use.
+ */
+const CRC32_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let c = i;
+        for (let j = 0; j < 8; j++) {
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        t[i] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(data) {
+    let c = 0xffffffff;
+    for (let i = 0; i < data.length; i++) {
+        c = CRC32_TABLE[(c ^ data[i]) & 0xff] ^ (c >>> 8);
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+// Convenience builders ------------------------------------------------------
+export function buildBindingRequest(transactionId) {
+    return encodeStun({
+        type: STUN_BINDING_REQUEST,
+        transactionId: transactionId ?? newTransactionId(),
+        attributes: []
+    });
+}
+export function buildBindingRequestWithIntegrity(opts) {
+    return encodeStun({
+        type: STUN_BINDING_REQUEST,
+        transactionId: opts.transactionId ?? newTransactionId(),
+        attributes: [
+            { type: STUN_ATTR_USERNAME, value: Uint8Array.from(Buffer.from(opts.username, "utf8")) }
+        ]
+    }, {
+        integrityKey: shortTermIntegrityKey(opts.password),
+        fingerprint: true
+    });
+}

package/dist/transport/udp.d.ts

@@ -8,6 +8,25 @@ export type UdpTransportOptions = {
     host?: string;
     port?: number;
 };
+/**
+ * A consumer that wants first dibs on inbound datagrams that look like
+ * STUN/TURN (RFC 5389 magic cookie at offset 4). ICE agents and TURN
+ * clients register here so net_crypto/DHT never sees their control
+ * packets, and so TURN DATA-INDICATIONs get unwrapped before the inner
+ * app packet is re-emitted as a normal datagram.
+ *
+ * Return true if the datagram was consumed (stop further dispatch).
+ */
+export type StunInterceptor = (data: Buffer, remote: RemoteInfo) => boolean;
+/**
+ * A TURN route: outbound datagrams addressed to `${host}:${port}` are
+ * handed to `send` instead of going out the raw socket. Used to tunnel
+ * net_crypto traffic through a TURN relay transparently — net_crypto
+ * sets session.remote to the peer's relay address and is none the wiser.
+ */
+export type TurnRoute = {
+    send: (data: Buffer) => void;
+};
 export declare class UdpTransport extends EventEmitter {
     #private;
     constructor();
@@ -21,4 +40,14 @@ export declare class UdpTransport extends EventEmitter {
      */
     localPort(): number | undefined;
     send(data: Buffer, host: string, port: number): Promise<void>;
+    /** Direct socket send, bypassing TURN routes. ICE/TURN use this so
+     *  their own control packets (SEND-INDICATION, binding checks) don't
+     *  recurse back through the route table. */
+    sendDirect(data: Buffer, host: string, port: number): Promise<void>;
+    /** Synchronous fire-and-forget direct send (for hot TURN data path). */
+    sendDirectSync(data: Buffer, host: string, port: number): void;
+    addStunInterceptor(fn: StunInterceptor): void;
+    removeStunInterceptor(fn: StunInterceptor): void;
+    registerTurnRoute(host: string, port: number, route: TurnRoute): void;
+    unregisterTurnRoute(host: string, port: number): void;
 }

package/dist/transport/udp.js

@@ -1,8 +1,25 @@
 import dgram from "node:dgram";
 import { EventEmitter } from "node:events";
+const STUN_MAGIC_COOKIE_BYTES = Uint8Array.of(0x21, 0x12, 0xa4, 0x42);
+function looksLikeStun(data) {
+    // RFC 7983 demux: STUN/TURN packets have the two high bits of byte 0
+    // clear AND the magic cookie at offset 4. net_crypto/DHT packets use
+    // a single type byte at offset 0 with no such cookie, so this is a
+    // reliable disambiguator on a shared socket.
+    if (data.length < 8)
+        return false;
+    if ((data[0] & 0xc0) !== 0)
+        return false;
+    return (data[4] === STUN_MAGIC_COOKIE_BYTES[0] &&
+        data[5] === STUN_MAGIC_COOKIE_BYTES[1] &&
+        data[6] === STUN_MAGIC_COOKIE_BYTES[2] &&
+        data[7] === STUN_MAGIC_COOKIE_BYTES[3]);
+}
 export class UdpTransport extends EventEmitter {
     #socket;
     #bound = false;
+    #stunInterceptors = [];
+    #turnRoutes = new Map();
     constructor() {
         super();
         // A long-running peer connects to ~9 bootstrap nodes and ~3 TCP
@@ -24,6 +41,16 @@ export class UdpTransport extends EventEmitter {
         const socket = dgram.createSocket("udp4");
         this.#socket = socket;
         socket.on("message", (data, remote) => {
+            // STUN/TURN packets get first dibs via registered interceptors
+            // (ICE connectivity checks, TURN ALLOCATE responses, and TURN
+            // DATA-INDICATION unwrapping). Only if none consume it does the
+            // datagram fall through to net_crypto/DHT dispatch.
+            if (this.#stunInterceptors.length > 0 && looksLikeStun(data)) {
+                for (const intercept of this.#stunInterceptors) {
+                    if (intercept(data, remote))
+                        return;
+                }
+            }
             this.emit("datagram", { data, remote });
         });
         socket.on("error", (error) => this.emit("error", error));
@@ -77,6 +104,15 @@ export class UdpTransport extends EventEmitter {
         if (!socket || !this.#bound) {
             throw new Error("UDP transport is not started");
         }
+        // If a TURN route is registered for this destination, tunnel the
+        // datagram through the relay instead of sending it raw. net_crypto
+        // addresses session.remote = the peer's relay address; we intercept
+        // here and wrap in a SEND-INDICATION transparently.
+        const route = this.#turnRoutes.get(`${host}:${port}`);
+        if (route) {
+            route.send(data);
+            return;
+        }
         await new Promise((resolve, reject) => {
             socket.send(data, port, host, (error) => {
                 if (error) {
@@ -87,4 +123,32 @@ export class UdpTransport extends EventEmitter {
             });
         });
     }
+    /** Direct socket send, bypassing TURN routes. ICE/TURN use this so
+     *  their own control packets (SEND-INDICATION, binding checks) don't
+     *  recurse back through the route table. */
+    async sendDirect(data, host, port) {
+        const socket = this.#socket;
+        if (!socket || !this.#bound) {
+            throw new Error("UDP transport is not started");
+        }
+        await new Promise((resolve, reject) => {
+            socket.send(data, port, host, (error) => (error ? reject(error) : resolve()));
+        });
+    }
+    /** Synchronous fire-and-forget direct send (for hot TURN data path). */
+    sendDirectSync(data, host, port) {
+        this.#socket?.send(data, port, host);
+    }
+    addStunInterceptor(fn) {
+        this.#stunInterceptors.push(fn);
+    }
+    removeStunInterceptor(fn) {
+        this.#stunInterceptors = this.#stunInterceptors.filter((f) => f !== fn);
+    }
+    registerTurnRoute(host, port, route) {
+        this.#turnRoutes.set(`${host}:${port}`, route);
+    }
+    unregisterTurnRoute(host, port) {
+        this.#turnRoutes.delete(`${host}:${port}`);
+    }
 }

package/dist/turn-creds.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Carrier-style TURN credential derivation.
+ *
+ * Ported verbatim from the C SDK:
+ *   ~/blockchain/ela/Elastos.NET.Carrier.Native.SDK/src/carrier/carrier_turnserver.c
+ *
+ * Every Carrier bootnode runs a TURN server on UDP/3478 with this exact
+ * authentication scheme. Credentials are derived per request from a
+ * freshly generated nonce and the ECDH shared key between our identity
+ * keypair and the bootnode's identity public key:
+ *
+ *   shared_key = nacl.box.before(bootnode_pk, our_sk)        // X25519
+ *   nonce      = 24 random bytes
+ *   digest     = HMAC-SHA256(shared_key, nonce)
+ *   username   = "{ourUserid}@{base58(nonce)}.auth.tox"
+ *   password   = base58(digest)
+ *   realm      = "elastos.org"
+ *
+ * The bootnode's TURN process knows its own secret key, can therefore
+ * compute the same shared_key, reads `nonce` out of the username, and
+ * recomputes the HMAC to verify our password.
+ */
+export declare const CARRIER_TURN_PORT = 3478;
+export declare const CARRIER_TURN_REALM = "elastos.org";
+export declare const CARRIER_TURN_USER_SUFFIX = "auth.tox";
+export interface CarrierTurnCreds {
+    host: string;
+    port: number;
+    realm: string;
+    username: string;
+    password: string;
+}
+export declare function deriveCarrierTurnCreds(opts: {
+    bootnodeHost: string;
+    bootnodePublicKey: Uint8Array;
+    ourUserid: string;
+    ourSecretKey: Uint8Array;
+}): CarrierTurnCreds;

package/dist/turn-creds.js

@@ -0,0 +1,49 @@
+/**
+ * Carrier-style TURN credential derivation.
+ *
+ * Ported verbatim from the C SDK:
+ *   ~/blockchain/ela/Elastos.NET.Carrier.Native.SDK/src/carrier/carrier_turnserver.c
+ *
+ * Every Carrier bootnode runs a TURN server on UDP/3478 with this exact
+ * authentication scheme. Credentials are derived per request from a
+ * freshly generated nonce and the ECDH shared key between our identity
+ * keypair and the bootnode's identity public key:
+ *
+ *   shared_key = nacl.box.before(bootnode_pk, our_sk)        // X25519
+ *   nonce      = 24 random bytes
+ *   digest     = HMAC-SHA256(shared_key, nonce)
+ *   username   = "{ourUserid}@{base58(nonce)}.auth.tox"
+ *   password   = base58(digest)
+ *   realm      = "elastos.org"
+ *
+ * The bootnode's TURN process knows its own secret key, can therefore
+ * compute the same shared_key, reads `nonce` out of the username, and
+ * recomputes the HMAC to verify our password.
+ */
+import { createHmac } from "crypto";
+import nacl from "tweetnacl";
+import { bytesToBase58 } from "./utils/base58.js";
+import { randomBytes } from "./utils/bytes.js";
+export const CARRIER_TURN_PORT = 3478;
+export const CARRIER_TURN_REALM = "elastos.org";
+export const CARRIER_TURN_USER_SUFFIX = "auth.tox";
+export function deriveCarrierTurnCreds(opts) {
+    if (opts.bootnodePublicKey.length !== 32) {
+        throw new Error(`bootnodePublicKey must be 32 bytes, got ${opts.bootnodePublicKey.length}`);
+    }
+    if (opts.ourSecretKey.length !== 32) {
+        throw new Error(`ourSecretKey must be 32 bytes, got ${opts.ourSecretKey.length}`);
+    }
+    const sharedKey = nacl.box.before(opts.bootnodePublicKey, opts.ourSecretKey);
+    const nonce = randomBytes(24);
+    const digest = createHmac("sha256", Buffer.from(sharedKey)).update(nonce).digest();
+    const nonceB58 = bytesToBase58(nonce);
+    const passwordB58 = bytesToBase58(Uint8Array.from(digest));
+    return {
+        host: opts.bootnodeHost,
+        port: CARRIER_TURN_PORT,
+        realm: CARRIER_TURN_REALM,
+        username: `${opts.ourUserid}@${nonceB58}.${CARRIER_TURN_USER_SUFFIX}`,
+        password: passwordB58
+    };
+}