livekit-client 1.12.3 → 1.13.1

package/src/e2ee/KeyProvider.ts

@@ -1,8 +1,10 @@
 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 { createKeyMaterialFromString } from './utils';
+import { type KeyProviderCallbacks, KeyProviderEvent } from './events';
+import type { KeyInfo, KeyProviderOptions } from './types';
+import { createKeyMaterialFromBuffer, createKeyMaterialFromString } from './utils';
 
 /**
  * @experimental
@@ -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,16 +65,29 @@ 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
+   * Accepts a passphrase that's used to create the crypto keys.
+   * When passing in a string, PBKDF2 is used.
+   * When passing in an Array buffer of cryptographically random numbers, HKDF is being used. (recommended)
    * @param key
    */
-  async setKey(key: string) {
-    const derivedKey = await createKeyMaterialFromString(key);
+  async setKey(key: string | ArrayBuffer) {
+    const derivedKey =
+      typeof key === 'string'
+        ? await createKeyMaterialFromString(key)
+        : await createKeyMaterialFromBuffer(key);
     this.onSetEncryptionKey(derivedKey);
   }
 }

package/src/e2ee/constants.ts

@@ -42,3 +42,6 @@ export const KEY_PROVIDER_DEFAULTS: KeyProviderOptions = {
   ratchetWindowSize: 8,
   failureTolerance: DECRYPTION_FAILURE_TOLERANCE,
 } as const;
