@stream-io/video-client 1.56.0 → 1.58.0

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

@@ -0,0 +1,65 @@
+import '../../__tests__/mocks/webrtc.mocks';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { preferredTransform } from '../transformSupport';
+import { isChrome } from '../../../helpers/browsers';
+
+// Mock browser detection so we can drive the Chrome vs non-Chrome transform
+// selection deterministically. Defaults to non-Chrome (reset in beforeEach).
+vi.mock('../../../helpers/browsers', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('../../../helpers/browsers')>();
+  return { ...actual, isChrome: vi.fn().mockReturnValue(false) };
+});
+
+describe('preferredTransform', () => {
+  const setInsertableStreams = (available: boolean) => {
+    if (available) {
+      Object.assign(RTCRtpSender.prototype, {
+        createEncodedStreams: vi.fn(),
+      });
+    } else {
+      // @ts-expect-error - cleaning up non-standard property from mock prototype
+      delete RTCRtpSender.prototype.createEncodedStreams;
+    }
+  };
+
+  beforeEach(() => {
+    vi.mocked(isChrome).mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    // @ts-expect-error - cleaning up non-standard property from mock prototype
+    delete RTCRtpSender.prototype.createEncodedStreams;
+  });
+
+  const setScriptTransform = (available: boolean) => {
+    if (available) return;
+    const original = globalThis.RTCRtpScriptTransform;
+    delete globalThis.RTCRtpScriptTransform;
+    return () => {
+      globalThis.RTCRtpScriptTransform = original;
+    };
+  };
+
+  // The whole selection policy is this matrix. Chrome is pinned to Insertable
+  // Streams wherever it exists, because its RTCRtpScriptTransform is still
+  // unreliable for E2EE; everything else prefers the standard API.
+  it.each([
+    ['chrome', true, true, true, 'insertable'],
+    ['chrome, no insertable streams', true, false, true, 'script'],
+    ['chrome, neither API', true, false, false, undefined],
+    ['non-chrome', false, true, true, 'script'],
+    ['non-chrome, no script transform', false, true, false, 'insertable'],
+    ['non-chrome, neither API', false, false, false, undefined],
+  ] as const)('%s', (_label, chrome, insertable, script, expected) => {
+    vi.mocked(isChrome).mockReturnValue(chrome);
+    setInsertableStreams(insertable);
+    const restore = setScriptTransform(script);
+    try {
+      expect(preferredTransform()).toBe(expected);
+    } finally {
+      restore?.();
+    }
+  });
+});

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

