@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/cjs/lib/ice/stun/transaction.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transaction = void 0;
+exports.resolveRequestAddress = resolveRequestAddress;
+exports.normalizeTransactionOptions = normalizeTransactionOptions;
+exports.addressEquals = addressEquals;
+exports.isChallenge = isChallenge;
+exports.buildTransactionOptions = buildTransactionOptions;
+const node_dns_1 = require("node:dns");
+const node_net_1 = require("node:net");
+const common_js_1 = require("../imports/common.js");
+const exceptions_js_1 = require("../exceptions.js");
+const const_js_1 = require("./const.js");
+const log = (0, common_js_1.debug)('webrtc/ice/stun/transaction');
+/**
+ * Resolve a request target to a concrete IP before creating a Transaction so
+ * response source-address checks match the UDP peer address (hostname ≠ IP).
+ *
+ * `family` is the family of the socket that will carry the request: a
+ * hostname resolves only in that family, and an IP literal of the other
+ * family throws AddressFamilyMismatch instead of retransmitting into a send
+ * that cannot succeed. Family 0 means unknown: no preference, no check.
+ */
+async function resolveRequestAddress(addr, family = 0) {
+    const literalFamily = (0, node_net_1.isIP)(addr[0]);
+    if (literalFamily) {
+        if (family !== 0 && literalFamily !== family) {
+            throw new exceptions_js_1.AddressFamilyMismatch(addr, family);
+        }
+        return addr;
+    }
+    const looked = await node_dns_1.promises.lookup(addr[0], { family });
+    return [looked.address, addr[1]];
+}
+/**
+ * Normalize legacy positional args and the options-object form into one shape.
+ * Existing callers pass `(retransmissions?, onRequestSent?)`.
+ */
+function normalizeTransactionOptions(retransmissionsOrOptions, onRequestSent) {
+    if (retransmissionsOrOptions !== null &&
+        typeof retransmissionsOrOptions === 'object') {
+        return retransmissionsOrOptions;
+    }
+    // After the object branch, only number | undefined remains (legacy positional API).
+    const retransmissions = typeof retransmissionsOrOptions === 'number'
+        ? retransmissionsOrOptions
+        : undefined;
+    return {
+        retransmissions,
+        onRequestSent
+    };
+}
+/**
+ * Compare ICE transport addresses (host, port).
+ * IPv6 literals are compared in canonical form because the socket reports
+ * `::1` even when the peer was configured as `0:0:0:0:0:0:0:1`.
+ */
+function addressEquals(a, b) {
+    return a[1] === b[1] && canonicalHost(a[0]) === canonicalHost(b[0]);
+}
+// Only used for comparison; never for the address a packet is sent to,
+// since the zone id is dropped (`fe80::1%eth0`). The serialization of the URLs
+// is the same in Node.js and Bun (the SocketAddress of Bun keeps the text given).
+function canonicalHost(host) {
+    if ((0, node_net_1.isIP)(host) !== 6)
+        return host;
+    return new URL(`http://[${host.split('%')[0]}]/`).hostname.slice(1, -1);
+}
+class Transaction {
+    constructor(request, addr, protocol, retransmissionsOrOptions, onRequestSent) {
+        this.request = request;
+        this.addr = addr;
+        this.protocol = protocol;
+        this.ended = false;
+        this.tries = 0;
+        this.onResponse = new common_js_1.Event();
+        /**
+       * Accept a matching authenticated non-error response from the expected
+       * remote address. Wrong address, missing MESSAGE-INTEGRITY (when required),
+       * or non-success class is rejected without completing the transaction
+       * (wrong address / unauthenticated responses are ignored so we keep waiting).
+       */
+        this.responseReceived = (message, addr) => {
+            if (this.ended || this.onResponse.length === 0) {
+                return;
+            }
+            // RFC 7675 / ICE: only responses from the request's transport address.
+            if (!addressEquals(this.expectedAddr, addr)) {
+                log('ignore STUN response from unexpected address', addr, 'expected', this.expectedAddr);
+                return;
+            }
+            // RFC 7675 authenticated consent: integrityKey requires MESSAGE-INTEGRITY.
+            // Wire HMAC is verified by protocol layers via parseMessage(data, key);
+            // this presence check is defense-in-depth if responseReceived is called
+            // with a constructed Message that skipped the wire re-parse path.
+            if (this.integrityKey) {
+                const hasIntegrity = message.attributesKeys.includes('MESSAGE-INTEGRITY') ||
+                    message.attributesKeys.includes('MESSAGE-INTEGRITY-SHA256');
+                if (!hasIntegrity && !isChallenge(message)) {
+                    log('ignore unauthenticated STUN response (MESSAGE-INTEGRITY required)');
+                    return;
+                }
+            }
+            if (message.messageClass === const_js_1.classes.RESPONSE) {
+                this.onResponse.execute(message, addr);
+                this.onResponse.complete();
+            }
+            else {
+                // ERROR class or other non-success
+                this.onResponse.error(new exceptions_js_1.TransactionFailed(message, addr));
+            }
+        };
+        this.run = async () => {
+            try {
+                if (this.signal?.aborted) {
+                    throw new exceptions_js_1.TransactionTimeout();
+                }
+                this.attachAbortListener();
+                this.retry().catch((e) => {
+                    log('retry failed', e);
+                });
+                const res = await this.onResponse.asPromise();
+                return res;
+            }
+            finally {
+                this.cancel();
+            }
+        };
+        this.retry = async () => {
+            while (this.tries < this.triesMax && !this.ended) {
+                this.onRequestSent?.(this.tries);
+                this.protocol.sendStun(this.request, this.addr).catch((e) => {
+                    log('send stun failed', e);
+                    if (this.failOnSendError) {
+                        this.fail(e);
+                    }
+                });
+                await this.wait(this.timeoutDelay);
+                if (this.ended) {
+                    break;
+                }
+                this.timeoutDelay *= 2;
+                this.tries++;
+            }
+            if (this.tries >= this.triesMax && !this.ended) {
+                log(`retry failed times:${this.tries} maxLimit:${this.triesMax}`);
+                this.failWithTimeout();
+            }
+        };
+        const options = normalizeTransactionOptions(retransmissionsOrOptions, onRequestSent);
+        // triesMax = initial send + retransmissions
+        this.triesMax = 1 + (options.retransmissions ?? const_js_1.RETRY_MAX);
+        // responseTimeout is independent of retransmission count (RFC 7675 / 8445)
+        this.timeoutDelay = options.responseTimeout ?? const_js_1.RETRY_RTO;
+        this.onRequestSent = options.onRequestSent;
+        this.signal = options.signal;
+        this.failOnSendError = options.failOnSendError ?? false;
+        this.expectedAddr = addr;
+        this.integrityKey = options.integrityKey;
+    }
+    attachAbortListener() {
+        if (!this.signal) {
+            return;
+        }
+        this.onAbort = () => {
+            this.failWithTimeout();
+        };
+        this.signal.addEventListener('abort', this.onAbort, { once: true });
+    }
+    failWithTimeout() {
+        this.fail(new exceptions_js_1.TransactionTimeout());
+    }
+    fail(error) {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        this.clearWait();
+        if (this.onResponse.length > 0) {
+            this.onResponse.error(error);
+        }
+    }
+    clearWait() {
+        if (this.waitTimer !== undefined) {
+            clearTimeout(this.waitTimer);
+            this.waitTimer = undefined;
+        }
+        const resolve = this.waitResolve;
+        this.waitResolve = undefined;
+        resolve?.();
+    }
+    wait(ms) {
+        return new Promise((resolve) => {
+            if (this.ended || this.signal?.aborted) {
+                resolve();
+                return;
+            }
+            this.waitResolve = resolve;
+            this.waitTimer = setTimeout(() => {
+                this.waitTimer = undefined;
+                this.waitResolve = undefined;
+                resolve();
+            }, ms);
+        });
+    }
+    cancel() {
+        this.ended = true;
+        this.clearWait();
+        if (this.signal && this.onAbort) {
+            this.signal.removeEventListener('abort', this.onAbort);
+            this.onAbort = undefined;
+        }
+    }
+}
+exports.Transaction = Transaction;
+/**
+ * Whether an error response is a challenge of long-term credentials: a 401
+ * or 438 (Stale Nonce) with a new NONCE. A server cannot protect it with the
+ * key of the nonce it rejects, so it comes without MESSAGE-INTEGRITY and the
+ * client retries with the new nonce (RFC 8489, section 9.2.5).
+ */
+function isChallenge(message) {
+    if (message.messageClass !== const_js_1.classes.ERROR || !message.getAttributeValue('NONCE')) {
+        return false;
+    }
+    const [code] = message.getAttributeValue('ERROR-CODE') ?? [];
+    return code === 401 || code === 438;
+}
+/**
+ * Build Transaction options for Protocol.request, folding integrityKey into
+ * options so response path can re-verify MESSAGE-INTEGRITY.
+ */
+function buildTransactionOptions(integrityKey, retransmissionsOrOptions, onRequestSent) {
+    const options = normalizeTransactionOptions(retransmissionsOrOptions, onRequestSent);
+    if (integrityKey && !options.integrityKey) {
+        options.integrityKey = integrityKey;
+    }
+    return options;
+}

