@stream-io/video-client 1.56.0 → 1.58.0

package/src/rtc/__tests__/Publisher.test.ts

@@ -146,6 +146,50 @@ describe('Publisher', () => {
       expect(negotiateSpy).toHaveBeenCalled();
     });
 
+    it('should attach an encryptor when E2EE manager is provided', async () => {
+      const e2eeMock = {
+        encrypt: vi.fn(),
+        decrypt: vi.fn(),
+      };
+      publisher.dispose();
+      publisher = new Publisher(
+        {
+          sfuClient,
+          dispatcher,
+          state,
+          tag: 'test',
+          enableTracing: false,
+          e2ee: e2eeMock,
+        },
+        [
+          {
+            id: 1,
+            trackType: TrackType.VIDEO,
+            bitrate: 1000,
+            // @ts-expect-error - incomplete data
+            codec: { name: 'vp9' },
+            fps: 30,
+            maxTemporalLayers: 3,
+            maxSpatialLayers: 3,
+          },
+        ],
+      );
+
+      const track = new MediaStreamTrack();
+      const clone = new MediaStreamTrack();
+      vi.spyOn(track, 'clone').mockReturnValue(clone);
+      // @ts-expect-error - private method
+      vi.spyOn(publisher, 'negotiate').mockResolvedValue();
+
+      await publisher.publish(track, TrackType.VIDEO);
+
+      expect(e2eeMock.encrypt).toHaveBeenCalledWith(
+        expect.anything(), // sender
+        'vp9',
+        'VIDEO',
+      );
+    });
+
     it('should update an existing transceiver for a new track', async () => {
       const track = new MediaStreamTrack();
       const clone = new MediaStreamTrack();
@@ -239,6 +283,63 @@ describe('Publisher', () => {
     });
   });
 
