graph LR
    A[Capture] --> B[Encoder]
    B --> C{Encoded Transform<br/>(Worker Thread)}
    C --> D[Packetizer / SRTP Encrypt]
    D --> E[Network Transport]
    E --> F[SRTP Decrypt / Depacketizer]
    F --> G{Encoded Transform<br/>(Worker Thread)}
    G --> H[Decoder]
    H --> I[Render]

// encryption-worker.js
const CRYPTO_ALGO = { name: 'AES-GCM', length: 256 };
const IV_LENGTH = 12; // GCM 推荐 96-bit IV
const TAG_LENGTH = 16; // GCM 认证标签 128-bit

let epochKey = null; // 通过 postMessage 从主线程接收的 CryptoKey
let frameCounter = 0; // 单调递增，防重放

// 1. 密钥派生：FK = HKDF(EK, FrameCounter)
async function deriveFrameKey(counter) {
  const counterBuffer = new Uint8Array(8);
  new DataView(counterBuffer.buffer).setBigUint64(0, BigInt(counter), false);
  return crypto.subtle.deriveKey(
    { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: counterBuffer },
    epochKey,
    CRYPTO_ALGO,
    false,
    ['encrypt']
  );
}

// 2. 构造 IV：建议使用 Frame Counter + SSRC 混淆，确保唯一性
function constructIV(counter, ssrc) {
  const iv = new Uint8Array(IV_LENGTH);
  const view = new DataView(iv.buffer);
  view.setBigUint64(0, BigInt(counter), false); // 高 64 位
  view.setUint32(8, ssrc, false); // 低 32 位 (假设 SSRC < 2^32)
  return iv;
}

// 3. 核心转换流处理
const transformer = new TransformStream({
  async transform(encodedFrame, controller) {
    // 仅处理视频关键帧/Delta帧，音频帧同理
    if (encodedFrame.type === 'key' || encodedFrame.type === 'delta') {
      try {
        // A. 序列化元数据 (需加密保护完整性)
        // 注意：修改 metadata 可能导致解码器异常，建议仅加密 payload
        const payload = encodedFrame.data; // ArrayBuffer
        
        // B. 派生密钥与 IV
        const frameKey = await deriveFrameKey(frameCounter);
        const iv = constructIV(frameCounter, encodedFrame.metadata.ssrc || 0);
        
        // C. AES-GCM 加密 (包含认证标签)
        // 输出格式: [IV (12B)] + [Ciphertext] + [AuthTag (16B)]
        const ciphertext = await crypto.subtle.encrypt(
          { name: 'AES-GCM', iv, tagLength: TAG_LENGTH * 8 },
          frameKey,
          payload
        );
        
        // D. 重组帧数据
        // 策略：将 IV 前置，密文+Tag 紧随其后。接收端需知晓此格式。
        const newData = new Uint8Array(IV_LENGTH + ciphertext.byteLength);
        newData.set(iv, 0);
        newData.set(new Uint8Array(ciphertext), IV_LENGTH);
        
        // E. 创建新帧对象 (不可变对象需重新构造)
        const newFrame = new RTCEncodedVideoFrame({
          type: encodedFrame.type,
          timestamp: encodedFrame.timestamp,
          data: newData.buffer,
          metadata: encodedFrame.metadata // 保留原始元数据供解码器参考
        });
        
        controller.enqueue(newFrame);
        frameCounter++;
      } catch (e) {
        console.error('Encryption failed, dropping frame:', e);
        controller.error(e); // 触发流错误，上层可感知
      }
    } else {
      // 非媒体帧 (如 FIR, PLI, Padding) 透传
      controller.enqueue(encodedFrame);
    }
  }
});

// 4. 主线程通信：接收密钥更新
self.onmessage = async (event) => {
  if (event.data.type === 'SET_EPOCH_KEY') {
    epochKey = await crypto.subtle.importKey(
      'raw', event.data.keyMaterial, CRYPTO_ALGO, false, ['deriveKey']
    );
    frameCounter = 0; // 密钥轮换重置计数器
  }
};

// 5. 连接管线
const transform = new RTCRtpScriptTransform(transformer.readable, transformer.writable);
self.port.postMessage({ transformer: transform }, [transform]);

