livekit-client 2.5.7 → 2.5.9

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

@@ -1,5 +1,6 @@
-import { describe, expect, it } from 'vitest';
-import { KEY_PROVIDER_DEFAULTS } from '../constants';
+import { describe, expect, it, vitest } from 'vitest';
+import { ENCRYPTION_ALGORITHM, KEY_PROVIDER_DEFAULTS } from '../constants';
+import { KeyHandlerEvent } from '../events';
 import { createKeyMaterialFromString } from '../utils';
 import { ParticipantKeyHandler } from './ParticipantKeyHandler';
 
@@ -35,11 +36,38 @@ describe('ParticipantKeyHandler', () => {
     expect(keyHandler.getKeySet(0)?.material).toEqual(materialB);
   });
 
-  it('marks invalid if more than failureTolerance failures', async () => {
+  it('defaults to key index of 0 when setting key', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+      ...KEY_PROVIDER_DEFAULTS,
+    });
+
+    const materialA = await createKeyMaterialFromString('passwordA');
+
+    await keyHandler.setKey(materialA);
+
+    expect(keyHandler.getKeySet(0)?.material).toEqual(materialA);
+  });
+
+  it('defaults to current key index when getting key', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+      ...KEY_PROVIDER_DEFAULTS,
+    });
+
+    const materialA = await createKeyMaterialFromString('passwordA');
+
+    await keyHandler.setKey(materialA, 10);
+
+    expect(keyHandler.getKeySet()?.material).toEqual(materialA);
+  });
+
+  it('marks current key invalid if more than failureTolerance failures', async () => {
     const keyHandler = new ParticipantKeyHandler(participantIdentity, {
       ...KEY_PROVIDER_DEFAULTS,
       failureTolerance: 2,
     });
+
+    keyHandler.setCurrentKeyIndex(10);
+
     expect(keyHandler.hasValidKey).toBe(true);
 
     // 1
@@ -55,13 +83,16 @@ describe('ParticipantKeyHandler', () => {
     expect(keyHandler.hasValidKey).toBe(false);
   });
 
-  it('marks valid on encryption success', async () => {
+  it('marks current key valid on encryption success', async () => {
     const keyHandler = new ParticipantKeyHandler(participantIdentity, {
       ...KEY_PROVIDER_DEFAULTS,
       failureTolerance: 0,
     });
 
+    keyHandler.setCurrentKeyIndex(10);
+
     expect(keyHandler.hasValidKey).toBe(true);
+    expect(keyHandler.hasInvalidKeyAtIndex(0)).toBe(false);
 
     keyHandler.decryptionFailure();
 
@@ -72,13 +103,62 @@ describe('ParticipantKeyHandler', () => {
     expect(keyHandler.hasValidKey).toBe(true);
   });
 
+  it('marks specific key invalid if more than failureTolerance failures', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+      ...KEY_PROVIDER_DEFAULTS,
+      failureTolerance: 2,
+    });
+
+    // set the current key to something different from what we are testing
+    keyHandler.setCurrentKeyIndex(10);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+
+    // 1
+    keyHandler.decryptionFailure(5);
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+
+    // 2
+    keyHandler.decryptionFailure(5);
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+
+    // 3
+    keyHandler.decryptionFailure(5);
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(true);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(10)).toBe(false);
+  });
+
+  it('marks specific key valid on encryption success', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+      ...KEY_PROVIDER_DEFAULTS,
+      failureTolerance: 0,
+    });
+
+    // set the current key to something different from what we are testing
+    keyHandler.setCurrentKeyIndex(10);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+
+    keyHandler.decryptionFailure(5);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(true);
+
+    keyHandler.decryptionSuccess(5);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+  });
+
   it('marks valid on new key', async () => {
     const keyHandler = new ParticipantKeyHandler(participantIdentity, {
       ...KEY_PROVIDER_DEFAULTS,
       failureTolerance: 0,
     });
 
+    keyHandler.setCurrentKeyIndex(10);
+
     expect(keyHandler.hasValidKey).toBe(true);
+    expect(keyHandler.hasInvalidKeyAtIndex(0)).toBe(false);
 
     keyHandler.decryptionFailure();
 
@@ -108,7 +188,14 @@ describe('ParticipantKeyHandler', () => {
     expect(keyHandler.getCurrentKeyIndex()).toBe(10);
   });
 
-  it('allows many failures if failureTolerance is -1', async () => {
+  it('allows currentKeyIndex to be explicitly set', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, KEY_PROVIDER_DEFAULTS);
+
+    keyHandler.setCurrentKeyIndex(10);
+    expect(keyHandler.getCurrentKeyIndex()).toBe(10);
+  });
+
+  it('allows many failures if failureTolerance is less than zero', async () => {
     const keyHandler = new ParticipantKeyHandler(participantIdentity, {
       ...KEY_PROVIDER_DEFAULTS,
       failureTolerance: -1,
@@ -119,4 +206,81 @@ describe('ParticipantKeyHandler', () => {
       expect(keyHandler.hasValidKey).toBe(true);
     }
   });
+
+  describe('resetKeyStatus', () => {
+    it('marks all keys as valid if no index is provided', () => {
+      const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+        ...KEY_PROVIDER_DEFAULTS,
+        failureTolerance: 0,
+      });
+
+      for (let i = 0; i < KEY_PROVIDER_DEFAULTS.keyringSize; i++) {
+        keyHandler.decryptionFailure(i);
+        expect(keyHandler.hasInvalidKeyAtIndex(i)).toBe(true);
+      }
+
+      keyHandler.resetKeyStatus();
+
+      for (let i = 0; i < KEY_PROVIDER_DEFAULTS.keyringSize; i++) {
+        expect(keyHandler.hasInvalidKeyAtIndex(i)).toBe(false);
+      }
+    });
+  });
+
+  describe('ratchetKey', () => {
+    it('emits event', async () => {
+      const keyHandler = new ParticipantKeyHandler(participantIdentity, KEY_PROVIDER_DEFAULTS);
+
+      const material = await createKeyMaterialFromString('password');
+
+      const keyRatched = vitest.fn();
+
+      keyHandler.on(KeyHandlerEvent.KeyRatcheted, keyRatched);
+
+      await keyHandler.setKey(material);
+
+      await keyHandler.ratchetKey();
+
+      const newMaterial = keyHandler.getKeySet()?.material;
+
+      expect(keyRatched).toHaveBeenCalledWith(newMaterial, participantIdentity, 0);
+    });
+
+    it('ratchets keys predictably', async () => {
+      // we can't extract the keys directly, so we instead use them to encrypt a known plaintext
+      const keyHandler = new ParticipantKeyHandler(participantIdentity, KEY_PROVIDER_DEFAULTS);
+
+      const originalMaterial = await createKeyMaterialFromString('password');
+
+      await keyHandler.setKey(originalMaterial);
+
+      const ciphertexts: Uint8Array[] = [];
+
+      const plaintext = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]);
+
+      const iv = new Uint8Array(12);
+      const additionalData = new Uint8Array(0);
+
+      for (let i = 0; i < 10; i++) {
+        const { encryptionKey } = keyHandler.getKeySet()!;
+
+        const ciphertext = await crypto.subtle.encrypt(
+          {
+            name: ENCRYPTION_ALGORITHM,
+            iv,
+            additionalData,
+          },
+          encryptionKey,
+          plaintext,
+        );
+        ciphertexts.push(new Uint8Array(ciphertext));
+        await keyHandler.ratchetKey();
+      }
+      // check that all ciphertexts are unique
+      expect(new Set(ciphertexts.map((x) => new TextDecoder().decode(x))).size).toEqual(
+        ciphertexts.length,
+      );
+      expect(ciphertexts).matchSnapshot('ciphertexts');
+    });
+  });
 });

