@stream-io/video-client 1.57.0 → 1.59.0

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

@@ -0,0 +1,129 @@
+/** Labels a perf sample carries. `codec` is known on the encode side only. */
+type StatLabels = { userId: string; trackType: string; codec?: string };
+
+/** Accumulator for one track, reset by each {@link StatsRegistry.flush}. */
+type StatEntry = StatLabels & { count: number; maxCryptoMs: number };
+
+/** One track's rates, as reported to the host. */
+type StatSample = StatLabels & { fps: number; maxCryptoMs: number };
+
+/**
+ * Whether reporting is on. Module-scoped rather than per registry: the worker
+ * has exactly one of each, and a single flag keeps encode and decode from
+ * drifting apart.
+ */
+let perfEnabled = false;
+let perfInterval: ReturnType<typeof setInterval> | null = null;
+let perfLastTick = 0;
+
+/**
+ * Counter handle for one track, held by that track's transform for its
+ * lifetime. Every method no-ops while reporting is off.
+ */
+class TrackStats {
+  private stats: Map<string, StatEntry>;
+  private readonly key: string;
+  private readonly labels: StatLabels;
+
+  constructor(stats: Map<string, StatEntry>, key: string, labels: StatLabels) {
+    this.stats = stats;
+    this.key = key;
+    this.labels = labels;
+  }
+
+  /**
+   * This track's accumulator, created on first use. Lazy on purpose: the entry
+   * is what puts a row in the next report, so a track that goes idle after a
+   * flush drops out instead of reporting 0 fps forever.
+   */
+  private entry = (): StatEntry | undefined => {
+    if (!perfEnabled) return undefined;
+    let stat = this.stats.get(this.key);
+    if (!stat) {
+      stat = { ...this.labels, count: 0, maxCryptoMs: 0 };
+      this.stats.set(this.key, stat);
+    }
+    return stat;
+  };
+
+  /** Count one frame through the transform. */
+  bump = (): void => {
+    const stat = this.entry();
+    if (stat) stat.count++;
+  };
+
+  /** Timestamp to hand back to {@link endCrypto}; 0 while disabled. */
+  startCrypto = (): number => (perfEnabled ? performance.now() : 0);
+
+  endCrypto = (startedAt: number): void => {
+    const stat = this.entry();
+    if (!stat) return;
+    stat.maxCryptoMs = Math.max(
+      stat.maxCryptoMs,
+      performance.now() - startedAt,
+    );
+  };
+}
+
+/**
+ * Per-track counters for one direction. The key is unique per track, so a vp8
+ * camera and a vp8 screen share (encode), or a peer's audio and video (decode),
+ * are reported apart instead of summed.
+ */
+class StatsRegistry {
+  private stats: Map<string, StatEntry> = new Map();
+
+  track = (key: string, labels: StatLabels): TrackStats =>
+    new TrackStats(this.stats, key, labels);
+
+  /** Drain all accumulators into per-track rates. */
+  flush = (dtSec: number): StatSample[] => {
+    const samples = Array.from(
+      this.stats.values(),
+      ({ count, maxCryptoMs, ...labels }) => ({
+        ...labels,
+        fps: count / dtSec,
+        maxCryptoMs,
+      }),
+    );
+    this.stats.clear();
+    return samples;
+  };
+
+  clear = (): void => this.stats.clear();
+
+  removeUser = (userId: string): void => {
+    for (const [key, stat] of this.stats) {
+      if (stat.userId === userId) this.stats.delete(key);
+    }
+  };
+}
+
+export const encodeStats = new StatsRegistry();
+export const decodeStats = new StatsRegistry();
+
+export const startPerfReport = () => {
+  if (perfInterval) return; // a second interval would leak
+  perfEnabled = true;
+  perfLastTick = performance.now();
+  perfInterval = setInterval(() => {
+    const now = performance.now();
+    const dtSec = Math.max(0.001, (now - perfLastTick) / 1000);
+    perfLastTick = now;
+    self.postMessage({
+      type: 'e2ee.perf_report',
+      encode: encodeStats.flush(dtSec),
+      decode: decodeStats.flush(dtSec),
+    });
+  }, 1000);
+};
+
+export const stopPerfReport = () => {
+  perfEnabled = false;
+  if (perfInterval) {
+    clearInterval(perfInterval);
+    perfInterval = null;
+  }
+  encodeStats.clear();
+  decodeStats.clear();
+};

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

