node-rtc-connection 1.0.18 → 2.0.4

package/src/dtls/prf.ts

@@ -0,0 +1,62 @@
+/**
+ * @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.
+ */
+
+'use strict';
+
+import * as crypto from 'crypto';
+
+/**
+ * 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 function pHash(
+  hashAlg: string,
+  secret: Buffer,
+  seed: Buffer,
+  length: number
+): Buffer {
+  const out: Buffer[] = [];
+  let total = 0;
+  let a = seed; // A(0)
+  while (total < length) {
+    a = crypto.createHmac(hashAlg, secret).update(a).digest(); // A(i)
+    const chunk = crypto
+      .createHmac(hashAlg, secret)
+      .update(Buffer.concat([a, seed]))
+      .digest();
+    out.push(chunk);
+    total += chunk.length;
+  }
+  return Buffer.concat(out).slice(0, length);
+}
+
+/**
+ * TLS 1.2 PRF = P_SHA256(secret, label + seed).
+ *
+ * @param secret
+ * @param label - ASCII label, e.g. "master secret".
+ * @param seed
+ * @param length
+ */
+export function prf(
+  secret: Buffer,
+  label: string,
+  seed: Buffer,
+  length: number
+): Buffer {
+  const labelAndSeed = Buffer.concat([Buffer.from(label, 'ascii'), seed]);
+  return pHash('sha256', secret, labelAndSeed, length);
+}

package/src/dtls/protocol.ts

