livekit-client 2.11.4 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.11.4",
+  "version": "2.12.0",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",
@@ -37,7 +37,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@livekit/mutex": "1.1.1",
-    "@livekit/protocol": "1.36.1",
+    "@livekit/protocol": "1.38.0",
     "events": "^3.3.0",
     "loglevel": "^1.9.2",
     "sdp-transform": "^2.15.0",

package/src/api/SignalClient.ts

@@ -15,6 +15,7 @@ import {
   ReconnectResponse,
   RequestResponse,
   Room,
+  RoomMovedResponse,
   SessionDescription,
   SignalRequest,
   SignalResponse,
@@ -148,6 +149,8 @@ export class SignalClient {
 
   onLocalTrackSubscribed?: (trackSid: string) => void;
 
+  onRoomMoved?: (res: RoomMovedResponse) => void;
+
   connectOptions?: ConnectOpts;
 
   ws?: WebSocket;
@@ -774,6 +777,13 @@ export class SignalClient {
       if (this.onLocalTrackSubscribed) {
         this.onLocalTrackSubscribed(msg.value.trackSid);
       }
+    } else if (msg.case === 'roomMoved') {
+      if (this.onTokenRefresh) {
+        this.onTokenRefresh(msg.value.token);
+      }
+      if (this.onRoomMoved) {
+        this.onRoomMoved(msg.value);
+      }
     } else {
       this.log.debug('unsupported message', { ...this.logContext, msgCase: msg.case });
     }

package/src/e2ee/E2eeManager.ts

@@ -152,7 +152,12 @@ export class E2EEManager
         }
         break;
       case 'ratchetKey':
-        this.keyProvider.emit(KeyProviderEvent.KeyRatcheted, data.material, data.keyIndex);
+        this.keyProvider.emit(
+          KeyProviderEvent.KeyRatcheted,
+          data.ratchetResult,
+          data.participantIdentity,
+          data.keyIndex,
+        );
         break;
       default:
         break;

package/src/e2ee/KeyProvider.ts

@@ -3,7 +3,7 @@ import type TypedEventEmitter from 'typed-emitter';
 import log from '../logger';
 import { KEY_PROVIDER_DEFAULTS } from './constants';
 import { type KeyProviderCallbacks, KeyProviderEvent } from './events';
-import type { KeyInfo, KeyProviderOptions } from './types';
+import type { KeyInfo, KeyProviderOptions, RatchetResult } from './types';
 import { createKeyMaterialFromBuffer, createKeyMaterialFromString } from './utils';
 
 /**
@@ -39,13 +39,20 @@ export class BaseKeyProvider extends (EventEmitter as new () => TypedEventEmitte
   }
 
   /**
-   * callback being invoked after a ratchet request has been performed on a participant
-   * that surfaces the new key material.
-   * @param material
+   * Callback being invoked after a key has been ratcheted.
+   * Can happen when:
+   * - A decryption failure occurs and the key is auto-ratcheted
+   * - A ratchet request is sent (see {@link ratchetKey()})
+   * @param ratchetResult Contains the ratcheted chain key (exportable to other participants) and the derived new key material.
+   * @param participantId
    * @param keyIndex
    */
-  protected onKeyRatcheted = (material: CryptoKey, keyIndex?: number) => {
-    log.debug('key ratcheted event received', { material, keyIndex });
+  protected onKeyRatcheted = (
+    ratchetResult: RatchetResult,
+    participantId?: string,
+    keyIndex?: number,
+  ) => {
+    log.debug('key ratcheted event received', { ratchetResult, participantId, keyIndex });
   };
 
   getKeys() {

package/src/e2ee/events.ts

@@ -1,26 +1,35 @@
 import type Participant from '../room/participant/Participant';
 import type { CryptorError } from './errors';
-import type { KeyInfo } from './types';
+import type { KeyInfo, RatchetResult } from './types';
 
 export enum KeyProviderEvent {
   SetKey = 'setKey',
+  /** Event for requesting to ratchet the key used to encrypt the stream */
   RatchetRequest = 'ratchetRequest',
+  /** Emitted when a key is ratcheted. Could be after auto-ratcheting on decryption failure or
+   *  following a `RatchetRequest`, will contain the ratcheted key material */
   KeyRatcheted = 'keyRatcheted',
 }
 
 export type KeyProviderCallbacks = {
   [KeyProviderEvent.SetKey]: (keyInfo: KeyInfo) => void;
   [KeyProviderEvent.RatchetRequest]: (participantIdentity?: string, keyIndex?: number) => void;
-  [KeyProviderEvent.KeyRatcheted]: (material: CryptoKey, keyIndex?: number) => void;
+  [KeyProviderEvent.KeyRatcheted]: (
+    ratchetedResult: RatchetResult,
+    participantIdentity?: string,
+    keyIndex?: number,
+  ) => void;
 };
 
 export enum KeyHandlerEvent {
+  /** Emitted when a key has been ratcheted. Is emitted when any key has been ratcheted
+   * i.e. when the FrameCryptor tried to ratchet when decryption is failing  */
   KeyRatcheted = 'keyRatcheted',
 }
 
 export type ParticipantKeyHandlerCallbacks = {
   [KeyHandlerEvent.KeyRatcheted]: (
-    material: CryptoKey,
+    ratchetResult: RatchetResult,
     participantIdentity: string,
     keyIndex?: number,
   ) => void;

package/src/e2ee/types.ts

@@ -82,7 +82,7 @@ export interface RatchetMessage extends BaseMessage {
   data: {
     participantIdentity: string;
     keyIndex?: number;
-    material: CryptoKey;
+    ratchetResult: RatchetResult;
   };
 }
 
@@ -124,6 +124,13 @@ export type E2EEWorkerMessage =
 
 export type KeySet = { material: CryptoKey; encryptionKey: CryptoKey };
 
+export type RatchetResult = {
+  // The ratchet chain key, which is used to derive the next key.
+  // Can be shared/exported to other participants.
+  chainKey: ArrayBuffer;
+  cryptoKey: CryptoKey;
+};
+
 export type KeyProviderOptions = {
   sharedKey: boolean;
   ratchetSalt: string;

package/src/e2ee/worker/FrameCryptor.ts

@@ -7,7 +7,7 @@ import type { VideoCodec } from '../../room/track/options';
 import { ENCRYPTION_ALGORITHM, IV_LENGTH, UNENCRYPTED_BYTES } from '../constants';
 import { CryptorError, CryptorErrorReason } from '../errors';
 import { type CryptorCallbacks, CryptorEvent } from '../events';
-import type { DecodeRatchetOptions, KeyProviderOptions, KeySet } from '../types';
+import type { DecodeRatchetOptions, KeyProviderOptions, KeySet, RatchetResult } from '../types';
 import { deriveKeys, isVideoFrame, needsRbspUnescaping, parseRbsp, writeRbsp } from '../utils';
 import type { ParticipantKeyHandler } from './ParticipantKeyHandler';
 import { SifGuard } from './SifGuard';
@@ -477,12 +477,16 @@ export class FrameCryptor extends BaseFrameCryptor {
           );
 
           let ratchetedKeySet: KeySet | undefined;
+          let ratchetResult: RatchetResult | undefined;
           if ((initialMaterial ?? keySet) === this.keys.getKeySet(keyIndex)) {
             // only ratchet if the currently set key is still the same as the one used to decrypt this frame
             // if not, it might be that a different frame has already ratcheted and we try with that one first
-            const newMaterial = await this.keys.ratchetKey(keyIndex, false);
+            ratchetResult = await this.keys.ratchetKey(keyIndex, false);
 
-            ratchetedKeySet = await deriveKeys(newMaterial, this.keyProviderOptions.ratchetSalt);
+            ratchetedKeySet = await deriveKeys(
+              ratchetResult.cryptoKey,
+              this.keyProviderOptions.ratchetSalt,
+            );
           }
 
           const frame = await this.decryptFrame(encodedFrame, keyIndex, initialMaterial || keySet, {
@@ -493,7 +497,7 @@ export class FrameCryptor extends BaseFrameCryptor {
             // before updating the keys, make sure that the keySet used for this frame is still the same as the currently set key
             // if it's not, a new key might have been set already, which we don't want to override
             if ((initialMaterial ?? keySet) === this.keys.getKeySet(keyIndex)) {
-              this.keys.setKeySet(ratchetedKeySet, keyIndex, true);
+              this.keys.setKeySet(ratchetedKeySet, keyIndex, ratchetResult);
               // decryption was successful, set the new key index to reflect the ratcheted key set
               this.keys.setCurrentKeyIndex(keyIndex);
             }

package/src/e2ee/worker/ParticipantKeyHandler.test.ts

@@ -1,7 +1,7 @@
-import { describe, expect, it, vitest } from 'vitest';
+import { describe, expect, it, test, vitest } from 'vitest';
 import { ENCRYPTION_ALGORITHM, KEY_PROVIDER_DEFAULTS } from '../constants';
 import { KeyHandlerEvent } from '../events';
-import { createKeyMaterialFromString } from '../utils';
+import { createKeyMaterialFromString, importKey } from '../utils';
 import { ParticipantKeyHandler } from './ParticipantKeyHandler';
 
 describe('ParticipantKeyHandler', () => {
@@ -239,11 +239,18 @@ describe('ParticipantKeyHandler', () => {
 
       await keyHandler.setKey(material);
 
-      await keyHandler.ratchetKey();
+      const ratchetResult = await keyHandler.ratchetKey();
 
       const newMaterial = keyHandler.getKeySet()?.material;
 
-      expect(keyRatched).toHaveBeenCalledWith(newMaterial, participantIdentity, 0);
+      expect(keyRatched).toHaveBeenCalledWith(
+        {
+          chainKey: ratchetResult.chainKey,
+          cryptoKey: newMaterial,
+        },
+        participantIdentity,
+        0,
+      );
     });
 
     it('ratchets keys predictably', async () => {
@@ -283,4 +290,97 @@ describe('ParticipantKeyHandler', () => {
       expect(ciphertexts).matchSnapshot('ciphertexts');
     });
   });
+
+  describe(`E2EE Ratcheting`, () => {
+    test('Should be possible to share ratcheted material to remote participant', async () => {
+      const senderKeyHandler = new ParticipantKeyHandler('test-sender', KEY_PROVIDER_DEFAULTS);
+      // Initial key
+      const initialMaterial = new Uint8Array(32);
+      crypto.getRandomValues(initialMaterial);
+      const rootMaterial = await importKey(initialMaterial, 'HKDF', 'derive');
+      await senderKeyHandler.setKeyFromMaterial(rootMaterial, 0);
+
+      const iv = new Uint8Array(12);
+      crypto.getRandomValues(iv);
+
+      const firstMessagePreRatchet = new TextEncoder().encode(
+        'Hello world, this is the first message',
+      );
+      const firstCipherText = await encrypt(senderKeyHandler, 0, iv, firstMessagePreRatchet);
+
+      let ratchetBufferResolve: (key: ArrayBuffer) => void;
+      const expectEmitted = new Promise<ArrayBuffer>(async (resolve) => {
+        ratchetBufferResolve = resolve;
+      });
+
+      senderKeyHandler.on(KeyHandlerEvent.KeyRatcheted, (material, identity, keyIndex) => {
+        expect(identity).toEqual('test-sender');
+        expect(keyIndex).toEqual(0);
+        ratchetBufferResolve(material.chainKey);
+      });
+
+      const currentKeyIndex = senderKeyHandler.getCurrentKeyIndex();
+      const ratchetResult = await senderKeyHandler.ratchetKey(currentKeyIndex, true);
+
+      // Notice that ratchetedKeySet is not exportable, so we cannot share it out-of-band.
+      // This is a limitation of webcrypto for KDFs keys, they cannot be exported.
+      expect(ratchetResult.cryptoKey.extractable).toBe(false);
+
+      const ratchetedMaterial = await expectEmitted;
+
+      // The ratcheted material can be sent out-of-band to new participants. And they
+      // should be able to generate the same keyMaterial
+
+      const generatedMaterial = await importKey(ratchetedMaterial, 'HKDF', 'derive');
+      const receiverKeyHandler = new ParticipantKeyHandler('test-receiver', KEY_PROVIDER_DEFAULTS);
+      await receiverKeyHandler.setKeyFromMaterial(generatedMaterial, 0);
+
+      // Now sender should be able to encrypt to recipient
+
+      const plainText = new TextEncoder().encode('Hello world, this is a test message');
+
+      const cipherText = await encrypt(senderKeyHandler, 0, iv, plainText);
+
+      const clearTextBuffer = await decrypt(receiverKeyHandler, 0, iv, cipherText);
+
+      const clearText = new Uint8Array(clearTextBuffer);
+      expect(clearText).toEqual(plainText);
+
+      // The receiver should not be able to decrypt the first message
+      const decryptPromise = decrypt(receiverKeyHandler, 0, iv, firstCipherText);
+      await expect(decryptPromise).rejects.toThrowError();
+    });
+
+    async function encrypt(
+      participantKeyHandler: ParticipantKeyHandler,
+      keyIndex: number,
+      iv: Uint8Array,
+      data: Uint8Array,
+    ): Promise<ArrayBuffer> {
+      return crypto.subtle.encrypt(
+        {
+          name: ENCRYPTION_ALGORITHM,
+          iv,
+        },
+        participantKeyHandler.getKeySet(keyIndex)!.encryptionKey,
+        data,
+      );
+    }
+
+    async function decrypt(
+      participantKeyHandler: ParticipantKeyHandler,
+      keyIndex: number,
+      iv: Uint8Array,
+      cipherText: ArrayBuffer,
+    ): Promise<ArrayBuffer> {
+      return crypto.subtle.decrypt(
+        {
+          name: ENCRYPTION_ALGORITHM,
+          iv,
+        },
+        participantKeyHandler.getKeySet(keyIndex)!.encryptionKey,
+        cipherText,
+      );
+    }
+  });
 });

package/src/e2ee/worker/ParticipantKeyHandler.ts

@@ -2,7 +2,7 @@ import { EventEmitter } from 'events';
 import type TypedEventEmitter from 'typed-emitter';
 import { workerLogger } from '../../logger';
 import { KeyHandlerEvent, type ParticipantKeyHandlerCallbacks } from '../events';
-import type { KeyProviderOptions, KeySet } from '../types';
+import type { KeyProviderOptions, KeySet, RatchetResult } from '../types';
 import { deriveKeys, importKey, ratchet } from '../utils';
 
 // TODO ParticipantKeyHandlers currently don't get destroyed on participant disconnect
@@ -25,7 +25,7 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
 
   private keyProviderOptions: KeyProviderOptions;
 
-  private ratchetPromiseMap: Map<number, Promise<CryptoKey>>;
+  private ratchetPromiseMap: Map<number, Promise<RatchetResult>>;
 
   private participantIdentity: string;
 
@@ -110,14 +110,14 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
    * @param keyIndex
    * @param setKey
    */
-  ratchetKey(keyIndex?: number, setKey = true): Promise<CryptoKey> {
+  ratchetKey(keyIndex?: number, setKey = true): Promise<RatchetResult> {
     const currentKeyIndex = keyIndex ?? this.getCurrentKeyIndex();
 
     const existingPromise = this.ratchetPromiseMap.get(currentKeyIndex);
     if (typeof existingPromise !== 'undefined') {
       return existingPromise;
     }
-    const ratchetPromise = new Promise<CryptoKey>(async (resolve, reject) => {
+    const ratchetPromise = new Promise<RatchetResult>(async (resolve, reject) => {
       try {
         const keySet = this.getKeySet(currentKeyIndex);
         if (!keySet) {
@@ -126,22 +126,17 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
           );
         }
         const currentMaterial = keySet.material;
-        const newMaterial = await importKey(
-          await ratchet(currentMaterial, this.keyProviderOptions.ratchetSalt),
-          currentMaterial.algorithm.name,
-          'derive',
-        );
-
+        const chainKey = await ratchet(currentMaterial, this.keyProviderOptions.ratchetSalt);
+        const newMaterial = await importKey(chainKey, currentMaterial.algorithm.name, 'derive');
+        const ratchetResult: RatchetResult = {
+          chainKey,
+          cryptoKey: newMaterial,
+        };
         if (setKey) {
-          await this.setKeyFromMaterial(newMaterial, currentKeyIndex, true);
-          this.emit(
-            KeyHandlerEvent.KeyRatcheted,
-            newMaterial,
-            this.participantIdentity,
-            currentKeyIndex,
-          );
+          // Set the new key and emit a ratchet event with the ratcheted chain key
+          await this.setKeyFromMaterial(newMaterial, currentKeyIndex, ratchetResult);
         }
-        resolve(newMaterial);
+        resolve(ratchetResult);
       } catch (e) {
         reject(e);
       } finally {
@@ -169,7 +164,11 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
    * together with the material
    * also updates the currentKeyIndex
    */
-  async setKeyFromMaterial(material: CryptoKey, keyIndex: number, emitRatchetEvent = false) {
+  async setKeyFromMaterial(
+    material: CryptoKey,
+    keyIndex: number,
+    ratchetedResult: RatchetResult | null = null,
+  ) {
     const keySet = await deriveKeys(material, this.keyProviderOptions.ratchetSalt);
     const newIndex = keyIndex >= 0 ? keyIndex % this.cryptoKeyRing.length : this.currentKeyIndex;
     workerLogger.debug(`setting new key with index ${keyIndex}`, {
@@ -177,15 +176,15 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
       algorithm: material.algorithm,
       ratchetSalt: this.keyProviderOptions.ratchetSalt,
     });
-    this.setKeySet(keySet, newIndex, emitRatchetEvent);
+    this.setKeySet(keySet, newIndex, ratchetedResult);
     if (newIndex >= 0) this.currentKeyIndex = newIndex;
   }
 
-  setKeySet(keySet: KeySet, keyIndex: number, emitRatchetEvent = false) {
+  setKeySet(keySet: KeySet, keyIndex: number, ratchetedResult: RatchetResult | null = null) {
     this.cryptoKeyRing[keyIndex % this.cryptoKeyRing.length] = keySet;
 
-    if (emitRatchetEvent) {
-      this.emit(KeyHandlerEvent.KeyRatcheted, keySet.material, this.participantIdentity, keyIndex);
+    if (ratchetedResult) {
+      this.emit(KeyHandlerEvent.KeyRatcheted, ratchetedResult, this.participantIdentity, keyIndex);
     }
   }
 

package/src/e2ee/worker/e2ee.worker.ts

@@ -11,6 +11,7 @@ import type {
   KeyProviderOptions,
   RatchetMessage,
   RatchetRequestMessage,
+  RatchetResult,
 } from '../types';
 import { FrameCryptor, encryptionEnabledMap } from './FrameCryptor';
 import { ParticipantKeyHandler } from './ParticipantKeyHandler';
@@ -229,13 +230,17 @@ function setupCryptorErrorEvents(cryptor: FrameCryptor) {
   });
 }
 
-function emitRatchetedKeys(material: CryptoKey, participantIdentity: string, keyIndex?: number) {
+function emitRatchetedKeys(
+  ratchetResult: RatchetResult,
+  participantIdentity: string,
+  keyIndex?: number,
+) {
   const msg: RatchetMessage = {
     kind: `ratchetKey`,
     data: {
       participantIdentity,
       keyIndex,
-      material,
+      ratchetResult,
     },
   };
   postMessage(msg);

package/src/room/RTCEngine.ts

@@ -16,6 +16,7 @@ import {
   type ReconnectResponse,
   RequestResponse,
   Room as RoomModel,
+  RoomMovedResponse,
   RpcAck,
   RpcResponse,
   SignalTarget,
@@ -529,6 +530,11 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       this.emit(EngineEvent.SubscribedQualityUpdate, update);
     };
 
+    this.client.onRoomMoved = (res: RoomMovedResponse) => {
+      this.participantSid = res.participant?.sid;
+      this.emit(EngineEvent.RoomMoved, res);
+    };
+
     this.client.onClose = () => {
       this.handleDisconnect('signal', ReconnectReason.RR_SIGNAL_DISCONNECTED);
     };
@@ -1493,6 +1499,7 @@ export type EngineEventCallbacks = {
   dcBufferStatusChanged: (isLow: boolean, kind: DataPacket_Kind) => void;
   participantUpdate: (infos: ParticipantInfo[]) => void;
   roomUpdate: (room: RoomModel) => void;
+  roomMoved: (room: RoomMovedResponse) => void;
   connectionQualityUpdate: (update: ConnectionQualityUpdate) => void;
   speakersChanged: (speakerUpdates: SpeakerInfo[]) => void;
   streamStateChanged: (update: StreamStateUpdate) => void;

package/src/room/Room.ts

@@ -589,6 +589,25 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
           trackPublication,
           this.localParticipant,
         );
+      })
+      .on(EngineEvent.RoomMoved, (roomMoved) => {
+        this.log.debug('room moved', roomMoved);
+
+        if (roomMoved.room) {
+          this.handleRoomUpdate(roomMoved.room);
+        }
+
+        this.remoteParticipants.forEach((participant, identity) => {
+          this.handleParticipantDisconnected(identity, participant);
+        });
+
+        this.emit(RoomEvent.Moved, roomMoved.room!.name, roomMoved.token);
+
+        if (roomMoved.participant) {
+          this.handleParticipantUpdates([roomMoved.participant, ...roomMoved.otherParticipants]);
+        } else {
+          this.handleParticipantUpdates(roomMoved.otherParticipants);
+        }
       });
 
     if (this.localParticipant) {
@@ -2611,6 +2630,7 @@ export type RoomEventCallbacks = {
   reconnected: () => void;
   disconnected: (reason?: DisconnectReason) => void;
   connectionStateChanged: (state: ConnectionState) => void;
+  moved: (name: string, token: string) => void;
   mediaDevicesChanged: () => void;
   participantConnected: (participant: RemoteParticipant) => void;
   participantDisconnected: (participant: RemoteParticipant) => void;

package/src/room/events.ts

@@ -52,6 +52,16 @@ export enum RoomEvent {
    */
   ConnectionStateChanged = 'connectionStateChanged',
 
+  /**
+   * When participant has been moved to a different room by the service request.
+   * The behavior looks like the participant has been disconnected and reconnected to a different room
+   * seamlessly without connection state transition.
+   * A new token will be provided for reconnecting to the new room if needed.
+   *
+   * args: ([[room: string, token: string]])
+   */
+  Moved = 'moved',
+
   /**
    * When input or output devices on the machine have changed.
    */
@@ -563,6 +573,7 @@ export enum EngineEvent {
   Offline = 'offline',
   SignalRequestResponse = 'signalRequestResponse',
   SignalConnected = 'signalConnected',
+  RoomMoved = 'roomMoved',
 }
 
 export enum TrackEvent {

package/src/room/participant/LocalParticipant.ts

@@ -2053,11 +2053,6 @@ export default class LocalParticipant extends Participant {
 
   /** @internal */
   updateInfo(info: ParticipantInfo): boolean {
-    if (info.sid !== this.sid) {
-      // drop updates that specify a wrong sid.
-      // the sid for local participant is only explicitly set on join and full reconnect
-      return false;
-    }
     if (!super.updateInfo(info)) {
       return false;
     }

package/src/room/track/RemoteAudioTrack.ts

@@ -104,8 +104,9 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
     }
 
     if (this.sinkId && supportsSetSinkId(element)) {
-      /* @ts-ignore */
-      element.setSinkId(this.sinkId);
+      element.setSinkId(this.sinkId).catch((e) => {
+        this.log.error('Failed to set sink id on remote audio track', e, this.logContext);
+      });
     }
     if (this.audioContext && needsNewWebAudioConnection) {
       this.log.debug('using audio context mapping', this.logContext);

package/src/version.ts

@@ -1,4 +1,4 @@
 import { version as v } from '../package.json';
 
 export const version = v;
-export const protocolVersion = 15;
+export const protocolVersion = 16;