node-rtc-connection 1.0.18 → 2.0.4

package/dist/types/sdp/sdp-utils.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @file sdp-utils.ts
+ * @description SDP generation/parsing for a WebRTC data-channel m-section.
+ * @module sdp/sdp-utils
+ *
+ * Emits the standard application m-line with the SCTP-over-DTLS profile and
+ * conveys transport addresses through ICE candidates (not the c=/m= lines, per
+ * the WebRTC JSEP/SDP rules). This is what browsers expect.
+ */
+/** ICE credentials. */
+export interface IceCredentials {
+    usernameFragment: string;
+    password: string;
+}
+/** DTLS certificate fingerprint. */
+export interface Fingerprint {
+    algorithm: string;
+    value: string;
+}
+/** A candidate descriptor as accepted by {@link buildSdp}. */
+export interface CandidateInput {
+    sdp?: string;
+    candidate?: string;
+}
+/** Options accepted by {@link buildSdp}. */
+export interface BuildSdpOptions {
+    kind?: 'offer' | 'answer';
+    iceUfrag: string;
+    icePwd: string;
+    fingerprint?: Fingerprint;
+    setup?: string;
+    candidates?: CandidateInput[];
+    sctpPort?: number;
+    maxMessageSize?: number;
+}
+/** Options accepted by {@link generateOffer} / {@link generateAnswer}. */
+export interface GenerateOptions extends BuildSdpOptions {
+}
+/** Parsed ICE parameters. */
+export interface IceParameters {
+    usernameFragment: string | null;
+    password: string | null;
+}
+/** Parsed DTLS parameters. */
+export interface DtlsParameters {
+    role: string;
+    fingerprints: Fingerprint[];
+    setup?: string;
+}
+/** Parsed SCTP parameters. */
+export interface SctpParameters {
+    port: number;
+    maxMessageSize: number;
+}
+/** A parsed ICE candidate. */
+export interface ParsedCandidate {
+    candidate: string;
+    foundation: string;
+    component: number;
+    protocol: string;
+    priority: number;
+    address: string;
+    port: number;
+    type: string;
+}
+/**
+ * Generate ICE credentials (ufrag >= 4 chars, pwd >= 22 chars per RFC 8445).
+ * @returns {{usernameFragment:string, password:string}}
+ */
+export declare function generateIceCredentials(): IceCredentials;
+/**
+ * Build the SDP for a data-channel-only session.
+ * @param {Object} o
+ * @param {'offer'|'answer'} o.kind
+ * @param {string} o.iceUfrag
+ * @param {string} o.icePwd
+ * @param {{algorithm:string,value:string}} o.fingerprint - DTLS cert fingerprint
+ * @param {string} o.setup - 'actpass' | 'active' | 'passive'
+ * @param {Array<{sdp?:string,candidate?:string}>} [o.candidates]
+ * @param {number} [o.sctpPort=5000]
+ * @param {number} [o.maxMessageSize=262144]
+ * @returns {string}
+ */
+export declare function buildSdp(o: BuildSdpOptions): string;
+export declare function generateOffer(opts: GenerateOptions): string;
+export declare function generateAnswer(opts: GenerateOptions): string;
+/** Parse ICE ufrag/pwd. */
+export declare function parseIceParameters(sdp: string): IceParameters;
+/** Parse DTLS setup role + fingerprints. */
+export declare function parseDtlsParameters(sdp: string): DtlsParameters;
+/** Parse SCTP port / max message size. */
+export declare function parseSctpParameters(sdp: string): SctpParameters;
+/**
+ * Parse ICE candidate lines into structured objects.
+ * @param {string} sdp
+ * @returns {Array<{candidate:string,foundation:string,component:number,protocol:string,priority:number,address:string,port:number,type:string}>}
+ */
+export declare function parseCandidates(sdp: string): ParsedCandidate[];
+/**
+ * Parse a single "candidate:..." string.
+ * @param {string} str
+ */
+export declare function parseCandidateLine(str: string): ParsedCandidate | null;