+
+export const MAX_SIF_COUNT = 100;
+export const MAX_SIF_DURATION = 2000;

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,13 +27,21 @@ export interface RTPVideoMapMessage extends BaseMessage {
   kind: 'setRTPMap';
   data: {
     map: Map<number, VideoCodec>;
+    participantIdentity: string;
+  };
+}
+
+export interface SifTrailerMessage extends BaseMessage {
+  kind: 'setSifTrailer';
+  data: {
+    trailer: Uint8Array;
   };
 }
 
 export interface EncodeMessage extends BaseMessage {
   kind: 'decode' | 'encode';
   data: {
-    participantId: string;
+    participantIdentity: string;
     readableStream: ReadableStream;
     writableStream: WritableStream;
     trackId: string;
@@ -45,7 +52,7 @@ export interface EncodeMessage extends BaseMessage {
 export interface RemoveTransformMessage extends BaseMessage {
   kind: 'removeTransform';
   data: {
-    participantId: string;
+    participantIdentity: string;
     trackId: string;
   };
 }
@@ -53,7 +60,7 @@ export interface RemoveTransformMessage extends BaseMessage {
 export interface UpdateCodecMessage extends BaseMessage {
   kind: 'updateCodec';
   data: {
-    participantId: string;
+    participantIdentity: string;
     trackId: string;
     codec: VideoCodec;
   };
@@ -62,7 +69,7 @@ export interface UpdateCodecMessage extends BaseMessage {
 export interface RatchetRequestMessage extends BaseMessage {
   kind: 'ratchetRequest';
   data: {
-    participantId: string | undefined;
+    participantIdentity?: string;
     keyIndex?: number;
   };
 }
@@ -70,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;
   };
@@ -86,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;
   };
 }
@@ -102,7 +115,9 @@ export type E2EEWorkerMessage =
   | RTPVideoMapMessage
   | UpdateCodecMessage
   | RatchetRequestMessage
-  | RatchetMessage;
+  | RatchetMessage
+  | SifTrailerMessage
+  | InitAck;
 
 export type KeySet = { material: CryptoKey; encryptionKey: CryptoKey };
 
@@ -113,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;
 };
 

package/src/e2ee/utils.ts

@@ -56,6 +56,15 @@ export async function createKeyMaterialFromString(password: string) {
   return keyMaterial;
 }
 
+export async function createKeyMaterialFromBuffer(cryptoBuffer: ArrayBuffer) {
+  const keyMaterial = await crypto.subtle.importKey('raw', cryptoBuffer, 'HKDF', false, [
+    'deriveBits',
+    'deriveKey',
+  ]);
+
+  return keyMaterial;
+}
+
 function getAlgoOptions(algorithmName: string, salt: string) {
   const textEncoder = new TextEncoder();
   const encodedSalt = textEncoder.encode(salt);

package/src/e2ee/worker/FrameCryptor.ts

@@ -6,15 +6,13 @@ import { workerLogger } from '../../logger';
 import type { VideoCodec } from '../../room/track/options';
 import { ENCRYPTION_ALGORITHM, IV_LENGTH, UNENCRYPTED_BYTES } from '../constants';
 import { CryptorError, CryptorErrorReason } from '../errors';
-import {
-  CryptorCallbacks,
-  CryptorEvent,
-  DecodeRatchetOptions,
-  KeyProviderOptions,
-  KeySet,
-} from '../types';
+import { CryptorCallbacks, CryptorEvent } from '../events';
+import type { DecodeRatchetOptions, KeyProviderOptions, KeySet } from '../types';
 import { deriveKeys, isVideoFrame } from '../utils';
 import type { ParticipantKeyHandler } from './ParticipantKeyHandler';
+import { SifGuard } from './SifGuard';
+
+export const encryptionEnabledMap: Map<string, boolean> = new Map();
 
 export interface FrameCryptorConstructor {
   new (opts?: unknown): BaseFrameCryptor;
@@ -28,14 +26,14 @@ export interface TransformerInfo {
 }
 
 export class BaseFrameCryptor extends (EventEmitter as new () => TypedEventEmitter<CryptorCallbacks>) {
-  encodeFunction(
+  protected encodeFunction(
     encodedFrame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
     controller: TransformStreamDefaultController,
   ): Promise<any> {
     throw Error('not implemented for subclass');
   }
 
-  decodeFunction(
+  protected decodeFunction(
     encodedFrame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
     controller: TransformStreamDefaultController,
   ): Promise<any> {
@@ -50,7 +48,7 @@ export class BaseFrameCryptor extends (EventEmitter as new () => TypedEventEmitt
 export class FrameCryptor extends BaseFrameCryptor {
   private sendCounts: Map<number, number>;
 
-  private participantId: string | undefined;
+  private participantIdentity: string | undefined;
 
   private trackId: string | undefined;
 
@@ -65,22 +63,24 @@ export class FrameCryptor extends BaseFrameCryptor {
   /**
    * used for detecting server injected unencrypted frames
    */
-  private unencryptedFrameByteTrailer: Uint8Array;
+  private sifTrailer: Uint8Array;
+
+  private sifGuard: SifGuard;
 
   constructor(opts: {
     keys: ParticipantKeyHandler;
-    participantId: string;
+    participantIdentity: string;
     keyProviderOptions: KeyProviderOptions;
-    unencryptedFrameBytes?: Uint8Array;
+    sifTrailer?: Uint8Array;
   }) {
     super();
     this.sendCounts = new Map();
     this.keys = opts.keys;
-    this.participantId = opts.participantId;
+    this.participantIdentity = opts.participantIdentity;
     this.rtpMap = new Map();
     this.keyProviderOptions = opts.keyProviderOptions;
-    this.unencryptedFrameByteTrailer =
-      opts.unencryptedFrameBytes ?? new TextEncoder().encode('LKROCKS');
+    this.sifTrailer = opts.sifTrailer ?? Uint8Array.from([]);
+    this.sifGuard = new SifGuard();
   }
 
   /**
@@ -90,16 +90,25 @@ export class FrameCryptor extends BaseFrameCryptor {
    * @param keys
    */
   setParticipant(id: string, keys: ParticipantKeyHandler) {
-    this.participantId = id;
+    this.participantIdentity = id;
     this.keys = keys;
+    this.sifGuard.reset();
   }
 
   unsetParticipant() {
-    this.participantId = undefined;
+    this.participantIdentity = undefined;
+  }
+
+  isEnabled() {
+    if (this.participantIdentity) {
+      return encryptionEnabledMap.get(this.participantIdentity);
+    } else {
+      return undefined;
+    }
   }
 
-  getParticipantId() {
-    return this.participantId;
+  getParticipantIdentity() {
+    return this.participantIdentity;
   }
 
   getTrackId() {
@@ -130,9 +139,10 @@ export class FrameCryptor extends BaseFrameCryptor {
     codec?: VideoCodec,
   ) {
     if (codec) {
-      console.info('setting codec on cryptor to', codec);
+      workerLogger.info('setting codec on cryptor to', { codec });
       this.videoCodec = codec;
     }
+
     const transformFn = operation === 'encode' ? this.encodeFunction : this.decodeFunction;
     const transformStream = new TransformStream({
       transform: transformFn.bind(this),
@@ -142,12 +152,16 @@ export class FrameCryptor extends BaseFrameCryptor {
       .pipeThrough(transformStream)
       .pipeTo(writable)
       .catch((e) => {
-        console.error(e);
-        this.emit('cryptorError', e instanceof CryptorError ? e : new CryptorError(e.message));
+        workerLogger.warn(e);
+        this.emit(CryptorEvent.Error, e instanceof CryptorError ? e : new CryptorError(e.message));
       });
     this.trackId = trackId;
   }
 
+  setSifTrailer(trailer: Uint8Array) {
+    this.sifTrailer = trailer;
+  }
+
   /**
    * Function that will be injected in a stream and will encrypt the given encoded frames.
    *
@@ -170,19 +184,26 @@ export class FrameCryptor extends BaseFrameCryptor {
    * 8) Append a single byte for the key identifier.
    * 9) Enqueue the encrypted frame for sending.
    */
-  async encodeFunction(
+  protected async encodeFunction(
     encodedFrame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
     controller: TransformStreamDefaultController,
   ) {
     if (
-      !this.keys.isEnabled() ||
+      !this.isEnabled() ||
       // skip for encryption for empty dtx frames
       encodedFrame.data.byteLength === 0
     ) {
       return controller.enqueue(encodedFrame);
     }
-
-    const { encryptionKey } = this.keys.getKeySet();
+    const keySet = this.keys.getKeySet();
+    if (!keySet) {
+      throw new TypeError(
+        `key set not found for ${
+          this.participantIdentity
+        } at index ${this.keys.getCurrentKeyIndex()}`,
+      );
+    }
+    const { encryptionKey } = keySet;
     const keyIndex = this.keys.getCurrentKeyIndex();
 
     if (encryptionKey) {
@@ -253,19 +274,31 @@ export class FrameCryptor extends BaseFrameCryptor {
    * @param {RTCEncodedVideoFrame|RTCEncodedAudioFrame} encodedFrame - Encoded video frame.
    * @param {TransformStreamDefaultController} controller - TransportStreamController.
    */
-  async decodeFunction(
+  protected async decodeFunction(
     encodedFrame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
     controller: TransformStreamDefaultController,
   ) {
     if (
-      !this.keys.isEnabled() ||
+      !this.isEnabled() ||
       // skip for decryption for empty dtx frames
-      encodedFrame.data.byteLength === 0 ||
-      // skip decryption if frame is server injected
-      isFrameServerInjected(encodedFrame.data, this.unencryptedFrameByteTrailer)
+      encodedFrame.data.byteLength === 0
     ) {
+      this.sifGuard.recordUserFrame();
       return controller.enqueue(encodedFrame);
     }
+
+    if (isFrameServerInjected(encodedFrame.data, this.sifTrailer)) {
+      this.sifGuard.recordSif();
+
+      if (this.sifGuard.isSifAllowed()) {
+        return controller.enqueue(encodedFrame);
+      } else {
+        workerLogger.warn('SIF limit reached, dropping frame');
+        return;
+      }
+    } else {
+      this.sifGuard.recordUserFrame();
+    }
     const data = new Uint8Array(encodedFrame.data);
     const keyIndex = data[encodedFrame.data.byteLength - 1];
 
@@ -279,11 +312,10 @@ export class FrameCryptor extends BaseFrameCryptor {
       } catch (error) {
         if (error instanceof CryptorError && error.reason === CryptorErrorReason.InvalidKey) {
           if (this.keys.hasValidKey) {
-            workerLogger.warn('invalid key');
             this.emit(
               CryptorEvent.Error,
               new CryptorError(
-                `invalid key for participant ${this.participantId}`,
+                `invalid key for participant ${this.participantIdentity}`,
                 CryptorErrorReason.InvalidKey,
               ),
             );
@@ -293,22 +325,33 @@ export class FrameCryptor extends BaseFrameCryptor {
           workerLogger.warn('decoding frame failed', { error });
         }
       }
+    } else if (!this.keys.getKeySet(keyIndex) && this.keys.hasValidKey) {
+      // emit an error in case the key index is out of bounds but the key handler thinks we still have a valid key
+      workerLogger.warn('skipping decryption due to missing key at index');
+      this.emit(
+        CryptorEvent.Error,
+        new CryptorError(
+          `missing key at index for participant ${this.participantIdentity}`,
+          CryptorErrorReason.MissingKey,
+        ),
+      );
     }
-
-    return controller.enqueue(encodedFrame);
   }
 
   /**
    * Function that will decrypt the given encoded frame. If the decryption fails, it will
    * ratchet the key for up to RATCHET_WINDOW_SIZE times.
    */
-  async decryptFrame(
+  private async decryptFrame(
     encodedFrame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
     keyIndex: number,
     initialMaterial: KeySet | undefined = undefined,
     ratchetOpts: DecodeRatchetOptions = { ratchetCount: 0 },
   ): Promise<RTCEncodedVideoFrame | RTCEncodedAudioFrame | undefined> {
     const keySet = this.keys.getKeySet(keyIndex);
+    if (!ratchetOpts.encryptionKey && !keySet) {
+      throw new TypeError(`no encryption key found for decryption of ${this.participantIdentity}`);
+    }
 
     // Construct frame trailer. Similar to the frame header described in
     // https://tools.ietf.org/html/draft-omara-sframe-00#section-4.2
@@ -344,7 +387,7 @@ export class FrameCryptor extends BaseFrameCryptor {
           iv,
           additionalData: new Uint8Array(encodedFrame.data, 0, frameHeader.byteLength),
         },
-        ratchetOpts.encryptionKey ?? keySet.encryptionKey,
+        ratchetOpts.encryptionKey ?? keySet!.encryptionKey,
         new Uint8Array(encodedFrame.data, cipherTextStart, cipherTextLength),
       );
 
@@ -397,13 +440,10 @@ export class FrameCryptor extends BaseFrameCryptor {
             this.keys.setKeyFromMaterial(initialMaterial.material, keyIndex);
           }
 
-          workerLogger.warn('maximum ratchet attempts exceeded, resetting key');
-          this.emit(
-            CryptorEvent.Error,
-            new CryptorError(
-              `valid key missing for participant ${this.participantId}`,
-              CryptorErrorReason.MissingKey,
-            ),
+          workerLogger.warn('maximum ratchet attempts exceeded');
+          throw new CryptorError(
+            `valid key missing for participant ${this.participantIdentity}`,
+            CryptorErrorReason.InvalidKey,
           );
         }
       } else {
@@ -455,7 +495,7 @@ export class FrameCryptor extends BaseFrameCryptor {
     return iv;
   }
 
-  getUnencryptedBytes(frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame): number {
+  private getUnencryptedBytes(frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame): number {
     if (isVideoFrame(frame)) {
       let detectedCodec = this.getVideoCodec(frame) ?? this.videoCodec;
 
@@ -504,7 +544,7 @@ export class FrameCryptor extends BaseFrameCryptor {
   /**
    * inspects frame payloadtype if available and maps it to the codec specified in rtpMap
    */
-  getVideoCodec(frame: RTCEncodedVideoFrame): VideoCodec | undefined {
+  private getVideoCodec(frame: RTCEncodedVideoFrame): VideoCodec | undefined {
     if (this.rtpMap.size === 0) {
       return undefined;
     }
@@ -605,6 +645,9 @@ export enum NALUType {
  * @internal
  */
 export function isFrameServerInjected(frameData: ArrayBuffer, trailerBytes: Uint8Array): boolean {
+  if (trailerBytes.byteLength === 0) {
+    return false;
+  }
   const frameTrailer = new Uint8Array(
     frameData.slice(frameData.byteLength - trailerBytes.byteLength),
   );