package/src/e2ee/worker/ParticipantKeyHandler.ts

@@ -21,18 +21,19 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
 
   private cryptoKeyRing: Array<KeySet | undefined>;
 
+  private decryptionFailureCounts: Array<number>;
+
   private keyProviderOptions: KeyProviderOptions;
 
   private ratchetPromiseMap: Map<number, Promise<CryptoKey>>;
 
   private participantIdentity: string;
 
-  private decryptionFailureCount = 0;
-
-  private _hasValidKey: boolean = true;
-
-  get hasValidKey() {
-    return this._hasValidKey;
+  /**
+   * true if the current key has not been marked as invalid
+   */
+  get hasValidKey(): boolean {
+    return !this.hasInvalidKeyAtIndex(this.currentKeyIndex);
   }
 
   constructor(participantIdentity: string, keyProviderOptions: KeyProviderOptions) {
@@ -42,35 +43,64 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
       throw new TypeError('Keyring size needs to be between 1 and 256');
     }
     this.cryptoKeyRing = new Array(keyProviderOptions.keyringSize).fill(undefined);
+    this.decryptionFailureCounts = new Array(keyProviderOptions.keyringSize).fill(0);
     this.keyProviderOptions = keyProviderOptions;
     this.ratchetPromiseMap = new Map();
     this.participantIdentity = participantIdentity;
-    this.resetKeyStatus();
   }
 
