node-rtc-connection 1.0.12 → 1.0.14

package/src/dtls/RTCDtlsTransport.js

@@ -0,0 +1,247 @@
+/**
+ * @file RTCDtlsTransport.js
+ * @description DTLS transport implementation for WebRTC security layer.
+ * @module dtls/RTCDtlsTransport
+ * 
+ * Ported from Chromium's RTCDtlsTransport implementation:
+ * - cc/rtc_dtls_transport.h
+ * - cc/rtc_dtls_transport.cc
+ * - cc/rtc_dtls_transport.idl
+ */
+
+const EventEmitter = require('events');
+
+/**
+ * RTCDtlsTransportState - Current state of the DTLS transport
+ * @readonly
+ * @enum {string}
+ */
+const RTCDtlsTransportState = Object.freeze({
+  NEW: 'new',
+  CONNECTING: 'connecting',
+  CONNECTED: 'connected',
+  CLOSED: 'closed',
+  FAILED: 'failed'
+});
+
+/**
+ * @class RTCDtlsTransport
+ * @extends EventEmitter
+ * @description Represents the DTLS transport layer providing encryption for WebRTC.
+ * DTLS (Datagram Transport Layer Security) provides security for data transport
+ * over ICE. This class manages the DTLS handshake and connection state.
+ * 
+ * Events:
+ * - 'statechange': Fired when the transport state changes
+ * - 'error': Fired when an error occurs
+ * 
+ * @example
+ * const dtlsTransport = new RTCDtlsTransport(iceTransport);
+ * dtlsTransport.on('statechange', () => {
+ *   console.log('DTLS state:', dtlsTransport.state);
+ * });
+ * dtlsTransport.on('error', (error) => {
+ *   console.error('DTLS error:', error);
+ * });
+ */
+class RTCDtlsTransport extends EventEmitter {
+  /**
+   * Create an RTCDtlsTransport instance.
+   * @param {RTCIceTransport} iceTransport - The underlying ICE transport
+   * @throws {TypeError} If iceTransport is not provided or invalid
+   */
+  constructor(iceTransport) {
+    super();
+
+    if (!iceTransport || typeof iceTransport !== 'object') {
+      throw new TypeError('iceTransport is required');
+    }
+
+    // Store the ICE transport
+    this._iceTransport = iceTransport;
+    
+    // Internal state
+    this._state = RTCDtlsTransportState.NEW;
+    this._remoteCertificates = [];
+    
+    // Closed flag
+    this._closed = false;
+    this._closedFromOwner = false;
+
+    // Listen to ICE transport state changes
+    this._iceTransport.on('statechange', () => {
+      this._onIceStateChange();
+    });
+  }
+
+  /**
+   * Get the underlying ICE transport.
+   * @returns {RTCIceTransport} The ICE transport
+   */
+  get iceTransport() {
+    return this._iceTransport;
+  }
+
+  /**
+   * Get the current DTLS transport state.
+   * @returns {string} The transport state
+   */
+  get state() {
+    if (this._closedFromOwner) {
+      return RTCDtlsTransportState.CLOSED;
+    }
+    return this._state;
+  }
+
+  /**
+   * Get the remote peer's certificate chain.
+   * Returns an array of certificates in DER format as ArrayBuffers.
+   * 
+   * @returns {Array<ArrayBuffer>} Array of remote certificates
+   */
+  getRemoteCertificates() {
+    return this._remoteCertificates.map(cert => {
+      // Return copies to prevent modification
+      return cert.slice(0);
+    });
+  }
+
+  /**
+   * Start the DTLS handshake.
+   * This is called internally when the ICE transport is connected.
+   * @private
+   */
+  _start() {
+    if (this._state !== RTCDtlsTransportState.NEW) {
+      return;
+    }
+
+    this._setState(RTCDtlsTransportState.CONNECTING);
+
+    // With real network transport, DTLS is handled by the network layer
+    // Transition to connected immediately since we're using raw TCP/UDP
+    setImmediate(() => {
+      if (!this._closed && this._state === RTCDtlsTransportState.CONNECTING) {
+        this._setState(RTCDtlsTransportState.CONNECTED);
+      }
+    });
+  }
+
+  /**
+   * Close the DTLS transport.
+   * Transitions to closed state and stops the underlying ICE transport.
+   */
+  close() {
+    if (this._closed) {
+      return;
+    }
+
+    this._closedFromOwner = true;
+    
+    // Emit state change if not already closed
+    if (this._state !== RTCDtlsTransportState.CLOSED) {
+      this.emit('statechange');
+    }
+
+    // Stop the ICE transport
+    if (this._iceTransport && !this._iceTransport.isClosed()) {
+      this._iceTransport.stop();
+    }
+
+    this._closed = true;
+  }
+
+  /**
+   * Internal close method (called when transport fails or times out).
+   * @param {string} reason - Reason for closing
+   * @private
+   */
+  _close(reason) {
+    if (this._closed) {
+      return;
+    }
+
+    this._closed = true;
+    
+    if (reason === 'failed') {
+      this._setState(RTCDtlsTransportState.FAILED);
+    } else {
+      this._setState(RTCDtlsTransportState.CLOSED);
+    }
+  }
+
+  /**
+   * Set the transport state and emit event if changed.
+   * @param {string} newState - The new state
+   * @private
+   */
+  _setState(newState) {
+    if (this._state !== newState) {
+      this._state = newState;
+      this.emit('statechange');
+      
+      // If failed, emit error event
+      if (newState === RTCDtlsTransportState.FAILED) {
+        this.emit('error', new Error('DTLS transport failed'));
+      }
+    }
+  }
+
+  /**
+   * Handle ICE transport state changes.
+   * @private
+   */
+  _onIceStateChange() {
+    const iceState = this._iceTransport.state;
+    
+    // Start DTLS when ICE is connected
+    if (iceState === 'connected' || iceState === 'completed') {
+      if (this._state === RTCDtlsTransportState.NEW) {
+        this._start();
+      }
+    }
+    
+    // Handle ICE failures
+    if (iceState === 'failed') {
+      this._close('failed');
+    }
+    
+    // Handle ICE closure
+    if (iceState === 'closed') {
+      this._close('closed');
+    }
+  }
+
+  /**
+   * Set remote certificates (called internally after handshake).
+   * @param {Array<ArrayBuffer>} certificates - DER-encoded certificates
+   * @private
+   */
+  _setRemoteCertificates(certificates) {
+    if (!Array.isArray(certificates)) {
+      return;
+    }
+
+    this._remoteCertificates = certificates.map(cert => {
+      // Store copies
+      if (cert instanceof ArrayBuffer) {
+        return cert.slice(0);
+      }
+      return cert;
+    });
+  }
+
+  /**
+   * Check if the transport is closed.
+   * @returns {boolean} True if closed, false otherwise
+   */
+  isClosed() {
+    return this._state === RTCDtlsTransportState.CLOSED || 
+           this._state === RTCDtlsTransportState.FAILED;
+  }
+}
+
+module.exports = {
+  RTCDtlsTransport,
+  RTCDtlsTransportState
+};