package/dist/types/stun/stun-client.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @file stun-client.ts
+ * @description STUN (Session Traversal Utilities for NAT) client implementation
+ * @module stun/stun-client
+ *
+ * STUN Protocol: RFC 5389
+ * TURN Protocol: RFC 5766
+ */
+import { EventEmitter } from 'events';
+/**
+ * Constructor options for {@link STUNClient}.
+ */
+interface STUNClientOptions {
+    /** STUN/TURN server address */
+    server: string;
+    /** Server port */
+    port: number;
+    /** TURN username */
+    username?: string;
+    /** TURN password */
+    credential?: string;
+    /** Transport protocol (udp/tcp) */
+    transport?: string;
+    /** Additional query parameters from URL */
+    params?: Record<string, unknown>;
+}
+/**
+ * Reflexive address info resolved from a STUN Binding response.
+ */
+interface ReflexiveAddress {
+    address: string;
+    port: number;
+    family: string;
+}
+/**
+ * Relay address info resolved from a TURN Allocate response.
+ */
+interface RelayAddress {
+    relayedAddress: string;
+    relayedPort: number;
+    lifetime: number;
+    type: 'relay';
+}
+/**
+ * Result of a TURN Refresh response.
+ */
+interface RefreshResult {
+    lifetime: number;
+}
+/**
+ * Result of a generic success response (CreatePermission / ChannelBind).
+ */
+interface OkResult {
+    ok: true;
+}
+/**
+ * Union of every result shape a transaction may resolve with.
+ */
+type TransactionResult = ReflexiveAddress | RelayAddress | RefreshResult | OkResult;
+/**
+ * @class STUNClient
+ * @description STUN/TURN client for NAT traversal
+ */
+declare class STUNClient extends EventEmitter {
+    #private;
+    /**
+     * Create a STUN client
+     * @param {Object} options - Client options
+     * @param {string} options.server - STUN/TURN server address
+     * @param {number} options.port - Server port
+     * @param {string} [options.username] - TURN username
+     * @param {string} [options.credential] - TURN password
+     * @param {string} [options.transport='udp'] - Transport protocol (udp/tcp)
+     * @param {Object} [options.params={}] - Additional query parameters from URL
+     */
+    constructor(options: STUNClientOptions);
+    /**
+     * Connect to the STUN/TURN server
+     * @returns {Promise<void>}
+     */
+    connect(): Promise<void>;
+    /**
+     * Send a STUN Binding Request to get reflexive address
+     * @returns {Promise<Object>} Reflexive address info
+     */
+    getReflexiveAddress(): Promise<TransactionResult>;
+    /**
+     * Send a TURN Allocate Request to get relay address
+     * @param {number} [lifetime=600] - Allocation lifetime in seconds
+     * @returns {Promise<Object>} Relay address info
+     */
+    allocateRelay(lifetime?: number): Promise<TransactionResult>;
+    /**
+     * Send a TURN Refresh Request to keep allocation alive
+     * @param {number} [lifetime=600] - Allocation lifetime in seconds
+     * @returns {Promise<Object>} Updated allocation info
+     */
+    refreshAllocation(lifetime?: number): Promise<TransactionResult>;
+    /**
+     * Create a TURN Permission for a peer
+     * @param {string} peerAddress - Peer IP address
+     * @returns {Promise<void>}
+     */
+    createPermission(peerAddress: string): Promise<void>;
+    /**
+     * Send data to a peer via TURN Send Indication
+     * @param {string} peerAddress - Peer IP address
+     * @param {number} peerPort - Peer port
+     * @param {Buffer} data - Data to send
+     * @returns {Promise<void>}
+     */
+    sendIndication(peerAddress: string, peerPort: number, data: Buffer): Promise<void>;
+    /**
+     * Close the client
+     */
+    close(): void;
+}
+export default STUNClient;
+export { STUNClient };

