@stream-io/video-client 1.57.0 → 1.58.0

package/src/rtc/e2ee/e2ee-worker/encode.ts

@@ -0,0 +1,147 @@
+import { EMPTY_AAD, IV_LEN, MAX_CLEAR_BYTES, TRAILER_LEN } from './constants';
+import {
+  boundarySeedZeros,
+  getCodecProfile,
+  rbspEscapeInto,
+  rbspEscapedLength,
+} from './codec';
+import { fillIV, writeTrailer } from './trailer';
+import { nextFrameCounter } from './frameCounter';
+import { keyStore } from './keyStore';
+import { encodeStats } from './perf';
+import { EncodeNotifier, notifyMissingEncodeKey } from './notifications';
+import type { EncodedFrame, FrameController } from './types';
+
+export const encodeTransform = (
+  userId: string,
+  codec: string | undefined,
+  trackType: string | undefined,
+) => {
+  const profile = getCodecProfile(codec);
+  const isNalu = profile.rbsp;
+  // trackType is unique per sender; fall back to codec when it is unlabeled.
+  const trackKey = trackType ?? codec ?? 'unknown';
+  const codecKey = codec ?? 'unknown';
+  const stats = encodeStats.track(trackKey, {
+    userId,
+    trackType: trackKey,
+    codec: codecKey,
+  });
+  const notify = new EncodeNotifier(userId, trackType);
+  const iv = new Uint8Array(IV_LEN);
+  const ivView = new DataView(iv.buffer);
+
+  /**
+   * Times the encryption, emits the frame, reports failures. `produce` returns
+   * the new bytes, or null when it already dropped the frame with its own
+   * reason. Any throw drops the frame; it is never emitted in the clear.
+   */
+  const finishEncode = async (
+    frame: EncodedFrame,
+    controller: FrameController,
+    produce: () => Promise<Uint8Array<ArrayBuffer> | null>,
+  ) => {
+    try {
+      const t0 = stats.startCrypto();
+      const out = await produce();
+      stats.endCrypto(t0);
+      if (!out) return;
+      frame.data = out.buffer;
+      controller.enqueue(frame);
+      notify.recovered();
+      stats.bump();
+    } catch (err: any) {
+      notify.failed(err?.message || String(err));
+    }
+  };
+
+  return new TransformStream<EncodedFrame, EncodedFrame>({
+    async transform(frame, controller) {
+      // No payload to encrypt.
+      if (frame.data.byteLength === 0) {
+        controller.enqueue(frame);
+        stats.bump();
+        return;
+      }
+
+      const entry = keyStore.getLatestKey(userId);
+      if (!entry) {
+        notifyMissingEncodeKey(userId);
+        return;
+      }
+
+      const { key: cryptoKey, keyIndex, ivPrefix: prefix } = entry;
+
+      return finishEncode(frame, controller, async () => {
+        // A key/delta type marks a video frame. An audio-only profile has no
+        // clear-byte rule for one, so drop it rather than ship a whole-frame,
+        // unescaped encrypt the SFU cannot read and a NALU packetizer would
+        // split. Checked before the counter, so a dropped frame costs no IV.
+        if (profile.audioOnly && frame.type !== undefined) {
+          notify.failed(`no clear-byte rule for video on codec ${codecKey}`);
+          return null;
+        }
+        const src = new Uint8Array(frame.data);
+        const clearBytes = profile.clearBytes(frame.type, src);
+        if (clearBytes > MAX_CLEAR_BYTES) {
+          // Writing this would overflow into the RBSP flag bit.
+          notify.failed('clearBytes exceeds trailer capacity');
+          return null;
+        }
+        // Throws at the 32-bit ceiling; finishEncode catches it, so the track
+        // fails closed instead of reusing an IV.
+        const counter = nextFrameCounter();
+        fillIV(iv, ivView, prefix, counter);
+        const aad = clearBytes > 0 ? src.subarray(0, clearBytes) : EMPTY_AAD;
+        const plaintext = clearBytes > 0 ? src.subarray(clearBytes) : src;
+        const encrypted = await crypto.subtle.encrypt(
+          { name: 'AES-GCM', iv, additionalData: aad as BufferSource },
+          cryptoKey,
+          plaintext as BufferSource,
+        );
+        const ciphertext = new Uint8Array(encrypted);
+        if (isNalu && clearBytes > 0) {
+          // Escape ciphertext and trailer as one unit: random ciphertext or
+          // the counter bytes could otherwise form a fake Annex-B start code
+          // that libwebrtc's H264 packetizer would split on. The escaper is
+          // seeded with the clear header's trailing zeros so a start code
+          // cannot form across the clear/encrypted boundary either.
+          //
+          // The last 7 trailer bytes survive escaping untouched: the RBSP flag
+          // holds the clearBytes high byte at >= 0x80, which breaks any zero
+          // run before it can reach them. The decoder reads them off the raw
+          // frame tail to locate the unit.
+          //
+          // Escaping straight behind the clear header copies the ciphertext
+          // once, instead of staging it through an intermediate unit buffer
+          // and copying it again.
+          const trailer = new Uint8Array(TRAILER_LEN);
+          writeTrailer(trailer, 0, counter, prefix, keyIndex, clearBytes, true);
+          const body = [ciphertext, trailer];
+          const seed = boundarySeedZeros(aad);
+          const dst = new Uint8Array(
+            clearBytes + rbspEscapedLength(body, seed),
+          );
+          dst.set(aad, 0);
+          rbspEscapeInto(dst, clearBytes, body, seed);
+          return dst;
+        }
+        const dst = new Uint8Array(
+          clearBytes + ciphertext.length + TRAILER_LEN,
+        );
+        if (clearBytes > 0) dst.set(aad, 0);
+        dst.set(ciphertext, clearBytes);
+        writeTrailer(
+          dst,
+          clearBytes + ciphertext.length,
+          counter,
+          prefix,
+          keyIndex,
+          clearBytes,
+          false,
+        );
+        return dst;
+      });
+    },
+  });
+};