@@ -0,0 +1,204 @@
+/**
+ * @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).
+ */
+
+'use strict';
+
+// DTLS 1.2 on the wire is version 0xFEFD (i.e. ~1.2).
+export const DTLS_1_2 = 0xfefd;
+
+export const CONTENT_TYPE = Object.freeze({
+  CHANGE_CIPHER_SPEC: 20,
+  ALERT: 21,
+  HANDSHAKE: 22,
+  APPLICATION_DATA: 23,
+});
+
+export const HANDSHAKE_TYPE = Object.freeze({
+  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 const ALERT_LEVEL = Object.freeze({ WARNING: 1, FATAL: 2 });
+export const ALERT_DESC = Object.freeze({
+  CLOSE_NOTIFY: 0,
+  HANDSHAKE_FAILURE: 40,
+  BAD_CERTIFICATE: 42,
+  DECRYPT_ERROR: 51,
+  INTERNAL_ERROR: 80,
+});
+
+// TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
+export const CIPHER_SUITE = 0xc02b;
+
+export const NAMED_GROUP = Object.freeze({ secp256r1: 0x0017 });
+export const EC_POINT_FORMAT = Object.freeze({ uncompressed: 0 });
+
+// SignatureAndHashAlgorithm
+export const HASH_ALG = Object.freeze({ sha256: 4, sha384: 5, sha512: 6 });
+export const SIG_ALG = Object.freeze({ rsa: 1, ecdsa: 3 });
+
+// ClientCertificateType
+export const CERT_TYPE = Object.freeze({ ecdsa_sign: 64, rsa_sign: 1 });
+
+export const EXTENSION = Object.freeze({
+  SUPPORTED_GROUPS: 10,
+  EC_POINT_FORMATS: 11,
+  SIGNATURE_ALGORITHMS: 13,
+  EXTENDED_MASTER_SECRET: 23,
+  RENEGOTIATION_INFO: 0xff01,
+});
+
+export const FINISHED_LABEL = Object.freeze({
+  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;
+}
+
+// ---- Vector / integer encoders -------------------------------------------
+
+/** Encode a uint24 (3 bytes, big-endian). */
+export function uint24(n: number): Buffer {
+  return Buffer.from([(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff]);
+}
+
+/** Read a uint24 at offset. */
+export function readUint24(buf: Buffer, off: number): number {
+  return (buf[off]! << 16) | (buf[off + 1]! << 8) | buf[off + 2]!;
+}
+
+/** Length-prefixed vector with a 1-byte length. */
+export function vec8(body: Buffer): Buffer {
+  return Buffer.concat([Buffer.from([body.length]), body]);
+}
+
+/** Length-prefixed vector with a 2-byte length. */
+export function vec16(body: Buffer): Buffer {
+  const len = Buffer.alloc(2);
+  len.writeUInt16BE(body.length, 0);
+  return Buffer.concat([len, body]);
+}
+
+/** Length-prefixed vector with a 3-byte length. */
+export function vec24(body: Buffer): Buffer {
+  return Buffer.concat([uint24(body.length), body]);
+}
+
+// ---- Record layer ---------------------------------------------------------
+
+/**
+ * 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 function encodeRecord(
+  type: number,
+  epoch: number,
+  seq: number,
+  fragment: Buffer,
+  version: number = DTLS_1_2
+): Buffer {
+  const header = Buffer.alloc(13);
+  header.writeUInt8(type, 0);
+  header.writeUInt16BE(version, 1);
+  header.writeUInt16BE(epoch, 3);
+  header.writeUIntBE(seq, 5, 6);
+  header.writeUInt16BE(fragment.length, 11);
+  return Buffer.concat([header, fragment]);
+}
+
+/**
+ * Parse one or more DTLS records from a datagram. Multiple records may be
+ * packed into a single UDP packet.
+ * @param packet
+ */
+export function parseRecords(packet: Buffer): Record[] {
+  const records: Record[] = [];
+  let off = 0;
+  while (off + 13 <= packet.length) {
+    const type = packet.readUInt8(off);
+    const version = packet.readUInt16BE(off + 1);
+    const epoch = packet.readUInt16BE(off + 3);
+    const seq = packet.readUIntBE(off + 5, 6);
+    const length = packet.readUInt16BE(off + 11);
+    const start = off + 13;
+    if (start + length > packet.length) break;
+    records.push({ type, version, epoch, seq, fragment: packet.slice(start, start + length) });
+    off = start + length;
+  }
+  return records;
+}
+
+// ---- Handshake layer -------------------------------------------------------
+
+/**
+ * Encode a DTLS handshake message header + body (unfragmented).
+ * @param msgType - HANDSHAKE_TYPE
+ * @param messageSeq
+ * @param body
+ */
+export function encodeHandshake(
+  msgType: number,
+  messageSeq: number,
+  body: Buffer
+): Buffer {
+  const header = Buffer.alloc(12);
+  header.writeUInt8(msgType, 0);
+  uint24(body.length).copy(header, 1); // length
+  header.writeUInt16BE(messageSeq, 4); // message_seq
+  uint24(0).copy(header, 6); // fragment_offset
+  uint24(body.length).copy(header, 9); // fragment_length
+  return Buffer.concat([header, body]);
+}
+
+/**
+ * Parse a handshake message header.
+ * @param buf - starts at the handshake header
+ */
+export function parseHandshake(buf: Buffer): Handshake {
+  const msgType = buf.readUInt8(0);
+  const length = readUint24(buf, 1);
+  const messageSeq = buf.readUInt16BE(4);
+  const fragmentOffset = readUint24(buf, 6);
+  const fragmentLength = readUint24(buf, 9);
+  const body = buf.slice(12, 12 + fragmentLength);
+  return { msgType, length, messageSeq, fragmentOffset, fragmentLength, body };
+}

package/src/foundation/{ByteBufferQueue.js → ByteBufferQueue.ts}

@@ -1,14 +1,11 @@
 /**
- * @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}
- * 
+ * @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 BSD-3-Clause
+ *
+ * @license MIT
  * @author nmhung1210
  */
 
@@ -16,7 +13,7 @@
 
 /**
  * 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
@@ -24,52 +21,56 @@
  * - Otherwise, frontBufferOffset_ < front buffer size
  */
 class ByteBufferQueue {
+  /**
+   * Total number of bytes available to read.
+   * @private {number}
+   */
+  #size: number;
+
+  /**
+   * Double-ended queue of byte buffers.
+   * Append() pushes to the back, ReadInto() consumes from the front.
+   * @private {Buffer[]}
+   */
+  #buffers: Buffer[];
+
+  /**
+   * Offset from which to start reading the front buffer.
+   * @private {number}
+   */
+  #frontBufferOffset: number;
+
   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;
+    this.#size = 0;
+    this.#buffers = [];
+    this.#frontBufferOffset = 0;
   }
 
   /**
    * Number of bytes that can be read.
    * @returns {number}
    */
-  get size() {
-    return this._size;
+  get size(): number {
+    return this.#size;
   }
 
   /**
    * Returns true if no bytes are available to read.
    * @returns {boolean}
    */
-  get empty() {
-    return this._size === 0;
+  get empty(): boolean {
+    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) {
+  readInto(bufferOut: Buffer): number {
     if (!Buffer.isBuffer(bufferOut)) {
       throw new TypeError('bufferOut must be a Buffer');
     }
@@ -77,9 +78,9 @@ class ByteBufferQueue {
     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;
+    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);
 
@@ -87,8 +88,8 @@ class ByteBufferQueue {
       frontBuffer.copy(
         bufferOut,
         outputOffset,
-        this._frontBufferOffset,
-        this._frontBufferOffset + toCopy
+        this.#frontBufferOffset,
+        this.#frontBufferOffset + toCopy
       );
 
       readAmount += toCopy;
@@ -96,27 +97,27 @@ class ByteBufferQueue {
 
       if (toCopy < availableInFront) {
         // Partial read, update offset
-        this._frontBufferOffset += toCopy;
+        this.#frontBufferOffset += toCopy;
       } else {
         // Consumed entire front buffer, remove it
-        this._buffers.shift();
-        this._frontBufferOffset = 0;
+        this.#buffers.shift();
+        this.#frontBufferOffset = 0;
       }
     }
 
-    this._size -= readAmount;
-    this._checkInvariants();
+    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) {
+  append(buffer: Buffer): void {
     if (!Buffer.isBuffer(buffer)) {
       throw new TypeError('buffer must be a Buffer');
     }
@@ -125,31 +126,31 @@ class ByteBufferQueue {
       return; // Ignore empty buffers
     }
 
-    this._size += buffer.length;
-    this._buffers.push(buffer);
-    this._checkInvariants();
+    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();
+  clear(): void {
+    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`);
+  read(n: number): Buffer {
+    if (n > this.#size) {
+      throw new RangeError(`Cannot read ${n} bytes, only ${this.#size} available`);
     }
     if (n === 0) {
       return Buffer.allocUnsafe(0);
@@ -167,12 +168,12 @@ class ByteBufferQueue {
 
   /**
    * Peeks at data without consuming it.
-   * 
-   * @param {number} [n=this._size] - Number of bytes to peek
+   *
+   * @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);
+  peek(n: number = this.#size): Buffer {
+    const peekAmount = Math.min(n, this.#size);
     if (peekAmount === 0) {
       return Buffer.allocUnsafe(0);
     }
@@ -180,10 +181,10 @@ class ByteBufferQueue {
     const result = Buffer.allocUnsafe(peekAmount);
     let written = 0;
     let bufferIndex = 0;
-    let offset = this._frontBufferOffset;
+    let offset = this.#frontBufferOffset;
 
-    while (written < peekAmount && bufferIndex < this._buffers.length) {
-      const buffer = this._buffers[bufferIndex];
+    while (written < peekAmount && bufferIndex < this.#buffers.length) {
+      const buffer = this.#buffers[bufferIndex]!;
       const available = buffer.length - offset;
       const toCopy = Math.min(available, peekAmount - written);
 
@@ -202,29 +203,29 @@ class ByteBufferQueue {
    * @private
    * @throws {Error} If invariants are violated
    */
-  _checkInvariants() {
+  #checkInvariants(): void {
     if (process.env.NODE_ENV !== 'production') {
       let bufferSizeSum = 0;
-      for (const buffer of this._buffers) {
+      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) {
+      const expectedSize = bufferSizeSum - this.#frontBufferOffset;
+      if (this.#size !== expectedSize) {
         throw new Error(
-          `Invariant violation: size=${this._size}, expected=${expectedSize}`
+          `Invariant violation: size=${this.#size}, expected=${expectedSize}`
         );
       }
 
-      if (this._buffers.length === 0) {
-        if (this._frontBufferOffset !== 0) {
+      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) {
+        if (this.#frontBufferOffset >= this.#buffers[0]!.length) {
           throw new Error('Invariant violation: offset >= front buffer size');
         }
       }
@@ -232,4 +233,5 @@ class ByteBufferQueue {
   }
 }
 
-module.exports = ByteBufferQueue;
+export default ByteBufferQueue;
+export { ByteBufferQueue };