@@ -0,0 +1,12 @@
+let tail: Promise<unknown> = Promise.resolve();
+
+/**
+ * Run tasks FIFO, one at a time, so a `setKey` cannot race transform setup.
+ * `tail` swallows errors so one rejection cannot stall the queue; the returned
+ * promise still carries that task's own outcome.
+ */
+export const enqueue = <T>(fn: () => Promise<T>): Promise<T> => {
+  const run = tail.then(fn);
+  tail = run.catch(() => {});
+  return run;
+};

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

@@ -0,0 +1,131 @@
+import { REPLAY_WINDOW } from './constants';
+
+/** Length-safe byte comparison, for matching a frame's prefix to an epoch. */
+const bytesEqual = (a: Uint8Array, b: Uint8Array): boolean => {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+};
+
+const REPLAY_WINDOW_WORDS = REPLAY_WINDOW >>> 5;
+
+/**
+ * One sender IV-prefix epoch: a high-water mark plus a bitmap over the
+ * preceding {@link REPLAY_WINDOW} counters, where bit `counter % REPLAY_WINDOW`
+ * marks a seen counter. O(1) checks and in-order advance, where a `Set` would
+ * need an O(REPLAY_WINDOW) prune per frame.
+ */
+class ReplayEpoch {
+  /** Copied, since the caller's view points into a frame buffer that is reused. */
+  readonly prefix: Uint8Array;
+  private highest: number;
+  private bitmap: Uint32Array = new Uint32Array(REPLAY_WINDOW_WORDS);
+
+  constructor(prefix: Uint8Array, counter: number) {
+    this.prefix = prefix.slice();
+    this.highest = counter;
+    this.mark(counter);
+  }
+
+  /** Above the high-water mark, or inside the window and not yet seen. */
+  accepts = (counter: number): boolean => {
+    if (counter > this.highest) return true;
+    if (counter <= this.highest - REPLAY_WINDOW) return false;
+    return !this.isMarked(counter);
+  };
+
+  record = (counter: number): void => {
+    if (counter > this.highest) {
+      // Slots repeat every REPLAY_WINDOW counters, so skipped ones can hold a
+      // stale bit and must be cleared. In-order frames skip none; a large jump
+      // makes the whole bitmap stale.
+      if (counter - this.highest >= REPLAY_WINDOW) {
+        this.bitmap.fill(0);
+      } else {
+        for (let c = this.highest + 1; c < counter; c++) this.clear(c);
+      }
+      this.highest = counter;
+    }
+    this.mark(counter);
+  };
+
+  private slot = (counter: number) => {
+    const idx = counter % REPLAY_WINDOW;
+    return { word: idx >>> 5, mask: 1 << (idx & 31) };
+  };
+
+  private isMarked = (counter: number): boolean => {
+    const { word, mask } = this.slot(counter);
+    return (this.bitmap[word] & mask) !== 0;
+  };
+
+  private mark = (counter: number): void => {
+    const { word, mask } = this.slot(counter);
+    this.bitmap[word] |= mask;
+  };
+
+  private clear = (counter: number): void => {
+    const { word, mask } = this.slot(counter);
+    this.bitmap[word] &= ~mask;
+  };
+}
+
+/**
+ * Sender IV-prefix "epochs" one track's guard keeps. One is normal; a second or
+ * third appears briefly around a key re-import or sender restart, while old and
+ * new prefixes interleave in the jitter buffer.
+ *
+ * Eviction is safe because the sender never reuses an (ivPrefix, counter) pair.
+ * Only `commit` creates and evicts epochs, and only authenticated frames reach
+ * it, so a relay cannot forge new-prefix frames to evict a genuine epoch.
+ */
+const REPLAY_EPOCHS = 3;
+
+/**
+ * Replay guard for one remote track.
+ *
+ * Shared across tracks it would couple them: independent SSRCs and jitter
+ * buffers mean delivery skew could advance the high-water mark far enough to
+ * reject a lagging track's frames, dropping media and reporting false failures.
+ *
+ * Inside a track the sender's IV prefix partitions the window further, so a
+ * sender restart (fresh prefix, counter near 0) opens a clean window instead of
+ * losing its low counters to a stale mark.
+ *
+ * Only receive-side bookkeeping is per track. The sender's counter stays global
+ * per user (see `frameCounter.ts`), which is what keeps IVs unique across a
+ * user's tracks and the wire format identical for other SDKs.
+ */
+export class ReplayWindow {
+  private epochs: ReplayEpoch[] = [];
+
+  private find = (ivPrefix: Uint8Array): ReplayEpoch | undefined =>
+    this.epochs.find((e) => bytesEqual(e.prefix, ivPrefix));
+
+  /**
+   * True when this prefix can accept `counter`: new prefix, above the
+   * high-water mark, or inside the window and not yet committed.
+   *
+   * Changes no state. A relay can forge the trailer fields this reads, so only
+   * an authenticated frame advances the window. See {@link commit}.
+   */
+  peek = (counter: number, ivPrefix: Uint8Array): boolean => {
+    // A prefix with no committed frame yet opens a clean window.
+    return this.find(ivPrefix)?.accepts(counter) ?? true;
+  };
+
+  /**
+   * Record `counter` as seen, advancing the high-water mark. Call it only after
+   * AES-GCM authenticates, so unauthenticated bytes cannot wedge the window or
+   * evict a genuine epoch.
+   */
+  commit = (counter: number, ivPrefix: Uint8Array): void => {
+    const epoch = this.find(ivPrefix);
+    if (epoch) {
+      epoch.record(counter);
+      return;
+    }
+    this.epochs.unshift(new ReplayEpoch(ivPrefix, counter));
+    if (this.epochs.length > REPLAY_EPOCHS) this.epochs.pop();
+  };
+}

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