-  decryptionFailure() {
+  /**
+   * Returns true if the key at the given index is marked as invalid.
+   *
+   * @param keyIndex the index of the key
+   */
+  hasInvalidKeyAtIndex(keyIndex: number): boolean {
+    return (
+      this.keyProviderOptions.failureTolerance >= 0 &&
+      this.decryptionFailureCounts[keyIndex] > this.keyProviderOptions.failureTolerance
+    );
+  }
+
+  /**
+   * Informs the key handler that a decryption failure occurred for an encryption key.
+   * @internal
+   * @param keyIndex the key index for which the failure occurred. Defaults to the current key index.
+   */
+  decryptionFailure(keyIndex: number = this.currentKeyIndex): void {
     if (this.keyProviderOptions.failureTolerance < 0) {
       return;
     }
-    this.decryptionFailureCount += 1;
 
-    if (this.decryptionFailureCount > this.keyProviderOptions.failureTolerance) {
-      workerLogger.warn(`key for ${this.participantIdentity} is being marked as invalid`);
-      this._hasValidKey = false;
+    this.decryptionFailureCounts[keyIndex] += 1;
+
+    if (this.decryptionFailureCounts[keyIndex] > this.keyProviderOptions.failureTolerance) {
+      workerLogger.warn(
+        `key for ${this.participantIdentity} at index ${keyIndex} is being marked as invalid`,
+      );
     }
   }
 
-  decryptionSuccess() {
-    this.resetKeyStatus();
+  /**
+   * Informs the key handler that a frame was successfully decrypted using an encryption key.
+   * @internal
+   * @param keyIndex the key index for which the success occurred. Defaults to the current key index.
+   */
+  decryptionSuccess(keyIndex: number = this.currentKeyIndex): void {
+    this.resetKeyStatus(keyIndex);
   }
 
   /**
    * Call this after user initiated ratchet or a new key has been set in order to make sure to mark potentially
    * invalid keys as valid again
+   *
+   * @param keyIndex the index of the key. Defaults to the current key index.
    */
-  resetKeyStatus() {
-    this.decryptionFailureCount = 0;
-    this._hasValidKey = true;
+  resetKeyStatus(keyIndex?: number): void {
+    if (keyIndex === undefined) {
+      this.decryptionFailureCounts.fill(0);
+    } else {
+      this.decryptionFailureCounts[keyIndex] = 0;
+    }
   }
 
   /**
@@ -103,7 +133,7 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
         );
 
         if (setKey) {
-          this.setKeyFromMaterial(newMaterial, currentKeyIndex, true);
+          await this.setKeyFromMaterial(newMaterial, currentKeyIndex, true);
           this.emit(
             KeyHandlerEvent.KeyRatcheted,
             newMaterial,
@@ -130,7 +160,7 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
    */
   async setKey(material: CryptoKey, keyIndex = 0) {
     await this.setKeyFromMaterial(material, keyIndex);
-    this.resetKeyStatus();
+    this.resetKeyStatus(keyIndex);
   }
 
   /**
@@ -161,7 +191,7 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
 
   async setCurrentKeyIndex(index: number) {
     this.currentKeyIndex = index % this.cryptoKeyRing.length;
-    this.resetKeyStatus();
+    this.resetKeyStatus(index);
   }
 
   getCurrentKeyIndex() {

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

@@ -0,0 +1,356 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ParticipantKeyHandler > ratchetKey > ratchets keys predictably > ciphertexts 1`] = `
+[
+  Uint8Array [
+    42,
+    226,
+    94,
+    49,
+    152,
+    18,
+    79,
+    1,
+    55,
+    190,
+    250,
+    80,
+    143,
+    19,
+    134,
+    218,
+    200,
+    55,
+    87,
+    102,
+    117,
+    217,
+    130,
+    48,
+    11,
+    66,
+    63,
+    102,
+    115,
+    144,
+    117,
+    92,
+    232,
+  ],
+  Uint8Array [
+    4,
+    164,
+    120,
+    76,
+    172,
+    225,
+    17,
+    14,
+    176,
+    186,
+    111,
+    5,
+    10,
+    176,
+    29,
+    42,
+    19,
+    215,
+    72,
+    227,
+    203,
+    139,
+    219,
+    147,
+    85,
+    78,
+    62,
+    191,
+    186,
+    123,
+    248,
+    60,
+    147,
+  ],
+  Uint8Array [
+    58,
+    173,
+    85,
+    162,
+    211,
+    200,
+    200,
+    87,
+    214,
+    65,
+    218,
+    92,
+    74,
+    53,
+    143,
+    183,
+    58,
+    242,
+    19,
+    39,
+    226,
+    180,
+    204,
+    127,
+    109,
+    219,
+    156,
+    152,
+    103,
+    158,
+    186,
+    240,
+    161,
+  ],
+  Uint8Array [
+    46,
+    137,
+    107,
+    8,
+    239,
+    248,
+    217,
+    214,
+    106,
+    234,
+    103,
+    34,
+    108,
+    179,
+    18,
+    186,
+    5,
+    33,
+    31,
+    21,
+    9,
+    48,
+    194,
+    205,
+    206,
+    136,
+    6,
+    179,
+    64,
+    150,
+    126,
+    175,
+    132,
+  ],
+  Uint8Array [
+    249,
+    123,
+    86,
+    179,
+    18,
+    9,
+    149,
+    42,
+    110,
+    112,
+    29,
+    193,
+    208,
+    63,
+    48,
+    118,
+    15,
+    186,
+    27,
+    101,
+    23,
+    31,
+    111,
+    152,
+    193,
+    235,
+    89,
+    25,
+    161,
+    246,
+    231,
+    198,
+    126,
+  ],
+  Uint8Array [
+    56,
+    134,
+    196,
+    195,
+    242,
+    10,
+    187,
+    122,
+    111,
+    179,
+    147,
+    206,
+    74,
+    153,
+    45,
+    244,
+    88,
+    119,
+    25,
+    114,
+    11,
+    2,
+    149,
+    121,
+    227,
+    219,
+    39,
+    11,
+    13,
+    175,
+    182,
+    168,
+    96,
+  ],
+  Uint8Array [
+    36,
+    12,
+    119,
+    157,
+    146,
+    42,
+    43,
+    107,
+    61,
+    43,
+    242,
+    166,
+    11,
+    180,
+    148,
+    39,
+    177,
+    248,
+    194,
+    166,
+    201,
+    53,
+    192,
+    57,
+    62,
+    70,
+    37,
+    252,
+    243,
+    156,
+    140,
+    185,
+    42,
+  ],
+  Uint8Array [
+    222,
+    127,
+    32,
+    228,
+    99,
+    198,
+    31,
+    158,
+    192,
+    101,
+    82,
+    129,
+    175,
+    153,
+    112,
+    43,
+    57,
+    207,
+    246,
+    54,
+    127,
+    165,
+    99,
+    254,
+    4,
+    178,
+    40,
+    53,
+    66,
+    92,
+    13,
+    69,
+    0,
+  ],
+  Uint8Array [
+    249,
+    181,
+    181,
+    168,
+    27,
+    48,
+    221,
+    221,
+    174,
+    187,
+    16,
+    153,
+    144,
+    156,
+    164,
+    232,
+    185,
+    202,
+    132,
+    58,
+    75,
+    156,
+    232,
+    238,
+    191,
+    33,
+    9,
+    31,
+    151,
+    43,
+    224,
+    136,
+    190,
+  ],
+  Uint8Array [
+    58,
+    99,
+    16,
+    151,
+    148,
+    131,
+    138,
+    94,
+    230,
+    95,
+    38,
+    81,
+    137,
+    162,
+    78,
+    61,
+    243,
+    207,
+    255,
+    109,
+    48,
+    248,
+    217,
+    135,
+    133,
+    248,
+    56,
+    74,
+    41,
+    113,
+    153,
+    108,
+    202,
+  ],
+]
+`;