package/dist/cjs/lib/ice/turn/frame.d.ts

@@ -0,0 +1 @@
+export * from '../../turn/turn/frame.js';

package/dist/cjs/lib/ice/turn/frame.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("../../turn/turn/frame.js"), exports);

package/dist/cjs/lib/ice/turn/protocol.d.ts

@@ -0,0 +1,170 @@
+import type { Candidate } from '../candidate.js';
+import { type Address, Event, type InterfaceAddresses, type TlsConnectionOptions, type Transport } from '../imports/common.js';
+import { Message } from '../stun/message.js';
+import { Transaction } from '../stun/transaction.js';
+import type { Protocol, TransactionRequestOptions } from '../types/model.js';
+/** Channel binding state for a single peer transport address. */
+export interface TurnChannel {
+    number: number;
+    address: Address;
+    /** Unix seconds when this channel should be refreshed. */
+    refreshAt: number;
+}
+export declare class StunOverTurnProtocol implements Protocol {
+    turn: TurnProtocol;
+    static type: string;
+    readonly type: string;
+    localCandidate: Candidate;
+    private disposer;
+    onRequestReceived: Event<[Message, Address, Buffer]>;
+    onDataReceived: Event<[Buffer]>;
+    constructor(turn: TurnProtocol);
+    private handleStunMessage;
+    request(request: Message, addr: Address, integrityKey?: Buffer, retransmissionsOrOptions?: number | TransactionRequestOptions, onRequestSent?: (attempt: number) => void): Promise<[Message, readonly [string, number]]>;
+    connectionMade(): Promise<void>;
+    sendData(data: Buffer, addr: Address): Promise<void>;
+    sendStun(message: Message, addr: Address): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class TurnProtocol implements Protocol {
+    /** TURN server as configured; the host may be a hostname. */
+    server: Address;
+    username: string;
+    password: string;
+    lifetime: number;
+    transport: Transport;
+    options: {
+        /**sec */
+        channelRefreshTime?: number;
+    };
+    static type: string;
+    readonly type: string;
+    readonly onData: Event<[Buffer<ArrayBufferLike>, readonly [string, number]]>;
+    onRequestReceived: Event<[Message, Address, Buffer]>;
+    onDataReceived: Event<[Buffer]>;
+    integrityKey?: Buffer;
+    nonce?: Buffer;
+    realm?: string;
+    relayedAddress: Address;
+    mappedAddress: Address;
+    localCandidate: Candidate;
+    transactions: {
+        [hexId: string]: Transaction;
+    };
+    /**When the allocation expires unless refreshed (ms since epoch), 0 when there is none */
+    private expiresAt;
+    private refreshHandle?;
+    private channelNumber;
+    private channelByAddr;
+    private addrByChannel;
+    /**sec */
+    private channelRefreshTime;
+    /**
+   * Serializes ChannelBind requests so allocation-wide auth state
+   * (nonce/realm/integrityKey) is not updated concurrently. Rejections
+   * must not poison this tail — see channelBindQueue assignment sites.
+   */
+    private channelBindQueue;
+    /** In-flight ChannelBind per peer transport address (dedupe concurrent). */
+    private channelBindingByAddr;
+    private tcpBuffer;
+    /** Permission cache keyed by peer IP only (RFC 8656). */
+    private permissionByAddr;
+    /**
+   * Serializes CreatePermission requests (auth state race avoidance).
+   * Rejections must not poison this tail.
+   */
+    private permissionQueue;
+    /** In-flight CreatePermission per peer IP (dedupe concurrent). */
+    private creatingPermissionByAddr;
+    /** Concrete TURN server address the allocation lives on, once selected. */
+    private pinnedServerEndpoint?;
+    private serverEndpointSelection?;
+    constructor(
+    /** TURN server as configured; the host may be a hostname. */
+    server: Address, username: string, password: string, lifetime: number, transport: Transport, options?: {
+        /**sec */
+        channelRefreshTime?: number;
+    });
+    connectionMade(): Promise<void>;
+    private handleChannelData;
+    private handleSTUNMessage;
+    private dataReceived;
+    private send;
+    private createPermission;
+    private refresh;
+    request(request: Message, addr: Address, _integrityKey?: Buffer, retransmissionsOrOptions?: number | TransactionRequestOptions, onRequestSent?: (attempt: number) => void): Promise<[Message, Address]>;
+    /**
+   * The concrete TURN server address, selected on the first request and
+   * pinned for the rest of the allocation, so a later DNS answer can never
+   * move REFRESH, CREATE_PERMISSION, CHANNEL_BIND or data to another server.
+   */
+    get serverEndpoint(): Address | undefined;
+    /**
+   * Address a request to `addr` is sent to, and the address its response
+   * must come from. A stream carries every request to the peer it is
+   * connected to, so it always uses the server endpoint.
+   */
+    private resolveRequestTarget;
+    private serverDestination;
+    private selectServerEndpoint;
+    /**
+   * UDP: resolve the configured server in the bound socket's family; a udp4
+   * socket cannot send to an IPv6 answer. TCP/TLS: use the peer the socket
+   * actually connected to. Looking the hostname up again could return a
+   * different A/AAAA record, and responses from the real peer would then be
+   * dropped as coming from an unexpected address.
+   */
+    private resolveServerEndpoint;
+    requestWithRetry(request: Message, addr: Address, signal?: AbortSignal): Promise<[Message, Address]>;
+    sendData(data: Buffer, addr: Address): Promise<void>;
+    /**
+   * Ensure a CreatePermission exists for the peer IP.
+   * Peer failures are isolated: a rejection for peer A does not poison peer B.
+   */
+    getPermission(addr: Address): Promise<void>;
+    /**
+   * Ensure a ChannelBind exists for the peer transport address.
+   * Peer failures are isolated; concurrent same-peer calls share one Promise.
+   */
+    getChannel(addr: Address): Promise<TurnChannel>;
+    /**
+   * Create or refresh a channel for addr. Provisional mapping is installed
+   * before the request so early ChannelData can be decoded; only a failed
+   * *initial* bind rolls the mapping back. Failed channel numbers are never
+   * reused.
+   */
+    private ensureChannel;
+    private channelBind;
+    sendStun(message: Message, addr: Address): Promise<void>;
+    /**
+   * Refresh the allocation now.
+   * @returns Whether the server still has it.
+   */
+    refreshAllocation(): Promise<boolean>;
+    close(): Promise<void>;
+}
+export interface TurnClientConfig {
+    address: Address;
+    username: string;
+    password: string;
+}
+export interface TurnClientOptions {
+    lifetime?: number;
+    ssl?: boolean;
+    transport?: 'udp' | 'tcp' | 'tls';
+    tlsOptions?: TlsConnectionOptions;
+    portRange?: [number, number];
+    interfaceAddresses?: InterfaceAddresses;
+    /** Maximum time to wait for TCP/TLS connection establishment, in milliseconds. */
+    connectTimeoutMs?: number;
+    /**
+   * Preferred IP family of the UDP socket, applied only when the server
+   * address is a hostname. Ignored for an IP literal server address, whose
+   * own family always selects the socket. Defaults to 4.
+   */
+    udpFamily?: 4 | 6;
+}
+export declare function createTurnClient({ address, username, password }: TurnClientConfig, { lifetime, portRange, interfaceAddresses, ssl, tlsOptions, transport: transportType, connectTimeoutMs, udpFamily }?: TurnClientOptions): Promise<TurnProtocol>;
+export declare function createStunOverTurnClient(config: TurnClientConfig, options?: TurnClientOptions): Promise<StunOverTurnProtocol>;
+export declare function makeIntegrityKey(username: string, realm: string, password: string): NonSharedBuffer;