livekit-client 2.11.4 → 2.13.0

package/dist/ts4.2/src/e2ee/events.d.ts

@@ -1,21 +1,26 @@
 import type Participant from '../room/participant/Participant';
 import type { CryptorError } from './errors';
-import type { KeyInfo } from './types';
+import type { KeyInfo, RatchetResult } from './types';
 export declare 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 declare 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, participantIdentity: string, keyIndex?: number) => void;
+    [KeyHandlerEvent.KeyRatcheted]: (ratchetResult: RatchetResult, participantIdentity: string, keyIndex?: number) => void;
 };
 export declare enum EncryptionEvent {
     ParticipantEncryptionStatusChanged = "participantEncryptionStatusChanged",

package/dist/ts4.2/src/e2ee/types.d.ts

@@ -72,7 +72,7 @@ export interface RatchetMessage extends BaseMessage {
     data: {
         participantIdentity: string;
         keyIndex?: number;
-        material: CryptoKey;
+        ratchetResult: RatchetResult;
     };
 }
 export interface ErrorMessage extends BaseMessage {
@@ -99,6 +99,10 @@ export type KeySet = {
     material: CryptoKey;
     encryptionKey: CryptoKey;
 };
+export type RatchetResult = {
+    chainKey: ArrayBuffer;
+    cryptoKey: CryptoKey;
+};
 export type KeyProviderOptions = {
     sharedKey: boolean;
     ratchetSalt: string;

package/dist/ts4.2/src/e2ee/worker/ParticipantKeyHandler.d.ts

@@ -1,6 +1,6 @@
 import type TypedEventEmitter from 'typed-emitter';
 import type { ParticipantKeyHandlerCallbacks } from '../events';
-import type { KeyProviderOptions, KeySet } from '../types';
+import type { KeyProviderOptions, KeySet, RatchetResult } from '../types';
 declare const ParticipantKeyHandler_base: new () => TypedEventEmitter<ParticipantKeyHandlerCallbacks>;
 /**
  * ParticipantKeyHandler is responsible for providing a cryptor instance with the
@@ -54,7 +54,7 @@ export declare class ParticipantKeyHandler extends ParticipantKeyHandler_base {
      * @param keyIndex
      * @param setKey
      */
-    ratchetKey(keyIndex?: number, setKey?: boolean): Promise<CryptoKey>;
+    ratchetKey(keyIndex?: number, setKey?: boolean): Promise<RatchetResult>;
     /**
      * takes in a key material with `deriveBits` and `deriveKey` set as key usages
      * and derives encryption keys from the material and sets it on the key ring buffer
@@ -68,8 +68,8 @@ export declare class ParticipantKeyHandler extends ParticipantKeyHandler_base {
      * together with the material
      * also updates the currentKeyIndex
      */
-    setKeyFromMaterial(material: CryptoKey, keyIndex: number, emitRatchetEvent?: boolean): Promise<void>;
-    setKeySet(keySet: KeySet, keyIndex: number, emitRatchetEvent?: boolean): void;
+    setKeyFromMaterial(material: CryptoKey, keyIndex: number, ratchetedResult?: RatchetResult | null): Promise<void>;
+    setKeySet(keySet: KeySet, keyIndex: number, ratchetedResult?: RatchetResult | null): void;
     setCurrentKeyIndex(index: number): Promise<void>;
     getCurrentKeyIndex(): number;
     /**

package/dist/ts4.2/src/room/RTCEngine.d.ts

@@ -1,5 +1,5 @@
 import type { AddTrackRequest, ConnectionQualityUpdate, JoinResponse, StreamStateUpdate, SubscriptionPermissionUpdate, SubscriptionResponse } from '@livekit/protocol';
-import { DataPacket, DataPacket_Kind, DisconnectReason, ParticipantInfo, RequestResponse, Room as RoomModel, SpeakerInfo, SubscribedQualityUpdate, TrackInfo, TrackUnpublishedResponse, Transcription } from '@livekit/protocol';
+import { DataPacket, DataPacket_Kind, DisconnectReason, ParticipantInfo, RequestResponse, Room as RoomModel, RoomMovedResponse, SpeakerInfo, SubscribedQualityUpdate, TrackInfo, TrackUnpublishedResponse, Transcription } from '@livekit/protocol';
 import type TypedEventEmitter from 'typed-emitter';
 import type { SignalOptions } from '../api/SignalClient';
 import { SignalClient } from '../api/SignalClient';
@@ -153,6 +153,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/dist/ts4.2/src/room/Room.d.ts

@@ -286,6 +286,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;
@@ -324,5 +325,6 @@ export type RoomEventCallbacks = {
     chatMessage: (message: ChatMessage, participant?: RemoteParticipant | LocalParticipant) => void;
     localTrackSubscribed: (publication: LocalTrackPublication, participant: LocalParticipant) => void;
     metricsReceived: (metrics: MetricsBatch, participant?: Participant) => void;
+    participantActive: (participant: Participant) => void;
 };
 //# sourceMappingURL=Room.d.ts.map

package/dist/ts4.2/src/room/events.d.ts

@@ -45,6 +45,15 @@ export declare enum RoomEvent {
      * args: ([[ConnectionState]])
      */
     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.
      */
@@ -169,6 +178,12 @@ export declare enum RoomEvent {
      * args: (changedAttributes: [[Record<string, string]], participant: [[Participant]])
      */
     ParticipantAttributesChanged = "participantAttributesChanged",
+    /**
+     * Emitted when the participant's state changes to ACTIVE and is ready to send/receive data messages
+     *
+     * args: (participant: [[Participant]])
+     */
+    ParticipantActive = "participantActive",
     /**
      * Room metadata is a simple way for app-specific state to be pushed to
      * all users.
@@ -459,7 +474,11 @@ export declare enum ParticipantEvent {
      */
     LocalTrackSubscribed = "localTrackSubscribed",
     /** only emitted on local participant */
-    ChatMessage = "chatMessage"
+    ChatMessage = "chatMessage",
+    /**
+     * Emitted when the participant's state changes to ACTIVE and is ready to send/receive data messages
+     */
+    Active = "active"
 }
 /** @internal */
 export declare enum EngineEvent {
@@ -491,7 +510,8 @@ export declare enum EngineEvent {
     LocalTrackSubscribed = "localTrackSubscribed",
     Offline = "offline",
     SignalRequestResponse = "signalRequestResponse",
-    SignalConnected = "signalConnected"
+    SignalConnected = "signalConnected",
+    RoomMoved = "roomMoved"
 }
 export declare enum TrackEvent {
     Message = "message",

package/dist/ts4.2/src/room/participant/Participant.d.ts

@@ -8,6 +8,7 @@ import type RemoteTrackPublication from '../track/RemoteTrackPublication';
 import { Track } from '../track/Track';
 import type { TrackPublication } from '../track/TrackPublication';
 import type { ChatMessage, LoggerOptions, TranscriptionSegment } from '../types';
+import { Future } from '../utils';
 export declare enum ConnectionQuality {
     Excellent = "excellent",
     Good = "good",
@@ -47,11 +48,13 @@ export default class Participant extends Participant_base {
     protected audioContext?: AudioContext;
     protected log: StructuredLogger;
     protected loggerOptions?: LoggerOptions;
+    protected activeFuture?: Future<void>;
     protected get logContext(): {
         [x: string]: unknown;
     };
     get isEncrypted(): boolean;
     get isAgent(): boolean;
+    get isActive(): boolean;
     get kind(): ParticipantKind;
     /** participant attributes, similar to metadata, but as a key/value map */
     get attributes(): Readonly<Record<string, string>>;
@@ -67,6 +70,11 @@ export default class Participant extends Participant_base {
      * Finds the first track that matches the track's name.
      */
     getTrackPublicationByName(name: string): TrackPublication | undefined;
+    /**
+     * Waits until the participant is active and ready to receive data messages
+     * @returns a promise that resolves when the participant is active
+     */
+    waitUntilActive(): Promise<void>;
     get connectionQuality(): ConnectionQuality;
     get isCameraEnabled(): boolean;
     get isMicrophoneEnabled(): boolean;
@@ -91,6 +99,10 @@ export default class Participant extends Participant_base {
     setIsSpeaking(speaking: boolean): void;
     /** @internal */
     setConnectionQuality(q: ProtoQuality): void;
+    /**
+     * @internal
+     */
+    setDisconnected(): void;
     /**
      * @internal
      */
@@ -123,5 +135,6 @@ export type ParticipantEventCallbacks = {
     attributesChanged: (changedAttributes: Record<string, string>) => void;
     localTrackSubscribed: (trackPublication: LocalTrackPublication) => void;
     chatMessage: (msg: ChatMessage) => void;
+    active: () => void;
 };
 //# sourceMappingURL=Participant.d.ts.map

package/dist/ts4.2/src/version.d.ts

@@ -1,3 +1,3 @@
 export declare const version: string;
-export declare const protocolVersion = 15;
+export declare const protocolVersion = 16;
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.11.4",
+  "version": "2.13.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);
     }
   }