node-rtc-connection 1.0.19 → 2.0.4

package/dist/types/dtls/protocol.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @file protocol.ts
+ * @description DTLS 1.2 wire-format constants and TLV/vector encoders.
+ * @module dtls/protocol
+ *
+ * Covers exactly what WebRTC's data channel needs:
+ *   cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 (0xC02B)
+ *   curve secp256r1, signature scheme ecdsa_secp256r1_sha256.
+ *
+ * References: RFC 6347 (DTLS 1.2), RFC 5246 (TLS 1.2), RFC 8422 (ECC).
+ */
+export declare const DTLS_1_2 = 65277;
+export declare const CONTENT_TYPE: Readonly<{
+    CHANGE_CIPHER_SPEC: 20;
+    ALERT: 21;
+    HANDSHAKE: 22;
+    APPLICATION_DATA: 23;
+}>;
+export declare const HANDSHAKE_TYPE: Readonly<{
+    HELLO_REQUEST: 0;
+    CLIENT_HELLO: 1;
+    SERVER_HELLO: 2;
+    HELLO_VERIFY_REQUEST: 3;
+    CERTIFICATE: 11;
+    SERVER_KEY_EXCHANGE: 12;
+    CERTIFICATE_REQUEST: 13;
+    SERVER_HELLO_DONE: 14;
+    CERTIFICATE_VERIFY: 15;
+    CLIENT_KEY_EXCHANGE: 16;
+    FINISHED: 20;
+}>;
+export declare const ALERT_LEVEL: Readonly<{
+    WARNING: 1;
+    FATAL: 2;
+}>;
+export declare const ALERT_DESC: Readonly<{
+    CLOSE_NOTIFY: 0;
+    HANDSHAKE_FAILURE: 40;
+    BAD_CERTIFICATE: 42;
+    DECRYPT_ERROR: 51;
+    INTERNAL_ERROR: 80;
+}>;
+export declare const CIPHER_SUITE = 49195;
+export declare const NAMED_GROUP: Readonly<{
+    secp256r1: 23;
+}>;
+export declare const EC_POINT_FORMAT: Readonly<{
+    uncompressed: 0;
+}>;
+export declare const HASH_ALG: Readonly<{
+    sha256: 4;
+    sha384: 5;
+    sha512: 6;
+}>;
+export declare const SIG_ALG: Readonly<{
+    rsa: 1;
+    ecdsa: 3;
+}>;
+export declare const CERT_TYPE: Readonly<{
+    ecdsa_sign: 64;
+    rsa_sign: 1;
+}>;
+export declare const EXTENSION: Readonly<{
+    SUPPORTED_GROUPS: 10;
+    EC_POINT_FORMATS: 11;
+    SIGNATURE_ALGORITHMS: 13;
+    EXTENDED_MASTER_SECRET: 23;
+    RENEGOTIATION_INFO: 65281;
+}>;
+export declare const FINISHED_LABEL: Readonly<{
+    CLIENT: "client finished";
+    SERVER: "server finished";
+}>;
+/** A parsed DTLS record from {@link parseRecords}. */
+export interface Record {
+    type: number;
+    version: number;
+    epoch: number;
+    seq: number;
+    fragment: Buffer;
+}
+/** A parsed handshake message header from {@link parseHandshake}. */
+export interface Handshake {
+    msgType: number;
+    length: number;
+    messageSeq: number;
+    fragmentOffset: number;
+    fragmentLength: number;
+    body: Buffer;
+}
+/** Encode a uint24 (3 bytes, big-endian). */
+export declare function uint24(n: number): Buffer;
+/** Read a uint24 at offset. */
+export declare function readUint24(buf: Buffer, off: number): number;
+/** Length-prefixed vector with a 1-byte length. */
+export declare function vec8(body: Buffer): Buffer;
+/** Length-prefixed vector with a 2-byte length. */
+export declare function vec16(body: Buffer): Buffer;
+/** Length-prefixed vector with a 3-byte length. */
+export declare function vec24(body: Buffer): Buffer;
+/**
+ * Encode a DTLS record (13-byte header + fragment).
+ * @param type - CONTENT_TYPE
+ * @param epoch
+ * @param seq - 48-bit sequence number
+ * @param fragment
+ * @param version
+ */
+export declare function encodeRecord(type: number, epoch: number, seq: number, fragment: Buffer, version?: number): Buffer;
+/**
+ * Parse one or more DTLS records from a datagram. Multiple records may be
+ * packed into a single UDP packet.
+ * @param packet
+ */
+export declare function parseRecords(packet: Buffer): Record[];
+/**
+ * Encode a DTLS handshake message header + body (unfragmented).
+ * @param msgType - HANDSHAKE_TYPE
+ * @param messageSeq
+ * @param body
+ */
+export declare function encodeHandshake(msgType: number, messageSeq: number, body: Buffer): Buffer;
+/**
+ * Parse a handshake message header.
+ * @param buf - starts at the handshake header
+ */
+export declare function parseHandshake(buf: Buffer): Handshake;

