tracegist-mcp-bridge 0.3.2 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 All notable changes to `tracegist-mcp-bridge`.
 
+## 1.0.0
+
+> ⚠️ **Breaking Remote Live Session protocol change** (`FRAME_VERSION` → 3):
+> a 1.0.0 bridge will NOT interoperate with an older extension, and vice
+> versa. It ships **in lockstep** with the TraceGist extension v1.0.0 release —
+> update both together. Includes everything from the (unpublished) 0.5.0 below.
+
+Hardens the E2E encryption per the security audit (findings F1–F3) plus a
+per-connection ephemeral-key handshake:
+
+- **Per-connection handshake (fixes the CRITICAL reconnect/replay flaw).** Data
+  frames are now encrypted under a _connection key_, not the code key. On every
+  (re)connection the tester sends a fresh nonce (tagged with a monotonic
+  wall-clock epoch); the agent replies with its own nonce; both HKDF a connection
+  key from the code secret + both nonces + epoch and reset their counter. Because
+  each connection derives a distinct key: (a) a routine single-sided reconnect
+  re-handshakes and resynchronizes both sides (no more "post-reconnect frames
+  rejected as replays" brick), and (b) a malicious relay replaying a previous
+  connection's frames fails to decrypt under the new key. The agent is idempotent
+  per epoch and the tester retransmits until it gets a reply (with a bounded
+  timeout that ends the session), so a dropped handshake nonce recovers.
+- **Anti-replay / anti-reflection (F1).** Every data frame authenticates a
+  per-direction monotonic counter + sender role via AES-GCM AAD; a `ReplayGuard`
+  rejects non-increasing counters (in-connection replay/reorder), and the
+  per-connection key rejects cross-connection replay.
+- **Slow KDF (F2).** The code secret is PBKDF2-SHA256 (210k iterations); the
+  handshake and connection keys are HKDF'd from it. The relay-visible room ID
+  stays a fast, domain-separated hash.
+- **Chunk-count cap (F3).** `FrameChunkAssembler` rejects a part count above
+  `MAX_CHUNK_TOTAL` (1024).
+
+Not included (deferred): **forward secrecy (F5)** — the nonce-mixed key does NOT
+provide it (a compromised code + logged nonces still derives the key); true FS
+needs ephemeral ECDH. Also deferred: raising session-code entropy above 75 bits.
+
+## 0.5.0
+
+_Never published to npm — these changes first shipped as part of 1.0.0._
+
+Remote Live Session agent-experience improvements (all additive — no breaking
+tool-signature changes), from real agent-session feedback.
+
+- `watch_live_session` gains an optional `wait_seconds` long-poll parameter (max
+  30). The call now blocks until the next event arrives (or the session ends),
+  so agents react instantly instead of sleeping-and-re-polling every few seconds.
+- **Tester reconnect grace window.** A transient tester disconnect (service-worker
+  suspend, network blip) no longer ends the session immediately; the bridge waits
+  `TRACEGIST_PEER_GRACE_MS` (default 15s) for the extension to reconnect and
+  re-announce, preserving buffered events and in-flight replies. An explicit
+  `session-end` (recording stopped / consent revoked) still ends at once.
+- **Actionable, differentiated errors** for `ask_tester_question` /
+  `get_live_screenshot`: distinguishes "tester hasn't joined / left", "connected
+  but not recording yet", and "momentarily disconnected, retry" instead of one
+  opaque message.
+- **Silent-recording detection.** A voice answer that transcribes to whisper's
+  `[BLANK_AUDIO]` (or empty) is now surfaced as an explicit "no speech detected —
+  consider re-asking" signal rather than a bogus transcript.
+- Every live event now carries `tsEpoch` (bridge wall-clock at ingestion) — a
+  single uniformly-comparable absolute timestamp, since `ts` is source-relative
+  for tester events but epoch for bridge control events.
+- `ask_tester_question` message limit raised 200 → 500 chars and reframed to allow
+  statements/replies, not only questions.
+
+## 0.4.0
+
+**Remote Live Sessions** — the live shadowing loop now works across machines.
+A tester anywhere starts a remote session in the TraceGist extension and
+shares a code; this bridge joins through a relay and every live tool works
+exactly as it does locally.
+
+- New tool `join_live_session({ code })`: joins the tester's session via a
+  relay (`TRACEGIST_RELAY_URL` env var overrides the default). All live-shadow
+  traffic is end-to-end encrypted with AES-256-GCM using a key derived from
+  the session code — the relay only ever sees ciphertext, and the room ID is
+  a hash of the code, so the relay cannot derive the key.
+- New tool `leave_live_session()`: disconnects from the remote session.
+- `live-session://status` now reports the active transport (`local` / `relay`
+  / `none`) and remote connection state.
+- The local localhost WebSocket transport is unchanged and remains the
+  default; remote mode is purely additive (semver minor).
+- `TRACEGIST_DISABLE_LIVE` now also disables `join_live_session`.
+- Relay reconnects use the same backoff strategy as the extension; a
+  `tester-connected` / `tester-disconnected` live event is pushed when the
+  tester's extension joins or drops.
+
+The relay itself ships separately as the `tracegist-relay` package
+(self-hostable; plain Node + ws).
+
 ## 0.3.0
 
 **Breaking changes:**

package/bin/lib.mjs

@@ -212,6 +212,44 @@ export function audioFormatFromMime(mimeType, fallback = "webm") {
   return m ? m[1] : fallback;
 }
 
+/**
+ * Interpret a raw transcription string from Whisper/OpenRouter. whisper.cpp
+ * emits the literal "[BLANK_AUDIO]" marker (and models can return near-empty
+ * text) when a recording has no speech — a silent mic. Strips those markers and
+ * reports silence explicitly so the caller can tell the agent to re-ask instead
+ * of forwarding a bogus "answer".
+ * @param {string | null | undefined} rawText
+ * @returns {{ transcription: string } | { silent: true }}
+ */
+export function interpretTranscription(rawText) {
+  const cleaned = String(rawText || "")
+    .replace(/\[BLANK_?AUDIO\]/gi, "")
+    .trim();
+  if (!cleaned) return { silent: true };
+  return { transcription: cleaned };
+}
+
+/**
+ * Validate a Whisper language code before it is handed to nodejs-whisper.
+ *
+ * nodejs-whisper interpolates this value UNescaped into a shell command string
+ * (`-l <language>`) executed via shelljs.exec, so an unvalidated value is a
+ * command-injection sink. Whisper language codes are ISO 639-1/639-2 (2-3
+ * ASCII letters) or the literal "auto". Returns the trimmed code, or `undefined`
+ * for an empty/absent value. Throws on anything else.
+ */
+export function sanitizeWhisperLanguage(language) {
+  const trimmed = typeof language === "string" ? language.trim() : "";
+  if (!trimmed) return undefined;
+  if (!/^(auto|[a-z]{2,3})$/i.test(trimmed)) {
+    throw new Error(
+      `Invalid language code: ${JSON.stringify(language)}. ` +
+        `Expected an ISO 639 code (e.g. "en", "de", "ja") or "auto".`,
+    );
+  }
+  return trimmed;
+}
+
 /**
  * Parse a boolean-ish env-var value. Treats "0", "false", "no", "off"
  * (case-insensitive) and empty/undefined as falsy; everything else as truthy.

package/bin/live-crypto.mjs

@@ -0,0 +1,535 @@
+/**
+ * Remote Live Sessions — session-code derivation and E2E frame crypto.
+ *
+ * Node-side mirror of the extension's lib/remote-session.ts. The two modules
+ * must stay byte-compatible: same code normalization, same room-ID and key
+ * derivation, same AES-256-GCM frame format (see docs/live-protocol.md in the
+ * TraceGist repo). This package is published standalone, so the primitives
+ * are duplicated here rather than imported from the extension codebase.
+ */
+
+import { webcrypto } from "node:crypto";
+
+const subtle = webcrypto.subtle;
+
+/** Crockford base32 alphabet — no I, L, O, U to avoid ambiguity. */
+const CODE_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const CODE_GROUP_LENGTH = 5;
+const CODE_GROUPS = 3;
+
+const ROOM_ID_CONTEXT = "tracegist-room-v1:";
+
+/**
+ * Key derivation: PBKDF2-SHA256, high iteration count, into an HKDF base key.
+ * v3 adds the per-connection ephemeral-key handshake (see HandshakeManager).
+ * MUST match lib/remote-session.ts.
+ */
+const PBKDF2_SALT = "tracegist-live-v2";
+const PBKDF2_ITERATIONS = 210_000;
+
+export const FRAME_VERSION = 3;
+
+const HKDF_HANDSHAKE_INFO = "tracegist-hs-key-v3";
+const HKDF_CONNECTION_INFO = "tracegist-conn-v3";
+const HKDF_SALT_CONST = "tracegist-live-v3";
+const HANDSHAKE_NONCE_BYTES = 16;
+
+/** AES-GCM IV length in bytes (protocol constant, see docs/live-protocol.md) */
+const GCM_IV_BYTES = 12;
+
+/**
+ * AAD bound into every DATA frame's AES-GCM tag: version + sender role +
+ * per-direction counter. Blocks reflection and replay/reorder. MUST match
+ * lib/remote-session.ts byte-for-byte.
+ * @param {"tester" | "agent"} senderRole
+ * @param {number} counter
+ */
+function frameAad(senderRole, counter) {
+  return new TextEncoder().encode(`tracegist-frame-v3|${senderRole}|${counter}`);
+}
+
+/** AAD for a handshake frame: binds protocol tag + sender role. */
+function handshakeAad(senderRole) {
+  return new TextEncoder().encode(`tracegist-hs-v3|${senderRole}`);
+}
+
+/**
+ * Rejects frames whose per-direction counter is not strictly increasing (anti
+ * replay/reorder). One instance per receive direction; reset per connection.
+ */
+export class ReplayGuard {
+  constructor() {
+    this.last = -1;
+  }
+  /** @param {number} counter */
+  accept(counter) {
+    if (!Number.isInteger(counter) || counter <= this.last) return false;
+    this.last = counter;
+    return true;
+  }
+}
+
+/**
+ * Normalize a user-entered session code: trim, uppercase.
+ * @param {string} raw
+ * @returns {string | null} normalized code, or null if malformed
+ */
+export function normalizeSessionCode(raw) {
+  const code = String(raw).trim().toUpperCase();
+  const groupPattern = `[${CODE_ALPHABET}]{${CODE_GROUP_LENGTH}}`;
+  const pattern = new RegExp(`^TG(-${groupPattern}){${CODE_GROUPS}}$`);
+  return pattern.test(code) ? code : null;
+}
+
+/**
+ * Derive the relay room ID (hex SHA-256) from a normalized session code.
+ * @param {string} code
+ * @returns {Promise<string>}
+ */
+export async function deriveRoomId(code) {
+  const data = new TextEncoder().encode(ROOM_ID_CONTEXT + code);
+  const digest = await subtle.digest("SHA-256", data);
+  return Buffer.from(digest).toString("hex");
+}
+
+/**
+ * Derive the long-term "code secret" (HKDF base key) from the session code via
+ * PBKDF2. Everything else is HKDF'd from this. MUST match lib/remote-session.ts.
+ * @param {string} code
+ * @returns {Promise<CryptoKey>}
+ */
+export async function deriveCodeSecret(code) {
+  const encoder = new TextEncoder();
+  const pbkdf2Key = await subtle.importKey("raw", encoder.encode(code), "PBKDF2", false, [
+    "deriveBits",
+  ]);
+  const bits = await subtle.deriveBits(
+    {
+      name: "PBKDF2",
+      hash: "SHA-256",
+      salt: encoder.encode(PBKDF2_SALT),
+      iterations: PBKDF2_ITERATIONS,
+    },
+    pbkdf2Key,
+    256,
+  );
+  return subtle.importKey("raw", bits, "HKDF", false, ["deriveKey"]);
+}
+
+/**
+ * Derive the handshake key (encrypts the nonce-exchange frames).
+ * @param {CryptoKey} codeSecret
+ * @returns {Promise<CryptoKey>}
+ */
+export async function deriveHandshakeKey(codeSecret) {
+  const encoder = new TextEncoder();
+  return subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: encoder.encode(HKDF_SALT_CONST),
+      info: encoder.encode(HKDF_HANDSHAKE_INFO),
+    },
+    codeSecret,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/**
+ * Derive the per-connection DATA key from the code secret + both handshake
+ * nonces + epoch (nonces concatenated tester-then-agent). MUST match
+ * lib/remote-session.ts.
+ * @param {CryptoKey} codeSecret
+ * @param {Uint8Array} testerNonce
+ * @param {Uint8Array} agentNonce
+ * @param {number} epoch
+ * @returns {Promise<CryptoKey>}
+ */
+export async function deriveConnectionKey(codeSecret, testerNonce, agentNonce, epoch) {
+  const salt = new Uint8Array(testerNonce.length + agentNonce.length);
+  salt.set(testerNonce, 0);
+  salt.set(agentNonce, testerNonce.length);
+  return subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt,
+      info: new TextEncoder().encode(`${HKDF_CONNECTION_INFO}|${epoch}`),
+    },
+    codeSecret,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/** Generate a fresh handshake nonce (raw bytes). */
+export function generateHandshakeNonce() {
+  return webcrypto.getRandomValues(new Uint8Array(HANDSHAKE_NONCE_BYTES));
+}
+
+/**
+ * Encrypt a live-shadow message into a frame payload. `senderRole` is this
+ * endpoint's own role, `counter` its per-direction monotonic sequence; both are
+ * authenticated via AAD.
+ * @param {CryptoKey} key
+ * @param {object} message
+ * @param {"tester" | "agent"} senderRole
+ * @param {number} counter
+ * @returns {Promise<{v: number, iv: string, ct: string, c: number}>}
+ */
+export async function encryptFrame(key, message, senderRole, counter) {
+  // Counter must be a non-negative safe integer (see lib/remote-session.ts).
+  if (!Number.isSafeInteger(counter) || counter < 0) {
+    throw new Error("Frame counter exhausted — a new session/key is required");
+  }
+  const iv = webcrypto.getRandomValues(new Uint8Array(GCM_IV_BYTES));
+  const plaintext = new TextEncoder().encode(JSON.stringify(message));
+  const additionalData = frameAad(senderRole, counter);
+  const ct = await subtle.encrypt({ name: "AES-GCM", iv, additionalData }, key, plaintext);
+  return {
+    v: FRAME_VERSION,
+    iv: Buffer.from(iv).toString("base64"),
+    ct: Buffer.from(ct).toString("base64"),
+    c: counter,
+  };
+}
+
+/**
+ * Decrypt a frame payload back into a message object. `senderRole` is the role
+ * the receiver EXPECTS (the peer's role); the AAD is rebuilt from it and the
+ * frame counter, so a reflected or counter-tampered frame fails to authenticate.
+ * Returns null for unknown versions, malformed payloads, or failed auth.
+ * Anti-replay is enforced separately by ReplayGuard.
+ * @param {CryptoKey} key
+ * @param {{v: number, iv: string, ct: string, c: number}} payload
+ * @param {"tester" | "agent"} senderRole
+ * @returns {Promise<object | null>}
+ */
+export async function decryptFrame(key, payload, senderRole) {
+  // Counters are non-negative safe integers by construction; reject anything
+  // else before it reaches AAD building or the ReplayGuard.
+  if (!payload || payload.v !== FRAME_VERSION || !Number.isSafeInteger(payload.c) || payload.c < 0)
+    return null;
+  try {
+    const iv = Buffer.from(payload.iv, "base64");
+    const ct = Buffer.from(payload.ct, "base64");
+    const additionalData = frameAad(senderRole, payload.c);
+    const plaintext = await subtle.decrypt({ name: "AES-GCM", iv, additionalData }, key, ct);
+    return JSON.parse(new TextDecoder().decode(plaintext));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Encrypt a handshake message under the handshake key (authenticated by role).
+ * @param {CryptoKey} handshakeKey
+ * @param {"tester" | "agent"} senderRole
+ * @param {{epoch: number, nonce: string, role: string}} message
+ * @returns {Promise<{hs: 1, iv: string, ct: string}>}
+ */
+export async function encryptHandshake(handshakeKey, senderRole, message) {
+  const iv = webcrypto.getRandomValues(new Uint8Array(GCM_IV_BYTES));
+  const plaintext = new TextEncoder().encode(JSON.stringify(message));
+  const additionalData = handshakeAad(senderRole);
+  const ct = await subtle.encrypt({ name: "AES-GCM", iv, additionalData }, handshakeKey, plaintext);
+  return {
+    hs: 1,
+    iv: Buffer.from(iv).toString("base64"),
+    ct: Buffer.from(ct).toString("base64"),
+  };
+}
+
+/**
+ * Decrypt a handshake frame. `senderRole` is the expected sender (peer) role.
+ * @param {CryptoKey} handshakeKey
+ * @param {"tester" | "agent"} senderRole
+ * @param {{hs: 1, iv: string, ct: string}} payload
+ * @returns {Promise<{epoch: number, nonce: string, role: string} | null>}
+ */
+export async function decryptHandshake(handshakeKey, senderRole, payload) {
+  if (!payload || payload.hs !== 1) return null;
+  try {
+    const iv = Buffer.from(payload.iv, "base64");
+    const ct = Buffer.from(payload.ct, "base64");
+    const additionalData = handshakeAad(senderRole);
+    const plaintext = await subtle.decrypt(
+      { name: "AES-GCM", iv, additionalData },
+      handshakeKey,
+      ct,
+    );
+    const msg = JSON.parse(new TextDecoder().decode(plaintext));
+    if (
+      !Number.isSafeInteger(msg.epoch) ||
+      msg.epoch < 0 ||
+      typeof msg.nonce !== "string" ||
+      (msg.role !== "tester" && msg.role !== "agent")
+    ) {
+      return null;
+    }
+    return msg;
+  } catch {
+    return null;
+  }
+}
+
+/** True if a relay payload is a handshake frame (vs a data frame). */
+export function isHandshakeFrame(payload) {
+  return typeof payload === "object" && payload !== null && payload.hs === 1;
+}
+
+/**
+ * Per-connection ephemeral-key handshake state machine — mirror of
+ * lib/remote-session.ts (see that file for the protocol description).
+ */
+export class HandshakeManager {
+  /**
+   * @param {"tester" | "agent"} role
+   * @param {CryptoKey} codeSecret
+   * @param {CryptoKey} handshakeKey
+   */
+  constructor(role, codeSecret, handshakeKey) {
+    this.role = role;
+    this.peerRole = role === "tester" ? "agent" : "tester";
+    this.codeSecret = codeSecret;
+    this.handshakeKey = handshakeKey;
+    this.connectionKey = null;
+    this.sendCounter = 0;
+    this.guard = new ReplayGuard();
+    this.pendingEpoch = -1;
+    this.pendingNonce = null;
+    this.lastEpoch = -1;
+    // Highest epoch the tester has established (idempotency guard; see
+    // lib/remote-session.ts).
+    this.establishedEpoch = -1;
+    this.respondedEpoch = -1;
+    this.respondedNonce = null;
+  }
+
+  /**
+   * @param {"tester" | "agent"} role
+   * @param {string} code
+   */
+  static async create(role, code) {
+    const codeSecret = await deriveCodeSecret(code);
+    const handshakeKey = await deriveHandshakeKey(codeSecret);
+    return new HandshakeManager(role, codeSecret, handshakeKey);
+  }
+
+  get ready() {
+    return this.connectionKey !== null;
+  }
+
+  /** @param {number} now */
+  nextEpoch(now) {
+    const e = Math.max(this.lastEpoch + 1, Math.floor(now));
+    this.lastEpoch = e;
+    return e;
+  }
+
+  /** TESTER: begin a fresh handshake. @param {number} now */
+  async startHandshake(now) {
+    if (this.role !== "tester") throw new Error("only the tester initiates the handshake");
+    this.connectionKey = null;
+    this.pendingEpoch = this.nextEpoch(now);
+    this.pendingNonce = generateHandshakeNonce();
+    return this.encryptPendingHandshake();
+  }
+
+  encryptPendingHandshake() {
+    return encryptHandshake(this.handshakeKey, "tester", {
+      epoch: this.pendingEpoch,
+      nonce: Buffer.from(this.pendingNonce).toString("base64"),
+      role: "tester",
+    });
+  }
+
+  /** TESTER: re-encrypt the in-flight handshake for retransmit (or null). */
+  async retransmit() {
+    if (this.role !== "tester" || this.connectionKey !== null || !this.pendingNonce) return null;
+    return this.encryptPendingHandshake();
+  }
+
+  /** Feed an incoming handshake frame. */
+  async onHandshakeFrame(payload) {
+    const msg = await decryptHandshake(this.handshakeKey, this.peerRole, payload);
+    if (!msg || msg.role !== this.peerRole) return { kind: "ignored" };
+
+    if (this.role === "agent") {
+      if (msg.epoch < this.respondedEpoch) return { kind: "ignored" };
+      if (msg.epoch === this.respondedEpoch && this.respondedNonce) {
+        const resend = await encryptHandshake(this.handshakeKey, "agent", {
+          epoch: msg.epoch,
+          nonce: Buffer.from(this.respondedNonce).toString("base64"),
+          role: "agent",
+        });
+        return { kind: "response", payload: resend, keyReady: this.connectionKey !== null };
+      }
+      const testerNonce = Buffer.from(msg.nonce, "base64");
+      // A wrong-size nonce would silently derive a mismatched key — fail loud.
+      if (testerNonce.length !== HANDSHAKE_NONCE_BYTES) return { kind: "ignored" };
+      const agentNonce = generateHandshakeNonce();
+      this.connectionKey = await deriveConnectionKey(
+        this.codeSecret,
+        testerNonce,
+        agentNonce,
+        msg.epoch,
+      );
+      this.sendCounter = 0;
+      this.guard = new ReplayGuard();
+      this.respondedEpoch = msg.epoch;
+      this.respondedNonce = agentNonce;
+      const response = await encryptHandshake(this.handshakeKey, "agent", {
+        epoch: msg.epoch,
+        nonce: Buffer.from(agentNonce).toString("base64"),
+        role: "agent",
+      });
+      return { kind: "response", payload: response, keyReady: true };
+    }
+
+    if (msg.epoch !== this.pendingEpoch || !this.pendingNonce) return { kind: "ignored" };
+    // Idempotent: a re-delivered/replayed response for an already-established
+    // epoch must not re-derive or reset (would rewind the counter + reopen the
+    // replay hole). A legitimate reconnect uses a strictly higher epoch.
+    if (this.establishedEpoch >= msg.epoch) return { kind: "ignored" };
+    const agentNonce = Buffer.from(msg.nonce, "base64");
+    // A wrong-size nonce would silently derive a mismatched key — fail loud.
+    if (agentNonce.length !== HANDSHAKE_NONCE_BYTES) return { kind: "ignored" };
+    this.connectionKey = await deriveConnectionKey(
+      this.codeSecret,
+      this.pendingNonce,
+      agentNonce,
+      msg.epoch,
+    );
+    this.sendCounter = 0;
+    this.guard = new ReplayGuard();
+    this.establishedEpoch = msg.epoch;
+    return { kind: "established" };
+  }
+
+  /** Encrypt a data message under the connection key. Throws if not ready. */
+  async encryptData(message) {
+    if (!this.connectionKey) throw new Error("handshake not complete");
+    return encryptFrame(this.connectionKey, message, this.role, this.sendCounter++);
+  }
+
+  /** Decrypt + replay-check a data frame. Null if not ready / invalid. */
+  async decryptData(payload) {
+    if (!this.connectionKey) return null;
+    const inner = await decryptFrame(this.connectionKey, payload, this.peerRole);
+    if (inner === null) return null;
+    if (!this.guard.accept(payload.c)) return null;
+    return inner;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Frame chunking — mirror of lib/remote-session.ts (see that file for the
+// size rationale). Hosted relays cap WebSocket messages (Cloudflare: 1 MiB);
+// oversized inner messages are split into `frame-chunk` parts BEFORE
+// encryption so relays only ever see ordinary frames.
+// ---------------------------------------------------------------------------
+
+/** Inner messages whose UTF-8 size exceeds this are chunked. */
+export const FRAME_CHUNK_THRESHOLD_BYTES = 700_000;
+/** UTF-8 bytes per chunk. */
+export const FRAME_CHUNK_BYTES = 500_000;
+/** Hard cap on part count — bounds new Array(total) from a peer-supplied total. */
+export const MAX_CHUNK_TOTAL = 1024;
+
+/**
+ * Split an oversized inner message into `frame-chunk` parts. Returns null
+ * when the message fits in a single frame. Operates on UTF-8 bytes so
+ * multi-byte characters and surrogate pairs can never be split.
+ * @param {object} message
+ * @returns {Array<{type: "frame-chunk", id: string, seq: number, total: number, data: string}> | null}
+ */
+export function chunkInnerMessage(message) {
+  const bytes = new TextEncoder().encode(JSON.stringify(message));
+  if (bytes.length <= FRAME_CHUNK_THRESHOLD_BYTES) return null;
+  const total = Math.ceil(bytes.length / FRAME_CHUNK_BYTES);
+  const id = webcrypto.randomUUID();
+  const parts = [];
+  for (let seq = 0; seq < total; seq++) {
+    parts.push({
+      type: "frame-chunk",
+      id,
+      seq,
+      total,
+      data: Buffer.from(
+        bytes.subarray(seq * FRAME_CHUNK_BYTES, (seq + 1) * FRAME_CHUNK_BYTES),
+      ).toString("base64"),
+    });
+  }
+  return parts;
+}
+
+/**
+ * Reassembles decrypted `frame-chunk` parts back into the original message.
+ * Non-chunk messages pass through unchanged; chunk parts return null until
+ * the final part completes the message. A part for a new id discards any
+ * incomplete assembly (peer reconnect mid-message).
+ */
+export class FrameChunkAssembler {
+  constructor() {
+    this.id = null;
+    this.parts = [];
+    this.received = 0;
+  }
+
+  /**
+   * @param {object} inner - a decrypted inner message
+   * @returns {object | null} pass-through message, completed reassembly, or null
+   */
+  push(inner) {
+    if (inner.type !== "frame-chunk") return inner;
+
+    const { id, seq, total, data } = inner;
+    if (
+      typeof id !== "string" ||
+      typeof data !== "string" ||
+      !Number.isInteger(seq) ||
+      !Number.isInteger(total) ||
+      total < 1 ||
+      total > MAX_CHUNK_TOTAL ||
+      seq < 0 ||
+      seq >= total
+    ) {
+      return null;
+    }
+
+    if (this.id !== id) {
+      this.id = id;
+      this.parts = new Array(total);
+      this.received = 0;
+    }
+
+    if (this.parts.length !== total || this.parts[seq] !== undefined) {
+      this.reset();
+      return null;
+    }
+
+    this.parts[seq] = data;
+    this.received++;
+    if (this.received < total) return null;
+
+    const assembled = this.parts;
+    this.reset();
+    try {
+      const bytes = Buffer.concat(assembled.map((p) => Buffer.from(p, "base64")));
+      return JSON.parse(new TextDecoder().decode(bytes));
+    } catch {
+      // Corrupt part payload — same posture as decryptFrame: drop, don't crash
+      return null;
+    }
+  }
+
+  reset() {
+    this.id = null;
+    this.parts = [];
+    this.received = 0;
+  }
+}