package/dist/types/transport-stack.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @file transport-stack.ts
+ * @description Composes ICE -> DTLS -> SCTP -> DCEP into one transport, the
+ * real WebRTC data-channel pipeline.
+ * @module transport-stack
+ *
+ * Wiring:
+ *   IceAgent  emits 'data' (non-STUN datagrams) -> DtlsConnection.handlePacket
+ *   DtlsConnection.output                        -> IceAgent.send
+ *   DtlsConnection 'data' (app records)          -> SctpAssociation.receivePacket
+ *   SctpAssociation 'output'                     -> DtlsConnection.send
+ *   SctpAssociation + DataChannelManager         -> RTCDataChannel
+ *
+ * The DTLS client/server role follows the negotiated a=setup; the SCTP client
+ * (INIT initiator) is the DTLS client, per RFC 8832.
+ */
+import { EventEmitter } from 'events';
+import { IceAgent } from './ice/ice-agent';
+import { DtlsConnection } from './dtls/connection';
+import { SctpAssociation } from './sctp/association';
+import { DataChannelManager, OpenRequestInfo } from './sctp/datachannel-manager';
+import type { RTCDataChannel, RTCDataChannelInit } from './datachannel/RTCDataChannel';
+import type { KeyObject } from 'crypto';
+export interface TransportStackOptions {
+    /** ICE controlling vs controlled (offerer is controlling). */
+    iceRole: 'controlling' | 'controlled';
+    /** DTLS role from a=setup (active=client). */
+    dtlsRole: 'client' | 'server';
+    localUfrag: string;
+    localPwd: string;
+    certDer: Buffer;
+    privateKey: KeyObject;
+    verifyFingerprint?: (fp: {
+        algorithm: string;
+        value: string;
+    }) => boolean;
+}
+export declare class TransportStack extends EventEmitter {
+    #private;
+    ice: IceAgent;
+    dtls: DtlsConnection | null;
+    sctp: SctpAssociation | null;
+    dcm: DataChannelManager | null;
+    constructor(opts: TransportStackOptions);
+    /**
+     * Begin gathering local candidates.
+     * @param opts - { iceServers, iceTransportPolicy } forwarded to ICE.
+     */
+    gather(opts?: {
+        iceServers?: unknown[];
+        iceTransportPolicy?: 'all' | 'relay';
+    }): Promise<void>;
+    getLocalCandidates(): ReturnType<IceAgent['getLocalCandidates']>;
+    /** Provide the peer's ICE credentials and start checks when ready. */
+    setRemote(ufrag: string, pwd: string): void;
+    addRemoteCandidate(cand: {
+        address: string;
+        port: number;
+        type?: string;
+        priority?: number;
+    }): void;
+    /** Open a locally-initiated data channel once SCTP is established. */
+    openChannel(channel: RTCDataChannel, init: RTCDataChannelInit): void;
+    /** Accept an inbound channel created from a 'datachannel-request'. */
+    acceptChannel(channel: RTCDataChannel, info: OpenRequestInfo): void;
+    isReady(): boolean;
+    close(): void;
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "node-rtc-connection",
-  "version": "1.0.18",
+  "version": "2.0.4",
   "description": "WebRTC DataChannel implementation for Node.js with STUN, TURN, NAT traversal, and encryption. Pure Node.js, no native dependencies.",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
-  "types": "src/index.d.ts",
+  "types": "dist/types/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/index.d.ts",
+      "types": "./dist/types/index.d.ts",
       "require": "./dist/index.cjs",
       "import": "./dist/index.mjs"
     }
@@ -20,20 +20,17 @@
   ],
   "scripts": {
     "build": "rollup -c",
+    "typecheck": "tsc -p tsconfig.test.json",
     "prepublishOnly": "npm run build && npm test",
-    "test": "node test/run-all-tests.js",
-    "test:watch": "node --test --watch test/*.test.js",
-    "test:unit": "SKIP_INTEGRATION=1 node --test test/*.test.js",
-    "test:integration": "node --test test/integration.test.js",
-    "test:all": "SKIP_INTEGRATION=0 node test/run-all-tests.js",
-    "test:stun": "node --test test/STUN.test.js",
-    "test:turn": "node --test test/TURN.test.js",
-    "test:turn-integration": "node --test test/turn-integration.test.js",
-    "test:turn-all": "node --test test/TURN.test.js test/turn-integration.test.js",
-    "example": "node examples/real-networking.js",
-    "example:simple": "node examples/simple-datachannel.js",
-    "example:stun": "node examples/with-stun-encryption.js",
-    "example:turn": "node examples/with-turn-relay.js",
+    "test": "node --import tsx test/run-all-tests.ts",
+    "test:ci": "bash scripts/ci-local.sh",
+    "test:unit": "SKIP_INTEGRATION=1 node --import tsx --test test/*.test.ts",
+    "test:coverage": "c8 node --import tsx test/run-all-tests.ts",
+    "test:coverage:check": "c8 --check-coverage node --import tsx test/run-all-tests.ts",
+    "test:watch": "node --import tsx --test --watch test/*.test.ts",
+    "example": "node --import tsx examples/browser-server.ts",
+    "example:browser": "node --import tsx examples/browser-server.ts",
+    "example:node": "node --import tsx examples/node-to-node.ts",
     "release:patch": "npm version patch && git push && git push --tags",
     "release:minor": "npm version minor && git push && git push --tags",
     "release:major": "npm version major && git push && git push --tags"
@@ -59,20 +56,28 @@
   "license": "MIT",
   "type": "commonjs",
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "rollup": "^4.54.0"
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^25.9.1",
+    "c8": "^11.0.0",
+    "playwright": "^1.60.0",
+    "rollup": "^4.54.0",
+    "tslib": "^2.8.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nmhung1210/nodertc.git"
+    "url": "git+https://github.com/nmhung1210/node-rtc-connection.git"
   },
   "bugs": {
-    "url": "https://github.com/nmhung1210/nodertc/issues"
+    "url": "https://github.com/nmhung1210/node-rtc-connection/issues"
   },
