@stream-io/video-client 1.56.0 → 1.58.0

package/src/rtc/e2ee/__tests__/keyStore.test.ts

@@ -0,0 +1,221 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { IV_PREFIX_LEN } from '../e2ee-worker/constants';
+
+// A failed import is reported through notifications.ts, which posts to the
+// host. Stub it so tests run in the default Node environment.
+const postMessage = vi.fn();
+vi.stubGlobal('self', { postMessage });
+
+import { keyStore } from '../e2ee-worker/keyStore';
+
+const rawKey = (seed = 0xab): ArrayBuffer => {
+  const buf = new ArrayBuffer(16);
+  const bytes = new Uint8Array(buf);
+  for (let i = 0; i < 16; i++) bytes[i] = (seed + i) & 0xff;
+  return buf;
+};
+
+beforeEach(() => {
+  keyStore.clear();
+  postMessage.mockClear();
+});
+
+describe('importKey', () => {
+  it('stores the key and generates a random 8-byte IV prefix', async () => {
+    await keyStore.importKey('alice', 1, rawKey());
+    expect(keyStore.getKey('alice', 1)).toBeDefined();
+
+    const prefix = keyStore.getLatestKey('alice')?.ivPrefix;
+    expect(prefix).toBeDefined();
+    expect(prefix!.length).toBe(IV_PREFIX_LEN);
+  });
+
+  it('generates a fresh prefix on each import (even for the same raw key)', async () => {
+    await keyStore.importKey('alice', 1, rawKey(0x01));
+    const p1 = Array.from(keyStore.getLatestKey('alice')!.ivPrefix);
+
+    await keyStore.importKey('alice', 1, rawKey(0x01));
+    const p2 = Array.from(keyStore.getLatestKey('alice')!.ivPrefix);
+
+    // 64 bits of randomness — practically impossible for two draws to collide.
+    expect(p2).not.toEqual(p1);
+  });
+
+  it('getLatestKey returns the most recently imported key', async () => {
+    await keyStore.importKey('alice', 1, rawKey(0x01));
+    await keyStore.importKey('alice', 5, rawKey(0x02));
+    const latest = keyStore.getLatestKey('alice');
+    expect(latest!.keyIndex).toBe(5);
+  });
+
+  it('falls back to the shared key when no per-user key is registered', async () => {
+    await keyStore.importSharedKey(3, rawKey(0x55));
+    const latest = keyStore.getLatestKey('bob');
+    expect(latest!.keyIndex).toBe(3);
+  });
+
+  it('accepts 32-byte raw material (AES-256-GCM)', async () => {
+    const rawKey32 = new ArrayBuffer(32);
+    new Uint8Array(rawKey32).fill(0x42);
+    await keyStore.importKey('alice', 1, rawKey32);
+    expect(keyStore.getKey('alice', 1)).toBeDefined();
+  });
+});
+
+describe('dumpKeyState', () => {
+  it('returns fingerprints (not raw key material)', async () => {
+    await keyStore.importKey('alice', 1, rawKey(0x01));
+    await keyStore.importSharedKey(0, rawKey(0x02));
+
+    const dump = keyStore.keyState();
+    expect(dump.perUserKeys).toHaveLength(1);
+    expect(dump.perUserKeys[0]).toMatchObject({
+      userId: 'alice',
+      keyIndex: 1,
+    });
+    // Fingerprint is 8 bytes = 16 hex chars.
+    expect(dump.perUserKeys[0].fingerprint).toMatch(/^[0-9a-f]{16}$/);
+    expect(dump.sharedKeys[0].fingerprint).toMatch(/^[0-9a-f]{16}$/);
+    expect(dump.sharedKeys).toEqual([
+      {
+        keyIndex: 0,
+        fingerprint: dump.sharedKeys[0].fingerprint,
+        isActive: true,
+      },
+    ]);
+  });
+
+  it('identifies key material: same key same print, different key different', async () => {
+    // What makes the dump useful: two peers can compare prints to confirm they
+    // hold the same key, under any user id or key index.
+    await keyStore.importKey('alice', 1, rawKey(0xaa));
+    const alice = keyStore.keyState().perUserKeys[0].fingerprint;
+
+    keyStore.clear();
+    await keyStore.importKey('bob', 99, rawKey(0xaa));
+    await keyStore.importKey('bob', 100, rawKey(0x02));
+    const [same, different] = keyStore.keyState().perUserKeys;
+
+    expect(same.fingerprint).toBe(alice);
+    expect(different.fingerprint).not.toBe(alice);
+  });
+});
+
+describe('shared-key rotation', () => {
+  it('retains old epochs for decryption and encrypts with the newest', async () => {
+    await keyStore.importSharedKey(1, rawKey(0x11));
+    const oldKey = keyStore.getKey('alice', 1);
+
+    await keyStore.importSharedKey(2, rawKey(0x22));
+
+    expect(keyStore.getKey('alice', 1)).toBe(oldKey);
+    expect(keyStore.getKey('alice', 2)).toBeDefined();
+    expect(keyStore.getLatestKey('alice')?.keyIndex).toBe(2);
+  });
+
+  it('keeps the active epoch when importing its replacement fails', async () => {
+    await keyStore.importSharedKey(1, rawKey(0x11));
+    const active = keyStore.getLatestKey('alice');
+
+    await keyStore.importSharedKey(2, new ArrayBuffer(7));
+
+    const stillActive = keyStore.getLatestKey('alice');
+    expect(stillActive?.keyIndex).toBe(1);
+    expect(stillActive?.key).toBe(active?.key);
+    expect(stillActive?.ivPrefix).toEqual(active?.ivPrefix);
+    expect(keyStore.getKey('alice', 2)).toBeUndefined();
+    expect(postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'e2ee.error',
+        message: expect.stringContaining('Failed to import shared key'),
+      }),
+    );
+  });
+
+  it('removes only the requested inactive epoch', async () => {
+    await keyStore.importSharedKey(1, rawKey(0x11));
+    await keyStore.importSharedKey(2, rawKey(0x22));
+
+    keyStore.removeSharedKey(1);
+
+    expect(keyStore.getKey('alice', 1)).toBeUndefined();
+    expect(keyStore.getKey('alice', 2)).toBeDefined();
+    expect(keyStore.getLatestKey('alice')?.keyIndex).toBe(2);
+  });
+
+  it('does not reactivate an old epoch when the active one is removed', async () => {
+    await keyStore.importSharedKey(1, rawKey(0x11));
+    await keyStore.importSharedKey(2, rawKey(0x22));
+
+    keyStore.removeSharedKey(2);
+
+    // Epoch 1 remains available to decrypt delayed frames, but silently
+    // resuming encryption with it would undo the caller's rotation policy.
+    expect(keyStore.getKey('alice', 1)).toBeDefined();
+    expect(keyStore.getKey('alice', 2)).toBeUndefined();
+    expect(keyStore.getLatestKey('alice')).toBeNull();
+    expect(keyStore.keyState()).toMatchObject({
+      sharedKeys: [{ keyIndex: 1, isActive: false }],
+    });
+  });
+});
+
+describe('removeKey', () => {
+  it('retires one epoch and leaves the rest decryptable', async () => {
+    await keyStore.importKey('alice', 1, rawKey(0x01));
+    await keyStore.importKey('alice', 2, rawKey(0x02));
+
+    keyStore.removeKey('alice', 1);
+
+    expect(keyStore.getKey('alice', 1)).toBeUndefined();
+    expect(keyStore.getKey('alice', 2)).toBeDefined();
+    // Epoch 2 is still the latest, so encoding is untouched.
+    expect(keyStore.getLatestKey('alice')).toMatchObject({ keyIndex: 2 });
+  });
+
+  it('clears the latest pointer when it removes the latest epoch', async () => {
+    await keyStore.importKey('alice', 1, rawKey(0x01));
+    await keyStore.importKey('alice', 2, rawKey(0x02));
+    await keyStore.importSharedKey(9, rawKey(0x09));
+
+    keyStore.removeKey('alice', 2);
+
+    // Leaving the pointer on the removed index would resolve nothing here and
+    // silently fall through to the shared epoch below, widening the key scope
+    // of every outgoing frame. Epoch 1 must not be promoted either.
+    expect(keyStore.getKey('alice', 1)).toBeDefined();
+    expect(keyStore.getLatestKey('alice')).toMatchObject({ keyIndex: 9 });
+  });
+
+  it('leaves no per-user key at all when the last epoch goes', async () => {
+    await keyStore.importKey('alice', 1, rawKey(0x01));
+
+    keyStore.removeKey('alice', 1);
+
+    expect(keyStore.getLatestKey('alice')).toBeNull();
+    expect(keyStore.keyState().perUserKeys).toEqual([]);
+  });
+
+  it('is a no-op for an epoch or user it does not hold', async () => {
+    await keyStore.importKey('alice', 1, rawKey(0x01));
+
+    keyStore.removeKey('alice', 7);
+    keyStore.removeKey('nobody', 1);
+
+    expect(keyStore.getKey('alice', 1)).toBeDefined();
+    expect(keyStore.getLatestKey('alice')).toMatchObject({ keyIndex: 1 });
+  });
+});
+
+describe('removeAllKeys', () => {
+  it('deletes that user key state and leaves the others', async () => {
+    await keyStore.importKey('alice', 1, rawKey(0x01));
+    await keyStore.importKey('bob', 1, rawKey(0x02));
+
+    keyStore.removeAllKeys('alice');
+
+    expect(keyStore.getKey('alice', 1)).toBeUndefined();
+    expect(keyStore.getLatestKey('alice')).toBeNull();
+    expect(keyStore.getKey('bob', 1)).toBeDefined();
+  });
+});