+  describe('E2EE peer connection config', () => {
+    const e2ee = { encrypt: vi.fn(), decrypt: vi.fn() };
+
+    /**
+     * Build a publisher and return the RTCConfiguration it constructed its peer
+     * connection with. The publisher from the outer `beforeEach` already
+     * consumed a call, hence the last one rather than the first.
+     */
+    const configOf = async (opts: { e2ee?: typeof e2ee }) => {
+      await publisher.dispose();
+      publisher = new Publisher(
+        {
+          sfuClient,
+          dispatcher,
+          state,
+          tag: 'test',
+          enableTracing: false,
+          ...opts,
+        },
+        [],
+      );
+      const calls = vi.mocked(globalThis.RTCPeerConnection).mock.calls;
+      return calls[calls.length - 1][0] as Record<string, unknown> | undefined;
+    };
+
+    const withInsertableStreams = (available: boolean) => {
+      if (available) {
+        Object.assign(RTCRtpSender.prototype, {
+          createEncodedStreams: vi.fn(),
+        });
+      } else {
+        // @ts-expect-error - non-standard property from the mock prototype
+        delete RTCRtpSender.prototype.createEncodedStreams;
+      }
+    };
+
+    afterEach(() => withInsertableStreams(false));
+
+    it('enables encodedInsertableStreams when a manager is attached', async () => {
+      withInsertableStreams(true);
+      const config = await configOf({ e2ee });
+      expect(config?.encodedInsertableStreams).toBe(true);
+    });
+
+    it('leaves the flag off when no manager is attached', async () => {
+      withInsertableStreams(true);
+      const config = await configOf({});
+      expect(config?.encodedInsertableStreams).toBeUndefined();
+    });
+
+    it('leaves the flag off on browsers without Insertable Streams', async () => {
+      withInsertableStreams(false);
+      const config = await configOf({ e2ee });
+      expect(config?.encodedInsertableStreams).toBeUndefined();
+    });
+  });
+
   describe('Event Handling', () => {
     it('handles changePublishQuality events', () => {
       publisher['changePublishQuality'] = vi.fn();

package/src/rtc/__tests__/Subscriber.test.ts

@@ -17,6 +17,7 @@ import { NegotiationError } from '../NegotiationError';
 import { ReconnectReason } from '../types';
 import { IceTrickleBuffer } from '../IceTrickleBuffer';
 import { StreamClient } from '../../coordinator/connection/client';
+import { fromPartial } from '@total-typescript/shoehorn';
 
 vi.mock('../../StreamSfuClient', () => {
   console.log('MOCKING StreamSfuClient');
@@ -522,6 +523,94 @@ describe('Subscriber', () => {
       expect(baseTrack.stop).toHaveBeenCalled();
       expect(baseStream.removeTrack).toHaveBeenCalledWith(baseTrack);
     });
+
+    it('should store receiver in orphaned track when E2EE is enabled', () => {
+      const e2eeMock = {
+        encrypt: vi.fn(),
+        decrypt: vi.fn(),
+      };
+      subscriber.dispose();
+      const e2eeState = new CallState();
+      subscriber = new Subscriber({
+        sfuClient,
+        dispatcher,
+        state: e2eeState,
+        connectionConfig: { iceServers: [] },
+        tag: 'test',
+        enableTracing: true,
+        e2ee: e2eeMock,
+      });
+
+      const mediaStream = new MediaStream();
+      const mediaStreamTrack = new MediaStreamTrack();
+      const receiver = {};
+      // @ts-expect-error - mock
+      mediaStream.id = 'orphan-prefix:TRACK_TYPE_VIDEO';
+
+      const registerOrphanedTrackSpy = vi.spyOn(
+        e2eeState,
+        'registerOrphanedTrack',
+      );
+      const onTrack = subscriber['handleOnTrack'];
+      // @ts-expect-error - incomplete mock
+      onTrack({ streams: [mediaStream], track: mediaStreamTrack, receiver });
+
+      // Decrypt is NOT called immediately for orphaned tracks
+      expect(e2eeMock.decrypt).not.toHaveBeenCalled();
+      // Receiver is stored with the orphaned track for later reconciliation
+      expect(registerOrphanedTrackSpy).toHaveBeenCalledWith({
+        id: mediaStream.id,
+        trackLookupPrefix: 'orphan-prefix',
+        track: mediaStream,
+        trackType: TrackType.VIDEO,
+        receiver,
+      });
+    });
+
+    it('should decrypt with userId when participant is found', () => {
+      const e2eeMock = {
+        encrypt: vi.fn(),
+        decrypt: vi.fn(),
+      };
+      subscriber.dispose();
+      const e2eeState = new CallState();
+      subscriber = new Subscriber({
+        sfuClient,
+        dispatcher,
+        state: e2eeState,
+        connectionConfig: { iceServers: [] },
+        tag: 'test',
+        enableTracing: true,
+        e2ee: e2eeMock,
+      });
+
+      // Register a participant whose trackLookupPrefix matches the stream
+      e2eeState.updateOrAddParticipant(
+        'session-id',
+        fromPartial({
+          sessionId: 'session-id',
+          userId: 'real-user-id',
+          trackLookupPrefix: '123',
+        }),
+      );
+
+      const mediaStream = new MediaStream();
+      const mediaStreamTrack = new MediaStreamTrack();
+      const receiver = {};
+      // @ts-expect-error - mock
+      mediaStream.id = '123:TRACK_TYPE_VIDEO';
+
+      const onTrack = subscriber['handleOnTrack'];
+      // @ts-expect-error - incomplete mock
+      onTrack({ streams: [mediaStream], track: mediaStreamTrack, receiver });
+
+      // Uses the participant's userId (not trackLookupPrefix) for key lookup
+      expect(e2eeMock.decrypt).toHaveBeenCalledWith(
+        receiver,
+        'real-user-id',
+        'VIDEO',
+      );
+    });
   });
 
   describe('interruptedTracks', () => {

package/src/rtc/__tests__/mocks/webrtc.mocks.ts

@@ -57,6 +57,7 @@ const RTCRtpTransceiverMock = vi.fn(function (): Partial<RTCRtpTransceiver> {
       replaceTrack: vi.fn(),
       getParameters: vi.fn().mockReturnValue({}),
       setParameters: vi.fn(),
+      transform: null,
     },
     setCodecPreferences: vi.fn(),
     mid: '',
@@ -80,6 +81,7 @@ const RTCRtpReceiverMock = vi.fn(function (): Partial<typeof RTCRtpReceiver> {
     getCapabilities: vi.fn(),
   };
 });
+RTCRtpReceiverMock.prototype.transform = null;
 vi.stubGlobal('RTCRtpReceiver', RTCRtpReceiverMock);
 
 const RTCRtpSenderMock = vi.fn(function (): Partial<typeof RTCRtpSender> {
@@ -89,8 +91,37 @@ const RTCRtpSenderMock = vi.fn(function (): Partial<typeof RTCRtpSender> {
     track: vi.fn(),
   };
 });
+RTCRtpSenderMock.prototype.transform = null;
 vi.stubGlobal('RTCRtpSender', RTCRtpSenderMock);
 
+const WorkerMock = vi.fn(function (): Partial<Worker> {
+  return {
+    postMessage: vi.fn(),
+    terminate: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  };
+});
+vi.stubGlobal('Worker', WorkerMock);
+
+const RTCRtpScriptTransformMock = vi.fn(function (
+  worker: Worker,
+  options?: unknown,
+): Partial<RTCRtpScriptTransform> {
+  return {
+    worker,
+    options,
+  };
+});
+vi.stubGlobal('RTCRtpScriptTransform', RTCRtpScriptTransformMock);
+
+if (typeof URL !== 'undefined' && typeof URL.createObjectURL !== 'function') {
+  Object.defineProperty(URL, 'createObjectURL', {
+    configurable: true,
+    value: vi.fn(() => 'blob:stream-video-e2ee'),
+  });
+}
+
 const AudioContextMock = vi.fn(function (): Partial<AudioContext> {
   return {
     state: 'suspended',

package/src/rtc/e2ee/E2EEManager.ts

@@ -0,0 +1,12 @@
+/**
+ * What the RTC layer needs to attach E2EE to a track. {@link EncryptionManager}
+ * is the built-in AES-GCM implementation, but `Call.setE2EEManager` takes any:
+ * an integrator can plug in another scheme, RFC 9605 SFrame for example, by
+ * attaching their own encoded transform in these two methods.
+ */
+export interface E2EEManager {
+  /** `trackType` only groups perf stats, keeping a camera and screen share apart. */
+  encrypt(sender: RTCRtpSender, codec?: string, trackType?: string): void;
+  /** `trackType` only groups perf stats, keeping a peer's audio and video apart. */
+  decrypt(receiver: RTCRtpReceiver, userId: string, trackType?: string): void;
+}

package/src/rtc/e2ee/EncryptionManager.ts

@@ -0,0 +1,336 @@
+import { preferredTransform } from './transformSupport';
+import { TypedEventEmitter } from '../../helpers/TypedEventEmitter';
+import type { E2EEEventMap } from './events';
+import type { E2EEManager } from './E2EEManager';
+
+export type {
+  E2EEEventMap,
+  DecryptionFailedEvent,
+  DecryptionResumedEvent,
+  DecryptionStalledEvent,
+  EncryptionFailedEvent,
+  KeyStateReport,
+  MissingKeyEvent,
+  PerfReport,
+  TrackPerf,
+  UnencryptedFrameEvent,
+  UnsupportedVersionEvent,
+} from './events';
+
+/**
+ * - `'AES-128-GCM'` (default): 16-byte keys, per BSI TR-02102-1 §3.2.
+ * - `'AES-256-GCM'`: 32-byte keys. For a compliance reviewer that requires
+ *   256-bit strength, such as a KBV Anlage 31b certifier.
+ */
+export type E2EEAlgorithm = 'AES-128-GCM' | 'AES-256-GCM';
+
+/** Options for {@link EncryptionManager.create}. */
+export type EncryptionManagerOptions = {
+  algorithm?: E2EEAlgorithm;
+};
+
+/**
+ * Distributes keys to the E2EE Web Worker and attaches encrypt/decrypt
+ * transforms to RTCRtpSenders and RTCRtpReceivers.
+ */
+export class EncryptionManager
+  extends TypedEventEmitter<E2EEEventMap>
+  implements E2EEManager
+{
+  private readonly algorithm: E2EEAlgorithm;
+  private readonly transform: 'script' | 'insertable';
+  private disposed = false;
+  private piped?: WeakSet<RTCRtpSender | RTCRtpReceiver>;
+
+  private readonly userId: string;
+  private readonly worker: Worker;
+  private readonly workerUrl: string;
+
+  private constructor(
+    userId: string,
+    worker: Worker,
+    workerUrl: string,
+    algorithm: E2EEAlgorithm,
+    transform: 'script' | 'insertable',
+  ) {
+    super('EncryptionManager');
+    this.userId = userId;
+    this.worker = worker;
+    this.workerUrl = workerUrl;
+    this.algorithm = algorithm;
+    this.transform = transform;
+    this.worker.addEventListener('message', this.handleWorkerMessage);
+    this.worker.addEventListener('error', this.handleWorkerError);
+  }
+
+  /**
+   * Whether this browser has WebRTC Encoded Transforms, which E2EE requires.
+   * Use it to guard UI, or to avoid calling {@link create} where it would throw.
+   */
+  static isSupported = (): boolean => {
+    return preferredTransform() !== undefined;
+  };
+
+  /**
+   * Create an EncryptionManager instance and initialize the E2EE Web Worker.
+   *
+   * @param userId - The local user's ID, normally `call.currentUserId`.
+   * @param options - the create options.
+   * @throws {Error} If the browser lacks Encoded Transforms.
+   *
+   * @example
+   * ```ts
+   * if (EncryptionManager.isSupported()) {
+   *   const e2ee = await EncryptionManager.create(call.currentUserId);
+   *   call.setE2EEManager(e2ee);
+   *   e2ee.setSharedKey(0, keyBytes);
+   * }
+   */
+  static create = async (
+    userId: string,
+    options?: EncryptionManagerOptions,
+  ): Promise<EncryptionManager> => {
+    const transform = preferredTransform();
+    if (!transform) {
+      throw new Error(`E2EE is not supported in this browser`);
+    }
+    const { e2eeWorker } = await import('./e2ee-worker');
+    const blob = new Blob([`(${e2eeWorker.toString()})()`], {
+      type: 'application/javascript',
+    });
+    const url = URL.createObjectURL(blob);
+    let worker: Worker;
+    try {
+      worker = new Worker(url, { name: 'stream-video-e2ee' });
+    } catch (err) {
+      // e.g. a CSP `worker-src` without `blob:`. Don't leak the object URL.
+      URL.revokeObjectURL(url);
+      throw err;
+    }
+    const algorithm = options?.algorithm ?? 'AES-128-GCM';
+    return new EncryptionManager(userId, worker, url, algorithm, transform);
+  };
+
+  /**
+   * {@link dispose} terminates the worker, so `postMessage` becomes a silent
+   * no-op and an attached transform points at a dead worker: frames would stall
+   * forever with no error and no event. Throwing is also fail-closed, since a
+   * caller that swallows it still publishes nothing rather than cleartext.
+   */
+  private assertUsable = () => {
+    if (this.disposed) throw new Error(`EncryptionManager is disposed`);
+  };
+
+  /**
+   * Terminate the worker and release all resources.
+   *
+   * The manager is unusable afterwards and every other method throws. Call
+   * {@link create} for a new one. Safe to call more than once.
+   */
+  dispose = (): void => {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.piped = undefined;
+    this.worker.removeEventListener('message', this.handleWorkerMessage);
+    this.worker.removeEventListener('error', this.handleWorkerError);
+    this.worker.terminate();
+    URL.revokeObjectURL(this.workerUrl);
+    this.removeAllListeners();
+  };
+
+  /**
+   * Set a per-user AES-GCM encryption key in the worker's key store.
+   *
+   * Use it when each participant has their own key from a central authority.
+   * The receiver picks the right one by the `keyIndex` in the frame trailer.
+   *
+   * @param userId - The key owner.
+   * @param keyIndex - Increases with each rotation.
+   * @param rawKey - 16 bytes for AES-128-GCM, 32 for AES-256-GCM.
+   */
+  setKey = (userId: string, keyIndex: number, rawKey: ArrayBuffer): void => {
+    this.assertUsable();
+    this.validateKeyIndex(keyIndex);
+    this.validateKeyLength(rawKey);
+    this.worker.postMessage({ type: 'cmd.set_key', userId, keyIndex, rawKey });
+  };
+
+  /**
+   * Fallback key for any user without a per-user key. The simplest E2EE mode:
+   * one key for everyone, usually passphrase-derived, no distribution needed.
+   * Setting an epoch makes it active for encryption while older epochs remain
+   * available to decrypt in-flight frames until {@link removeSharedKey}.
+   *
+   * @param keyIndex - An integer 0-255, since one trailer byte carries it.
+   * @param rawKey - 16 bytes for AES-128-GCM, 32 for AES-256-GCM.
+   */
+  setSharedKey = (keyIndex: number, rawKey: ArrayBuffer): void => {
+    this.assertUsable();
+    this.validateKeyIndex(keyIndex);
+    this.validateKeyLength(rawKey);
+    this.worker.postMessage({ type: 'cmd.set_shared_key', keyIndex, rawKey });
+  };
+
+  /**
+   * Remove one shared-key epoch from the worker's receive key ring.
+   *
+   * If this is the active epoch, shared-key encryption stops until
+   * {@link setSharedKey} succeeds again. An older epoch is not reactivated.
+   *
+   * @param keyIndex - The exact shared-key epoch to remove.
+   */
+  removeSharedKey = (keyIndex: number): void => {
+    this.assertUsable();
+    this.validateKeyIndex(keyIndex);
+    this.worker.postMessage({ type: 'cmd.remove_shared_key', keyIndex });
+  };
+
+  /**
+   * Retire one of a user's key epochs, leaving their other epochs usable.
+   *
+   * @param userId - The key owner.
+   * @param keyIndex - The exact epoch to remove. Absent epochs are a no-op.
+   */
+  removeKey = (userId: string, keyIndex: number): void => {
+    this.assertUsable();
+    this.validateKeyIndex(keyIndex);
+    this.worker.postMessage({ type: 'cmd.remove_key', userId, keyIndex });
+  };
+
+  /**
+   * Drop every key a user holds, revoking their ability to decrypt later
+   * frames. Call it when a participant leaves.
+   *
+   * To retire one rotated epoch instead, use {@link removeKey}.
+   */
+  removeAllKeys = (userId: string): void => {
+    this.assertUsable();
+    this.worker.postMessage({ type: 'cmd.remove_all_keys', userId });
+  };
+
+  /**
+   * Called by the Publisher when it adds a transceiver.
+   *
+   * @param sender - The sender to encrypt.
+   * @param codec - Codec name, e.g. 'vp8', selecting the clear-byte rules.
+   * @param trackType - Optional label; only groups perf stats.
+   * @internal
+   */
+  encrypt = (
+    sender: RTCRtpSender,
+    codec?: string,
+    trackType?: string,
+  ): void => {
+    this.assertUsable();
+    this.pipe(sender, {
+      operation: 'encode',
+      userId: this.userId,
+      codec,
+      trackType,
+    });
+  };
+
+  /**
+   * Called by the Subscriber when a remote track arrives.
+   *
+   * @param receiver - The receiver to decrypt.
+   * @param userId - The remote user, for key lookup in the worker.
+   * @param trackType - Optional label; only groups perf stats.
+   * @internal
+   */
+  decrypt = (
+    receiver: RTCRtpReceiver,
+    userId: string,
+    trackType?: string,
+  ): void => {
+    this.assertUsable();
+    this.pipe(receiver, { operation: 'decode', userId, trackType });
+  };
+
+  /** Pipe through the worker's transform, tracking targets to avoid double-piping. */
+  private pipe = (
+    target: RTCRtpSender | RTCRtpReceiver,
+    options: {
+      operation: string;
+      userId: string;
+      codec?: string;
+      trackType?: string;
+    },
+  ): void => {
+    if (this.transform === 'script') {
+      target.transform = new RTCRtpScriptTransform(this.worker, options);
+      return;
+    }
+
+    if ((this.piped ??= new WeakSet()).has(target)) return;
+    this.piped.add(target);
+    // @ts-expect-error createEncodedStreams is not in the standard typedefs
+    const { readable, writable } = target.createEncodedStreams();
+    this.worker.postMessage(
+      { type: 'cmd.setup_transform', ...options, readable, writable },
+      [readable, writable],
+    );
+  };
+
+  /**
+   * Toggle periodic performance reporting from the E2EE worker.
+   *
+   * While on, the worker emits `e2ee.perf_report` once per second with per-track
+   * FPS and crypto timings. Useful for debugging throughput.
+   */
+  enablePerformanceReporting = (enabled: boolean): void => {
+    this.assertUsable();
+    this.worker.postMessage({
+      type: 'cmd.enable_performance_reporting',
+      enabled,
+    });
+  };
+
+  /**
+   * Request a snapshot of the worker's keys. It arrives later as the
+   * `e2ee.key_state` event, listing fingerprints only, never key material.
+   */
+  requestKeyState = (): void => {
+    this.assertUsable();
+    this.worker.postMessage({ type: 'cmd.request_key_state' });
+  };
+
+  private handleWorkerMessage = (e: MessageEvent) => {
+    const { type, ...payload } = e.data ?? {};
+    if (type === 'e2ee.error') {
+      this.logger.error(e.data.message);
+      return;
+    }
+    const event = type as keyof E2EEEventMap;
+    this.logger.debug('Dispatching', event, payload);
+
+    this.emit(event, payload as never);
+  };
+
+  private handleWorkerError = (e: ErrorEvent) => {
+    this.logger.error('Unhandled worker error:', e.message);
+  };
+
+  private validateKeyLength = (rawKey: ArrayBuffer) => {
+    const is256 = this.algorithm === 'AES-256-GCM';
+    const expected = is256 ? 32 : 16;
+    if (rawKey.byteLength !== expected) {
+      throw new Error(
+        `Key must be exactly ${expected} bytes (${is256 ? 'AES-256' : 'AES-128'})`,
+      );
+    }
+  };
+
+  /**
+   * One trailer byte carries the keyIndex. A larger value would truncate to
+   * `keyIndex & 0xFF`, so the receiver would look up the wrong key and fail
+   * every decrypt. Reject it rather than ship a silently broken key epoch.
+   */
+  private validateKeyIndex = (keyIndex: number) => {
+    if (!Number.isInteger(keyIndex) || keyIndex < 0 || keyIndex > 255) {
+      throw new Error(
+        `keyIndex must be an integer between 0 and 255, got ${keyIndex}`,
+      );
+    }
+  };
+}