node-rtc-connection 1.0.19 → 2.0.5

package/types/sctp/datachannel-manager.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file datachannel-manager.ts
+ * @description Bridges SCTP streams + DCEP to RTCDataChannel instances.
+ * @module sctp/datachannel-manager
+ *
+ * Responsibilities:
+ *  - Allocate SCTP stream IDs per RFC 8832 §6: the DTLS client (a=setup:active)
+ *    uses even stream IDs, the DTLS server uses odd.
+ *  - Send DATA_CHANNEL_OPEN and await DATA_CHANNEL_ACK; respond to inbound OPEN.
+ *  - Map outgoing string/binary sends to the correct PPID, and incoming PPIDs
+ *    back to string/binary, including the EMPTY variants for zero-length data.
+ */
+import { EventEmitter } from 'events';
+import type { SctpAssociation } from './association';
+import { RTCDataChannel } from '../datachannel/RTCDataChannel';
+/** Subset of RTCDataChannelInit used when opening/accepting channels. */
+interface ChannelInit {
+    ordered?: boolean;
+    maxRetransmits?: number | null;
+    maxPacketLifeTime?: number | null;
+    protocol?: string;
+}
+/** Information surfaced on the 'open-request' event for an inbound channel. */
+export interface OpenRequestInfo {
+    streamId: number;
+    label: string;
+    protocol: string;
+    ordered: boolean;
+    channelType: number;
+    reliabilityParameter: number;
+}
+declare class DataChannelManager extends EventEmitter {
+    #private;
+    /**
+     * @param {import('./association').SctpAssociation} association
+     * @param {boolean} isDtlsClient - true if we are the DTLS client (even IDs)
+     */
+    constructor(association: SctpAssociation, isDtlsClient: boolean);
+    /**
+     * Open a channel initiated locally.
+     * @param {import('../datachannel/RTCDataChannel').RTCDataChannel} channel
+     * @param {Object} init - { ordered, maxRetransmits, maxPacketLifeTime, protocol }
+     */
+    openChannel(channel: RTCDataChannel, init?: ChannelInit): void;
+    /**
+     * Register an inbound channel (created in response to 'open-request') and
+     * attach its sender.
+     */
+    acceptChannel(channel: RTCDataChannel, info: OpenRequestInfo): void;
+}
+export { DataChannelManager };

package/types/sctp/dcep.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file dcep.ts
+ * @description Data Channel Establishment Protocol (RFC 8832) message codec.
+ * @module sctp/dcep
+ *
+ * DCEP runs on PPID 50 and negotiates a data channel on an SCTP stream:
+ *   DATA_CHANNEL_OPEN (0x03)  -> DATA_CHANNEL_ACK (0x02)
+ */
+export declare const MESSAGE_TYPE: Readonly<{
+    DATA_CHANNEL_ACK: 2;
+    DATA_CHANNEL_OPEN: 3;
+}>;
+export declare const CHANNEL_TYPE: Readonly<{
+    RELIABLE: 0;
+    RELIABLE_UNORDERED: 128;
+    PARTIAL_RELIABLE_REXMIT: 1;
+    PARTIAL_RELIABLE_REXMIT_UNORDERED: 129;
+    PARTIAL_RELIABLE_TIMED: 2;
+    PARTIAL_RELIABLE_TIMED_UNORDERED: 130;
+}>;
+export interface OpenParams {
+    channelType: number;
+    priority?: number;
+    reliabilityParameter?: number;
+    label?: string;
+    protocol?: string;
+}
+export interface DecodedOpen {
+    channelType: number;
+    priority: number;
+    reliabilityParameter: number;
+    label: string;
+    protocol: string;
+    unordered: boolean;
+}
+/**
+ * Encode a DATA_CHANNEL_OPEN message.
+ * @param {Object} p
+ * @param {number} p.channelType
+ * @param {number} p.priority
+ * @param {number} p.reliabilityParameter
+ * @param {string} p.label
+ * @param {string} p.protocol
+ * @returns {Buffer}
+ */
+export declare function encodeOpen({ channelType, priority, reliabilityParameter, label, protocol }: OpenParams): Buffer;
+/**
+ * Decode a DATA_CHANNEL_OPEN message.
+ * @param {Buffer} buf
+ * @returns {Object}
+ */
+export declare function decodeOpen(buf: Buffer): DecodedOpen;
+/** Encode a DATA_CHANNEL_ACK message. */
+export declare function encodeAck(): Buffer;
+/** Return the message type of a DCEP buffer. */
+export declare function messageType(buf: Buffer): number;

package/types/sdp/RTCSessionDescription.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file RTCSessionDescription.ts
+ * @description Session Description Protocol (SDP) representation
+ * @module sdp/RTCSessionDescription
+ *
+ * Implements the W3C RTCSessionDescription interface
+ * (https://www.w3.org/TR/webrtc/#rtcsessiondescription-class).
+ */
+/**
+ * RTCSdpType - Types of session descriptions
+ * @readonly
+ * @enum {string}
+ */
+export declare const RTCSdpType: Readonly<Record<string, string>>;
+/**
+ * Session description init object.
+ */
+export interface RTCSessionDescriptionInit {
+    type?: string;
+    sdp?: string;
+}
+/**
+ * JSON representation of an RTCSessionDescription.
+ */
+export interface RTCSessionDescriptionJSON {
+    type: string | null;
+    sdp: string | null;
+}
+/**
+ * @class RTCSessionDescription
+ * @description Represents a WebRTC session description (offer/answer)
+ *
+ * @example
+ * const desc = new RTCSessionDescription({
+ *   type: 'offer',
+ *   sdp: 'v=0\r\no=- 123456 2 IN IP4 127.0.0.1\r\n...'
+ * });
+ */
+export declare class RTCSessionDescription {
+    #private;
+    /**
+     * Create an RTCSessionDescription instance.
+     * @param {Object} [init] - Session description init
+     * @param {string} [init.type] - SDP type (offer/answer/pranswer/rollback)
+     * @param {string} [init.sdp] - SDP string
+     */
+    constructor(init?: RTCSessionDescriptionInit);
+    /**
+     * Get the SDP type.
+     * @returns {string|null} SDP type
+     */
+    get type(): string | null;
+    /**
+     * Set the SDP type.
+     * @param {string} value - SDP type
+     */
+    set type(value: string | null);
+    /**
+     * Get the SDP string.
+     * @returns {string|null} SDP string
+     */
+    get sdp(): string | null;
+    /**
+     * Set the SDP string.
+     * @param {string} value - SDP string
+     */
+    set sdp(value: string | null);
+    /**
+     * Convert to JSON representation.
+     * @returns {Object} JSON representation
+     */
+    toJSON(): RTCSessionDescriptionJSON;
+}

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