@@ -0,0 +1,155 @@
+/**
+ * The on-wire framing: the 20-byte trailer appended to every encrypted frame,
+ * and the 12-byte IV both directions derive.
+ *
+ * Write and read live together on purpose. They are one contract - the encoder
+ * lays out bytes the decoder must find at the same offsets - so the layout is
+ * defined once, here, and a change to it is a wire break: bump
+ * {@link E2EE_VERSION} and regenerate the SPEC section 11 vectors.
+ *
+ * Layout, from the trailer's first byte:
+ *   [4B frameCounter][8B ivPrefix][1B keyIndex][2B clearBytes|flags]
+ *   [1B version][4B magic]
+ */
+
+import {
+  E2EE_VERSION,
+  FRAME_COUNTER_LEN,
+  IV_PREFIX_LEN,
+  MAGIC,
+  MAX_CLEAR_BYTES,
+  RBSP_FLAG,
+  TRAILER_LEN,
+} from './constants';
+import type { Trailer } from './types';
+
+const OFF_IV_PREFIX = FRAME_COUNTER_LEN; // 4
+const OFF_KEY_INDEX = OFF_IV_PREFIX + IV_PREFIX_LEN; // 12
+const OFF_CLEAR_BYTES = OFF_KEY_INDEX + 1; // 13
+const OFF_VERSION = OFF_CLEAR_BYTES + 2; // 15
+const OFF_MAGIC = OFF_VERSION + 1; // 16
+
+/**
+ * Fill a pre-allocated 12-byte IV: `[8B ivPrefix][4B frameCounter, BE]`.
+ *
+ * The encoder builds it from its own prefix and counter; the decoder rebuilds
+ * the identical bytes from the trailer. The buffer is reused across frames
+ * rather than allocated per frame - this runs once per frame on every track.
+ */
+export const fillIV = (
+  iv: Uint8Array,
+  ivView: DataView,
+  prefix: Uint8Array,
+  frameCounter: number,
+) => {
+  iv.set(prefix, 0);
+  ivView.setUint32(IV_PREFIX_LEN, frameCounter);
+};
+
+export const writeTrailer = (
+  dst: Uint8Array,
+  offset: number,
+  frameCounter: number,
+  ivPrefix: Uint8Array,
+  keyIndex: number,
+  clearBytes: number,
+  isRbsp: boolean,
+) => {
+  if (clearBytes > MAX_CLEAR_BYTES) {
+    throw new Error(
+      `clearBytes ${clearBytes} exceeds 15-bit max ${MAX_CLEAR_BYTES}`,
+    );
+  }
+  if (ivPrefix.length !== IV_PREFIX_LEN) {
+    throw new Error(
+      `ivPrefix must be ${IV_PREFIX_LEN} bytes, got ${ivPrefix.length}`,
+    );
+  }
+  const view = new DataView(dst.buffer, dst.byteOffset, dst.byteLength);
+  view.setUint32(offset, frameCounter);
+  dst.set(ivPrefix, offset + OFF_IV_PREFIX);
+  dst[offset + OFF_KEY_INDEX] = keyIndex;
+  view.setUint16(
+    offset + OFF_CLEAR_BYTES,
+    isRbsp ? clearBytes | RBSP_FLAG : clearBytes,
+  );
+  dst[offset + OFF_VERSION] = E2EE_VERSION;
+  view.setUint32(offset + OFF_MAGIC, MAGIC);
+};
+
+/**
+ * IV fields only, from an already-recognized trailer. An H264 RBSP frame
+ * escapes these three with the ciphertext, so un-escape the unit before
+ * calling this.
+ */
+export const readTrailerIv = (
+  buf: Uint8Array,
+): Pick<Trailer, 'frameCounter' | 'ivPrefix' | 'keyIndex'> => {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  const start = buf.length - TRAILER_LEN;
+  return {
+    frameCounter: view.getUint32(start),
+    ivPrefix: buf.subarray(start + OFF_IV_PREFIX, start + OFF_KEY_INDEX),
+    keyIndex: buf[start + OFF_KEY_INDEX],
+  };
+};
+
+/**
+ * The frozen identification suffix: `version (1) || magic (4)`. A literal, not
+ * `TRAILER_LEN - OFF_VERSION`, because this length is frozen at 5 for every
+ * version present and future while those two constants describe v1 only - a
+ * later layout change must break the round-trip test, not silently move the
+ * suffix older receivers depend on. `trailer.test.ts` pins it to the bytes
+ * `writeTrailer` actually emits.
+ *
+ * Read from the end rather than from a trailer start, because a future version
+ * may not use a 20-byte trailer, and a receiver that cannot decrypt such a
+ * frame still has to recognize it.
+ */
+const IDENT_SUFFIX_LEN = 5;
+/** Within the suffix: the magic follows the single version byte. */
+const OFF_SUFFIX_MAGIC = 1;
+
+/**
+ * The framing version of a frame carrying this format, or `null` if the frame
+ * is not ours at all.
+ *
+ * This is what separates the two reasons {@link readTrailer} returns `null`:
+ * an unrelated cleartext frame, versus an encrypted frame from a peer on a
+ * version this build cannot decrypt.
+ *
+ * @param view - An existing view over exactly `src`, to avoid a second
+ * allocation on the per-frame decode path. Built here when omitted.
+ */
+export const readFramingVersion = (
+  src: Uint8Array,
+  view?: DataView,
+): number | null => {
+  if (src.length < IDENT_SUFFIX_LEN) return null;
+  const bytes =
+    view ?? new DataView(src.buffer, src.byteOffset, src.byteLength);
+  const start = src.length - IDENT_SUFFIX_LEN;
+  if (bytes.getUint32(start + OFF_SUFFIX_MAGIC) !== MAGIC) return null;
+  return src[start];
+};
+
+export const readTrailer = (src: Uint8Array): Trailer | null => {
+  if (src.length < TRAILER_LEN) return null;
+  const view = new DataView(src.buffer, src.byteOffset, src.byteLength);
+  if (readFramingVersion(src, view) !== E2EE_VERSION) return null;
+  const start = src.length - TRAILER_LEN;
+  const raw = view.getUint16(start + OFF_CLEAR_BYTES);
+  const clearBytes = raw & MAX_CLEAR_BYTES;
+  // Bail out before allocating; the decrypt would fail anyway.
+  if (clearBytes > src.length - TRAILER_LEN) return null;
+  // The last 7 bytes survive escaping untouched: the RBSP flag holds the
+  // clearBytes high byte >= 0x80 and breaks any zero run. The three below are
+  // valid only on a non-RBSP frame; see {@link readTrailerIv}.
+  return {
+    frameCounter: view.getUint32(start),
+    ivPrefix: src.subarray(start + OFF_IV_PREFIX, start + OFF_KEY_INDEX),
+    keyIndex: src[start + OFF_KEY_INDEX],
+    clearBytes,
+    isRbsp: (raw & RBSP_FLAG) !== 0,
+  };
+};