package/src/rtc/e2ee/e2ee-worker/failureTracker.ts

@@ -0,0 +1,26 @@
+import { FAILURE_TOLERANCE } from './constants';
+
+/**
+ * Consecutive decryption failures on one track, keyed by keyIndex so a rotation
+ * starts fresh.
+ */
+export class FailureTracker {
+  private counts: Map<number, number> = new Map();
+
+  /**
+   * True only on the failure crossing {@link FAILURE_TOLERANCE}, so
+   * `e2ee.decryption_stalled` fires once per run.
+   */
+  recordFailure = (keyIndex: number): boolean => {
+    const next = (this.counts.get(keyIndex) ?? 0) + 1;
+    this.counts.set(keyIndex, next);
+    return next === FAILURE_TOLERANCE + 1;
+  };
+
+  /**
+   * True if there was a count to clear. Do NOT gate `e2ee.decryption_resumed`
+   * on it: that event names a track, not a key epoch, so a track recovering on
+   * a new keyIndex must still clear it.
+   */
+  recordSuccess = (keyIndex: number): boolean => this.counts.delete(keyIndex);
+}

package/src/rtc/e2ee/e2ee-worker/frameCounter.ts

@@ -0,0 +1,37 @@
+import { COUNTER_HARD_LIMIT } from './constants';
+
+/**
+ * Monotonic, and deliberately shared across every track and codec this sender
+ * publishes: the IV is `ivPrefix ∥ counter`, so two tracks drawing from
+ * separate counters would encrypt different frames under the same IV.
+ *
+ * Survives `removeAllKeys` on purpose - if the same raw key is imported again the
+ * counter keeps climbing, so no (ivPrefix, counter) pair repeats. Second guard
+ * against IV reuse, after the per-import random prefix.
+ */
+let counter = 0;
+
+export const nextFrameCounter = (): number => {
+  const next = counter + 1;
+  if (next > COUNTER_HARD_LIMIT) {
+    throw new Error('frame counter exhausted, create a new EncryptionManager');
+  }
+  counter = next;
+  return next;
+};
+
+/**
+ * @internal Test-only. Reaches counter values that would otherwise need 2^32
+ * frames. Unused in production, so the bundler drops it.
+ */
+export const __setFrameCounterForTest = (value: number) => {
+  counter = value;
+};
+
+/**
+ * @internal Test-only. Resets between test cases. Production teardown is
+ * `Worker.terminate()`, which reclaims the whole worker.
+ */
+export const __resetFrameCounterForTest = () => {
+  counter = 0;
+};