@@ -0,0 +1,220 @@
+/**
+ * Codec-specific framing: how many header bytes stay clear, and H.264 RBSP
+ * escaping so ciphertext cannot contain a fake Annex B start code.
+ */
+const findStartCode = (
+  data: Uint8Array,
+  offset: number,
+): { pos: number; len: number } | null => {
+  for (let i = offset; i < data.length - 2; ++i) {
+    if (data[i] === 0 && data[i + 1] === 0) {
+      if (data[i + 2] === 1) return { pos: i, len: 3 };
+      if (data[i + 2] === 0 && i + 3 < data.length && data[i + 3] === 1) {
+        return { pos: i, len: 4 };
+      }
+    }
+  }
+  return null;
+};
+
+/**
+ * Clear bytes up to the first slice NALU (type 1 or 5) plus 2: start code,
+ * NALU header, one byte of slice header. Ignores frameType, to match
+ * {@link CodecProfile.clearBytes}.
+ */
+const h264ClearBytes = (
+  _frameType: string | undefined,
+  data: Uint8Array,
+): number => {
+  let sc = findStartCode(data, 0);
+  while (sc) {
+    const headerPos = sc.pos + sc.len;
+    if (headerPos >= data.length) break;
+    const naluType = data[headerPos] & 0x1f;
+    if (naluType === 1 || naluType === 5) {
+      const clear = sc.pos + sc.len + 2;
+      // A real slice header exceeds 2 bytes, so this clamp should never bite.
+      return clear > data.length ? data.length : clear;
+    }
+    sc = findStartCode(data, headerPos);
+  }
+  return 0;
+};
+
+/**
+ * Escape-state seed for the clear-header boundary: how many 0x00 bytes end the
+ * clear header, capped at 2 (a longer run does not change the escaper's next
+ * decision).
+ *
+ * The clear header itself is never escaped, but its tail and the first escaped
+ * bytes form one contiguous stream on the wire: a header ending in 0x00
+ * followed by ciphertext starting 0x00 0x01 is a fake start code the
+ * packetizer would split on. Seeding the escaper as if the header's zeros were
+ * already scanned closes that gap. Encode and decode both derive the seed from
+ * the same clear bytes, so nothing extra travels in the frame.
+ */
+export const boundarySeedZeros = (clearHeader: Uint8Array): number => {
+  const n = clearHeader.length;
+  let zeros = 0;
+  while (zeros < 2 && zeros < n && clearHeader[n - 1 - zeros] === 0) zeros++;
+  return zeros;
+};
+
+/**
+ * Escaped length of `segments`, read as one contiguous stream so a 0x00 0x00
+ * run spanning a boundary counts. Sizes the buffer for {@link rbspEscapeInto}.
+ *
+ * @param seedZeros zero-run state entering the stream; see
+ *         {@link boundarySeedZeros}.
+ */
+export const rbspEscapedLength = (
+  segments: Uint8Array[],
+  seedZeros: number,
+): number => {
+  let total = 0;
+  let zeros = seedZeros;
+  for (const seg of segments) {
+    total += seg.length;
+    for (let i = 0; i < seg.length; ++i) {
+      const byte = seg[i];
+      if (zeros >= 2 && byte <= 3) {
+        total++;
+        zeros = 0;
+      }
+      zeros = byte === 0 ? zeros + 1 : 0;
+    }
+  }
+  return total;
+};
+
+/**
+ * Escape `segments` into `dst` at `offset`, inserting 0x03 after each 0x00 0x00
+ * run followed by 0x00-0x03. `dst` needs {@link rbspEscapedLength} bytes free,
+ * computed with the same `seedZeros`.
+ *
+ * Sizing separately lets the encoder escape straight behind the clear header,
+ * copying the ciphertext once instead of twice.
+ */
+export const rbspEscapeInto = (
+  dst: Uint8Array,
+  offset: number,
+  segments: Uint8Array[],
+  seedZeros: number,
+): void => {
+  let j = offset;
+  let zeros = seedZeros;
+  for (const seg of segments) {
+    for (let i = 0; i < seg.length; ++i) {
+      const byte = seg[i];
+      if (zeros >= 2 && byte <= 3) {
+        dst[j++] = 3;
+        zeros = 0;
+      }
+      dst[j++] = byte;
+      zeros = byte === 0 ? zeros + 1 : 0;
+    }
+  }
+};
+
+/**
+ * Reverse of {@link rbspEscapeInto}: drop each 0x03 the escaper inserted,
+ * tracked with the same zero-run state so an escape byte right at the
+ * clear-header boundary (possible only with a non-zero `seedZeros`) is
+ * recognized too.
+ */
+export const rbspUnescape = (
+  data: Uint8Array,
+  seedZeros: number,
+): Uint8Array => {
+  const isEscapeByte = (i: number, zeros: number): boolean =>
+    zeros >= 2 && data[i] === 3 && i + 1 < data.length && data[i + 1] <= 3;
+  let remove = 0;
+  let zeros = seedZeros;
+  for (let i = 0; i < data.length; ++i) {
+    if (isEscapeByte(i, zeros)) {
+      remove++;
+      zeros = 0;
+      continue;
+    }
+    zeros = data[i] === 0 ? zeros + 1 : 0;
+  }
+  if (remove === 0) return data;
+  const result = new Uint8Array(data.length - remove);
+  let j = 0;
+  zeros = seedZeros;
+  for (let i = 0; i < data.length; ++i) {
+    if (isEscapeByte(i, zeros)) {
+      zeros = 0;
+      continue;
+    }
+    result[j++] = data[i];
+    zeros = data[i] === 0 ? zeros + 1 : 0;
+  }
+  return result;
+};
+
+/**
+ * How E2EE splits a frame, for one codec. The only place holding encode-side
+ * codec knowledge: one entry wires support detection, clear-byte sizing and
+ * RBSP escaping together, so no codec can be half-supported. An H265 entry
+ * that forgot NALU escaping would ship start-code-corrupting ciphertext.
+ */
+export interface CodecProfile {
+  /** Escape ciphertext and trailer against fake Annex-B start codes (H264). */
+  rbsp: boolean;
+  /**
+   * The profile can frame audio only, so the encoder fails closed on a frame
+   * that carries a key/delta type. Without this an unlabeled video frame would
+   * be encrypted whole and unescaped: the SFU could not read its headers, and a
+   * NALU packetizer would split it on a random start code in the ciphertext.
+   */
+  audioOnly: boolean;
+  /** Leading bytes left clear and passed as AAD, so the SFU can select layers. */
+  clearBytes: (frameType: string | undefined, data: Uint8Array) => number;
+}
+
+// Audio has no keyframes, so the absence of a frame type identifies it. Keep
+// the Opus TOC byte clear. Only reached for audio: `audioOnly` rejects a video
+// frame before this runs.
+const defaultClearBytes = (frameType: string | undefined): number =>
+  frameType === undefined ? 1 : 0;
+
+// Clamped to the frame length. A short frame claiming more would make encode
+// zero-pad the header and decode build an AAD of a different length.
+const vpClearBytes = (
+  frameType: string | undefined,
+  data: Uint8Array,
+): number => {
+  const clear = frameType === 'key' ? 10 : 3;
+  return clear > data.length ? data.length : clear;
+};
+
+// AV1 is absent on purpose: the AV1 RTP packetizer parses the OBU stream, so a
+// frame trailer does not survive. It needs its own scheme. Without an entry it
+// falls through to isSupportedCodec and fails closed.
+const CODEC_PROFILES: Record<string, CodecProfile> = {
+  opus: { rbsp: false, audioOnly: true, clearBytes: defaultClearBytes },
+  vp8: { rbsp: false, audioOnly: false, clearBytes: vpClearBytes },
+  vp9: { rbsp: false, audioOnly: false, clearBytes: vpClearBytes },
+  h264: { rbsp: true, audioOnly: false, clearBytes: h264ClearBytes },
+};
+
+// Used when the caller names no codec. Audio is safe to frame unlabeled, since
+// the TOC byte rule holds for any audio codec. Video is not: the right clear
+// header and whether to escape both depend on the codec, so it fails closed.
+const DEFAULT_PROFILE: CodecProfile = {
+  rbsp: false,
+  audioOnly: true,
+  clearBytes: defaultClearBytes,
+};
+
+// Object.hasOwn, not `in`: `in` walks the prototype chain, so a codec named
+// like an Object.prototype member ('toString') would resolve to a function
+// instead of a profile.
+export const getCodecProfile = (codec: string | undefined): CodecProfile =>
+  codec !== undefined && Object.hasOwn(CODEC_PROFILES, codec)
+    ? CODEC_PROFILES[codec]
+    : DEFAULT_PROFILE;
+
+export const isSupportedCodec = (codec: string | undefined): boolean =>
+  codec === undefined || Object.hasOwn(CODEC_PROFILES, codec);

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