// main-thread.js
async function setupE2EE(pc, trackKind) {
  // 1. 创建 Worker
  const worker = new Worker('encryption-worker.js', { type: 'module' });
  
  // 2. 生成/协商 Epoch Key (此处简化，实际需通过 MLS/Signal 协商)
  const keyMaterial = crypto.getRandomValues(new Uint8Array(32));
  const epochKey = await crypto.subtle.importKey('raw', keyMaterial, 'AES-GCM', false, ['deriveKey']);
  
  // 3. 将 Transformer 注入 PeerConnection
  const sender = pc.getSenders().find(s => s.track?.kind === trackKind);
  if (sender) {
    const transform = await new Promise(resolve => {
      worker.onmessage = (e) => { if (e.data.transformer) resolve(e.data.transformer); };
    });
    sender.transform = transform;
  }
  
  // 4. 下发密钥至 Worker
  worker.postMessage({ type: 'SET_EPOCH_KEY', keyMaterial });
  
  // 5. 密钥轮换定时器 (示例: 1小时)
  setInterval(async () => {
    const newKey = crypto.getRandomValues(new Uint8Array(32));
    // 1. 通过信令安全下发新密钥给对端
    // 2. 确认对端已就绪后
    worker.postMessage({ type: 'SET_EPOCH_KEY', keyMaterial: newKey });
  }, 3600 * 1000);
}

// watermark-worker.js (TransformStream transform 方法中)
function injectSEIWatermark(frame, userId) {
  if (frame.type !== 'key') return frame; // 仅在关键帧注入，降低开销与检测概率
  
  const payload = frame.data; // Uint8Array
  // 简易 NALU 解析查找 SPS/PPS 位置 (实际建议使用成熟解析库如 h264-profile-level-id)
  // 此处伪代码演示插入逻辑
  const seiNalu = buildSEINALU(userId); // 构造 SEI NALU (payloadType=5, user_data_unregistered)
  
  // 将 SEI 插入 SPS 之后、IDR Slice 之前
  const newPayload = insertNALU(payload, seiNalu, 'after_sps');
  
  return new RTCEncodedVideoFrame({
    type: frame.type,
    timestamp: frame.timestamp,
    data: newPayload.buffer,
    metadata: frame.metadata
  });
}

// receiver-transform-worker.js
const receivedFrames = new Map(); // frameId -> frame metadata
const MAX_BUFFER = 50;

const transformer = new TransformStream({
  transform(encodedFrame, controller) {
    // 1. 记录帧依赖关系
    if (encodedFrame.metadata.frameId !== undefined) {
      receivedFrames.set(encodedFrame.metadata.frameId, {
        deps: encodedFrame.metadata.dependencies || [],
        timestamp: encodedFrame.timestamp
      });
      // 简单 LRU 清理
      if (receivedFrames.size > MAX_BUFFER) {
        const firstKey = receivedFrames.keys().next().value;
        receivedFrames.delete(firstKey);
      }
    }

    // 2. 丢包检测与 NACK 生成 (简化逻辑)
    // 实际需结合 RTP Sequence Number (在 metadata 中可能不可用，需配合 RTP Header Extension)
    // 此处演示基于 FrameId 连续性的应用层 FIR 请求
    if (encodedFrame.type === 'key') {
      checkAndRequestRecovery(encodedFrame.metadata.frameId);
    }

    controller.enqueue(encodedFrame); // 透传给解码器
  }
});

function checkAndRequestRecovery(currentKeyFrameId) {
  // 检测当前关键帧依赖的前向帧是否缺失
  // 此处需主线程协助发送 RTCP FIR/NACK，可通过 port.postMessage 通知主线程
  // self.port.postMessage({ type: 'REQUEST_KEY_FRAME', reason: 'dependency_lost' });
}

+----------------+----------------+------------------------+
| Epoch ID (2B)  | Frame Seq (2B) | Encrypted Payload ...  |
+----------------+----------------+------------------------+

// mls-decrypt-worker.js
class MLSEpochKeyStore {
  constructor() {
    // Map<EpochID, { secret: CryptoKey, ratchet: RatchetState, expiry: Timestamp }>
    this.epochs = new Map(); 
    this.currentEpoch = 0;
    this.MAX_EPOCHS = 3; // 保留当前、前一个、下一个 (预接收)
  }

