node-rtc-connection 1.0.19 → 2.0.5

package/types/dtls/connection.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file connection.ts
+ * @description DTLS 1.2 connection state machine (client and server roles).
+ * @module dtls/connection
+ *
+ * Implements the handshake for TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 over an
+ * abstract datagram channel. The owner supplies an `output` callback to send
+ * datagrams and feeds inbound datagrams to `handlePacket`. On success the
+ * connection emits 'connect'; application records arrive via 'data' and are
+ * sent via `send`.
+ *
+ * Scope: one cipher suite, secp256r1, ECDSA P-256 certificates, extended
+ * master secret. This is the subset Chromium/Firefox negotiate for data
+ * channels, so it interoperates with browsers while staying pure-Node.
+ *
+ * References: RFC 6347 (DTLS 1.2), RFC 5246 (TLS 1.2), RFC 7627 (EMS),
+ * RFC 8422 (ECC cipher suites), RFC 5288 (AES-GCM).
+ */
+import * as crypto from 'crypto';
+import { EventEmitter } from 'events';
+declare const ROLE: Readonly<{
+    CLIENT: "client";
+    SERVER: "server";
+}>;
+declare const STATE: Readonly<{
+    NEW: "new";
+    HANDSHAKING: "handshaking";
+    CONNECTED: "connected";
+    CLOSED: "closed";
+    FAILED: "failed";
+}>;
+/** A certificate fingerprint as advertised in SDP a=fingerprint. */
+interface Fingerprint {
+    algorithm: string;
+    value: string;
+}
+/** Callback used to verify the peer's certificate fingerprint. */
+type VerifyFingerprint = (fp: Fingerprint, remoteCertDer: Buffer) => boolean;
+/** Constructor options for {@link DtlsConnection}. */
+interface DtlsConnectionOptions {
+    /** 'client' | 'server' */
+    role: string;
+    /** local DER certificate */
+    certDer: Buffer;
+    /** local EC private key */
+    privateKey: crypto.KeyObject;
+    /** called with the peer cert fingerprint; return false to reject. */
+    verifyFingerprint?: VerifyFingerprint;
+    /** send a datagram to the peer */
+    output: (datagram: Buffer) => void;
+}
+/**
+ * @class DtlsConnection
+ * @extends EventEmitter
+ */
+declare class DtlsConnection extends EventEmitter {
+    #private;
+    role: string;
+    state: string;
+    /**
+     * @param opts connection options
+     */
+    constructor(opts: DtlsConnectionOptions);
+    /** Begin the handshake (client sends the first flight). */
+    start(): void;
+    /**
+     * Feed an inbound datagram (one UDP packet, possibly several records).
+     * @param packet
+     */
+    handlePacket(packet: Buffer): void;
+    /**
+     * Send application data over the established connection.
+     * @param data
+     */
+    send(data: Buffer): void;
+    /** Send a close_notify and tear down. */
+    close(): void;
+    /** The peer's certificate DER, available after the handshake. */
+    getRemoteCertificate(): Buffer | null;
+}
+export { DtlsConnection, ROLE, STATE };

package/types/dtls/prf.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file prf.ts
+ * @description TLS 1.2 pseudo-random function (RFC 5246 §5) with SHA-256.
+ * @module dtls/prf
+ *
+ * The cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 uses P_SHA256 for
+ * the PRF. This module also exposes the underlying HMAC-based P_hash.
+ */
+/**
+ * P_hash(secret, seed) expanded to `length` bytes (RFC 5246 §5).
+ *   A(0) = seed
+ *   A(i) = HMAC(secret, A(i-1))
+ *   P_hash = HMAC(secret, A(1)+seed) | HMAC(secret, A(2)+seed) | ...
+ *
+ * @param hashAlg - Node hash name, e.g. 'sha256'.
+ * @param secret
+ * @param seed
+ * @param length
+ */
+export declare function pHash(hashAlg: string, secret: Buffer, seed: Buffer, length: number): Buffer;
+/**
+ * TLS 1.2 PRF = P_SHA256(secret, label + seed).
+ *
+ * @param secret
+ * @param label - ASCII label, e.g. "master secret".
+ * @param seed
+ * @param length
+ */
+export declare function prf(secret: Buffer, label: string, seed: Buffer, length: number): Buffer;

package/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/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/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/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 };