@@ -0,0 +1,47 @@
+/** Marks an encrypted frame's trailer. */
+export const MAGIC = 0xe2eefeed;
+
+/**
+ * Wire format version. Bump it when the trailer layout or IV derivation change.
+ *
+ * v1: [4B frameCounter][8B ivPrefix][1B keyIndex][2B clearBytes|flags]
+ * [1B version][4B magic]. IV = ivPrefix ∥ frameCounter.
+ */
+export const E2EE_VERSION = 1;
+
+export const IV_PREFIX_LEN = 8;
+export const FRAME_COUNTER_LEN = 4;
+export const IV_LEN = IV_PREFIX_LEN + FRAME_COUNTER_LEN;
+
+const KEY_INDEX_LEN = 1;
+const CLEAR_BYTES_LEN = 2;
+const VERSION_LEN = 1;
+const MAGIC_LEN = 4;
+
+/** 4 + 8 + 1 + 2 + 1 + 4 */
+export const TRAILER_LEN =
+  FRAME_COUNTER_LEN +
+  IV_PREFIX_LEN +
+  KEY_INDEX_LEN +
+  CLEAR_BYTES_LEN +
+  VERSION_LEN +
+  MAGIC_LEN;
+
+/** Bit 15 of the clearBytes field. Signals RBSP escaping. */
+export const RBSP_FLAG = 0x8000;
+/** Bit 15 belongs to RBSP_FLAG, so clearBytes gets 15 bits. */
+export const MAX_CLEAR_BYTES = 0x7fff;
+
+export const EMPTY_AAD = new Uint8Array(0);
+
+/** Consecutive decrypt failures on one track before `e2ee.decryption_stalled` fires. */
+export const FAILURE_TOLERANCE = 10;
+
+/** Replay window in frames. A counter <= highestSeen - this is rejected. */
+export const REPLAY_WINDOW = 1024;
+
+/**
+ * One more than this wraps into an (ivPrefix, counter) pair the sender already
+ * used, which is IV reuse under AES-GCM. Encoding throws instead.
+ */
+export const COUNTER_HARD_LIMIT = 0xffffffff; // 2^32 - 1

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