package/src/rtc/e2ee/e2ee-worker/keyStore.ts

@@ -0,0 +1,211 @@
+import { IV_PREFIX_LEN } from './constants';
+import { reportError } from './notifications';
+import type { ResolvedKey } from './types';
+
+/** Nested rather than a `"userId:keyIndex"` string key, which a colon in the
+ * userId would make ambiguous. */
+type UserKeyMap<V> = Map<string, Map<number, V>>;
+
+const getOrCreate = <V>(map: UserKeyMap<V>, userId: string): Map<number, V> => {
+  let inner = map.get(userId);
+  if (!inner) {
+    inner = new Map();
+    map.set(userId, inner);
+  }
+  return inner;
+};
+
+/** One imported key. Always written and deleted as a unit. */
+interface KeyMaterial {
+  key: CryptoKey;
+  /**
+   * Sender-side, fresh per import, so two imports of the same raw key get
+   * different prefixes and cannot reuse an IV. Receivers read the prefix off
+   * the frame trailer instead.
+   */
+  ivPrefix: Uint8Array;
+  /** First 8 bytes of SHA-256(rawKey). Not reversible, so safe to expose. */
+  fingerprint: Uint8Array;
+}
+
+const randomBytes = (n: number): Uint8Array => {
+  const bytes = new Uint8Array(n);
+  crypto.getRandomValues(bytes);
+  return bytes;
+};
+
+const fingerprint = async (rawKey: ArrayBuffer): Promise<Uint8Array> => {
+  const hash = await crypto.subtle.digest('SHA-256', rawKey);
+  return new Uint8Array(hash, 0, 8);
+};
+
+/**
+ * The buffer length picks the variant; EncryptionManager already validated it
+ * as 16 or 32 bytes. Passing `length` keeps WebCrypto unambiguous across
+ * browsers.
+ */
+const aesGcmParams = (rawKey: ArrayBuffer): AesKeyAlgorithm => ({
+  name: 'AES-GCM',
+  length: rawKey.byteLength * 8,
+});
+
+/**
+ * Import into a non-extractable CryptoKey, with a fresh random IV prefix and
+ * the fingerprint. The fresh prefix is what lets the same raw key be imported
+ * again without IV reuse.
+ */
+const importKeyMaterial = async (rawKey: ArrayBuffer): Promise<KeyMaterial> => {
+  const [key, fp] = await Promise.all([
+    crypto.subtle.importKey('raw', rawKey, aesGcmParams(rawKey), false, [
+      'encrypt',
+      'decrypt',
+    ]),
+    fingerprint(rawKey),
+  ]);
+  return { key, ivPrefix: randomBytes(IV_PREFIX_LEN), fingerprint: fp };
+};
+
+const toHex = (bytes: Uint8Array): string =>
+  Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+
+export class KeyStore {
+  private perUserKeys: UserKeyMap<KeyMaterial> = new Map();
+  private latestKeyIndex = new Map<string, number>();
+  /** Shared receive keys retained by epoch so in-flight frames survive rotation. */
+  private sharedKeys = new Map<number, KeyMaterial>();
+  /** The shared epoch used for encode fallback. Older retained epochs never win. */
+  private activeSharedKeyIndex: number | undefined;
+
+  /**
+   * Decryption key for (userId, keyIndex): per-user entry, else the shared key
+   * at that index. The keyIndex comes from the frame trailer.
+   */
+  getKey = (userId: string, keyIndex: number): CryptoKey | undefined => {
+    const perUser = this.perUserKeys.get(userId)?.get(keyIndex);
+    if (perUser) return perUser.key;
+    return this.sharedKeys.get(keyIndex)?.key;
+  };
+
+  /**
+   * The encode path's only lookup: latest per-user key, else the explicitly
+   * active shared key. Retained shared epochs are receive-only. The `ivPrefix`
+   * rides along so the encoder never resolves the same material twice.
+   */
+  getLatestKey = (
+    userId: string,
+  ): (ResolvedKey & { ivPrefix: Uint8Array }) | null => {
+    const idx = this.latestKeyIndex.get(userId);
+    if (idx !== undefined) {
+      const km = this.perUserKeys.get(userId)?.get(idx);
+      if (km) return { key: km.key, keyIndex: idx, ivPrefix: km.ivPrefix };
+    }
+    if (this.activeSharedKeyIndex === undefined) return null;
+    const shared = this.sharedKeys.get(this.activeSharedKeyIndex);
+    return shared
+      ? {
+          key: shared.key,
+          keyIndex: this.activeSharedKeyIndex,
+          ivPrefix: shared.ivPrefix,
+        }
+      : null;
+  };
+
+  importKey = async (userId: string, keyIndex: number, rawKey: ArrayBuffer) => {
+    try {
+      getOrCreate(this.perUserKeys, userId).set(
+        keyIndex,
+        await importKeyMaterial(rawKey),
+      );
+      this.latestKeyIndex.set(userId, keyIndex);
+    } catch (e: any) {
+      reportError(
+        `Failed to import key for user ${userId}: ${e?.message || e}`,
+      );
+    }
+  };
+
+  importSharedKey = async (keyIndex: number, rawKey: ArrayBuffer) => {
+    try {
+      const material = await importKeyMaterial(rawKey);
+      this.sharedKeys.set(keyIndex, material);
+      this.activeSharedKeyIndex = keyIndex;
+    } catch (e: any) {
+      reportError(`Failed to import shared key: ${e?.message || e}`);
+    }
+  };
+
+  /**
+   * Retire exactly one of a user's epochs, leaving the rest usable.
+   *
+   * Clearing `latestKeyIndex` along with the slot is load-bearing. Left on a
+   * removed index, {@link getLatestKey} resolves nothing there and falls
+   * through to the active shared epoch, so the local user's frames would
+   * quietly move from a key only they hold to one every participant holds. No
+   * older epoch is promoted either, matching {@link removeSharedKey}.
+   */
+  removeKey = (userId: string, keyIndex: number) => {
+    const perKeyIndex = this.perUserKeys.get(userId);
+    if (!perKeyIndex?.delete(keyIndex)) return;
+    if (perKeyIndex.size === 0) this.perUserKeys.delete(userId);
+    if (this.latestKeyIndex.get(userId) === keyIndex) {
+      this.latestKeyIndex.delete(userId);
+    }
+  };
+
+  /**
+   * Leaves the frame counters intact on purpose: a reset counter would reuse
+   * IVs if the same raw key is imported again later. They live in
+   * `frameCounter.ts`, so this cannot reach them even by accident.
+   */
+  removeAllKeys = (userId: string) => {
+    this.perUserKeys.delete(userId);
+    this.latestKeyIndex.delete(userId);
+  };
+
+  /**
+   * Removes exactly one shared receive epoch. Removing the active epoch also
+   * disables shared-key encode fallback; an older epoch is never reactivated
+   * implicitly because doing so could resume sending with a retired key.
+   */
+  removeSharedKey = (keyIndex: number) => {
+    this.sharedKeys.delete(keyIndex);
+    if (this.activeSharedKeyIndex === keyIndex) {
+      this.activeSharedKeyIndex = undefined;
+    }
+  };
+
+  /**
+   * Debug snapshot. Fingerprints only: enough to confirm a sender and receiver
+   * hold matching key material, and it exposes no key.
+   */
+  keyState = () => ({
+    perUserKeys: Array.from(this.perUserKeys).flatMap(([userId, perKeyIndex]) =>
+      Array.from(perKeyIndex, ([keyIndex, km]) => ({
+        userId,
+        keyIndex,
+        fingerprint: toHex(km.fingerprint),
+      })),
+    ),
+    sharedKeys: Array.from(this.sharedKeys, ([keyIndex, material]) => ({
+      keyIndex,
+      fingerprint: toHex(material.fingerprint),
+      isActive: keyIndex === this.activeSharedKeyIndex,
+    })),
+  });
+
+  /**
+   * @internal Test-only. Production teardown is `Worker.terminate()`, which
+   * reclaims the whole worker.
+   */
+  clear = () => {
+    this.perUserKeys.clear();
+    this.latestKeyIndex.clear();
+    this.sharedKeys.clear();
+    this.activeSharedKeyIndex = undefined;
+  };
+}
+
+/** The worker has exactly one. */
+export const keyStore = new KeyStore();