package/dist/types/foundation/ByteBufferQueue.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @file ByteBufferQueue - Efficient byte buffer with O(1) append and O(n) read.
+ *
+ * This class provides efficient management of byte buffers with O(1) append operations
+ * and O(n) read operations. Clients can append entire buffers then copy data out across
+ * buffer boundaries.
+ *
+ * @license MIT
+ * @author nmhung1210
+ */
+/**
+ * A ByteBufferQueue manages a queue of byte buffers with efficient operations.
+ *
+ * Invariants maintained:
+ * - size_ = sum of all buffer sizes - frontBufferOffset_
+ * - No buffer in the queue is empty
+ * - If queue is empty, frontBufferOffset_ = 0
+ * - Otherwise, frontBufferOffset_ < front buffer size
+ */
+declare class ByteBufferQueue {
+    #private;
+    constructor();
+    /**
+     * Number of bytes that can be read.
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Returns true if no bytes are available to read.
+     * @returns {boolean}
+     */
+    get empty(): boolean;
+    /**
+     * Copies data into the given buffer. Consumes bytes from the queue.
+     * Returns the number of bytes written to bufferOut.
+     *
+     * @param {Buffer} bufferOut - Destination buffer to read into
+     * @returns {number} Number of bytes actually read
+     * @throws {TypeError} If bufferOut is not a Buffer
+     */
+    readInto(bufferOut: Buffer): number;
+    /**
+     * Appends a buffer to the queue. Takes ownership of the buffer.
+     * Empty buffers are ignored.
+     *
+     * @param {Buffer} buffer - Buffer to append
+     * @throws {TypeError} If buffer is not a Buffer
+     */
+    append(buffer: Buffer): void;
+    /**
+     * Clears all stored buffers.
+     */
+    clear(): void;
+    /**
+     * Reads and consumes exactly n bytes.
+     *
+     * @param {number} n - Number of bytes to read
+     * @returns {Buffer} Buffer containing exactly n bytes
+     * @throws {RangeError} If fewer than n bytes are available
+     */
+    read(n: number): Buffer;
+    /**
+     * Peeks at data without consuming it.
+     *
+     * @param {number} [n=this.#size] - Number of bytes to peek
+     * @returns {Buffer} Buffer containing up to n bytes (not consumed)
+     */
+    peek(n?: number): Buffer;
+}
+export default ByteBufferQueue;
+export { ByteBufferQueue };