package/src/rtc/e2ee/__tests__/notifications.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * The SPEC section 10 delivery rules, tested directly rather than through the
+ * transforms: throttling needs controllable time, and the pipeline tests cannot
+ * assert "and nothing more was delivered for another second" without it.
+ */
+
+const postMessage = vi.fn();
+vi.stubGlobal('self', { postMessage });
+
+const { DecodeNotifier, EncodeNotifier, notifyMissingEncodeKey } =
+  await import('../e2ee-worker/notifications');
+
+const types = () => postMessage.mock.calls.map(([m]) => m.type);
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  // A non-zero epoch: the throttle compares against a 0 default for an unseen
+  // key, so starting at time 0 would suppress the very first notification.
+  vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+  postMessage.mockClear();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('EncodeNotifier', () => {
+  it('latches: one signal per failure run, and time alone does not re-arm it', () => {
+    // Latching is not throttling: a permanently dead track reports once, no
+    // matter how long it keeps failing.
+    const notify = new EncodeNotifier('alice', 'VIDEO');
+    notify.failed('first');
+    notify.failed('second');
+    vi.advanceTimersByTime(60_000);
+    notify.failed('still dead');
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    expect(postMessage).toHaveBeenCalledWith({
+      type: 'e2ee.encryption_failed',
+      userId: 'alice',
+      trackType: 'VIDEO',
+      reason: 'first',
+    });
+  });
+
+  it('re-arms on recovery so a later permanent failure is not hidden', () => {
+    const notify = new EncodeNotifier('alice', 'VIDEO');
+    notify.failed('transient');
+    notify.recovered();
+    notify.failed('counter exhausted');
+    expect(types()).toEqual([
+      'e2ee.encryption_failed',
+      'e2ee.encryption_failed',
+    ]);
+    expect(postMessage.mock.calls[1][0].reason).toBe('counter exhausted');
+  });
+});
+
+describe('DecodeNotifier throttling', () => {
+  // Levels: they describe a condition that persists, so one per second is
+  // enough - the next frame re-raises the same condition.
+  it.each([
+    ['decryption_failed', (n: DecodeNotifier) => n.failed()],
+    ['unencrypted_frame', (n: DecodeNotifier) => n.unencrypted()],
+    ['unsupported_version', (n: DecodeNotifier) => n.unsupportedVersion(2)],
+  ])('delivers at most one %s per second', (type, raise) => {
+    const notify = new DecodeNotifier('bob', 'VIDEO');
+    raise(notify);
+    raise(notify);
+    raise(notify);
+    expect(types()).toEqual([`e2ee.${type}`]);
+
+    vi.advanceTimersByTime(1001);
+    raise(notify);
+    expect(types()).toEqual([`e2ee.${type}`, `e2ee.${type}`]);
+  });
+
+  // The version byte is plaintext, so a relay can rewrite it per frame. Keying
+  // the throttle by version would hand it one event per distinct value, 255x
+  // the intended rate, for free.
+  it('throttles unsupported_version per track, not per version', () => {
+    const notify = new DecodeNotifier('bob', 'VIDEO');
+    notify.unsupportedVersion(2);
+    notify.unsupportedVersion(3);
+    notify.unsupportedVersion(99);
+    expect(types()).toEqual(['e2ee.unsupported_version']);
+    expect(postMessage.mock.calls[0][0].version).toBe(2);
+  });
+
+  it('throttles missing_key per keyIndex, so a rotation still reports', () => {
+    const notify = new DecodeNotifier('bob', 'VIDEO');
+    notify.missingKey(1);
+    notify.missingKey(1);
+    // A different key epoch is a different condition and must not be
+    // suppressed by the first one's window.
+    notify.missingKey(2);
+    expect(postMessage.mock.calls.map(([m]) => m.keyIndex)).toEqual([1, 2]);
+  });
+
+  it('does not throttle decryption_stalled: it is already once per failure run', () => {
+    const notify = new DecodeNotifier('bob', 'VIDEO');
+    notify.stalled(0);
+    notify.stalled(1);
+    expect(types()).toEqual([
+      'e2ee.decryption_stalled',
+      'e2ee.decryption_stalled',
+    ]);
+  });
+
+  it('scopes throttles per notifier, so one track cannot mute another', () => {
+    const video = new DecodeNotifier('bob', 'VIDEO');
+    const audio = new DecodeNotifier('bob', 'AUDIO');
+    video.failed();
+    audio.failed();
+    expect(postMessage.mock.calls.map(([m]) => m.trackType)).toEqual([
+      'VIDEO',
+      'AUDIO',
+    ]);
+  });
+});
+
+describe('DecodeNotifier failure/recovery pairing', () => {
+  it('emits exactly one recovery per delivered failure, unthrottled', () => {
+    const notify = new DecodeNotifier('bob', 'VIDEO');
+    notify.resumed(); // nothing was reported yet, so nothing to clear
+    expect(postMessage).not.toHaveBeenCalled();
+
+    notify.failed();
+    notify.resumed(); // inside the failure's own throttle window, still fires:
+    notify.resumed(); // an edge must never be delayed or dropped...
+    notify.resumed(); // ...but it also does not repeat.
+    expect(types()).toEqual([
+      'e2ee.decryption_failed',
+      'e2ee.decryption_resumed',
+    ]);
+  });
+
+  it('does not emit a recovery for a failure the throttle swallowed', () => {
+    const notify = new DecodeNotifier('bob', 'VIDEO');
+    notify.failed(); // delivered
+    notify.resumed(); // pairs with it
+    postMessage.mockClear();
+    notify.failed(); // suppressed: still inside the window
+    notify.resumed(); // the host never heard the failure, so nothing to clear
+    expect(postMessage).not.toHaveBeenCalled();
+  });
+});
+
+describe('notifyMissingEncodeKey', () => {
+  it('throttles per user and carries no trackType', () => {
+    // The local encoder holding no key stalls every outgoing track at once, so
+    // this is reported once for the user rather than per track.
+    notifyMissingEncodeKey('alice');
+    notifyMissingEncodeKey('alice');
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    expect(postMessage).toHaveBeenCalledWith({
+      type: 'e2ee.missing_key',
+      userId: 'alice',
+    });
+
+    notifyMissingEncodeKey('carol');
+    expect(postMessage).toHaveBeenCalledTimes(2);
+  });
+});

