@stream-io/video-client 1.57.0 → 1.58.0

package/src/gen/video/sfu/models/models.ts

@@ -40,6 +40,14 @@ export interface CallState {
    * @generated from protobuf field: repeated stream.video.sfu.models.Pin pins = 4;
    */
   pins: Pin[];
+  /**
+   * e2ee_enabled is true when the call uses end-to-end encryption. Clients
+   * must enable their frame encryptor; the SFU forwards encrypted frames
+   * opaquely and server-side recording/transcription/broadcasting are disabled.
+   *
+   * @generated from protobuf field: bool e2ee_enabled = 5 [json_name = "e2eeEnabled"];
+   */
+  e2EeEnabled: boolean;
 }
 /**
  * @generated from protobuf message stream.video.sfu.models.ParticipantCount
@@ -1401,6 +1409,13 @@ class CallState$Type extends MessageType<CallState> {
         repeat: 2 /*RepeatType.UNPACKED*/,
         T: () => Pin,
       },
+      {
+        no: 5,
+        name: 'e2ee_enabled',
+        kind: 'scalar',
+        jsonName: 'e2eeEnabled',
+        T: 8 /*ScalarType.BOOL*/,
+      },
     ]);
   }
 }

package/src/helpers/TypedEventEmitter.ts

@@ -0,0 +1,71 @@
+import { ScopedLogger, videoLoggerSystem } from '../logger';
+
+export type EventMap = Record<string, unknown>;
+
+export type Listener<P> = (payload: P) => void | Promise<void>;
+
+/**
+ * Tiny, type-safe event emitter.
+ *
+ * Usage styles:
+ * - compose: `private readonly events = new TypedEventEmitter<MyMap>()`
+ * - extend:  `class Foo extends TypedEventEmitter<MyMap> {}`
+ *
+ * Listener exceptions (sync throw or rejected promise) are caught and logged,
+ * so one bad listener cannot break dispatch for the rest.
+ */
+export class TypedEventEmitter<M extends EventMap> {
+  protected readonly logger: ScopedLogger;
+  private readonly byEvent = new Map<keyof M, Set<Listener<any>>>();
+
+  constructor(logger: ScopedLogger | string = 'TypedEventEmitter') {
+    this.logger =
+      typeof logger === 'string' ? videoLoggerSystem.getLogger(logger) : logger;
+  }
+
+  on = <E extends keyof M>(event: E, fn: Listener<M[E]>): (() => void) => {
+    let listeners = this.byEvent.get(event);
+    if (!listeners) {
+      listeners = new Set();
+      this.byEvent.set(event, listeners);
+    }
+    listeners.add(fn as Listener<any>);
+    return () => this.off(event, fn);
+  };
+
+  off = <E extends keyof M>(event: E, fn: Listener<M[E]>): void => {
+    const listeners = this.byEvent.get(event);
+    if (!listeners) return;
+    listeners.delete(fn as Listener<any>);
+    if (listeners.size === 0) this.byEvent.delete(event);
+  };
+
+  emit = <E extends keyof M>(event: E, payload: M[E]): void => {
+    const listeners = this.byEvent.get(event);
+    if (!listeners || listeners.size === 0) return;
+    for (const listener of [...listeners]) {
+      this.invoke(() => listener(payload), event);
+    }
+  };
+
+  removeAllListeners = (event?: keyof M): void => {
+    if (event === undefined) {
+      this.byEvent.clear();
+    } else {
+      this.byEvent.delete(event);
+    }
+  };
+
+  private invoke = (run: () => void | Promise<void>, event: keyof M): void => {
+    try {
+      const result = run();
+      if (result && typeof (result as Promise<void>).then === 'function') {
+        (result as Promise<void>).catch((err) => {
+          this.logger.warn(`Listener for '${String(event)}' rejected`, err);
+        });
+      }
+    } catch (err) {
+      this.logger.warn(`Listener for '${String(event)}' threw`, err);
+    }
+  };
+}

package/src/helpers/__tests__/TypedEventEmitter.test.ts