@@ -0,0 +1,159 @@
+import { E2EE_VERSION, EMPTY_AAD, IV_LEN, TRAILER_LEN } from './constants';
+import { boundarySeedZeros, rbspUnescape } from './codec';
+import {
+  fillIV,
+  readFramingVersion,
+  readTrailer,
+  readTrailerIv,
+} from './trailer';
+import { FailureTracker } from './failureTracker';
+import { ReplayWindow } from './replayWindow';
+import { keyStore } from './keyStore';
+import { decodeStats } from './perf';
+import { DecodeNotifier } from './notifications';
+import type { EncodedFrame, FrameController } from './types';
+
+export const decodeTransform = (
+  userId: string,
+  trackType: string | undefined,
+) => {
+  // Counts a peer's audio and video apart.
+  const trackKey = trackType ?? 'unknown';
+  const stats = decodeStats.track(`${userId}/${trackKey}`, {
+    userId,
+    trackType: trackKey,
+  });
+  const notify = new DecodeNotifier(userId, trackType);
+  const iv = new Uint8Array(IV_LEN);
+  const ivView = new DataView(iv.buffer);
+
+  // Per track, so a user's audio, video and screen share never share a window
+  // or a failure count. The separate count is what lets
+  // e2ee.decryption_stalled fire.
+  const replay = new ReplayWindow();
+  const failures = new FailureTracker();
+
+  /**
+   * Gates on key and replay, decrypts, emits, then records failure or recovery.
+   * `decrypt` throws on a GCM tag failure, dropping the frame. Separate from
+   * the framing parse so the trust ordering lives in one place.
+   *
+   * Trust ordering (the SFrame/SRTP rule): a relay can forge `frameCounter`,
+   * `ivPrefix` and `keyIndex`, which are plaintext in the trailer, so nothing
+   * changes trust state until GCM authenticates. Hence peek before, commit
+   * after. The failure counter is diagnostic only - it gates `e2ee.decryption_stalled`,
+   * never the decrypt attempt - so forged frames cannot mark a key invalid.
+   */
+  const finishDecode = async (
+    frame: EncodedFrame,
+    controller: FrameController,
+    keyIndex: number,
+    ivPrefix: Uint8Array,
+    frameCounter: number,
+    decrypt: (key: CryptoKey) => Promise<ArrayBuffer>,
+  ) => {
+    const cryptoKey = keyStore.getKey(userId, keyIndex);
+    if (!cryptoKey) {
+      notify.missingKey(keyIndex);
+      return;
+    }
+    // No state change. A replay or an out-of-window frame is dropped silently;
+    // neither is a decryption failure.
+    if (!replay.peek(frameCounter, ivPrefix)) return;
+    try {
+      const t0 = stats.startCrypto();
+      const data = await decrypt(cryptoKey);
+      stats.endCrypto(t0);
+      // Authenticated: only now is it safe to advance the replay window.
+      replay.commit(frameCounter, ivPrefix);
+      // Independent on purpose: the count is per keyIndex, but
+      // `decryption_failed` is per track, so a track recovering on a NEW
+      // keyIndex must still clear it. Gating on recordSuccess would latch the
+      // host on failed forever.
+      failures.recordSuccess(keyIndex);
+      notify.resumed();
+      frame.data = data;
+      controller.enqueue(frame);
+      stats.bump();
+    } catch {
+      // True only on the failure crossing the tolerance, so
+      // `e2ee.decryption_stalled` fires once per run, not once per frame.
+      const stalled = failures.recordFailure(keyIndex);
+      notify.failed();
+      if (stalled) notify.stalled(keyIndex);
+    }
+  };
+
+  return new TransformStream<EncodedFrame, EncodedFrame>({
+    async transform(frame, controller) {
+      if (frame.data.byteLength === 0) {
+        controller.enqueue(frame);
+        stats.bump();
+        return;
+      }
+
+      const src = new Uint8Array(frame.data);
+      const trailer = readTrailer(src);
+
+      if (!trailer) {
+        // Ours but unreadable: drop rather than forward. Handing ciphertext to
+        // the decoder renders corruption and reads to the host as a downgrade,
+        // when the actual condition is that this build is the older one.
+        const version = readFramingVersion(src);
+        if (version !== null && version !== E2EE_VERSION) {
+          notify.unsupportedVersion(version);
+          return;
+        }
+        notify.unencrypted();
+        controller.enqueue(frame);
+        stats.bump();
+        return;
+      }
+
+      const { clearBytes, isRbsp } = trailer;
+
+      // An RBSP (H264) frame escaped the ciphertext together with the counter,
+      // ivPrefix and keyIndex, so un-escape to recover them; only the trailer
+      // tail read above stayed clear. A non-RBSP frame keeps the trailer raw.
+      let { frameCounter, ivPrefix, keyIndex } = trailer;
+      let ciphertext: Uint8Array;
+      if (isRbsp) {
+        // Same boundary seed as the encoder, derived from the same clear bytes.
+        const seed = boundarySeedZeros(src.subarray(0, clearBytes));
+        const unit = rbspUnescape(src.subarray(clearBytes), seed);
+        // Un-escaping can leave less than a trailer, since readTrailer sized
+        // clearBytes against the raw frame. A negative offset would throw out
+        // of transform() and kill this track's pipeline for the session, and a
+        // relay can forge the shape: clearBytes and the flag are plaintext.
+        if (unit.length < TRAILER_LEN) return;
+        ({ frameCounter, ivPrefix, keyIndex } = readTrailerIv(unit));
+        ciphertext = unit.subarray(0, unit.length - TRAILER_LEN);
+      } else {
+        ciphertext = src.subarray(clearBytes, src.length - TRAILER_LEN);
+      }
+
+      return finishDecode(
+        frame,
+        controller,
+        keyIndex,
+        ivPrefix,
+        frameCounter,
+        async (key) => {
+          fillIV(iv, ivView, ivPrefix, frameCounter);
+          const aad = clearBytes > 0 ? src.subarray(0, clearBytes) : EMPTY_AAD;
+          const decrypted = await crypto.subtle.decrypt(
+            { name: 'AES-GCM', iv, additionalData: aad as BufferSource },
+            key,
+            ciphertext as BufferSource,
+          );
+          if (clearBytes === 0) return decrypted;
+          const plaintext = new Uint8Array(decrypted);
+          const dst = new Uint8Array(clearBytes + plaintext.length);
+          dst.set(src.subarray(0, clearBytes), 0);
+          dst.set(plaintext, clearBytes);
+          return dst.buffer;
+        },
+      );
+    },
+  });
+};

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