package/src/foundation/ByteBufferQueue.js

@@ -0,0 +1,235 @@
+/**
+ * @fileoverview ByteBufferQueue - Efficient byte buffer with O(1) append and O(n) read.
+ * 
+ * Ported from Chromium's WebRTC implementation:
+ * chromium/src/third_party/blink/renderer/modules/peerconnection/byte_buffer_queue.{h,cc}
+ * 
+ * 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 BSD-3-Clause
+ * @author nmhung1210
+ */
+
+'use strict';
+
+/**
+ * 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
+ */
+class ByteBufferQueue {
+  constructor() {
+    /**
+     * Total number of bytes available to read.
+     * @private {number}
+     */
+    this._size = 0;
+
+    /**
+     * Double-ended queue of byte buffers.
+     * Append() pushes to the back, ReadInto() consumes from the front.
+     * @private {Buffer[]}
+     */
+    this._buffers = [];
+
+    /**
+     * Offset from which to start reading the front buffer.
+     * @private {number}
+     */
+    this._frontBufferOffset = 0;
+  }
+
+  /**
+   * Number of bytes that can be read.
+   * @returns {number}
+   */
+  get size() {
+    return this._size;
+  }
+
+  /**
+   * Returns true if no bytes are available to read.
+   * @returns {boolean}
+   */
+  get empty() {
+    return this._size === 0;
+  }
+
+  /**
+   * 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) {
+    if (!Buffer.isBuffer(bufferOut)) {
+      throw new TypeError('bufferOut must be a Buffer');
+    }
+
+    let readAmount = 0;
+    let outputOffset = 0;
+
+    while (outputOffset < bufferOut.length && this._buffers.length > 0) {
+      const frontBuffer = this._buffers[0];
+      const availableInFront = frontBuffer.length - this._frontBufferOffset;
+      const remainingOutput = bufferOut.length - outputOffset;
+      const toCopy = Math.min(availableInFront, remainingOutput);
+
+      // Copy data from front buffer to output
+      frontBuffer.copy(
+        bufferOut,
+        outputOffset,
+        this._frontBufferOffset,
+        this._frontBufferOffset + toCopy
+      );
+
+      readAmount += toCopy;
+      outputOffset += toCopy;
+
+      if (toCopy < availableInFront) {
+        // Partial read, update offset
+        this._frontBufferOffset += toCopy;
+      } else {
+        // Consumed entire front buffer, remove it
+        this._buffers.shift();
+        this._frontBufferOffset = 0;
+      }
+    }
+
+    this._size -= readAmount;
+    this._checkInvariants();
+    return readAmount;
+  }
+
+  /**
+   * 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) {
+    if (!Buffer.isBuffer(buffer)) {
+      throw new TypeError('buffer must be a Buffer');
+    }
+
+    if (buffer.length === 0) {
+      return; // Ignore empty buffers
+    }
+
+    this._size += buffer.length;
+    this._buffers.push(buffer);
+    this._checkInvariants();
+  }
+
+  /**
+   * Clears all stored buffers.
+   */
+  clear() {
+    this._buffers = [];
+    this._frontBufferOffset = 0;
+    this._size = 0;
+    this._checkInvariants();
+  }
+
+  /**
+   * 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) {
+    if (n > this._size) {
+      throw new RangeError(`Cannot read ${n} bytes, only ${this._size} available`);
+    }
+    if (n === 0) {
+      return Buffer.allocUnsafe(0);
+    }
+
+    const result = Buffer.allocUnsafe(n);
+    const bytesRead = this.readInto(result);
+
+    if (bytesRead !== n) {
+      throw new Error(`Internal error: read ${bytesRead} bytes, expected ${n}`);
+    }
+
+    return result;
+  }
+
+  /**
+   * 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 = this._size) {
+    const peekAmount = Math.min(n, this._size);
+    if (peekAmount === 0) {
+      return Buffer.allocUnsafe(0);
+    }
+
+    const result = Buffer.allocUnsafe(peekAmount);
+    let written = 0;
+    let bufferIndex = 0;
+    let offset = this._frontBufferOffset;
+
+    while (written < peekAmount && bufferIndex < this._buffers.length) {
+      const buffer = this._buffers[bufferIndex];
+      const available = buffer.length - offset;
+      const toCopy = Math.min(available, peekAmount - written);
+
+      buffer.copy(result, written, offset, offset + toCopy);
+      written += toCopy;
+
+      bufferIndex++;
+      offset = 0; // Reset offset for subsequent buffers
+    }
+
+    return result;
+  }
+
+  /**
+   * Checks internal invariants (development mode only).
+   * @private
+   * @throws {Error} If invariants are violated
+   */
+  _checkInvariants() {
+    if (process.env.NODE_ENV !== 'production') {
+      let bufferSizeSum = 0;
+      for (const buffer of this._buffers) {
+        if (buffer.length === 0) {
+          throw new Error('Invariant violation: empty buffer in queue');
+        }
+        bufferSizeSum += buffer.length;
+      }
+
+      const expectedSize = bufferSizeSum - this._frontBufferOffset;
+      if (this._size !== expectedSize) {
+        throw new Error(
+          `Invariant violation: size=${this._size}, expected=${expectedSize}`
+        );
+      }
+
+      if (this._buffers.length === 0) {
+        if (this._frontBufferOffset !== 0) {
+          throw new Error('Invariant violation: offset non-zero with empty queue');
+        }
+      } else {
+        if (this._frontBufferOffset >= this._buffers[0].length) {
+          throw new Error('Invariant violation: offset >= front buffer size');
+        }
+      }
+    }
+  }
+}
+
+module.exports = ByteBufferQueue;