package/dist/types/foundation/RTCError.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @file RTCError - WebRTC-specific error types.
+ *
+ * Implements the W3C RTCError interface
+ * (https://www.w3.org/TR/webrtc/#rtcerror-interface).
+ *
+ * Provides WebRTC-specific error types extending the standard Error class
+ * with additional error detail types and metadata fields.
+ *
+ * @license MIT
+ * @author nmhung1210
+ */
+/**
+ * RTCErrorDetailType enum - Standardized WebRTC error details.
+ * Maps to RTCErrorDetailType from the WebRTC spec.
+ *
+ * @readonly
+ * @enum {string}
+ */
+declare const RTCErrorDetailType: Readonly<{
+    readonly NONE: "none";
+    readonly DATA_CHANNEL_FAILURE: "data-channel-failure";
+    readonly DTLS_FAILURE: "dtls-failure";
+    readonly FINGERPRINT_FAILURE: "fingerprint-failure";
+    readonly SCTP_FAILURE: "sctp-failure";
+    readonly SDP_SYNTAX_ERROR: "sdp-syntax-error";
+    readonly HARDWARE_ENCODER_NOT_AVAILABLE: "hardware-encoder-not-available";
+    readonly HARDWARE_ENCODER_ERROR: "hardware-encoder-error";
+    readonly INVALID_STATE: "invalid-state";
+    readonly INVALID_MODIFICATION: "invalid-modification";
+    readonly INVALID_ACCESS_ERROR: "invalid-access-error";
+    readonly OPERATION_ERROR: "operation-error";
+}>;
+/**
+ * Error detail type string union.
+ */
+type RTCErrorDetail = typeof RTCErrorDetailType[keyof typeof RTCErrorDetailType];
+/**
+ * Error initialization dictionary.
+ */
+interface RTCErrorInit {
+    errorDetail?: string;
+    sdpLineNumber?: number | null;
+    httpRequestStatusCode?: number | null;
+    sctpCauseCode?: number | null;
+    receivedAlert?: number | null;
+    sentAlert?: number | null;
+}
+/**
+ * Native WebRTC error object shape.
+ */
+interface NativeRTCError {
+    error_detail?: string;
+    sctp_cause_code?: number;
+    message?: string;
+}
+/**
+ * JSON representation of an RTCError.
+ */
+interface RTCErrorJSON {
+    name: string;
+    message: string;
+    errorDetail: string;
+    sdpLineNumber?: number;
+    httpRequestStatusCode?: number;
+    sctpCauseCode?: number;
+    receivedAlert?: number;
+    sentAlert?: number;
+}
+/**
+ * RTCError extends Error with WebRTC-specific error details.
+ *
+ * @extends Error
+ */
+declare class RTCError extends Error {
+    #private;
+    /** Export error detail types as static property */
+    static readonly DetailType: Readonly<{
+        readonly NONE: "none";
+        readonly DATA_CHANNEL_FAILURE: "data-channel-failure";
+        readonly DTLS_FAILURE: "dtls-failure";
+        readonly FINGERPRINT_FAILURE: "fingerprint-failure";
+        readonly SCTP_FAILURE: "sctp-failure";
+        readonly SDP_SYNTAX_ERROR: "sdp-syntax-error";
+        readonly HARDWARE_ENCODER_NOT_AVAILABLE: "hardware-encoder-not-available";
+        readonly HARDWARE_ENCODER_ERROR: "hardware-encoder-error";
+        readonly INVALID_STATE: "invalid-state";
+        readonly INVALID_MODIFICATION: "invalid-modification";
+        readonly INVALID_ACCESS_ERROR: "invalid-access-error";
+        readonly OPERATION_ERROR: "operation-error";
+    }>;
+    /**
+     * Creates a new RTCError.
+     *
+     * @param {RTCErrorInit} [init={}] - Error initialization dictionary
+     * @param {string} [init.errorDetail='none'] - Error detail type
+     * @param {number} [init.sdpLineNumber] - SDP line number where error occurred
+     * @param {number} [init.httpRequestStatusCode] - HTTP status code if relevant
+     * @param {number} [init.sctpCauseCode] - SCTP cause code
+     * @param {number} [init.receivedAlert] - TLS alert received
+     * @param {number} [init.sentAlert] - TLS alert sent
+     * @param {string} [message=''] - Error message
+     */
+    constructor(init?: RTCErrorInit, message?: string);
+    /**
+     * RTCErrorDetailType - specific error category.
+     * @type {string}
+     */
+    get errorDetail(): string;
+    /**
+     * SDP line number where the error occurred (if applicable).
+     * @type {number|null}
+     */
+    get sdpLineNumber(): number | null;
+    /**
+     * HTTP request status code (if applicable).
+     * @type {number|null}
+     */
+    get httpRequestStatusCode(): number | null;
+    /**
+     * SCTP cause code (if applicable).
+     * @type {number|null}
+     */
+    get sctpCauseCode(): number | null;
+    /**
+     * TLS alert value received (if applicable).
+     * @type {number|null}
+     */
+    get receivedAlert(): number | null;
+    /**
+     * TLS alert value sent (if applicable).
+     * @type {number|null}
+     */
+    get sentAlert(): number | null;
+    /**
+     * Converts error to JSON representation.
+     * @returns {Object} JSON representation of the error
+     */
+    toJSON(): RTCErrorJSON;
+    /**
+     * Creates RTCError from a native WebRTC error object.
+     * @param {Object} nativeError - Native error object
+     * @param {string} [nativeError.error_detail] - Error detail type
+     * @param {number} [nativeError.sctp_cause_code] - SCTP cause code
+     * @param {string} [nativeError.message] - Error message
+     * @returns {RTCError}
+     */
+    static fromNative(nativeError: NativeRTCError): RTCError;
+}
+export default RTCError;
+export { RTCError, RTCErrorDetailType };
+export type { RTCErrorInit, RTCErrorDetail, NativeRTCError, RTCErrorJSON };

package/dist/types/ice/RTCIceCandidate.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @file RTCIceCandidate - ICE candidate representation.
+ *
+ * Implements the W3C RTCIceCandidate interface
+ * (https://www.w3.org/TR/webrtc/#rtcicecandidate-interface).
+ *
+ * Represents an ICE (Interactive Connectivity Establishment) candidate that
+ * describes a potential way to establish a connection with a peer.
+ *
+ * @license MIT
+ * @author nmhung1210
+ */
+/**
+ * Initialization dictionary for RTCIceCandidate.
+ */
+interface RTCIceCandidateInit {
+    candidate?: string;
+    sdpMid?: string | null;
+    sdpMLineIndex?: number | null;
+    usernameFragment?: string | null;
+}
+/**
+ * Parsed attributes extracted from an ICE candidate string.
+ */
+interface ParsedCandidateAttributes {
+    foundation: string | null;
+    component: string | null;
+    protocol: string | null;
+    priority: number | null;
+    address: string | null;
+    port: number | null;
+    type: string | null;
+    tcpType: string | null;
+    relatedAddress: string | null;
+    relatedPort: number | null;
+}
+/**
+ * JSON representation of an RTCIceCandidate.
+ */
+interface RTCIceCandidateJSON {
+    candidate: string;
+    sdpMid: string | null;
+    sdpMLineIndex: number | null;
+    usernameFragment?: string;
+}
+/**
+ * RTCIceCandidate represents a potential method for establishing connectivity.
+ *
+ * ICE candidates are described using SDP (Session Description Protocol) syntax.
+ * Each candidate describes a single address/port combination and transport protocol.
+ */
+declare class RTCIceCandidate {
+    #private;
+    /**
+     * Creates a new RTCIceCandidate.
+     *
+     * @param {RTCIceCandidateInit} [candidateInit={}] - Initialization dictionary
+     * @param {string} [candidateInit.candidate=''] - SDP candidate string
+     * @param {string|null} [candidateInit.sdpMid] - Media stream ID
+     * @param {number|null} [candidateInit.sdpMLineIndex] - M-line index
+     * @param {string} [candidateInit.usernameFragment] - ICE username fragment
+     * @throws {TypeError} If both sdpMid and sdpMLineIndex are null
+     */
+    constructor(candidateInit?: RTCIceCandidateInit);
+    /**
+     * SDP candidate attribute containing the candidate description.
+     * @type {string}
+     */
+    get candidate(): string;
+    /**
+     * Media stream identification tag.
+     * @type {string|null}
+     */
+    get sdpMid(): string | null;
+    /**
+     * Index of the m-line in the SDP this candidate is associated with.
+     * @type {number|null}
+     */
+    get sdpMLineIndex(): number | null;
+    /**
+     * ICE username fragment.
+     * @type {string|null}
+     */
+    get usernameFragment(): string | null;
+    /**
+     * Unique identifier for this candidate.
+     * @type {string|null}
+     */
+    get foundation(): string | null;
+    /**
+     * Component identifier (rtp=1, rtcp=2).
+     * @type {string|null}
+     */
+    get component(): string | null;
+    /**
+     * Priority value for this candidate.
+     * Higher priority candidates are preferred.
+     * @type {number|null}
+     */
+    get priority(): number | null;
+    /**
+     * IP address of this candidate.
+     * @type {string|null}
+     */
+    get address(): string | null;
+    /**
+     * Transport protocol (udp/tcp).
+     * @type {string|null}
+     */
+    get protocol(): string | null;
+    /**
+     * Port number.
+     * @type {number|null}
+     */
+    get port(): number | null;
+    /**
+     * Type of candidate (host, srflx, prflx, relay).
+     * @type {string|null}
+     */
+    get type(): string | null;
+    /**
+     * TCP candidate type (active, passive, so).
+     * Only applicable for TCP candidates.
+     * @type {string|null}
+     */
+    get tcpType(): string | null;
+    /**
+     * Related address for reflexive/relay candidates.
+     * @type {string|null}
+     */
+    get relatedAddress(): string | null;
+    /**
+     * Related port for reflexive/relay candidates.
+     * @type {number|null}
+     */
+    get relatedPort(): number | null;
+    /**
+     * Converts candidate to JSON representation.
+     * @returns {Object} JSON representation
+     */
+    toJSON(): RTCIceCandidateJSON;
+    /**
+     * Creates an RTCIceCandidate from a candidate string.
+     *
+     * @param {string} candidateStr - ICE candidate string
+     * @param {string|null} [sdpMid=null] - Media stream ID
+     * @param {number|null} [sdpMLineIndex=0] - M-line index
+     * @returns {RTCIceCandidate}
+     */
+    static fromString(candidateStr: string, sdpMid?: string | null, sdpMLineIndex?: number | null): RTCIceCandidate;
+    /**
+     * Validates if a string is a valid candidate format.
+     *
+     * @param {string} candidateStr - String to validate
+     * @returns {boolean} True if valid candidate format
+     */
+    static isValid(candidateStr: string): boolean;
+}
+export default RTCIceCandidate;
+export { RTCIceCandidate };
+export type { RTCIceCandidateInit, ParsedCandidateAttributes, RTCIceCandidateJSON };

package/dist/types/ice/ice-agent.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @file ice-agent.ts
+ * @description A small but RFC 8445-compliant ICE agent for a single data
+ * component, with browser-compatible connectivity checks and TURN relay.
+ * @module ice/ice-agent
+ *
+ * Responsibilities:
+ *  - Gather UDP host candidates, server-reflexive (srflx) candidates via STUN,
+ *    and relay candidates via TURN (RFC 5766 ALLOCATE).
+ *  - Send/answer STUN Binding connectivity checks carrying USERNAME,
+ *    MESSAGE-INTEGRITY (keyed by the remote/local ice-pwd), PRIORITY, the
+ *    ICE-CONTROLLING/CONTROLLED role attribute, and USE-CANDIDATE.
+ *  - Nominate a candidate pair and expose it as the selected path.
+ *  - Demultiplex inbound datagrams per RFC 7983: STUN (first byte 0-3) is
+ *    handled internally; everything else (DTLS records, first byte 20-63) is
+ *    emitted as 'data' for the upper stack.
+ *
+ * Each local candidate carries a `transport` with a uniform interface so the
+ * connectivity-check and data paths are identical whether the candidate is a
+ * host socket or a TURN relay:
+ *   transport.send(buf, remoteAddress, remotePort)
+ *   transport.onMessage = (buf, {address, port}) => ...
+ */
+import { EventEmitter } from 'events';
+/** Remote info accompanying an inbound datagram. */
+interface RemoteInfo {
+    address: string;
+    port: number;
+}
+/**
+ * Uniform transport abstraction shared by host sockets and TURN relays.
+ */
+interface Transport {
+    kind: string;
+    send(buf: Buffer, address: string, port: number): void;
+    onMessage: ((msg: Buffer, rinfo: RemoteInfo) => void) | null;
+    close(): void;
+}
+/** A local ICE candidate. */
+interface LocalCandidate {
+    foundation: string;
+    component: number;
+    protocol: string;
+    priority: number;
+    address: string;
+    port: number;
+    type: string;
+    transport: Transport;
+    sdp: string;
+}
+/** A remote ICE candidate (parsed from an a=candidate line or object). */
+interface RemoteCandidate {
+    address: string;
+    port: number;
+    priority?: number;
+    type?: string;
+}
+/** A candidate pair under connectivity checking. */
+interface CandidatePair {
+    key?: string;
+    local: {
+        transport: Transport;
+    } & Partial<LocalCandidate>;
+    remote: {
+        address: string;
+        port: number;
+    } & Partial<RemoteCandidate>;
+    state?: string;
+    nominated?: boolean;
+}
+/** Description of a single ICE server entry. */
+interface IceServer {
+    urls: string | string[];
+    username?: string;
+    credential?: string;
+}
+/** Options accepted by {@link IceAgent#gather}. */
+interface GatherOptions {
+    iceServers?: IceServer[];
+    iceTransportPolicy?: 'all' | 'relay';
+}
+/** Parsed query parameters from a STUN/TURN URL. */
+type IceServerParams = Record<string, string | true>;
+/** Result of {@link parseIceServerUrl}. */
+interface ParsedIceServerUrl {
+    scheme: string;
+    protocol: string;
+    host: string;
+    port: number;
+    transport: string;
+    params: IceServerParams;
+}
+/** Options accepted by the {@link IceAgent} constructor. */
+interface IceAgentOptions {
+    role: 'controlling' | 'controlled';
+    localUfrag: string;
+    localPwd: string;
+}
+/**
+ * Compute an ICE candidate priority (RFC 8445 §5.1.2.1).
+ */
+declare function candidatePriority(type: string, localPref?: number, componentId?: number): number;
+/**
+ * Parse a STUN/TURN server URL: (stun|turn|turns):host[:port][?key=val&...].
+ * Query parameters are returned in `params`; a flag without a value (e.g.
+ * "?secure") is recorded as `true`, an empty value ("?transport=") as "".
+ * @param {string} url
+ * @returns {{scheme:string, protocol:string, host:string, port:number,
+ *            transport:string, params:Object}|null} null if the URL is invalid.
+ */
+declare function parseIceServerUrl(url: string): ParsedIceServerUrl | null;
+declare class IceAgent extends EventEmitter {
+    #private;
+    role: 'controlling' | 'controlled';
+    localUfrag: string;
+    localPwd: string;
+    remoteUfrag: string | null;
+    remotePwd: string | null;
+    /**
+     * @param {Object} opts
+     * @param {'controlling'|'controlled'} opts.role
+     * @param {string} opts.localUfrag
+     * @param {string} opts.localPwd
+     */
+    constructor(opts: IceAgentOptions);
+    /**
+     * Gather candidates. Host candidates always; srflx/relay when iceServers are
+     * given. With iceTransportPolicy 'relay', only relay candidates are kept.
+     * @param {Object} [opts]
+     * @param {Array<{urls:string|string[],username?:string,credential?:string}>} [opts.iceServers]
+     * @param {'all'|'relay'} [opts.iceTransportPolicy='all']
+     */
+    gather(opts?: GatherOptions): Promise<void>;
+    getLocalCandidates(): LocalCandidate[];
+    /** Set remote ICE credentials (from the peer's SDP). */
+    setRemoteCredentials(ufrag: string, pwd: string): void;
+    /**
+     * Add a remote candidate (parsed from an a=candidate line or object).
+     * @param {{address:string, port:number, priority?:number, type?:string}} cand
+     */
+    addRemoteCandidate(cand: RemoteCandidate): void;
+    /** Begin connectivity checks (call once remote creds + candidates exist). */
+    start(): void;
+    /**
+     * Send application (DTLS) data over the selected path.
+     * @param {Buffer} data
+     */
+    send(data: Buffer): void;
+    getSelectedPair(): CandidatePair | null;
+    /** Type of the selected local candidate ('host'|'srflx'|'relay'|'prflx'). */
+    getSelectedCandidateType(): string | null | undefined;
+    close(): void;
+}
+export { IceAgent, candidatePriority, parseIceServerUrl };