@@ -0,0 +1,137 @@
+/**
+ * E2EE Web Worker entry point. Owns the worker's message interface and wires
+ * the encrypt/decrypt transforms into WebRTC Encoded Transforms. The main
+ * thread distributes keys by postMessage, and transforms look one up per frame
+ * by (userId, keyIndex).
+ *
+ * ## Wire format
+ *
+ * Frame layout is [clear header][ciphertext + GCM tag][20B trailer], so 36
+ * bytes of overhead. The trailer holds:
+ *   [4B frameCounter][8B ivPrefix][1B keyIndex][2B clearBytes|flags]
+ *   [1B version][4B 0xE2EEFEED]
+ *
+ * The clear header keeps codec headers readable so the SFU can detect keyframes
+ * and select layers: 1 byte for Opus, 10/3 for VP8 and VP9 (key/delta), and for
+ * H264 everything up to the first slice NALU + 2, with the encrypted tail
+ * RBSP-escaped against fake start codes. It doubles as the AAD, so the SFU can
+ * read it but decrypt still detects tampering.
+ *
+ * The 12-byte IV is [ivPrefix][frameCounter]. `ivPrefix` is random per key
+ * import and travels in the trailer, so IVs stay unique even when the host
+ * imports the same raw key twice.
+ *
+ * rollup-plugin-inline-worker bundles this into the function
+ * `../e2ee-worker.ts` exports.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Using_Encoded_Transforms
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-gcm
+ */
+
+import { isSupportedCodec } from './codec';
+import { enqueue } from './queue';
+import { keyStore } from './keyStore';
+import { decodeStats, startPerfReport, stopPerfReport } from './perf';
+import { EncodeNotifier, reportError } from './notifications';
+import { encodeTransform } from './encode';
+import { decodeTransform } from './decode';
+import type { EncodedFrame } from './types';
+
+/**
+ * Decode always runs. An encode whose codec the worker cannot split fails
+ * closed: it still installs a transform, but one that drops every frame, since
+ * returning without one leaves the encoder buffering forever with no signal.
+ */
+const selectTransform = (
+  operation: string,
+  userId: string,
+  codec: string | undefined,
+  trackType: string | undefined,
+): TransformStream<EncodedFrame, EncodedFrame> => {
+  if (operation !== 'encode') return decodeTransform(userId, trackType);
+  if (isSupportedCodec(codec)) return encodeTransform(userId, codec, trackType);
+  new EncodeNotifier(userId, trackType).failed(
+    `unsupported codec for E2EE: ${codec}`,
+  );
+  // Enqueues nothing: every frame is dropped.
+  return new TransformStream<EncodedFrame, EncodedFrame>({ transform() {} });
+};
+
+const setupTransform = ({
+  readable,
+  writable,
+  operation,
+  userId,
+  codec,
+  trackType,
+}: {
+  readable: ReadableStream;
+  writable: WritableStream;
+  operation: string;
+  userId: string;
+  codec?: string;
+  trackType?: string;
+}) => {
+  const transform = selectTransform(operation, userId, codec, trackType);
+  readable
+    .pipeThrough(transform)
+    .pipeTo(writable)
+    .catch((err: any) => {
+      reportError(
+        `Transform pipeline error (${operation}, ${userId}): ${
+          err?.message || err
+        }`,
+      );
+    });
+};
+
+addEventListener('rtctransform', (event) => {
+  const { readable, writable, options } = event.transformer;
+  // Same queue as message-based setup, so an in-flight key import completes
+  // before the transform is wired up.
+  enqueue(async () => {
+    setupTransform({ readable, writable, ...options });
+  }).catch((err: any) => {
+    reportError(`Transform setup failed: ${err?.message || err}`);
+  });
+});
+
+addEventListener('message', ({ data }) => {
+  enqueue(async () => {
+    switch (data.type) {
+      case 'cmd.set_key':
+        await keyStore.importKey(data.userId, data.keyIndex, data.rawKey);
+        break;
+      case 'cmd.set_shared_key':
+        await keyStore.importSharedKey(data.keyIndex, data.rawKey);
+        break;
+      case 'cmd.remove_shared_key':
+        keyStore.removeSharedKey(data.keyIndex);
+        break;
+      case 'cmd.remove_key':
+        // Deliberately keeps this user's decode stats: they are still
+        // publishing, one epoch was retired.
+        keyStore.removeKey(data.userId, data.keyIndex);
+        break;
+      case 'cmd.remove_all_keys':
+        keyStore.removeAllKeys(data.userId);
+        decodeStats.removeUser(data.userId);
+        break;
+      case 'cmd.enable_performance_reporting':
+        if (data.enabled) startPerfReport();
+        else stopPerfReport();
+        break;
+      case 'cmd.request_key_state':
+        self.postMessage({ type: 'e2ee.key_state', ...keyStore.keyState() });
+        break;
+      case 'cmd.setup_transform':
+        setupTransform(data);
+        break;
+      default:
+        reportError(`Unknown command type: ${data.type}`);
+        break;
+    }
+  }).catch((err: any) => {
+    reportError(`Message handler error: ${err?.message || err}`);
+  });
+});