package/src/rtc/e2ee/__tests__/perf.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const postMessage = vi.fn();
+vi.stubGlobal('self', { postMessage });
+
+const { decodeStats, encodeStats, startPerfReport, stopPerfReport } =
+  await import('../e2ee-worker/perf');
+
+const encodeTrack = (trackType: string, userId = 'alice') =>
+  encodeStats.track(trackType, { userId, trackType, codec: 'vp8' });
+const decodeTrack = (userId: string, trackType = 'VIDEO') =>
+  decodeStats.track(`${userId}/${trackType}`, { userId, trackType });
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  postMessage.mockClear();
+});
+
+afterEach(() => {
+  stopPerfReport();
+  vi.useRealTimers();
+});
+
+describe('while reporting is off', () => {
+  it('records nothing, so the transforms need no guard of their own', () => {
+    const track = encodeTrack('VIDEO');
+    track.bump();
+    track.endCrypto(track.startCrypto());
+    expect(encodeStats.flush(1)).toEqual([]);
+  });
+});
+
+describe('counting', () => {
+  beforeEach(() => startPerfReport());
+
+  it('reports each track separately, as a rate over the elapsed window', () => {
+    // Two tracks on one sender: a vp8 camera and a vp8 screen share must be
+    // reported apart rather than summed.
+    const camera = encodeTrack('VIDEO');
+    camera.bump();
+    camera.bump();
+    camera.bump();
+    encodeTrack('SCREEN_SHARE').bump();
+
+    expect(encodeStats.flush(1.5)).toEqual([
+      {
+        userId: 'alice',
+        trackType: 'VIDEO',
+        codec: 'vp8',
+        fps: 2,
+        maxCryptoMs: 0,
+      },
+      {
+        userId: 'alice',
+        trackType: 'SCREEN_SHARE',
+        codec: 'vp8',
+        fps: 1 / 1.5,
+        maxCryptoMs: 0,
+      },
+    ]);
+  });
+
+  it('drops an idle track from the next report instead of reporting 0 fps', () => {
+    // The accumulator is created on demand and cleared by flush, so a track
+    // that stops delivering disappears rather than reporting zeroes forever.
+    const track = encodeTrack('VIDEO');
+    track.bump();
+    expect(encodeStats.flush(1)).toHaveLength(1);
+    expect(encodeStats.flush(1)).toHaveLength(0);
+    // ...and it comes back as soon as it delivers again.
+    track.bump();
+    expect(encodeStats.flush(1)).toHaveLength(1);
+  });
+
+  it('takes the worst crypto time seen in the window', () => {
+    const track = encodeTrack('VIDEO');
+    const slow = track.startCrypto();
+    vi.advanceTimersByTime(7);
+    track.endCrypto(slow);
+    const fast = track.startCrypto();
+    vi.advanceTimersByTime(2);
+    track.endCrypto(fast);
+    expect(encodeStats.flush(1)[0].maxCryptoMs).toBe(7);
+  });
+
+  it('labels decode samples without a codec', () => {
+    // A remote sender's codec is not reliably known locally, so decode rows
+    // carry only (userId, trackType).
+    decodeTrack('bob').bump();
+    expect(decodeStats.flush(1)).toEqual([
+      { userId: 'bob', trackType: 'VIDEO', fps: 1, maxCryptoMs: 0 },
+    ]);
+  });
+
+  it('removeUser drops that user rows and leaves the others', () => {
+    decodeTrack('bob').bump();
+    decodeTrack('carol').bump();
+    decodeStats.removeUser('bob');
+    expect(decodeStats.flush(1).map((s) => s.userId)).toEqual(['carol']);
+  });
+});
+
+describe('the reporting interval', () => {
+  it('posts one report per second with both directions', () => {
+    startPerfReport();
+    encodeTrack('VIDEO').bump();
+    decodeTrack('bob').bump();
+
+    vi.advanceTimersByTime(1000);
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const report = postMessage.mock.calls[0][0];
+    expect(report.type).toBe('e2ee.perf_report');
+    expect(report.encode).toHaveLength(1);
+    expect(report.decode).toHaveLength(1);
+  });
+
+  it('is idempotent: a second start does not add a second interval', () => {
+    startPerfReport();
+    startPerfReport();
+    startPerfReport();
+    encodeTrack('VIDEO').bump();
+
+    vi.advanceTimersByTime(1000);
+
+    // A leaked interval would post the same window several times over.
+    expect(postMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops the interval and clears the counters on stop', () => {
+    startPerfReport();
+    encodeTrack('VIDEO').bump();
+    stopPerfReport();
+
+    expect(encodeStats.flush(1)).toEqual([]);
+    vi.advanceTimersByTime(5000);
+    expect(postMessage).not.toHaveBeenCalled();
+  });
+});

package/src/rtc/e2ee/__tests__/queue.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { enqueue } from '../e2ee-worker/queue';
+
+describe('enqueue', () => {
+  it('carries the task outcome back to its own caller', async () => {
+    await expect(enqueue(async () => 42)).resolves.toBe(42);
+    await expect(
+      enqueue(async () => {
+        throw new Error('boom');
+      }),
+    ).rejects.toThrow('boom');
+  });
+
+  it('preserves task ordering', async () => {
+    const order: number[] = [];
+    const promises = [];
+    for (let i = 0; i < 5; i++) {
+      promises.push(
+        enqueue(async () => {
+          await Promise.resolve();
+          order.push(i);
+        }),
+      );
+    }
+    await Promise.all(promises);
+    expect(order).toEqual([0, 1, 2, 3, 4]);
+  });
+
+  it('runs tasks serially, never overlapping a previous task still in flight', async () => {
+    // Serialization, not just emission order: each task body yields several
+    // microtasks while "active". If two ran concurrently, active would exceed 1.
+    let active = 0;
+    let maxActive = 0;
+    const task = () =>
+      enqueue(async () => {
+        active++;
+        maxActive = Math.max(maxActive, active);
+        await Promise.resolve();
+        await Promise.resolve();
+        active--;
+      });
+    await Promise.all([task(), task(), task()]);
+    expect(maxActive).toBe(1);
+  });
+
+  it('continues running later tasks after one rejects', async () => {
+    const seen: string[] = [];
+    const ok1 = enqueue(async () => {
+      seen.push('a');
+    });
+    const bad = enqueue(async () => {
+      seen.push('b');
+      throw new Error('fail');
+    });
+    const ok2 = enqueue(async () => {
+      seen.push('c');
+    });
+    await Promise.all([ok1, bad.catch(() => {}), ok2]);
+    expect(seen).toEqual(['a', 'b', 'c']);
+  });
+});