livekit-client 1.13.0 → 1.13.1

package/src/e2ee/E2eeManager.ts

@@ -13,8 +13,8 @@ import type { Track } from '../room/track/Track';
 import type { VideoCodec } from '../room/track/options';
 import type { BaseKeyProvider } from './KeyProvider';
 import { E2EE_FLAG } from './constants';
+import { type E2EEManagerCallbacks, EncryptionEvent, KeyProviderEvent } from './events';
 import type {
-  E2EEManagerCallbacks,
   E2EEOptions,
   E2EEWorkerMessage,
   EnableMessage,
@@ -28,7 +28,6 @@ import type {
   SifTrailerMessage,
   UpdateCodecMessage,
 } from './types';
-import { EncryptionEvent } from './types';
 import { isE2EESupported, isScriptTransformSupported, mimeTypeToVideoCodecString } from './utils';
 
 /**
@@ -43,10 +42,6 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
 
   private keyProvider: BaseKeyProvider;
 
-  get isEnabled() {
-    return this.encryptionEnabled;
-  }
-
   constructor(options: E2EEOptions) {
     super();
     this.keyProvider = options.keyProvider;
@@ -86,18 +81,9 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
   /**
    * @internal
    */
-  async setParticipantCryptorEnabled(enabled: boolean, participantId?: string) {
-    log.info(`set e2ee to ${enabled}`);
-
-    if (this.worker) {
-      const enableMsg: EnableMessage = {
-        kind: 'enable',
-        data: { enabled, participantId },
-      };
-      this.worker.postMessage(enableMsg);
-    } else {
-      throw new ReferenceError('failed to enable e2ee, worker is not ready');
-    }
+  setParticipantCryptorEnabled(enabled: boolean, participantIdentity: string) {
+    log.debug(`set e2ee to ${enabled} for participant ${participantIdentity}`);
+    this.postEnable(enabled, participantIdentity);
   }
 
   /**
@@ -115,19 +101,35 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
     const { kind, data } = ev.data;
     switch (kind) {
       case 'error':
-        console.error('error in worker', { data });
-        this.emit(EncryptionEvent.Error, data.error);
+        log.error(data.error.message);
+        this.emit(EncryptionEvent.EncryptionError, data.error);
+        break;
+      case 'initAck':
+        if (data.enabled) {
+          this.keyProvider.getKeys().forEach((keyInfo) => {
+            this.postKey(keyInfo);
+          });
+        }
         break;
+
       case 'enable':
-        if (this.encryptionEnabled !== data.enabled && !data.participantId) {
+        if (
+          this.encryptionEnabled !== data.enabled &&
+          data.participantIdentity === this.room?.localParticipant.identity
+        ) {
           this.emit(
             EncryptionEvent.ParticipantEncryptionStatusChanged,
             data.enabled,
-            this.room?.localParticipant,
+            this.room!.localParticipant,
           );
           this.encryptionEnabled = data.enabled;
-        } else if (data.participantId) {
-          const participant = this.room?.getParticipantByIdentity(data.participantId);
+        } else if (data.participantIdentity) {
+          const participant = this.room?.getParticipantByIdentity(data.participantIdentity);
+          if (!participant) {
+            throw TypeError(
+              `couldn't set encryption status, participant not found${data.participantIdentity}`,
+            );
+          }
           this.emit(EncryptionEvent.ParticipantEncryptionStatusChanged, data.enabled, participant);
         }
         if (this.encryptionEnabled) {
@@ -137,7 +139,7 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
         }
         break;
       case 'ratchetKey':
-        this.keyProvider.emit('keyRatcheted', data.material, data.keyIndex);
+        this.keyProvider.emit(KeyProviderEvent.KeyRatcheted, data.material, data.keyIndex);
         break;
       default:
         break;
@@ -146,7 +148,7 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
 
   private onWorkerError = (ev: ErrorEvent) => {
     log.error('e2ee worker encountered an error:', { error: ev.error });
-    this.emit(EncryptionEvent.Error, ev.error);
+    this.emit(EncryptionEvent.EncryptionError, ev.error);
   };
 
   public setupEngine(engine: RTCEngine) {
@@ -162,69 +164,78 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
         participant.identity,
       ),
     );
-    room.on(RoomEvent.ConnectionStateChanged, (state) => {
-      if (state === ConnectionState.Connected) {
-        room.participants.forEach((participant) => {
-          participant.tracks.forEach((pub) => {
-            this.setParticipantCryptorEnabled(
-              pub.trackInfo!.encryption !== Encryption_Type.NONE,
-              participant.identity,
-            );
+    room
+      .on(RoomEvent.ConnectionStateChanged, (state) => {
+        if (state === ConnectionState.Connected) {
+          room.participants.forEach((participant) => {
+            participant.tracks.forEach((pub) => {
+              this.setParticipantCryptorEnabled(
+                pub.trackInfo!.encryption !== Encryption_Type.NONE,
+                participant.identity,
+              );
+            });
           });
+        }
+      })
+      .on(RoomEvent.TrackUnsubscribed, (track, _, participant) => {
+        const msg: RemoveTransformMessage = {
+          kind: 'removeTransform',
+          data: {
+            participantIdentity: participant.identity,
+            trackId: track.mediaStreamID,
+          },
+        };
+        this.worker?.postMessage(msg);
+      })
+      .on(RoomEvent.TrackSubscribed, (track, pub, participant) => {
+        this.setupE2EEReceiver(track, participant.identity, pub.trackInfo);
+      })
+      .on(RoomEvent.SignalConnected, () => {
+        if (!this.room) {
+          throw new TypeError(`expected room to be present on signal connect`);
+        }
+        this.setParticipantCryptorEnabled(
+          this.room.localParticipant.isE2EEEnabled,
+          this.room.localParticipant.identity,
+        );
+        keyProvider.getKeys().forEach((keyInfo) => {
+          this.postKey(keyInfo);
         });
-      }
-    });
-
-    room.on(RoomEvent.TrackUnsubscribed, (track, _, participant) => {
-      const msg: RemoveTransformMessage = {
-        kind: 'removeTransform',
-        data: {
-          participantId: participant.identity,
-          trackId: track.mediaStreamID,
-        },
-      };
-      this.worker?.postMessage(msg);
-    });
-    room.on(RoomEvent.TrackSubscribed, (track, pub, participant) => {
-      this.setupE2EEReceiver(track, participant.identity, pub.trackInfo);
-    });
+      });
     room.localParticipant.on(ParticipantEvent.LocalTrackPublished, async (publication) => {
-      this.setupE2EESender(
-        publication.track!,
-        publication.track!.sender!,
-        room.localParticipant.identity,
-      );
+      this.setupE2EESender(publication.track!, publication.track!.sender!);
     });
 
     keyProvider
-      .on('setKey', (keyInfo) => this.postKey(keyInfo))
-      .on('ratchetRequest', (participantId, keyIndex) =>
+      .on(KeyProviderEvent.SetKey, (keyInfo) => this.postKey(keyInfo))
+      .on(KeyProviderEvent.RatchetRequest, (participantId, keyIndex) =>
         this.postRatchetRequest(participantId, keyIndex),
       );
   }
 
-  private postRatchetRequest(participantId?: string, keyIndex?: number) {
+  private postRatchetRequest(participantIdentity?: string, keyIndex?: number) {
     if (!this.worker) {
       throw Error('could not ratchet key, worker is missing');
     }
     const msg: RatchetRequestMessage = {
       kind: 'ratchetRequest',
       data: {
-        participantId,
+        participantIdentity: participantIdentity,
         keyIndex,
       },
     };
     this.worker.postMessage(msg);
   }
 
-  private postKey({ key, participantId, keyIndex }: KeyInfo) {
+  private postKey({ key, participantIdentity, keyIndex }: KeyInfo) {
     if (!this.worker) {
       throw Error('could not set key, worker is missing');
     }
     const msg: SetKeyMessage = {
       kind: 'setKey',
       data: {
-        participantId,
+        participantIdentity: participantIdentity,
+        isPublisher: participantIdentity === this.room?.localParticipant.identity,
         key,
         keyIndex,
       },
@@ -232,14 +243,33 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
     this.worker.postMessage(msg);
   }
 
+  private postEnable(enabled: boolean, participantIdentity: string) {
+    if (this.worker) {
+      const enableMsg: EnableMessage = {
+        kind: 'enable',
+        data: {
+          enabled,
+          participantIdentity,
+        },
+      };
+      this.worker.postMessage(enableMsg);
+    } else {
+      throw new ReferenceError('failed to enable e2ee, worker is not ready');
+    }
+  }
+
   private postRTPMap(map: Map<number, VideoCodec>) {
     if (!this.worker) {
-      throw Error('could not post rtp map, worker is missing');
+      throw TypeError('could not post rtp map, worker is missing');
+    }
+    if (!this.room?.localParticipant.identity) {
+      throw TypeError('could not post rtp map, local participant identity is missing');
     }
     const msg: RTPVideoMapMessage = {
       kind: 'setRTPMap',
       data: {
         map,
+        participantIdentity: this.room.localParticipant.identity,
       },
     };
     this.worker.postMessage(msg);
@@ -273,12 +303,12 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
     );
   }
 
-  private setupE2EESender(track: Track, sender: RTCRtpSender, localId: string) {
+  private setupE2EESender(track: Track, sender: RTCRtpSender) {
     if (!(track instanceof LocalTrack) || !sender) {
       if (!sender) log.warn('early return because sender is not ready');
       return;
     }
-    this.handleSender(sender, track.mediaStreamID, localId, undefined);
+    this.handleSender(sender, track.mediaStreamID, undefined);
   }
 
   /**
@@ -289,7 +319,7 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
   private async handleReceiver(
     receiver: RTCRtpReceiver,
     trackId: string,
-    participantId: string,
+    participantIdentity: string,
     codec?: VideoCodec,
   ) {
     if (!this.worker) {
@@ -299,7 +329,7 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
     if (isScriptTransformSupported()) {
       const options = {
         kind: 'decode',
-        participantId,
+        participantIdentity,
         trackId,
         codec,
       };
@@ -313,7 +343,7 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
           data: {
             trackId,
             codec,
-            participantId,
+            participantIdentity: participantIdentity,
           },
         };
         this.worker.postMessage(msg);
@@ -341,7 +371,7 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
           writableStream: writable,
           trackId: trackId,
           codec,
-          participantId,
+          participantIdentity: participantIdentity,
         },
       };
       this.worker.postMessage(msg, [readable, writable]);
@@ -356,22 +386,20 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
    * a frame encoder.
    *
    */
-  private handleSender(
-    sender: RTCRtpSender,
-    trackId: string,
-    participantId: string,
-    codec?: VideoCodec,
-  ) {
+  private handleSender(sender: RTCRtpSender, trackId: string, codec?: VideoCodec) {
     if (E2EE_FLAG in sender || !this.worker) {
       return;
     }
 
+    if (!this.room?.localParticipant.identity || this.room.localParticipant.identity === '') {
+      throw TypeError('local identity needs to be known in order to set up encrypted sender');
+    }
+
     if (isScriptTransformSupported()) {
       log.info('initialize script transform');
-
       const options = {
         kind: 'encode',
-        participantId,
+        participantIdentity: this.room.localParticipant.identity,
         trackId,
         codec,
       };
@@ -388,7 +416,7 @@ export class E2EEManager extends (EventEmitter as new () => TypedEventEmitter<E2
           writableStream: senderStreams.writable,
           codec,
           trackId,
-          participantId,
+          participantIdentity: this.room.localParticipant.identity,
         },
       };
       this.worker.postMessage(msg, [senderStreams.readable, senderStreams.writable]);

package/src/e2ee/KeyProvider.ts

@@ -1,7 +1,9 @@
 import { EventEmitter } from 'events';
 import type TypedEventEmitter from 'typed-emitter';
+import log from '../logger';
 import { KEY_PROVIDER_DEFAULTS } from './constants';
-import type { KeyInfo, KeyProviderCallbacks, KeyProviderOptions } from './types';
+import { type KeyProviderCallbacks, KeyProviderEvent } from './events';
+import type { KeyInfo, KeyProviderOptions } from './types';
 import { createKeyMaterialFromBuffer, createKeyMaterialFromString } from './utils';
 
 /**
@@ -16,29 +18,29 @@ export class BaseKeyProvider extends (EventEmitter as new () => TypedEventEmitte
     super();
     this.keyInfoMap = new Map();
     this.options = { ...KEY_PROVIDER_DEFAULTS, ...options };
-    this.on('keyRatcheted', this.onKeyRatcheted);
+    this.on(KeyProviderEvent.KeyRatcheted, this.onKeyRatcheted);
   }
 
   /**
    * callback to invoke once a key has been set for a participant
    * @param key
-   * @param participantId
+   * @param participantIdentity
    * @param keyIndex
    */
-  protected onSetEncryptionKey(key: CryptoKey, participantId?: string, keyIndex?: number) {
-    const keyInfo: KeyInfo = { key, participantId, keyIndex };
-    this.keyInfoMap.set(`${participantId ?? 'shared'}-${keyIndex ?? 0}`, keyInfo);
-    this.emit('setKey', keyInfo);
+  protected onSetEncryptionKey(key: CryptoKey, participantIdentity?: string, keyIndex?: number) {
+    const keyInfo: KeyInfo = { key, participantIdentity, keyIndex };
+    this.keyInfoMap.set(`${participantIdentity ?? 'shared'}-${keyIndex ?? 0}`, keyInfo);
+    this.emit(KeyProviderEvent.SetKey, keyInfo);
   }
 
   /**
-   * callback being invoked after a ratchet request has been performed on the local participant
+   * callback being invoked after a ratchet request has been performed on a participant
    * that surfaces the new key material.
    * @param material
    * @param keyIndex
    */
   protected onKeyRatcheted = (material: CryptoKey, keyIndex?: number) => {
-    console.debug('key ratcheted event received', material, keyIndex);
+    log.debug('key ratcheted event received', { material, keyIndex });
   };
 
   getKeys() {
@@ -49,8 +51,8 @@ export class BaseKeyProvider extends (EventEmitter as new () => TypedEventEmitte
     return this.options;
   }
 
-  ratchetKey(participantId?: string, keyIndex?: number) {
-    this.emit('ratchetRequest', participantId, keyIndex);
+  ratchetKey(participantIdentity?: string, keyIndex?: number) {
+    this.emit(KeyProviderEvent.RatchetRequest, participantIdentity, keyIndex);
   }
 }
 
@@ -63,14 +65,22 @@ export class ExternalE2EEKeyProvider extends BaseKeyProvider {
   ratchetInterval: number | undefined;
 
   constructor(options: Partial<Omit<KeyProviderOptions, 'sharedKey'>> = {}) {
-    const opts: Partial<KeyProviderOptions> = { ...options, sharedKey: true };
+    const opts: Partial<KeyProviderOptions> = {
+      ...options,
+      sharedKey: true,
+      // for a shared key provider failing to decrypt for a specific participant
+      // should not mark the key as invalid, so we accept wrong keys forever
+      // and won't try to auto-ratchet
+      ratchetWindowSize: 0,
+      failureTolerance: -1,
+    };
     super(opts);
   }
 
   /**
    * Accepts a passphrase that's used to create the crypto keys.
    * When passing in a string, PBKDF2 is used.
-   * Also accepts an Array buffer of cryptographically random numbers that uses HKDF.
+   * When passing in an Array buffer of cryptographically random numbers, HKDF is being used. (recommended)
    * @param key
    */
   async setKey(key: string | ArrayBuffer) {

package/src/e2ee/events.ts

@@ -0,0 +1,48 @@
+import type Participant from '../room/participant/Participant';
+import type { CryptorError } from './errors';
+import type { KeyInfo } from './types';
+
+export enum KeyProviderEvent {
+  SetKey = 'setKey',
+  RatchetRequest = 'ratchetRequest',
+  KeyRatcheted = 'keyRatcheted',
+}
+
+export type KeyProviderCallbacks = {
+  [KeyProviderEvent.SetKey]: (keyInfo: KeyInfo) => void;
+  [KeyProviderEvent.RatchetRequest]: (participantIdentity?: string, keyIndex?: number) => void;
+  [KeyProviderEvent.KeyRatcheted]: (material: CryptoKey, keyIndex?: number) => void;
+};
+
+export enum KeyHandlerEvent {
+  KeyRatcheted = 'keyRatcheted',
+}
+
+export type ParticipantKeyHandlerCallbacks = {
+  [KeyHandlerEvent.KeyRatcheted]: (
+    material: CryptoKey,
+    participantIdentity: string,
+    keyIndex?: number,
+  ) => void;
+};
+
+export enum EncryptionEvent {
+  ParticipantEncryptionStatusChanged = 'participantEncryptionStatusChanged',
+  EncryptionError = 'encryptionError',
+}
+
+export type E2EEManagerCallbacks = {
+  [EncryptionEvent.ParticipantEncryptionStatusChanged]: (
+    enabled: boolean,
+    participant: Participant,
+  ) => void;
+  [EncryptionEvent.EncryptionError]: (error: Error) => void;
+};
+
+export type CryptorCallbacks = {
+  [CryptorEvent.Error]: (error: CryptorError) => void;
+};
+
+export enum CryptorEvent {
+  Error = 'cryptorError',
+}

package/src/e2ee/index.ts

@@ -1,3 +1,4 @@
 export * from './KeyProvider';
 export * from './utils';
 export * from './types';
+export * from './events';

package/src/e2ee/types.ts

@@ -1,7 +1,5 @@
-import type Participant from '../room/participant/Participant';
 import type { VideoCodec } from '../room/track/options';
 import type { BaseKeyProvider } from './KeyProvider';
-import type { CryptorError } from './errors';
 
 export interface BaseMessage {
   kind: string;
@@ -18,7 +16,8 @@ export interface InitMessage extends BaseMessage {
 export interface SetKeyMessage extends BaseMessage {
   kind: 'setKey';
   data: {
-    participantId?: string;
+    participantIdentity?: string;
+    isPublisher: boolean;
     key: CryptoKey;
     keyIndex?: number;
   };
@@ -28,6 +27,7 @@ export interface RTPVideoMapMessage extends BaseMessage {
   kind: 'setRTPMap';
   data: {
     map: Map<number, VideoCodec>;
+    participantIdentity: string;
   };
 }
 
@@ -41,7 +41,7 @@ export interface SifTrailerMessage extends BaseMessage {
 export interface EncodeMessage extends BaseMessage {
   kind: 'decode' | 'encode';
   data: {
-    participantId: string;
+    participantIdentity: string;
     readableStream: ReadableStream;
     writableStream: WritableStream;
     trackId: string;
@@ -52,7 +52,7 @@ export interface EncodeMessage extends BaseMessage {
 export interface RemoveTransformMessage extends BaseMessage {
   kind: 'removeTransform';
   data: {
-    participantId: string;
+    participantIdentity: string;
     trackId: string;
   };
 }
@@ -60,7 +60,7 @@ export interface RemoveTransformMessage extends BaseMessage {
 export interface UpdateCodecMessage extends BaseMessage {
   kind: 'updateCodec';
   data: {
-    participantId: string;
+    participantIdentity: string;
     trackId: string;
     codec: VideoCodec;
   };
@@ -69,7 +69,7 @@ export interface UpdateCodecMessage extends BaseMessage {
 export interface RatchetRequestMessage extends BaseMessage {
   kind: 'ratchetRequest';
   data: {
-    participantId: string | undefined;
+    participantIdentity?: string;
     keyIndex?: number;
   };
 }
@@ -77,7 +77,7 @@ export interface RatchetRequestMessage extends BaseMessage {
 export interface RatchetMessage extends BaseMessage {
   kind: 'ratchetKey';
   data: {
-    // participantId: string | undefined;
+    participantIdentity: string;
     keyIndex?: number;
     material: CryptoKey;
   };
@@ -93,8 +93,14 @@ export interface ErrorMessage extends BaseMessage {
 export interface EnableMessage extends BaseMessage {
   kind: 'enable';
   data: {
-    // if no participant id is set it indicates publisher encryption enable/disable
-    participantId?: string;
+    participantIdentity: string;
+    enabled: boolean;
+  };
+}
+
+export interface InitAck extends BaseMessage {
+  kind: 'initAck';
+  data: {
     enabled: boolean;
   };
 }
@@ -110,7 +116,8 @@ export type E2EEWorkerMessage =
   | UpdateCodecMessage
   | RatchetRequestMessage
   | RatchetMessage
-  | SifTrailerMessage;
+  | SifTrailerMessage
+  | InitAck;
 
 export type KeySet = { material: CryptoKey; encryptionKey: CryptoKey };
 
@@ -121,38 +128,9 @@ export type KeyProviderOptions = {
   failureTolerance: number;
 };
 
-export type KeyProviderCallbacks = {
-  setKey: (keyInfo: KeyInfo) => void;
-  ratchetRequest: (participantId?: string, keyIndex?: number) => void;
-  /** currently only emitted for local participant */
-  keyRatcheted: (material: CryptoKey, keyIndex?: number) => void;
-};
-
-export type ParticipantKeyHandlerCallbacks = {
-  keyRatcheted: (material: CryptoKey, keyIndex?: number, participantId?: string) => void;
-};
-
-export type E2EEManagerCallbacks = {
-  participantEncryptionStatusChanged: (enabled: boolean, participant?: Participant) => void;
-  encryptionError: (error: Error) => void;
-};
-
-export const EncryptionEvent = {
-  ParticipantEncryptionStatusChanged: 'participantEncryptionStatusChanged',
-  Error: 'encryptionError',
-} as const;
-
-export type CryptorCallbacks = {
-  cryptorError: (error: CryptorError) => void;
-};
-
-export const CryptorEvent = {
-  Error: 'cryptorError',
-} as const;
-
 export type KeyInfo = {
   key: CryptoKey;
-  participantId?: string;
+  participantIdentity?: string;
   keyIndex?: number;
 };