package/src/rtc/e2ee/e2ee-worker/notifications.ts

@@ -0,0 +1,190 @@
+/** At most one notification per second per key. */
+const THROTTLE_INTERVAL_MS = 1000;
+
+/**
+ * Rate limiter keyed by an arbitrary string, so one throttle can cover several
+ * independent conditions (a keyIndex, a userId) without them muting each other.
+ *
+ * Lives here because throttling is a delivery rule, not a general utility -
+ * every user of it is in this file.
+ */
+class Throttle {
+  private readonly intervalMs: number;
+  private lastFiredAt: Map<string, number> = new Map();
+
+  constructor(intervalMs: number) {
+    this.intervalMs = intervalMs;
+  }
+
+  /**
+   * True at most once per `intervalMs` for that key, so a sustained failure
+   * cannot flood the host with notifications.
+   */
+  tryFire = (key: string): boolean => {
+    const now = Date.now();
+    if (now - (this.lastFiredAt.get(key) ?? 0) > this.intervalMs) {
+      this.lastFiredAt.set(key, now);
+      return true;
+    }
+    return false;
+  };
+}
+
+/**
+ * Internal log-only channel: no `E2EEEventMap` entry, so the manager logs it
+ * rather than emitting it to the host.
+ */
+export const reportError = (message: string): void => {
+  self.postMessage({ type: 'e2ee.error', message });
+};
+
+/**
+ * The encoder holds no key, so every outgoing frame is dropped. Without this
+ * the host just sees black video with nothing to act on. Throttled per user,
+ * and stops on its own once a key arrives.
+ *
+ * Module-scoped rather than per transform: this condition is per user by
+ * definition, so every track sharing one throttle is the point.
+ */
+const missingKeyThrottle = new Throttle(THROTTLE_INTERVAL_MS);
+export const notifyMissingEncodeKey = (userId: string): void => {
+  if (missingKeyThrottle.tryFire(userId)) {
+    self.postMessage({ type: 'e2ee.missing_key', userId });
+  }
+};
+
+/** Encode-side signals for one track. */
+export class EncodeNotifier {
+  private readonly userId: string;
+  private readonly trackType: string | undefined;
+  /** True once a failure was reported, until {@link recovered} re-arms it. */
+  private latched = false;
+
+  constructor(userId: string, trackType: string | undefined) {
+    this.userId = userId;
+    this.trackType = trackType;
+  }
+
+  /** First failure of a run; silent until {@link recovered} re-arms it. */
+  failed = (reason: string): void => {
+    if (this.latched) return;
+    this.latched = true;
+    self.postMessage({
+      type: 'e2ee.encryption_failed',
+      userId: this.userId,
+      trackType: this.trackType,
+      reason,
+    });
+  };
+
+  /**
+   * A frame encrypted again, so the next failure is worth reporting. Re-arming
+   * is deliberate: it stops one early transient error from hiding a later
+   * permanent one, such as the frame-counter hard limit.
+   */
+  recovered = (): void => {
+    this.latched = false;
+  };
+}
+
+/**
+ * Decode-side signals for one track.
+ *
+ * One notifier is one track, so `userId` is constant: each throttle holds a
+ * single entry and limits that track alone.
+ */
+export class DecodeNotifier {
+  private readonly userId: string;
+  private readonly trackType: string | undefined;
+  private readonly failureThrottle = new Throttle(THROTTLE_INTERVAL_MS);
+  /**
+   * A key in flight, or a rotation whose keyIndex has not arrived, are both
+   * normal. Keyed by keyIndex: one signal per key epoch.
+   */
+  private readonly missingKeyThrottle = new Throttle(THROTTLE_INTERVAL_MS);
+  private readonly cleartextThrottle = new Throttle(THROTTLE_INTERVAL_MS);
+  /**
+   * Keyed by user, deliberately not by version. A sender's version is a
+   * compile-time constant, so a track only ever sees one value legitimately -
+   * while the byte is plaintext, so a relay rewriting it per frame would
+   * otherwise get one event per distinct value and multiply the rate by 255.
+   */
+  private readonly versionThrottle = new Throttle(THROTTLE_INTERVAL_MS);
+  /**
+   * True once a `decryption_failed` reached the host. Pairs the two signals:
+   * only a delivered failure needs clearing, and clearing it re-arms this.
+   */
+  private failureReported = false;
+
+  constructor(userId: string, trackType: string | undefined) {
+    this.userId = userId;
+    this.trackType = trackType;
+  }
+
+  /** GCM tag failure. Throttled; records that a failure reached the host. */
+  failed = (): void => {
+    if (!this.failureThrottle.tryFire(this.userId)) return;
+    this.failureReported = true;
+    self.postMessage({
+      type: 'e2ee.decryption_failed',
+      userId: this.userId,
+      trackType: this.trackType,
+    });
+  };
+
+  /** Paired with {@link failed}: no-op unless a failure was delivered. */
+  resumed = (): void => {
+    if (!this.failureReported) return;
+    this.failureReported = false;
+    self.postMessage({
+      type: 'e2ee.decryption_resumed',
+      userId: this.userId,
+      trackType: this.trackType,
+    });
+  };
+
+  /** A frame named a key this peer does not hold. Throttled per keyIndex. */
+  missingKey = (keyIndex: number): void => {
+    if (!this.missingKeyThrottle.tryFire(String(keyIndex))) return;
+    self.postMessage({
+      type: 'e2ee.missing_key',
+      userId: this.userId,
+      trackType: this.trackType,
+      keyIndex,
+    });
+  };
+
+  /**
+   * A frame carried this format but a version this build cannot decrypt, so it
+   * was dropped. Throttled per track.
+   */
+  unsupportedVersion = (version: number): void => {
+    if (!this.versionThrottle.tryFire(this.userId)) return;
+    self.postMessage({
+      type: 'e2ee.unsupported_version',
+      userId: this.userId,
+      trackType: this.trackType,
+      version,
+    });
+  };
+
+  /** A frame carried no E2EE framing and was forwarded as-is. Throttled. */
+  unencrypted = (): void => {
+    if (!this.cleartextThrottle.tryFire(this.userId)) return;
+    self.postMessage({
+      type: 'e2ee.unencrypted_frame',
+      userId: this.userId,
+      trackType: this.trackType,
+    });
+  };
+
+  /** Consecutive failures crossed the tolerance. Already once-per-run. */
+  stalled = (keyIndex: number): void => {
+    self.postMessage({
+      type: 'e2ee.decryption_stalled',
+      userId: this.userId,
+      trackType: this.trackType,
+      keyIndex,
+    });
+  };
+}