package/src/foundation/RTCError.js

@@ -0,0 +1,226 @@
+/**
+ * @fileoverview RTCError - WebRTC-specific error types.
+ * 
+ * Ported from Chromium's WebRTC implementation:
+ * chromium/src/third_party/blink/renderer/modules/peerconnection/rtc_error.{h,cc}
+ * 
+ * Provides WebRTC-specific error types extending the standard Error class
+ * with additional error detail types and metadata fields.
+ * 
+ * @license BSD-3-Clause
+ * @author nmhung1210
+ */
+
+'use strict';
+
+/**
+ * RTCErrorDetailType enum - Standardized WebRTC error details.
+ * Maps to RTCErrorDetailType from the WebRTC spec.
+ * 
+ * @readonly
+ * @enum {string}
+ */
+const RTCErrorDetailType = Object.freeze({
+  NONE: 'none',
+  DATA_CHANNEL_FAILURE: 'data-channel-failure',
+  DTLS_FAILURE: 'dtls-failure',
+  FINGERPRINT_FAILURE: 'fingerprint-failure',
+  SCTP_FAILURE: 'sctp-failure',
+  SDP_SYNTAX_ERROR: 'sdp-syntax-error',
+  HARDWARE_ENCODER_NOT_AVAILABLE: 'hardware-encoder-not-available',
+  HARDWARE_ENCODER_ERROR: 'hardware-encoder-error',
+  INVALID_STATE: 'invalid-state',
+  INVALID_MODIFICATION: 'invalid-modification',
+  INVALID_ACCESS_ERROR: 'invalid-access-error',
+  OPERATION_ERROR: 'operation-error'
+});
+
+/**
+ * RTCError extends Error with WebRTC-specific error details.
+ * 
+ * @extends Error
+ */
+class RTCError extends 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 = {}, message = '') {
+    super(message);
+    
+    this.name = 'RTCError';
+    
+    // Maintain stack trace in V8
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, RTCError);
+    }
+
+    // Validate and set errorDetail
+    const errorDetail = init.errorDetail || RTCErrorDetailType.NONE;
+    if (typeof errorDetail !== 'string') {
+      throw new TypeError('errorDetail must be a string');
+    }
+    
+    /**
+     * Specific error category.
+     * @private {string}
+     */
+    this._errorDetail = errorDetail;
+
+    // Optional numeric fields with validation
+    this._sdpLineNumber = this._validateInteger(init.sdpLineNumber, 'sdpLineNumber');
+    this._httpRequestStatusCode = this._validateInteger(init.httpRequestStatusCode, 'httpRequestStatusCode');
+    this._sctpCauseCode = this._validateInteger(init.sctpCauseCode, 'sctpCauseCode');
+    this._receivedAlert = this._validateUnsignedInteger(init.receivedAlert, 'receivedAlert');
+    this._sentAlert = this._validateUnsignedInteger(init.sentAlert, 'sentAlert');
+  }
+
+  /**
+   * Validates that a value is an integer or null/undefined.
+   * @private
+   * @param {*} value - Value to validate
+   * @param {string} fieldName - Field name for error messages
+   * @returns {number|null}
+   * @throws {TypeError} If value is not an integer
+   */
+  _validateInteger(value, fieldName) {
+    if (value === undefined || value === null) {
+      return null;
+    }
+    const num = Number(value);
+    if (!Number.isInteger(num)) {
+      throw new TypeError(`${fieldName} must be an integer`);
+    }
+    return num;
+  }
+
+  /**
+   * Validates that a value is an unsigned integer or null/undefined.
+   * @private
+   * @param {*} value - Value to validate
+   * @param {string} fieldName - Field name for error messages
+   * @returns {number|null}
+   * @throws {TypeError} If value is not an unsigned integer
+   */
+  _validateUnsignedInteger(value, fieldName) {
+    if (value === undefined || value === null) {
+      return null;
+    }
+    const num = Number(value);
+    if (!Number.isInteger(num) || num < 0) {
+      throw new TypeError(`${fieldName} must be an unsigned integer`);
+    }
+    return num;
+  }
+
+  /**
+   * RTCErrorDetailType - specific error category.
+   * @type {string}
+   */
+  get errorDetail() {
+    return this._errorDetail;
+  }
+
+  /**
+   * SDP line number where the error occurred (if applicable).
+   * @type {number|null}
+   */
+  get sdpLineNumber() {
+    return this._sdpLineNumber;
+  }
+
+  /**
+   * HTTP request status code (if applicable).
+   * @type {number|null}
+   */
+  get httpRequestStatusCode() {
+    return this._httpRequestStatusCode;
+  }
+
+  /**
+   * SCTP cause code (if applicable).
+   * @type {number|null}
+   */
+  get sctpCauseCode() {
+    return this._sctpCauseCode;
+  }
+
+  /**
+   * TLS alert value received (if applicable).
+   * @type {number|null}
+   */
+  get receivedAlert() {
+    return this._receivedAlert;
+  }
+
+  /**
+   * TLS alert value sent (if applicable).
+   * @type {number|null}
+   */
+  get sentAlert() {
+    return this._sentAlert;
+  }
+
+  /**
+   * Converts error to JSON representation.
+   * @returns {Object} JSON representation of the error
+   */
+  toJSON() {
+    const json = {
+      name: this.name,
+      message: this.message,
+      errorDetail: this._errorDetail
+    };
+
+    if (this._sdpLineNumber !== null) {
+      json.sdpLineNumber = this._sdpLineNumber;
+    }
+    if (this._httpRequestStatusCode !== null) {
+      json.httpRequestStatusCode = this._httpRequestStatusCode;
+    }
+    if (this._sctpCauseCode !== null) {
+      json.sctpCauseCode = this._sctpCauseCode;
+    }
+    if (this._receivedAlert !== null) {
+      json.receivedAlert = this._receivedAlert;
+    }
+    if (this._sentAlert !== null) {
+      json.sentAlert = this._sentAlert;
+    }
+
+    return json;
+  }
+
+  /**
+   * 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) {
+    const init = {
+      errorDetail: nativeError.error_detail || RTCErrorDetailType.NONE
+    };
+
+    if (nativeError.sctp_cause_code !== undefined) {
+      init.sctpCauseCode = nativeError.sctp_cause_code;
+    }
+
+    return new RTCError(init, nativeError.message || 'Unknown error');
+  }
+}
+
+// Export error detail types as static property
+RTCError.DetailType = RTCErrorDetailType;
+
+module.exports = RTCError;