  // 主线程通过 postMessage 下发 MLS KeyPackage / Welcome / Commit 处理后的 Epoch Secrets
  async importEpochSecret(epochId, epochSecret, keySchedule) {
    // 使用 MLS KeySchedule 导出 `sender_data_secret` -> `media_key` / `media_salt`
    // 此处简化：假设主线程已完成 HKDF-Expand-Label 导出 AEAD Key/Salt
    const { aeadKey, aeadSalt } = await this.deriveMediaKeys(epochSecret);
    const cryptoKey = await crypto.subtle.importKey('raw', aeadKey, 'AES-GCM', false, ['decrypt']);
    
    this.epochs.set(epochId, {
      key: cryptoKey,
      salt: aeadSalt, // 用于构造 Nonce: Nonce = Salt XOR FrameSeq
      ratchet: { nextKey: null }, // 如需逐帧 Ratchet 可在此维护
      expiry: Date.now() + 24 * 3600 * 1000
    });
    this.gc();
  }

  async decryptFrame(encodedFrame) {
    const payload = new Uint8Array(encodedFrame.data);
    if (payload.length < 4) return { success: false, reason: 'header_too_short' };

    const view = new DataView(payload.buffer, payload.byteOffset, 4);
    const epochId = view.getUint16(0, false);
    const frameSeq = view.getUint16(2, false);
    const ciphertext = payload.slice(4); // 包含 AuthTag

    const epochCtx = this.epochs.get(epochId);
    if (!epochCtx) {
      // 触发主线程请求 KeyPackage / Re-key
      self.port.postMessage({ type: 'REQUEST_EPOCH_KEY', epochId });
      return { success: false, reason: 'epoch_missing', frame: encodedFrame }; // 缓存待解密
    }

    // 构造 Nonce: Salt (12B) XOR FrameSeq (8B big-endian)
    const nonce = new Uint8Array(epochCtx.salt);
    const seqBuf = new ArrayBuffer(8);
    new DataView(seqBuf).setBigUint64(0, BigInt(frameSeq), false);
    for (let i = 0; i < 8; i++) nonce[4 + i] ^= new Uint8Array(seqBuf)[i]; // 低 8 字节混入 Seq

    try {
      const plaintext = await crypto.subtle.decrypt(
        { name: 'AES-GCM', iv: nonce, tagLength: 128 },
        epochCtx.key,
        ciphertext
      );
      // 重组原始帧数据 (移除自定义 Header)
      const newFrame = new RTCEncodedVideoFrame({
        type: encodedFrame.type,
        timestamp: encodedFrame.timestamp,
        data: plaintext,
        metadata: encodedFrame.metadata
      });
      return { success: true, frame: newFrame };
    } catch (e) {
      // AuthTag 验证失败：可能是密钥错、重放攻击、数据损坏
      console.warn(`Decrypt failed Epoch:${epochId} Seq:${frameSeq}`, e);
      return { success: false, reason: 'auth_failed' };
    }
  }

  gc() { /* 清理过期 Epoch */ }
}

// audio-level-worker.js (TransformStream)
function estimateOpusLevel(opusPacket) {
  // 简易启发式：解析 TOC Byte -> 帧数/模式/带宽
  // 仅演示单帧 CBR 场景：取 Payload 后半段能量均值 (CELT 模式频域系数近似)
  // 生产环境建议移植 opus_decoder 的 energy 计算逻辑至 WASM (opus.wasm)
  const toc = opusPacket[0];
  const frames = parseTOC(toc); // 解析帧数、帧长
  let totalEnergy = 0;
  let offset = 1; // Skip TOC
  
  for (let i = 0; i < frames.count; i++) {
    const frameSize = frames.sizes[i];
    const frameData = opusPacket.subarray(offset, offset + frameSize);
    // 粗略计算 L2 范数 (需根据 Opus 编码模式调整权重)
    let sumSq = 0;
    for (let j = 0; j < frameData.length; j++) sumSq += frameData[j] * frameData[j];
    totalEnergy += sumSq / frameSize;
    offset += frameSize;
  }
  // 映射到 -127 ~ 0 dBov (RFC 6464 定义)
  const level = Math.max(-127, Math.min(0, Math.round(10 * Math.log10(totalEnergy / frames.count + 1e-9) + 90)));
  return level; // 上报主线程驱动 UI 波形图
}

// media_envelope.proto
syntax = "proto3";
package rtc.e2ee.v1;

message EncryptedFrameEnvelope {
  // 通用头部 (固定 8 字节)
  uint32 epoch_id = 1;        // MLS Epoch / Session Key Version
  uint32 frame_sequence = 2;  // 单调递增，用于 Nonce 构造 & 乱序检测
  FrameType frame_type = 3;   // KEY, DELTA, AUDIO, FEC, RED
  uint32 payload_offset = 4;  // 加密载荷在整个 buffer 中的偏移 (通常=8)
  
  // 扩展字段 (TLV 格式，预留)
  bytes extensions = 10;      
  
  // 加密载荷 (AES-GCM Ciphertext || AuthTag)
  bytes encrypted_payload = 100; 
}