package/src/rtc/e2ee/e2ee-worker/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@stream-io/typescript-config/library-web.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "lib": ["ES2022", "WebWorker"]
+  },
+  "include": ["./**/*.ts"]
+}

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

@@ -0,0 +1,29 @@
+/** Minimal shape of an RTCEncodedVideo/AudioFrame. */
+export interface EncodedFrame {
+  data: ArrayBuffer;
+  /** Absent on audio: the lack of a key/delta type is how audio is recognized. */
+  type?: 'key' | 'delta' | 'empty';
+  timestamp: number;
+}
+
+/** The subset of TransformStreamDefaultController the transforms use. */
+export type FrameController = {
+  enqueue(frame: EncodedFrame): void;
+  terminate(): void;
+};
+
+/** A resolved encryption key paired with its rotation index. */
+export interface ResolvedKey {
+  key: CryptoKey;
+  keyIndex: number;
+}
+
+/** Parsed 20-byte frame trailer appended to every encrypted frame (v1). */
+export interface Trailer {
+  frameCounter: number;
+  /** View of the 8-byte IV prefix inside the source frame buffer. */
+  ivPrefix: Uint8Array;
+  keyIndex: number;
+  clearBytes: number;
+  isRbsp: boolean;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * E2EE worker. The build populates it.
+ *
+ * The actual implementation lives in `e2ee-worker/e2ee-worker-impl.ts` and its
+ * sibling modules (`constants.ts`, `codec.ts`, `crypto.ts`, `utils.ts`,
+ * `types.ts`), all written as real TypeScript with full type checking
+ * and import support.
+ *
+ * ## How it works
+ *
+ * 1. You edit files in `e2ee-worker/` as normal TypeScript
+ * 2. `yarn build` runs Rollup, which invokes `rollup-plugin-inline-worker`
+ * 3. The plugin bundles `e2ee-worker/e2ee-worker-impl.ts` (and its imports)
+ *    into a single function via a nested Rollup + TypeScript build
+ * 4. The function replaces this file's export at build time
+ * 5. `EncryptionManager.create()` creates a Worker from `e2eeWorker.toString()`
+ *
+ * In tests, this module is mocked (see `__tests__/EncryptionManager.test.ts`),
+ * so the placeholder is never evaluated.
+ *
+ * @see e2ee-worker/e2ee-worker-impl.ts - the entry point
+ * @see ../../plugins/rollup-plugin-inline-worker.ts - the Rollup plugin
+ * @see EncryptionManager.ts - consumes e2eeWorker
+ */
+export function e2eeWorker() {
+  // will be populated at build time
+}

package/src/rtc/e2ee/events.ts

@@ -0,0 +1,179 @@
+/**
+ * Throughput sample for one track. `userId` is the local sender on encode, the
+ * remote sender on decode. The (userId, trackType) pair keeps a peer's audio
+ * and video reported apart instead of summed.
+ */
+export type TrackPerf = {
+  userId: string;
+  trackType: string;
+  fps: number;
+  maxCryptoMs: number;
+};
+
+/**
+ * Encode entries carry the `codec` the publisher knows; decode entries cannot,
+ * since a remote sender's codec is not reliably known locally.
+ */
+export type PerfReport = {
+  encode: (TrackPerf & { codec: string })[];
+  decode: TrackPerf[];
+};
+
+/**
+ * Fired when a needed key is not held. The `keyIndex` tells the two cases apart:
+ *
+ * - Without it, the local encoder has no key and drops every outgoing frame.
+ *   The host never provided a key, or a key import failed.
+ * - With it, a remote sender's frame named a key this peer does not hold, so
+ *   the frame was dropped. This is normal while a key is in flight, or while a
+ *   rotation propagates.
+ */
+export type MissingKeyEvent = {
+  /** The local user, or the remote sender. */
+  userId: string;
+  /** Decode direction only; absent when the local encoder has no key. */
+  keyIndex?: number;
+  /**
+   * Decode direction only, which reports per track: a peer's tracks can sit on
+   * different key epochs, so one may stall while another plays. The encode
+   * direction stops every outgoing track at once and is reported per user.
+   */
+  trackType?: string;
+};
+
+/**
+ * A remote frame arrived unencrypted and went to the decoder as-is. Expected
+ * when the call's mode is `available` and that peer publishes plain; where every
+ * peer must encrypt, it means media renders without authentication.
+ */
+export type UnencryptedFrameEvent = {
+  userId: string;
+  trackType?: string;
+};
+
+/**
+ * A remote frame carried this format's framing but a `version` this build
+ * cannot decrypt, so it was dropped.
+ *
+ * **This client is the one that needs updating**, not the peer: the peer wrote
+ * a newer format than this SDK implements. Prompt the local user to update the
+ * app; no key changes anything.
+ */
+export type UnsupportedVersionEvent = {
+  userId: string;
+  trackType?: string;
+  /** The framing version read from the frame. */
+  version: number;
+};
+
+/** The worker could not decrypt a remote frame. Throttled per track. */
+export type DecryptionFailedEvent = {
+  userId: string;
+  trackType?: string;
+};
+
+/**
+ * Fired when a track decrypts again after a reported failure. See
+ * {@link E2EEEventMap} for how it pairs with `e2ee.decryption_failed`.
+ */
+export type DecryptionResumedEvent = {
+  userId: string;
+  trackType?: string;
+};
+
+/**
+ * An outgoing frame could not be encrypted, so that track publishes nothing.
+ * Latched per track, so a permanently failing track reports once.
+ */
+export type EncryptionFailedEvent = {
+  userId: string;
+  /** Only this track is affected; the sender's others keep publishing. */
+  trackType?: string;
+  /** Short, human-readable reason. */
+  reason: string;
+};
+
+/**
+ * Fired when a remote track passes the internal failure tolerance: decryption
+ * has failed on that many consecutive frames, so the track renders nothing until
+ * it recovers. The cause is not known here: a key mismatch is the common one,
+ * but a tampered or truncated frame looks the same to the decryptor.
+ */
+export type DecryptionStalledEvent = {
+  userId: string;
+  /** The keyIndex that crossed the tolerance. */
+  keyIndex: number;
+  trackType?: string;
+};
+
+/**
+ * Answer to {@link EncryptionManager.requestKeyState}. `fingerprint` is hex of
+ * the first 8 bytes of SHA-256(rawKey): not reversible, so safe to log. Key
+ * material is never returned.
+ */
+export type KeyStateReport = {
+  perUserKeys: Array<{
+    userId: string;
+    keyIndex: number;
+    fingerprint: string;
+  }>;
+  /** Every shared receive epoch, including the one currently used to encode. */
+  sharedKeys: Array<{
+    keyIndex: number;
+    fingerprint: string;
+    isActive: boolean;
+  }>;
+};
+
+/**
+ * Events that the E2EE {@link EncryptionManager} emits.
+ *
+ * Subscribe with `manager.on(eventName, handler)`. To unsubscribe, call the
+ * function it returns, or `manager.off(eventName, handler)`.
+ *
+ * Every name follows the `e2ee.<snake_case>` convention. That makes them easy
+ * to grep, and keeps them distinct from SFU and coordinator events.
+ */
+export type E2EEEventMap = {
+  /** Key mismatch, rotation in progress, or a tampered frame. */
+  'e2ee.decryption_failed': DecryptionFailedEvent;
+
+  /**
+   * Pairs one-to-one with `e2ee.decryption_failed` and is never throttled, so a
+   * host can drive its UI from the pair alone. Also fires for a track that
+   * recovers on a new keyIndex.
+   */
+  'e2ee.decryption_resumed': DecryptionResumedEvent;
+
+  /**
+   * Consecutive decrypt failures on one track crossed the internal tolerance.
+   * Fires once per (userId, keyIndex) entering that state, and
+   * `e2ee.decryption_resumed` is what clears it.
+   */
+  'e2ee.decryption_stalled': DecryptionStalledEvent;
+
+  /** That track is publishing nothing. Latched, so it reports once. */
+  'e2ee.encryption_failed': EncryptionFailedEvent;
+
+  /**
+   * The host must set or distribute a key. Distinct from
+   * `e2ee.encryption_failed`, where a key was present but the crypto threw.
+   * Throttled, and stops once the key arrives.
+   */
+  'e2ee.missing_key': MissingKeyEvent;
+
+  'e2ee.unencrypted_frame': UnencryptedFrameEvent;
+
+  /**
+   * A peer is publishing a framing version this build cannot read, so its
+   * frames are dropped. Throttled per track; surface it as a prompt to update
+   * **this** client.
+   */
+  'e2ee.unsupported_version': UnsupportedVersionEvent;
+
+  /** Once per second while {@link EncryptionManager.enablePerformanceReporting} is on. */
+  'e2ee.perf_report': PerfReport;
+
+  /** Answer to {@link EncryptionManager.requestKeyState}. */
+  'e2ee.key_state': KeyStateReport;
+};