@@ -0,0 +1,133 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { TypedEventEmitter } from '../TypedEventEmitter';
+
+type TestEvents = {
+  hello: string;
+  ping: { n: number };
+  empty: undefined;
+};
+
+describe('TypedEventEmitter', () => {
+  let emitter: TypedEventEmitter<TestEvents>;
+
+  beforeEach(() => {
+    emitter = new TypedEventEmitter<TestEvents>();
+  });
+
+  it('invokes listeners registered with on()', () => {
+    const listener = vi.fn();
+    emitter.on('hello', listener);
+    emitter.emit('hello', 'world');
+    expect(listener).toHaveBeenCalledWith('world');
+  });
+
+  it('returns an unsubscribe function from on()', () => {
+    const listener = vi.fn();
+    const unsubscribe = emitter.on('hello', listener);
+    unsubscribe();
+    emitter.emit('hello', 'world');
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('removes listeners via off()', () => {
+    const listener = vi.fn();
+    emitter.on('hello', listener);
+    emitter.off('hello', listener);
+    emitter.emit('hello', 'world');
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('supports multiple listeners for the same event', () => {
+    const a = vi.fn();
+    const b = vi.fn();
+    emitter.on('ping', a);
+    emitter.on('ping', b);
+    emitter.emit('ping', { n: 1 });
+    expect(a).toHaveBeenCalledWith({ n: 1 });
+    expect(b).toHaveBeenCalledWith({ n: 1 });
+  });
+
+  it('deduplicates identical listener references', () => {
+    const listener = vi.fn();
+    emitter.on('hello', listener);
+    emitter.on('hello', listener);
+    emitter.emit('hello', 'once');
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('isolates a throwing listener from subsequent listeners', () => {
+    const bad = vi.fn(() => {
+      throw new Error('boom');
+    });
+    const good = vi.fn();
+    emitter.on('hello', bad);
+    emitter.on('hello', good);
+    expect(() => emitter.emit('hello', 'world')).not.toThrow();
+    expect(bad).toHaveBeenCalled();
+    expect(good).toHaveBeenCalledWith('world');
+  });
+
+  it('isolates a rejecting async listener', async () => {
+    const rejected = vi.fn(async () => {
+      throw new Error('async boom');
+    });
+    const good = vi.fn();
+    emitter.on('hello', rejected);
+    emitter.on('hello', good);
+    expect(() => emitter.emit('hello', 'world')).not.toThrow();
+    expect(good).toHaveBeenCalled();
+    // allow microtask to settle; rejection should have been swallowed by the emitter
+    await Promise.resolve();
+  });
+
+  it('is safe to call off() from within a listener (current emit still fires siblings)', () => {
+    const sibling = vi.fn();
+    const self = vi.fn(() => {
+      emitter.off('hello', self);
+    });
+    emitter.on('hello', self);
+    emitter.on('hello', sibling);
+    emitter.emit('hello', 'world');
+    expect(self).toHaveBeenCalledTimes(1);
+    expect(sibling).toHaveBeenCalledTimes(1);
+    // second emit should not invoke self again
+    emitter.emit('hello', 'again');
+    expect(self).toHaveBeenCalledTimes(1);
+    expect(sibling).toHaveBeenCalledTimes(2);
+  });
+
+  it('is safe to add a listener from within a listener (added listener does not fire in current emit)', () => {
+    const later = vi.fn();
+    emitter.on('hello', () => {
+      emitter.on('hello', later);
+    });
+    emitter.emit('hello', 'first');
+    expect(later).not.toHaveBeenCalled();
+    emitter.emit('hello', 'second');
+    expect(later).toHaveBeenCalledWith('second');
+  });
+
+  it('removeAllListeners() clears every subscription when called without args', () => {
+    const a = vi.fn();
+    const b = vi.fn();
+    emitter.on('hello', a);
+    emitter.on('ping', b);
+    emitter.removeAllListeners();
+    emitter.emit('hello', 'world');
+    emitter.emit('ping', { n: 1 });
+    expect(a).not.toHaveBeenCalled();
+    expect(b).not.toHaveBeenCalled();
+  });
+
+  it('removeAllListeners(event) clears only that event', () => {
+    const a = vi.fn();
+    const b = vi.fn();
+    emitter.on('hello', a);
+    emitter.on('ping', b);
+    emitter.removeAllListeners('hello');
+    emitter.emit('hello', 'world');
+    emitter.emit('ping', { n: 1 });
+    expect(a).not.toHaveBeenCalled();
+    expect(b).toHaveBeenCalledWith({ n: 1 });
+  });
+});

package/src/helpers/ensureExhausted.ts

@@ -1,5 +1,7 @@
 import { videoLoggerSystem } from '../logger';
 
-export const ensureExhausted = (x: never, message: string) => {
-  videoLoggerSystem.getLogger('helpers').warn(message, x);
+export const ensureExhausted = (x: never, message?: string) => {
+  if (message) {
+    videoLoggerSystem.getLogger('helpers').warn(message, x);
+  }
 };

package/src/permissions/PermissionsContext.ts

@@ -1,4 +1,8 @@
-import { CallSettingsResponse, OwnCapability } from '../gen/coordinator';
+import {
+  CallSettingsResponse,
+  OwnCapability,
+  RequestPermissionRequestPermissionsEnum,
+} from '../gen/coordinator';
 import { TrackType } from '../gen/video/sfu/models/models';
 import { ensureExhausted } from '../helpers/ensureExhausted';
 
@@ -70,20 +74,21 @@ export class PermissionsContext {
    * @param settings the call settings to check against (optional).
    */
   canRequest = (
-    permission: OwnCapability,
+    permission: RequestPermissionRequestPermissionsEnum,
     settings: CallSettingsResponse | undefined = this.settings,
   ) => {
     if (!settings) return false;
 
     const { audio, video, screensharing } = settings;
     switch (permission) {
-      case OwnCapability.SEND_AUDIO:
+      case RequestPermissionRequestPermissionsEnum.SEND_AUDIO:
         return audio.access_request_enabled;
-      case OwnCapability.SEND_VIDEO:
+      case RequestPermissionRequestPermissionsEnum.SEND_VIDEO:
         return video.access_request_enabled;
-      case OwnCapability.SCREENSHARE:
+      case RequestPermissionRequestPermissionsEnum.SCREENSHARE:
         return screensharing.access_request_enabled;
       default:
+        ensureExhausted(permission);
         return false;
     }
   };

package/src/rtc/BasePeerConnection.ts

@@ -8,6 +8,8 @@ import {
   TrackType,
   WebsocketReconnectStrategy,
 } from '../gen/video/sfu/models/models';
+import type { E2EEManager } from './e2ee/E2EEManager';
+import { hasInsertableStreams } from './e2ee/transformSupport';
 import { NegotiationError } from './NegotiationError';
 import { StreamSfuClient } from '../StreamSfuClient';
 import { AllSfuEvents, Dispatcher } from './Dispatcher';
@@ -35,6 +37,7 @@ export abstract class BasePeerConnection {
   protected readonly state: CallState;
   protected readonly dispatcher: Dispatcher;
   protected readonly clientPublishOptions?: ClientPublishOptions;
+  protected readonly e2ee?: E2EEManager;
   protected tag: string;
   protected sfuClient: StreamSfuClient;
 
@@ -75,6 +78,7 @@ export abstract class BasePeerConnection {
       tag,
       enableTracing,
       clientPublishOptions,
+      e2ee,
       iceRestartDelay = 2500,
       statsTimestampDriftThresholdMs = 0,
     }: BasePeerConnectionOpts,
@@ -85,6 +89,7 @@ export abstract class BasePeerConnection {
     this.dispatcher = dispatcher;
     this.iceRestartDelay = iceRestartDelay;
     this.clientPublishOptions = clientPublishOptions;
+    this.e2ee = e2ee;
     this.tag = tag;
     this.onReconnectionNeeded = onReconnectionNeeded;
     this.onIceConnected = onIceConnected;
@@ -114,7 +119,13 @@ export abstract class BasePeerConnection {
   }
 
   private createPeerConnection = (connectionConfig?: RTCConfiguration) => {
-    const pc = new RTCPeerConnection(connectionConfig);
+    const config: RTCConfiguration = { ...connectionConfig };
+    // The legacy Insertable Streams path requires this non-standard flag.
+    if (this.e2ee && hasInsertableStreams()) {
+      // @ts-expect-error not part of the standard lib yet
+      config.encodedInsertableStreams = true;
+    }
+    const pc = new RTCPeerConnection(config);
     pc.addEventListener('icecandidate', this.onIceCandidate);
     pc.addEventListener('icecandidateerror', this.onIceCandidateError);
     pc.addEventListener(

package/src/rtc/Publisher.ts

@@ -166,6 +166,14 @@ export class Publisher extends BasePeerConnection {
       toRTCDegradationPreference(publishOption.degradationPreference) ??
       'maintain-framerate';
     await transceiver.sender.setParameters(params);
+    if (this.e2ee) {
+      this.e2ee.encrypt(
+        transceiver.sender,
+        publishOption.codec?.name.toLowerCase(),
+        TrackType[publishOption.trackType],
+      );
+      this.logger.debug('E2EE encryptor attached to sender');
+    }
 
     await this.negotiate();
   };

package/src/rtc/Subscriber.ts

@@ -151,8 +151,13 @@ export class Subscriber extends BasePeerConnection {
         trackLookupPrefix: trackId,
         track: primaryStream,
         trackType,
+        receiver: this.e2ee ? e.receiver : undefined,
       });
       return;
+    } else if (this.e2ee) {
+      const { userId } = participantToUpdate;
+      this.e2ee.decrypt(e.receiver, userId, TrackType[trackType]);
+      this.logger.debug('E2EE decryptor attached to receiver', userId);
     }
 
     const streamKindProp = trackTypeToParticipantStreamKey(trackType);

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