enum FrameType {
  FRAME_TYPE_UNSPECIFIED = 0;
  VIDEO_KEY_FRAME = 1;
  VIDEO_DELTA_FRAME = 2;
  AUDIO_FRAME = 3;
  VIDEO_FEC_FRAME = 4;
  AUDIO_RED_FRAME = 5;
}

// crypto-core.test.ts
import { deriveFrameKey, constructIV, encryptFrame, decryptFrame } from './crypto-core';
import { generateKeyPair, exportKey } from './mls-wrapper'; // Mock MLS

describe('E2EE Crypto Core', () => {
  let epochKey: CryptoKey;
  beforeAll(async () => {
    epochKey = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['deriveKey']);
  });

  test('Roundtrip: Encrypt -> Decrypt preserves payload', async () => {
    const payload = new Uint8Array([0x00, 0x00, 0x00, 0x01, 0x67, ...]); // H.264 NALU
    const frameSeq = 100;
    const ssrc = 0x12345678;

    const { ciphertext, iv } = await encryptFrame(epochKey, payload, frameSeq, ssrc);
    const plaintext = await decryptFrame(epochKey, ciphertext, iv, frameSeq, ssrc);
    
    expect(new Uint8Array(plaintext)).toEqual(payload);
  });

  test('Tamper detection: Modified ciphertext throws', async () => {
    const { ciphertext, iv } = await encryptFrame(epochKey, new Uint8Array([1,2,3]), 1, 1);
    ciphertext[0] ^= 0xFF; // 篡改
    await expect(decryptFrame(epochKey, ciphertext, iv, 1, 1)).rejects.toThrow('AEADBadTag');
  });
  
  test('Replay protection: Same FrameSeq different Epoch fails', async () => {
    // ... 验证 Epoch 隔离性
  });
});

// e2e/e2ee-key-rotation.spec.ts
test('Key Rotation during active call: No frame loss > 200ms', async ({ page, browser }) => {
  const [caller, callee] = await Promise.all([
    createContext(page, 'caller'),
    createContext(page, 'callee')
  ]);

  // 1. 建立通话，验证视频流正常 (检测 Canvas 像素变化)
  await expectVideoPlaying(caller);
  await expectVideoPlaying(callee);

  // 2. 模拟 5% 丢包、100ms RTT
  await caller.context.setOffline(false);
  await caller.page.route('**/*', route => route.continue());
  // 使用 CDP 模拟网络
  const client = await caller.context.newCDPSession(caller.page);
  await client.send('Network.emulateNetworkConditions', {
    offline: false, latency: 100, downloadThroughput: 1.5 * 1024 * 1024 / 8, uploadThroughput: 1.5 * 1024 * 1024 / 8, packetLoss: 0.05
  });

  // 3. 触发服务端 MLS Commit (模拟成员加入/离开)
  await triggerServerKeyRotation(caller.roomId);

  // 4. 监控双端解码器状态：连续 5s 无 freeze、无 "key frame request" 风暴
  const metrics = await monitorDecodingHealth(caller, callee, 10000);
  expect(metrics.freezeCount).toBe(0);
  expect(metrics.keyFrameRequests).toBeLessThan(3); // 允许极少量因乱序触发的请求
});

rtc-e2ee-sdk/
├── packages/
│   ├── core-crypto/          # 纯 TS/Rust 核心加密逻辑 (无 WebRTC 依赖) -> 单测 100%
│   ├── mls-adapter/          # MLS 协议封装 (mls-js / openmls FFI)
│   ├── web-transformer/      # Web Worker 入口、流控制、主线程通信
│   ├── native-bridge/        # UniFFI / JNI / SwiftPM 绑定层
│   ├── signaling-protocol/   # 信令 Protobuf 定义、KeyPackage 交换逻辑
│   └── integration-tests/    # Playwright + Docker SFU 集成测试套件
├── docs/
│   ├── ARCHITECTURE.md       # 架构决策记录 (ADR)
│   ├── SECURITY_AUDIT.md     # 第三方安全审计报告归档
│   └── INTEROP_MATRIX.md     # 版本兼容矩阵
└── .github/workflows/        # CI: Lint -> Unit -> Integration -> Fuzz -> Release