@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/cjs/lib/peer/secureTransportManager.d.ts

@@ -0,0 +1,96 @@
+import { Event } from './imports/common.js';
+import type { TransceiverManager } from './media/index.js';
+import type { RTCStats } from './media/stats.js';
+import type { PeerConfig } from './peerConnection.js';
+import type { SctpTransportManager } from './sctpManager.js';
+import type { SessionDescription } from './sdp.js';
+import { type DtlsKeys, RTCCertificate, RTCDtlsTransport } from './transport/dtls.js';
+import { IceCandidate, type IceGathererState, type RTCIceCandidate, type RTCIceCandidateInit, type RTCIceConnectionState, RTCIceTransport } from './transport/ice.js';
+import type { ConnectionState } from './types/domain.js';
+export declare class SecureTransportManager {
+    connectionState: ConnectionState;
+    iceConnectionState: RTCIceConnectionState;
+    iceGatheringState: IceGathererState;
+    certificate?: RTCCertificate;
+    readonly iceGatheringStateChange: Event<["new" | "complete" | "gathering"]>;
+    readonly iceConnectionStateChange: Event<["disconnected" | "connected" | "failed" | "closed" | "new" | "completed" | "checking"]>;
+    readonly onIceCandidate: Event<[IceCandidate | undefined]>;
+    readonly connectionStateChange: Event<["disconnected" | "connected" | "failed" | "closed" | "connecting" | "new"]>;
+    private config;
+    private transceiverManager;
+    private sctpManager;
+    constructor({ config, transceiverManager, sctpManager }: {
+        config: PeerConfig;
+        transceiverManager: TransceiverManager;
+        sctpManager: SctpTransportManager;
+    });
+    /**live な m-line (停止確定していない transceiver / SCTP) が使う transport */
+    get dtlsTransports(): RTCDtlsTransport[];
+    /**停止済み transceiver の transport も含めた全 transport */
+    private get allDtlsTransports();
+    private readonly createdTransports;
+    get iceTransports(): RTCIceTransport[];
+    setupCertificate(keys: DtlsKeys): void;
+    /**
+   * Resolve STUN/TURN options from the current PeerConfig.
+   * Always returns every server-related field (including undefined) so
+   * Connection.setIceServers can fully replace residual TURN credentials.
+   */
+    private resolveIceServerOptions;
+    /**
+   * Re-apply ICE servers from the current config to ICE transports that have
+   * not started gathering yet (`gatheringState === "new"`).
+   *
+   * JSEP (RFC 8829 §4.1.18) / ticket scope: server changes affect the next
+   * gathering phase. Once gathering has started or finished, leave the live
+   * Connection alone so existing candidates and TURN protocols are not
+   * disturbed. Used when TURN is learned after the gatherer was built
+   * (e.g. from a WHIP Link header) but before setLocalDescription gathers.
+   */
+    updateIceServers(): void;
+    createTransport({ inheritCredentials }?: {
+        inheritCredentials?: boolean | undefined;
+    }): RTCDtlsTransport;
+    /**
+   * sdpMid / sdpMLineIndex は ICE transport を所有する受け入れ済み m-line
+   * (BUNDLE なら tag) を呼び出し側で解決して渡す。
+   */
+    handleNewIceCandidate({ candidate, sdpMid, sdpMLineIndex }: {
+        candidate: IceCandidate;
+        sdpMid?: string;
+        sdpMLineIndex?: number;
+    }): IceCandidate;
+    addIceCandidate(sdp: SessionDescription, candidateMessage: RTCIceCandidate | RTCIceCandidateInit | null): Promise<{
+        kind: "end-of-candidates";
+        mediaIndices: number[];
+        candidate?: undefined;
+    } | {
+        kind: "candidate";
+        candidate: IceCandidate;
+        mediaIndices: number[];
+    }>;
+    private resolveCandidateMediaIndices;
+    private isRejectedMedia;
+    private getTransportByMid;
+    private getTransportByMLineIndex;
+    restartIce(): void;
+    setLocalRole({ type, role, roleOfTransport }: {
+        type: 'offer' | 'answer';
+        /**transport 個別の role がない場合に使う local description 先頭の role */
+        role: 'auto' | 'client' | 'server' | undefined;
+        /**local description でその transport を使う m-line の role */
+        roleOfTransport?: Map<RTCDtlsTransport, 'auto' | 'client' | 'server'>;
+    }): void;
+    private updateIceGatheringState;
+    updateIceConnectionState(): void;
+    /**
+   * 未収集 (gatheringState=new) の ICE transport だけ候補を収集する。
+   * 収集済み transport は gather() が何もしないので、確立済み BUNDLE の transport は再収集されず、
+   * BUNDLE group 外に新設した独立 transport だけが候補を収集する。
+   */
+    gatherCandidates(): Promise<void>;
+    setConnectionState(state: ConnectionState): void;
+    getStats(timestamp?: number): Promise<RTCStats[]>;
+    ensureCerts(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/cjs/lib/peer/secureTransportManager.js

@@ -0,0 +1,472 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecureTransportManager = void 0;
+const const_js_1 = require("./const.js");
+const errors_js_1 = require("./errors.js");
+const common_js_1 = require("./imports/common.js");
+const dtls_js_1 = require("./transport/dtls.js");
+const ice_js_1 = require("./transport/ice.js");
+const utils_js_1 = require("./utils.js");
+const log = (0, common_js_1.debug)('webrtc/peer/secureTransportManager');
+class SecureTransportManager {
+    constructor({ config, transceiverManager, sctpManager }) {
+        this.connectionState = 'new';
+        this.iceConnectionState = 'new';
+        this.iceGatheringState = 'new';
+        this.iceGatheringStateChange = new common_js_1.Event();
+        this.iceConnectionStateChange = new common_js_1.Event();
+        this.onIceCandidate = new common_js_1.Event();
+        this.connectionStateChange = new common_js_1.Event();
+        //Every transport created, the ones a BUNDLE group replaced included: all are stopped when the connection closes
+        this.createdTransports = new Set();
+        this.config = config;
+        this.transceiverManager = transceiverManager;
+        this.sctpManager = sctpManager;
+        if (this.config.dtls) {
+            const { keys } = this.config.dtls;
+            if (this.config.certificates[0]) {
+                this.certificate = this.config.certificates[0];
+            }
+            else if (keys) {
+                this.setupCertificate(keys);
+            }
+        }
+    }
+    /**live な m-line (停止確定していない transceiver / SCTP) が使う transport */
+    get dtlsTransports() {
+        return uniqueTransports([
+            ...this.transceiverManager
+                .getTransceivers()
+                .filter((t) => !t.stopped)
+                .map((t) => t?.dtlsTransport),
+            this.sctpManager.sctpTransport?.dtlsTransport
+        ]);
+    }
+    /**停止済み transceiver の transport も含めた全 transport */
+    get allDtlsTransports() {
+        return uniqueTransports([
+            ...this.transceiverManager.getTransceivers().map((t) => t?.dtlsTransport),
+            this.sctpManager.sctpTransport?.dtlsTransport
+        ]);
+    }
+    get iceTransports() {
+        return this.dtlsTransports.map((d) => d.iceTransport);
+    }
+    setupCertificate(keys) {
+        this.certificate = new dtls_js_1.RTCCertificate(keys.keyPem, keys.certPem, keys.signatureHash);
+    }
+    /**
+   * Resolve STUN/TURN options from the current PeerConfig.
+   * Always returns every server-related field (including undefined) so
+   * Connection.setIceServers can fully replace residual TURN credentials.
+   */
+    resolveIceServerOptions() {
+        const iceServerOptions = (0, utils_js_1.parseIceServers)(this.config.iceServers);
+        const turnTransport = (0, utils_js_1.resolveTurnTransport)({
+            parsedTurnTransport: iceServerOptions.turnTransport,
+            configuredTurnTransport: this.config.turnTransport,
+            forceTurnTCP: this.config.forceTurnTCP
+        });
+        return {
+            stunServer: iceServerOptions.stunServer,
+            turnServer: iceServerOptions.turnServer,
+            turnUsername: iceServerOptions.turnUsername,
+            turnPassword: iceServerOptions.turnPassword,
+            turnTransport,
+            stunServers: iceServerOptions.stunServers,
+            turnServers: iceServerOptions.turnServers.map((server) => ({
+                ...server,
+                transport: (0, utils_js_1.resolveTurnTransport)({
+                    parsedTurnTransport: server.transport,
+                    configuredTurnTransport: this.config.turnTransport,
+                    forceTurnTCP: this.config.forceTurnTCP
+                })
+            }))
+        };
+    }
+    /**
+   * Re-apply ICE servers from the current config to ICE transports that have
+   * not started gathering yet (`gatheringState === "new"`).
+   *
+   * JSEP (RFC 8829 §4.1.18) / ticket scope: server changes affect the next
+   * gathering phase. Once gathering has started or finished, leave the live
+   * Connection alone so existing candidates and TURN protocols are not
+   * disturbed. Used when TURN is learned after the gatherer was built
+   * (e.g. from a WHIP Link header) but before setLocalDescription gathers.
+   */
+    updateIceServers() {
+        const options = {
+            ...this.resolveIceServerOptions(),
+            forceTurn: this.config.iceTransportPolicy === 'relay',
+            useTcp: this.config.iceUseTcp,
+            turnUdpFamily: this.config.turnUdpFamily
+        };
+        for (const iceTransport of this.iceTransports) {
+            // Only update gatherers that have never gathered in this generation.
+            // Applying after gathering would leave stale TURN protocols in
+            // Connection.protocols that get re-advertised on a later restart.
+            if (iceTransport.gatheringState === 'new') {
+                iceTransport.setIceServers(options);
+            }
+        }
+    }
+    createTransport({ inheritCredentials = true } = {}) {
+        const existing = inheritCredentials
+            ? this.iceTransports.find((transport) => transport.state !== 'closed')
+            : undefined;
+        const iceGatherer = new ice_js_1.RTCIceGatherer({
+            ...this.resolveIceServerOptions(),
+            iceLite: this.config.iceLite,
+            forceTurn: this.config.iceTransportPolicy === 'relay',
+            portRange: this.config.icePortRange,
+            interfaceAddresses: this.config.iceInterfaceAddresses,
+            additionalHostAddresses: this.config.iceAdditionalHostAddresses,
+            filterStunResponse: this.config.iceFilterStunResponse,
+            filterCandidatePair: this.config.iceFilterCandidatePair,
+            localPasswordPrefix: this.config.icePasswordPrefix,
+            useIpv4: this.config.iceUseIpv4,
+            useIpv6: this.config.iceUseIpv6,
+            useTcp: this.config.iceUseTcp,
+            tcpPassive: this.config.iceTcpPassive,
+            stunGatherTimeout: this.config.iceStunGatherTimeout,
+            turnConnectTimeout: this.config.iceTurnConnectTimeout,
+            turnTlsOptions: this.config.turnTlsOptions,
+            turnUdpFamily: this.config.turnUdpFamily,
+            useLinkLocalAddress: this.config.iceUseLinkLocalAddress
+        });
+        if (existing) {
+            iceGatherer.connection.localUsername = existing.connection.localUsername;
+            iceGatherer.connection.localPassword = existing.connection.localPassword;
+        }
+        iceGatherer.onGatheringStateChange.subscribe(() => {
+            this.updateIceGatheringState();
+        });
+        this.updateIceGatheringState();
+        const iceTransport = new ice_js_1.RTCIceTransport(iceGatherer);
+        iceTransport.onStateChange.subscribe(() => {
+            this.updateIceConnectionState();
+        });
+        const dtlsTransport = new dtls_js_1.RTCDtlsTransport(this.config, iceTransport, this.certificate, srtpProfiles);
+        this.createdTransports.add(dtlsTransport);
+        return dtlsTransport;
+    }
+    /**
+   * sdpMid / sdpMLineIndex は ICE transport を所有する受け入れ済み m-line
+   * (BUNDLE なら tag) を呼び出し側で解決して渡す。
+   */
+    handleNewIceCandidate({ candidate, sdpMid, sdpMLineIndex }) {
+        candidate.sdpMid = sdpMid;
+        candidate.sdpMLineIndex = sdpMLineIndex;
+        if (candidate.foundation &&
+            !candidate.foundation.startsWith('candidate:')) {
+            candidate.foundation = 'candidate:' + candidate.foundation;
+        }
+        this.onIceCandidate.execute(candidate);
+        return candidate;
+    }
+    async addIceCandidate(sdp, candidateMessage) {
+        const candidateText = candidateMessage?.candidate;
+        const sdpMid = candidateMessage?.sdpMid;
+        const sdpMLineIndex = candidateMessage?.sdpMLineIndex;
+        const usernameFragment = candidateMessage?.usernameFragment;
+        const isEndOfCandidates = candidateMessage == null || candidateText == null || candidateText === '';
+        const mediaIndices = this.resolveCandidateMediaIndices({
+            sdp,
+            isEndOfCandidates,
+            sdpMid,
+            sdpMLineIndex,
+            usernameFragment
+        });
+        if (isEndOfCandidates) {
+            const candidateTarget = mediaIndices
+                .map((index) => this.getTransportByMLineIndex(sdp, index))
+                .filter((iceTransport) => !!iceTransport)
+                .reduce((acc, transport) => {
+                if (!acc.find(({ id }) => id === transport.id)) {
+                    acc.push(transport);
+                }
+                return acc;
+            }, []);
+            await Promise.all(candidateTarget.map((iceTransport) => iceTransport.addRemoteCandidate(undefined)));
+            return {
+                kind: 'end-of-candidates',
+                mediaIndices
+            };
+        }
+        const candidate = ice_js_1.IceCandidate.fromJSON(candidateMessage);
+        if (!candidate) {
+            throw (0, errors_js_1.createWebRtcDomException)('OperationError', 'Failed to parse ICE candidate');
+        }
+        const targetMediaIndex = mediaIndices[0];
+        const targetMedia = sdp.media[targetMediaIndex];
+        if (!targetMedia) {
+            throw (0, errors_js_1.createWebRtcDomException)('OperationError', 'ICE media section not found');
+        }
+        candidate.sdpMid = targetMedia.rtp.muxId ?? undefined;
+        candidate.sdpMLineIndex = targetMediaIndex;
+        const iceTransport = this.getTransportByMLineIndex(sdp, targetMediaIndex);
+        if (!iceTransport) {
+            if (this.isRejectedMedia(targetMedia)) {
+                // 拒否 / 停止した m-line の候補は MID / index を保ったまま記録だけする
+                return {
+                    kind: 'candidate',
+                    candidate,
+                    mediaIndices: [targetMediaIndex]
+                };
+            }
+            throw (0, errors_js_1.createWebRtcDomException)('OperationError', 'ICE transport not found for candidate');
+        }
+        await iceTransport.addRemoteCandidate(candidate);
+        return {
+            kind: 'candidate',
+            candidate,
+            mediaIndices: [targetMediaIndex]
+        };
+    }
+    resolveCandidateMediaIndices({ sdp, isEndOfCandidates, sdpMid, sdpMLineIndex, usernameFragment }) {
+        let mediaIndices;
+        if (typeof sdpMid === 'string') {
+            const mediaIndex = sdp.media.findIndex((media) => media.rtp.muxId === sdpMid);
+            if (mediaIndex < 0) {
+                throw (0, errors_js_1.createWebRtcDomException)('OperationError', 'Media section for sdpMid was not found');
+            }
+            mediaIndices = [mediaIndex];
+        }
+        else if (typeof sdpMLineIndex === 'number') {
+            if (sdpMLineIndex < 0 || sdpMLineIndex >= sdp.media.length) {
+                throw (0, errors_js_1.createWebRtcDomException)('OperationError', 'Media section for sdpMLineIndex was not found');
+            }
+            mediaIndices = [sdpMLineIndex];
+        }
+        else if (isEndOfCandidates) {
+            mediaIndices = sdp.media.map((_, index) => index);
+        }
+        else {
+            throw (0, errors_js_1.createWebRtcTypeError)('sdpMid or sdpMLineIndex must be provided with a candidate');
+        }
+        if (typeof usernameFragment === 'string') {
+            const matchingIndices = mediaIndices.filter((index) => sdp.media[index]?.iceParams?.usernameFragment === usernameFragment);
+            if (matchingIndices.length === 0) {
+                throw (0, errors_js_1.createWebRtcDomException)('OperationError', 'No media section matched the ICE usernameFragment');
+            }
+            mediaIndices = matchingIndices;
+        }
+        return mediaIndices;
+    }
+    isRejectedMedia(media) {
+        if (media.port === 0) {
+            return true;
+        }
+        if (!['audio', 'video'].includes(media.kind)) {
+            return false;
+        }
+        const transceiver = this.transceiverManager
+            .getTransceivers()
+            .find((t) => t.mid != undefined && t.mid === media.rtp.muxId);
+        return (!transceiver ||
+            transceiver.stopped ||
+            transceiver.stopping ||
+            transceiver.pendingRejection);
+    }
+    getTransportByMid(mid) {
+        if (!mid) {
+            return;
+        }
+        let iceTransport;
+        const transceiver = this.transceiverManager
+            .getTransceivers()
+            .find((t) => t.mid === mid);
+        if (transceiver) {
+            iceTransport = transceiver.dtlsTransport?.iceTransport;
+        }
+        else if (!iceTransport && this.sctpManager.sctpTransport?.mid === mid) {
+            iceTransport = this.sctpManager.sctpTransport.dtlsTransport.iceTransport;
+        }
+        if (iceTransport?.state === 'closed') {
+            return;
+        }
+        return iceTransport;
+    }
+    getTransportByMLineIndex(sdp, index) {
+        const media = sdp.media[index];
+        if (!media) {
+            return;
+        }
+        const transport = this.getTransportByMid(media.rtp.muxId);
+        return transport;
+    }
+    restartIce() {
+        for (const transport of this.iceTransports) {
+            transport.restart();
+        }
+        // restart() resets each gatherer to "new"; refresh the aggregate cache
+        // even if a gatherer failed to emit onGatheringStateChange.
+        this.updateIceGatheringState();
+    }
+    setLocalRole({ type, role, roleOfTransport }) {
+        for (const dtlsTransport of this.dtlsTransports) {
+            const iceTransport = dtlsTransport.iceTransport;
+            //The roles are set by the offer and the answer starting the ICE session (the first ones, or those of an ICE
+            //restart, which makes the transport new again) and kept by the later ones (RFC 8445 section 6.1.1): taken
+            //from each later description, they flipped with each offer of the other side, both sides could end up
+            //controlled, and SCTP, whose INIT the controlling side sends, never started
+            if (iceTransport.state === 'new') {
+                if (iceTransport.connection.iceLite) {
+                    iceTransport.connection.iceControlling = false;
+                }
+                else if (iceTransport.connection.remoteIsLite) {
+                    // RFC 8445 S6.1.1
+                    iceTransport.connection.iceControlling = true;
+                }
+                else {
+                    iceTransport.connection.iceControlling = type === 'offer';
+                }
+            }
+            // # set DTLS role for mediasoup
+            if (type === 'answer') {
+                const transportRole = roleOfTransport?.get(dtlsTransport) ?? role;
+                if (transportRole) {
+                    dtlsTransport.role = transportRole;
+                }
+            }
+        }
+    }
+    // https://w3c.github.io/webrtc-pc/#dom-rtcicegatheringstate
+    updateIceGatheringState() {
+        const all = this.iceTransports;
+        function allMatch(...state) {
+            return (all.filter((check) => state.includes(check.gatheringState)).length ===
+                all.length);
+        }
+        let newState;
+        if (all.length && allMatch('complete')) {
+            newState = 'complete';
+        }
+        else if (!all.length || allMatch('new', 'complete')) {
+            newState = 'new';
+        }
+        else if (all.map((check) => check.gatheringState).includes('gathering')) {
+            newState = 'gathering';
+        }
+        else {
+            newState = 'new';
+        }
+        if (this.iceGatheringState === newState) {
+            return;
+        }
+        this.iceGatheringState = newState;
+        this.iceGatheringStateChange.execute(newState);
+    }
+    // https://w3c.github.io/webrtc-pc/#dom-rtciceconnectionstate
+    updateIceConnectionState() {
+        const all = this.iceTransports;
+        let newState;
+        function allMatch(...state) {
+            return (all.filter((check) => state.includes(check.state)).length === all.length);
+        }
+        function anyMatch(...state) {
+            return all.some((check) => state.includes(check.state));
+        }
+        if (this.connectionState === 'closed') {
+            newState = 'closed';
+        }
+        else if (anyMatch('failed')) {
+            newState = 'failed';
+        }
+        else if (anyMatch('disconnected')) {
+            newState = 'disconnected';
+        }
+        else if (allMatch('new', 'closed')) {
+            newState = 'new';
+        }
+        else if (anyMatch('new', 'checking')) {
+            newState = 'checking';
+        }
+        else if (allMatch('completed', 'closed')) {
+            newState = 'completed';
+        }
+        else if (allMatch('connected', 'completed', 'closed')) {
+            newState = 'connected';
+        }
+        else {
+            // unreachable?
+            newState = 'new';
+        }
+        if (this.iceConnectionState === newState) {
+            return;
+        }
+        log('iceConnectionStateChange', newState);
+        this.iceConnectionState = newState;
+        this.iceConnectionStateChange.execute(newState);
+        // Runtime ICE failure (e.g. RFC 7675 consent expiry) must surface on
+        // PeerConnection.connectionState without treating it as an explicit close().
+        if (newState === 'failed' && this.connectionState !== 'closed') {
+            this.setConnectionState('failed');
+        }
+        else if (newState === 'disconnected' &&
+            this.connectionState === 'connected') {
+            this.setConnectionState('disconnected');
+        }
+    }
+    /**
+   * 未収集 (gatheringState=new) の ICE transport だけ候補を収集する。
+   * 収集済み transport は gather() が何もしないので、確立済み BUNDLE の transport は再収集されず、
+   * BUNDLE group 外に新設した独立 transport だけが候補を収集する。
+   */
+    async gatherCandidates() {
+        await Promise.allSettled(this.iceTransports
+            .filter((iceTransport) => iceTransport.state !== 'closed')
+            .map((iceTransport) => iceTransport.gather())).catch((e) => {
+            log('gatherCandidates failed', e);
+        });
+    }
+    setConnectionState(state) {
+        //A closed connection stays closed: a connection still being made when it was closed ends later
+        if (this.connectionState === state || this.connectionState === 'closed') {
+            return;
+        }
+        log('connectionStateChange', state);
+        this.connectionState = state;
+        this.connectionStateChange.execute(state);
+    }
+    async getStats(timestamp) {
+        const stats = [];
+        for (const dtlsTransport of this.dtlsTransports) {
+            const transportStats = await dtlsTransport.getStats(timestamp);
+            if (transportStats) {
+                stats.push(...transportStats);
+            }
+        }
+        return stats;
+    }
+    async ensureCerts() {
+        if (!this.certificate) {
+            this.certificate = await dtls_js_1.RTCDtlsTransport.SetupCertificate();
+        }
+        for (const dtlsTransport of this.dtlsTransports) {
+            dtlsTransport.localCertificate = this.certificate;
+        }
+    }
+    async close() {
+        this.setConnectionState('closed');
+        await Promise.allSettled(uniqueTransports([...this.allDtlsTransports, ...this.createdTransports]).map((t) => t.stop()));
+        this.createdTransports.clear();
+        this.iceGatheringStateChange.allUnsubscribe();
+        this.iceConnectionStateChange.allUnsubscribe();
+        this.onIceCandidate.allUnsubscribe();
+        this.connectionStateChange.allUnsubscribe();
+    }
+}
+exports.SecureTransportManager = SecureTransportManager;
+function uniqueTransports(transports) {
+    return transports.reduce((acc, cur) => {
+        if (cur && !acc.map((d) => d.id).includes(cur.id)) {
+            acc.push(cur);
+        }
+        return acc;
+    }, []);
+}
+const srtpProfiles = [
+    const_js_1.SRTP_PROFILE.SRTP_AEAD_AES_128_GCM, // prefer
+    const_js_1.SRTP_PROFILE.SRTP_AES128_CM_HMAC_SHA1_80
+];