-  "homepage": "https://github.com/nmhung1210/nodertc#readme"
+  "homepage": "https://github.com/nmhung1210/node-rtc-connection#readme"
 }

package/src/crypto/der.ts

@@ -0,0 +1,205 @@
+/**
+ * @file der.ts
+ * @description Minimal ASN.1 DER encoder/decoder for X.509 certificate generation.
+ * @module crypto/der
+ *
+ * Implements just enough of ITU-T X.690 DER to build and read the structures
+ * WebRTC needs: self-signed ECDSA certificates and SubjectPublicKeyInfo.
+ *
+ * All encoders return Buffers. The TLV length is always encoded in the
+ * minimal (definite, shortest-form) representation required by DER.
+ */
+
+'use strict';
+
+// ASN.1 universal tag numbers (class 0, primitive/constructed as noted).
+export const TAG = Object.freeze({
+  BOOLEAN: 0x01,
+  INTEGER: 0x02,
+  BIT_STRING: 0x03,
+  OCTET_STRING: 0x04,
+  NULL: 0x05,
+  OID: 0x06,
+  UTF8_STRING: 0x0c,
+  PRINTABLE_STRING: 0x13,
+  IA5_STRING: 0x16,
+  UTC_TIME: 0x17,
+  GENERALIZED_TIME: 0x18,
+  SEQUENCE: 0x30, // constructed
+  SET: 0x31, // constructed
+});
+
+/**
+ * Encode a DER length in definite, shortest form.
+ * @param {number} len
+ * @returns {Buffer}
+ */
+export function encodeLength(len: number): Buffer {
+  if (len < 0x80) {
+    return Buffer.from([len]);
+  }
+  const bytes: number[] = [];
+  let n = len;
+  while (n > 0) {
+    bytes.unshift(n & 0xff);
+    n >>>= 8;
+  }
+  return Buffer.from([0x80 | bytes.length, ...bytes]);
+}
+
+/**
+ * Wrap a body in a TLV with the given tag.
+ * @param {number} tag
+ * @param {Buffer} body
+ * @returns {Buffer}
+ */
+export function tlv(tag: number, body: Buffer): Buffer {
+  return Buffer.concat([Buffer.from([tag]), encodeLength(body.length), body]);
+}
+
+/**
+ * Encode an unsigned big-endian integer (from a Buffer) as a DER INTEGER,
+ * adding a leading 0x00 when the high bit is set so it stays positive.
+ * @param {Buffer} buf - Big-endian magnitude.
+ * @returns {Buffer}
+ */
+export function encodeIntegerFromBuffer(buf: Buffer): Buffer {
+  let start = 0;
+  while (start < buf.length - 1 && buf[start] === 0x00) {
+    start++; // strip leading zeros (keep at least one byte)
+  }
+  let body = buf.slice(start);
+  if (body[0]! & 0x80) {
+    body = Buffer.concat([Buffer.from([0x00]), body]);
+  }
+  return tlv(TAG.INTEGER, body);
+}
+
+/**
+ * Encode a small non-negative JS integer as a DER INTEGER.
+ * @param {number} value
+ * @returns {Buffer}
+ */
+export function encodeInteger(value: number): Buffer {
+  if (value === 0) {
+    return tlv(TAG.INTEGER, Buffer.from([0x00]));
+  }
+  const bytes: number[] = [];
+  let n = value;
+  while (n > 0) {
+    bytes.unshift(n & 0xff);
+    n = Math.floor(n / 256);
+  }
+  if (bytes[0]! & 0x80) {
+    bytes.unshift(0x00);
+  }
+  return tlv(TAG.INTEGER, Buffer.from(bytes));
+}
+
+/**
+ * Encode an OBJECT IDENTIFIER from its dotted-decimal string.
+ * @param {string} oid - e.g. "1.2.840.10045.2.1"
+ * @returns {Buffer}
+ */
+export function encodeOID(oid: string): Buffer {
+  const parts = oid.split('.').map(Number);
+  if (parts.length < 2) {
+    throw new Error(`Invalid OID: ${oid}`);
+  }
+  const bytes = [40 * parts[0]! + parts[1]!];
+  for (let i = 2; i < parts.length; i++) {
+    let v = parts[i]!;
+    const stack = [v & 0x7f];
+    v = Math.floor(v / 128);
+    while (v > 0) {
+      stack.unshift((v & 0x7f) | 0x80);
+      v = Math.floor(v / 128);
+    }
+    bytes.push(...stack);
+  }
+  return tlv(TAG.OID, Buffer.from(bytes));
+}
+
+/**
+ * Encode a BIT STRING with zero unused bits.
+ * @param {Buffer} data
+ * @returns {Buffer}
+ */
+export function encodeBitString(data: Buffer): Buffer {
+  return tlv(TAG.BIT_STRING, Buffer.concat([Buffer.from([0x00]), data]));
+}
+
+/**
+ * Encode an OCTET STRING.
+ * @param {Buffer} data
+ * @returns {Buffer}
+ */
+export function encodeOctetString(data: Buffer): Buffer {
+  return tlv(TAG.OCTET_STRING, data);
+}
+
+/**
+ * Encode a SEQUENCE from already-encoded components.
+ * @param {Buffer[]} components
+ * @returns {Buffer}
+ */
+export function encodeSequence(components: Buffer[]): Buffer {
+  return tlv(TAG.SEQUENCE, Buffer.concat(components));
+}
+
+/**
+ * Encode a SET from already-encoded components.
+ * @param {Buffer[]} components
+ * @returns {Buffer}
+ */
+export function encodeSet(components: Buffer[]): Buffer {
+  return tlv(TAG.SET, Buffer.concat(components));
+}
+
+/**
+ * Encode NULL.
+ * @returns {Buffer}
+ */
+export function encodeNull(): Buffer {
+  return tlv(TAG.NULL, Buffer.alloc(0));
+}
+
+/**
+ * Encode a UTF8String.
+ * @param {string} str
+ * @returns {Buffer}
+ */
+export function encodeUTF8String(str: string): Buffer {
+  return tlv(TAG.UTF8_STRING, Buffer.from(str, 'utf8'));
+}
+
+/**
+ * Encode a context-specific [n] explicit wrapper (constructed).
+ * @param {number} n - context tag number
+ * @param {Buffer} body
+ * @returns {Buffer}
+ */
+export function encodeExplicit(n: number, body: Buffer): Buffer {
+  return tlv(0xa0 | n, body);
+}
+
+/**
+ * Encode an X.509 time. Uses UTCTime for years < 2050, else GeneralizedTime,
+ * per RFC 5280 §4.1.2.5.
+ * @param {Date} date
+ * @returns {Buffer}
+ */
+export function encodeTime(date: Date): Buffer {
+  const yyyy = date.getUTCFullYear();
+  const pad = (v: number, n = 2): string => String(v).padStart(n, '0');
+  const mm = pad(date.getUTCMonth() + 1);
+  const dd = pad(date.getUTCDate());
+  const hh = pad(date.getUTCHours());
+  const mi = pad(date.getUTCMinutes());
+  const ss = pad(date.getUTCSeconds());
+  if (yyyy < 2050) {
+    const yy = pad(yyyy % 100);
+    return tlv(TAG.UTC_TIME, Buffer.from(`${yy}${mm}${dd}${hh}${mi}${ss}Z`, 'ascii'));
+  }
+  return tlv(TAG.GENERALIZED_TIME, Buffer.from(`${yyyy}${mm}${dd}${hh}${mi}${ss}Z`, 'ascii'));
+}