agent-yes 1.119.1 → 1.121.0

package/lab/ui/index.html

@@ -843,6 +843,21 @@
         hasIdent,
         deviceCount,
       } from "./console-logic.js";
+      import {
+        MARKER as E2E_MARKER,
+        ALLOW_LEGACY_PLAINTEXT,
+        FLAG_CONFIRM,
+        CONFIRM_TIMEOUT_MS,
+        deriveAuthToken,
+        deriveDirKeys,
+        computeTranscriptHash,
+        seal as e2eSeal,
+        open as e2eOpen,
+        packEnvelope,
+        unpackEnvelope,
+        parseSecret,
+        randomHex,
+      } from "./e2e.js";
 
       let entries = [];
       let sel = null; // selected agent's composite key (room#pid)
@@ -908,18 +923,46 @@
       // envelope in lab/ui/share-host.ts: {t:"req"|"abort"} out, {t:"res"|"data"|"end"} in.
       class RTCClient {
         constructor(host, room, token) {
+          let resolveKeys;
+          const keysReady = new Promise((r) => (resolveKeys = r));
           Object.assign(this, {
             host,
             room,
             token,
             dc: null,
-            nextId: 1,
             calls: new Map(),
             streams: new Map(),
             onstate: () => {},
+            // e2e (v2) per-connection state
+            _s: null,
+            _v2: false,
+            _send: { sendCtr: 0n },
+            _recvState: { lastSeen: -1n },
+            _tHash: null,
+            _keyH2C: null, // host->client: client decrypts with this
+            _keyC2H: null, // client->host: client encrypts with this
+            _keysReady: keysReady,
+            _resolveKeys: resolveKeys,
+            _myNonce: randomHex(16),
+            _confirmedIn: false,
+            _confirmedOut: false,
+            _confirmed: false,
+            _confirmTimer: null,
+            _recvChain: Promise.resolve(), // serialize decrypts (ordered replay check)
+            _sendChain: Promise.resolve(), // serialize seals (wire order == counter order)
           });
         }
-        connect() {
+        async connect() {
+          // Parse the secret marker (fail-closed on malformed) and split into the
+          // server-visible authToken vs the end-to-end keys the server never sees.
+          const { s, v2 } = parseSecret(this.token);
+          this._s = s;
+          this._v2 = v2;
+          if (!v2 && !ALLOW_LEGACY_PLAINTEXT)
+            throw new Error(
+              "this link uses the old unencrypted protocol — ask the host to upgrade",
+            );
+          const authToken = v2 ? await deriveAuthToken(s, this.room, this.host) : this.token;
           return new Promise((resolve, reject) => {
             const ws = new WebSocket(`wss://${this.host}/${this.room}`, [SUB]);
             this.ws = ws; // kept so close() can drop the signaling registration too
@@ -931,11 +974,22 @@
                 reject(e);
               }
             };
+            // Resolve ONLY after the mutual key-confirmation completes (see _dcRecv),
+            // never on bare dc.onopen — there must be no "connected but unverified" window.
+            const done = () => {
+              if (!settled) {
+                settled = true;
+                this.onstate("open");
+                resolve();
+              }
+            };
             ws.onopen = () =>
-              ws.send(JSON.stringify({ type: "hello", role: "client", token: this.token }));
+              ws.send(JSON.stringify({ type: "hello", role: "client", v: 2, token: authToken }));
             ws.onmessage = async (ev) => {
               const m = JSON.parse(ev.data);
               if (m.type === "welcome") {
+                if (this._v2 && m.v !== 2)
+                  return fail(new Error("host is running an old agent-yes — ask it to upgrade"));
                 pc = new RTCPeerConnection({
                   iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
                 });
@@ -947,18 +1001,44 @@
                 pc.onconnectionstatechange = () => this.onstate(pc.connectionState);
                 pc.ondatachannel = (e) => {
                   this.dc = e.channel;
-                  this.dc.onopen = () => {
-                    settled = true;
-                    this.onstate("open");
-                    resolve();
+                  this.dc.binaryType = "arraybuffer";
+                  this.dc.onopen = async () => {
+                    try {
+                      await this._keysReady;
+                      // Open the bidirectional confirmation handshake.
+                      this._dcSend(FLAG_CONFIRM, { t: "confirm", nonce: this._myNonce });
+                      this._confirmTimer = setTimeout(() => {
+                        if (!this._confirmed) fail(new Error("key confirmation timed out"));
+                      }, CONFIRM_TIMEOUT_MS);
+                    } catch (err) {
+                      fail(err);
+                    }
+                  };
+                  this.dc.onmessage = (ev2) => {
+                    this._recvChain = this._recvChain
+                      .then(() => this._dcRecv(ev2.data, done))
+                      .catch(() => {});
                   };
-                  this.dc.onmessage = (ev2) => this._recv(JSON.parse(ev2.data));
                   this.dc.onclose = () => this.onstate("closed");
                 };
               } else if (m.type === "offer") {
                 await pc.setRemoteDescription({ type: "offer", sdp: m.sdp });
                 await pc.setLocalDescription(await pc.createAnswer());
                 ws.send(JSON.stringify({ type: "answer", sdp: pc.localDescription.sdp }));
+                // Derive per-connection keys now both descriptions are stable, before
+                // the DataChannel opens. Client: remote=host offer, local=our answer.
+                try {
+                  this._tHash = await computeTranscriptHash(
+                    pc.remoteDescription.sdp,
+                    pc.localDescription.sdp,
+                  );
+                  const { keyH2C, keyC2H } = await deriveDirKeys(this._s, this._tHash);
+                  this._keyH2C = keyH2C;
+                  this._keyC2H = keyC2H;
+                  this._resolveKeys();
+                } catch (err) {
+                  fail(err);
+                }
               } else if (m.type === "candidate") {
                 await pc.addIceCandidate(m.candidate).catch(() => {});
               }
@@ -968,28 +1048,93 @@
             setTimeout(() => fail(new Error("connect timeout")), 8000);
           });
         }
+        // Seal an envelope and send it, serialized so wire order == counter order.
+        _dcSend(flags, obj) {
+          this._sendChain = this._sendChain.then(async () => {
+            if (!this.dc || this.dc.readyState !== "open" || !this._keyC2H || !this._tHash) return;
+            let frame;
+            try {
+              frame = await e2eSeal(
+                this._keyC2H,
+                this._send,
+                flags,
+                this._tHash,
+                packEnvelope(obj),
+              );
+            } catch {
+              this.close();
+              return;
+            }
+            try {
+              this.dc.send(frame);
+            } catch {}
+          });
+          return this._sendChain;
+        }
+        // Decrypt + route one frame. Fail-closed: any failure, replay, string
+        // frame, or pre-confirmation app frame closes the connection.
+        async _dcRecv(data, done) {
+          if (!this.dc) return;
+          if (typeof data === "string" || !this._keyH2C || !this._tHash) return this.close();
+          let env;
+          try {
+            const { plaintext } = await e2eOpen(this._keyH2C, data, this._tHash, this._recvState);
+            env = unpackEnvelope(plaintext);
+          } catch {
+            return this.close();
+          }
+          if (!this._confirmed) {
+            if (!env || env.t !== "confirm") return this.close();
+            if (typeof env.nonce === "string" && !this._confirmedOut) {
+              // Send (and flush) our echo BEFORE marking confirmed-out, so connect()
+              // can't resolve and let a req() race ahead of the echo on the wire.
+              await this._dcSend(FLAG_CONFIRM, {
+                t: "confirm",
+                nonce: this._myNonce,
+                echo: env.nonce,
+              });
+              this._confirmedOut = true;
+            }
+            if (env.echo && env.echo === this._myNonce) this._confirmedIn = true;
+            if (this._confirmedIn && this._confirmedOut) {
+              this._confirmed = true;
+              if (this._confirmTimer) clearTimeout(this._confirmTimer);
+              done(); // connect() resolves only now — the channel is mutually verified
+            }
+            return;
+          }
+          if (!env || env.t === "confirm") return; // stray confirm after handshake
+          this._recv(env);
+        }
         _recv(r) {
+          // Frames are authenticated + replay-checked before they reach here, so an
+          // id we don't know is a late/cancelled response from the legitimate host,
+          // not an attack — drop it rather than tear down the channel.
           const call = this.calls.get(r.id),
             stream = this.streams.get(r.id);
           if (r.t === "res") {
+            if (call) call.status = r.status;
+          } else if (r.t === "data") {
             if (call) {
-              call.status = r.status;
+              call.body += r.chunk;
+              call.dataCount = (call.dataCount || 0) + 1;
             }
-          } else if (r.t === "data") {
-            if (call) call.body += r.chunk;
             if (stream) stream(r.chunk);
           } else if (r.t === "end") {
             if (call) {
               clearTimeout(call.timer);
               this.calls.delete(r.id);
-              r.error
-                ? call.reject(new Error(r.error))
-                : call.resolve({ status: call.status, text: call.body });
+              // end.seq is the count of data frames the host sent; a mismatch means
+              // the stream was truncated, so don't resolve it as complete.
+              if (typeof r.seq === "number" && r.seq !== (call.dataCount || 0))
+                call.reject(new Error("truncated response"));
+              else if (r.error) call.reject(new Error(r.error));
+              else call.resolve({ status: call.status, text: call.body });
             }
           }
         }
         req(method, path, body) {
-          const id = this.nextId++;
+          const id = randomHex(16);
           return new Promise((resolve, reject) => {
             // Without a deadline a request over a silently-dead DataChannel (host
             // gone, ICE not yet timed out) never settles, so the caller — and the
@@ -998,31 +1143,28 @@
             const timer = setTimeout(() => {
               if (this.calls.delete(id)) reject(new Error("request timed out"));
             }, 12000);
-            this.calls.set(id, { status: 0, body: "", resolve, reject, timer });
-            try {
-              this.dc.send(JSON.stringify({ t: "req", id, method, path, body }));
-            } catch (e) {
+            this.calls.set(id, { status: 0, body: "", dataCount: 0, resolve, reject, timer });
+            this._dcSend(0, { t: "req", id, method, path, body }).catch((e) => {
               clearTimeout(timer);
               this.calls.delete(id);
               reject(e); // channel already torn down
-            }
+            });
           });
         }
         subscribe(path, onRaw) {
-          const id = this.nextId++;
+          const id = randomHex(16);
           this.streams.set(id, onRaw);
-          this.dc.send(JSON.stringify({ t: "req", id, method: "GET", path }));
+          this._dcSend(0, { t: "req", id, method: "GET", path });
           return () => {
             this.streams.delete(id);
-            try {
-              this.dc.send(JSON.stringify({ t: "abort", id }));
-            } catch {}
+            this._dcSend(0, { t: "abort", id });
           };
         }
         // Tear down BOTH wires. Closing only the pc leaves the signaling socket
         // open and this client registered in the room, so each reconnect would
         // leak another peer on the host. onstate is detached by the caller first.
         close() {
+          if (this._confirmTimer) clearTimeout(this._confirmTimer);
           try {
             this.ws?.close();
           } catch {}
@@ -1763,9 +1905,20 @@
 
       // ---- rooms: localStorage cache + a manager you open by clicking the badge ----
       const ROOMS_KEY = "ay.rooms";
+      const ROOM_TTL_MS = 90 * 24 * 60 * 60 * 1000; // evict stale rooms to bound how long a secret lingers in localStorage
       const loadRooms = () => {
         try {
-          return JSON.parse(localStorage.getItem(ROOMS_KEY) || "{}");
+          const r = JSON.parse(localStorage.getItem(ROOMS_KEY) || "{}");
+          const now = Date.now();
+          let changed = false;
+          for (const k of Object.keys(r)) {
+            if (r[k]?.ts && now - r[k].ts > ROOM_TTL_MS) {
+              delete r[k];
+              changed = true;
+            }
+          }
+          if (changed) localStorage.setItem(ROOMS_KEY, JSON.stringify(r));
+          return r;
         } catch {
           return {};
         }
@@ -2277,6 +2430,7 @@
         const aidLike =
           full &&
           !full[3] &&
+          !/^e\d/i.test(full[2]) && // an e<N>. version marker is always a secret, never an agent id
           /^\d{1,7}$/.test(full[2]) &&
           (full[1] === LOCAL || !!loadRooms()[full[1]]);
         if (full && !aidLike) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-yes",
-  "version": "1.119.1",
+  "version": "1.121.0",
   "description": "A wrapper tool that automates interactions with various AI CLI tools by automatically handling common prompts and responses.",
   "keywords": [
     "ai",
@@ -56,8 +56,11 @@
     "!dist/**/*.map",
     "dist/**/*.js",
     "lab/ui/console-logic.js",
+    "lab/ui/e2e.d.ts",
+    "lab/ui/e2e.js",
     "lab/ui/index.html",
-    "lab/ui/room-client.js"
+    "lab/ui/room-client.js",
+    "lab/ui/blog/**"
   ],
   "type": "module",
   "module": "ts/index.ts",
@@ -72,6 +75,7 @@
   },
   "scripts": {
     "build": "tsdown",
+    "check:e2e": "bun scripts/check-e2e.ts",
     "cf": "bun scripts/cf.ts",
     "build:rs": "cargo install --path rs --features swarm",
     "postbuild": "bun ./ts/postbuild.ts",

package/scripts/check-e2e.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env bun
+// CI guard: the WebRTC DataChannel must ALWAYS be end-to-end encrypted. This
+// fails the build if a plaintext-fallback pattern reappears in any of the three
+// DataChannel handlers — a sealed channel that silently falls back to
+// JSON.stringify/JSON.parse would defeat the whole protocol (see lab/ui/e2e.js).
+//
+// Note: signaling (the WebSocket) is plaintext by design — JSON.parse(ev.data)
+// in a ws.onmessage handler is fine. We only forbid the DataChannel patterns.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const root = path.join(import.meta.dir, "..");
+const FILES = ["ts/share.ts", "lab/ui/share-host.ts", "lab/ui/index.html"];
+
+// Literal substrings that only ever appear on a plaintext DataChannel path.
+const FORBIDDEN = [
+  "dc.send(JSON.stringify(",
+  "this.dc.send(JSON.stringify(",
+  "JSON.parse(ev2.data)", // browser dc.onmessage
+  "onReq(dc, aborts, JSON.parse", // host dc.onmessage (old form)
+];
+
+let violations = 0;
+for (const rel of FILES) {
+  const src = readFileSync(path.join(root, rel), "utf8");
+  for (const pat of FORBIDDEN) {
+    if (src.includes(pat)) {
+      console.error(`✗ ${rel}: forbidden plaintext-DataChannel pattern \`${pat}\``);
+      violations++;
+    }
+  }
+}
+
+if (violations) {
+  console.error(
+    `\n${violations} plaintext-fallback pattern(s) found — DataChannel frames MUST go through seal()/open() in lab/ui/e2e.js.`,
+  );
+  process.exit(1);
+}
+console.log("✓ e2e: no plaintext-DataChannel fallback in", FILES.join(", "));

package/ts/e2e-crypto.spec.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect } from "vitest";
+import {
+  V,
+  PROTO,
+  MARKER,
+  FLAG_CONFIRM,
+  validateS,
+  deriveAuthToken,
+  deriveDirKeys,
+  computeTranscriptHash,
+  seal,
+  open,
+  packEnvelope,
+  unpackEnvelope,
+  parseSecret,
+  randomHex,
+} from "../lab/ui/e2e.js";
+
+const S = "a".repeat(64); // a valid 64-hex secret for tests
+const S2 = "b".repeat(64);
+const TH = new Uint8Array(32).fill(7); // a fake transcript hash
+const TH2 = new Uint8Array(32).fill(9);
+
+// Minimal but realistic SDP fragments carrying the lines the binding reads.
+function sdp(fp: string, setup: string, ufrag: string): string {
+  return [
+    "v=0",
+    "o=- 1 1 IN IP4 0.0.0.0",
+    "s=-",
+    "t=0 0",
+    "m=application 9 UDP/DTLS/SCTP webrtc-datachannel",
+    `a=ice-ufrag:${ufrag}`,
+    `a=setup:${setup}`,
+    `a=fingerprint:${fp}`,
+  ].join("\r\n");
+}
+const FP_A = "sha-256 AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99";
+const FP_B = "sha-256 11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00";
+
+describe("e2e version constants", () => {
+  it("are internally consistent", () => {
+    expect(V).toBe(1);
+    expect(PROTO).toBe("ay-e2e-1");
+    expect(MARKER).toBe("e1.");
+    expect(FLAG_CONFIRM).toBe(0x01);
+  });
+});
+
+describe("validateS", () => {
+  it("accepts a 64-hex secret", () => {
+    expect(validateS(S)).toBe(S);
+  });
+  it("rejects bad input without echoing it", () => {
+    for (const bad of ["", "xyz", S.toUpperCase(), "e1." + S, S + "0", 123 as unknown as string]) {
+      try {
+        validateS(bad);
+        throw new Error("should have thrown for " + bad);
+      } catch (e) {
+        expect((e as Error).message).toBe("invalid share token");
+        expect((e as Error).message).not.toContain(String(bad).slice(0, 8) || "∅");
+      }
+    }
+  });
+});
+
+describe("deriveAuthToken", () => {
+  it("is deterministic and 64-hex", async () => {
+    const a = await deriveAuthToken(S, "room1", "s.agent-yes.com");
+    const b = await deriveAuthToken(S, "room1", "s.agent-yes.com");
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{64}$/);
+  });
+  it("is not equal to S (one-way) and binds room + sighost", async () => {
+    const base = await deriveAuthToken(S, "room1", "s.agent-yes.com");
+    expect(base).not.toBe(S);
+    expect(await deriveAuthToken(S, "room2", "s.agent-yes.com")).not.toBe(base);
+    expect(await deriveAuthToken(S, "room1", "other.host")).not.toBe(base);
+    expect(await deriveAuthToken(S2, "room1", "s.agent-yes.com")).not.toBe(base);
+  });
+});
+
+describe("seal / open round trip", () => {
+  it("round-trips a sealed envelope", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const send = { sendCtr: 0n };
+    const recv = { lastSeen: -1n };
+    const frame = await seal(keyH2C, send, 0, TH, packEnvelope({ t: "req", id: "x", path: "/p" }));
+    expect(frame).toBeInstanceOf(ArrayBuffer);
+    expect(new Uint8Array(frame)[0]).toBe(0x01); // VER
+    const { plaintext, counter, flags } = await open(keyH2C, frame, TH, recv);
+    expect(counter).toBe(0n);
+    expect(flags).toBe(0);
+    expect(unpackEnvelope(plaintext)).toEqual({ t: "req", id: "x", path: "/p" });
+  });
+
+  it("increments the counter and never repeats a nonce, even concurrently", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const send = { sendCtr: 0n };
+    const [f0, f1] = await Promise.all([
+      seal(keyH2C, send, 0, TH, packEnvelope({ n: 0 })),
+      seal(keyH2C, send, 0, TH, packEnvelope({ n: 1 })),
+    ]);
+    const nonce = (f: ArrayBuffer) => new Uint8Array(f).slice(2, 14).join(",");
+    expect(nonce(f0)).not.toBe(nonce(f1));
+    expect(send.sendCtr).toBe(2n);
+  });
+
+  it("carries the confirmation FLAG through", async () => {
+    const { keyC2H } = await deriveDirKeys(S, TH);
+    const frame = await seal(
+      keyC2H,
+      { sendCtr: 0n },
+      FLAG_CONFIRM,
+      TH,
+      packEnvelope({ t: "confirm" }),
+    );
+    const { flags } = await open(keyC2H, frame, TH, { lastSeen: -1n });
+    expect(flags & FLAG_CONFIRM).toBe(FLAG_CONFIRM);
+  });
+});
+
+describe("open is fail-closed", () => {
+  it("rejects a tampered ciphertext bit", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    const bytes = new Uint8Array(frame);
+    const last = bytes.length - 1;
+    bytes[last] = (bytes[last] ?? 0) ^ 0x01; // flip a tag bit
+    await expect(open(keyH2C, bytes, TH, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects a tampered header (VER/FLAGS/NONCE are authenticated)", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    const bytes = new Uint8Array(frame);
+    bytes[1] = (bytes[1] ?? 0) ^ 0x02; // flip a FLAGS bit
+    await expect(open(keyH2C, bytes, TH, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects a bad version byte", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    const bytes = new Uint8Array(frame);
+    bytes[0] = 0x02;
+    await expect(open(keyH2C, bytes, TH, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects a frame bound to a different transcript (per-frame binding)", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    await expect(open(keyH2C, frame, TH2, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects the wrong direction key", async () => {
+    const { keyH2C, keyC2H } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    await expect(open(keyC2H, frame, TH, { lastSeen: -1n })).rejects.toThrow();
+  });
+  it("rejects a first frame whose counter is not 0", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const frame = await seal(keyH2C, { sendCtr: 5n }, 0, TH, packEnvelope({ t: "confirm" }));
+    await expect(open(keyH2C, frame, TH, { lastSeen: -1n })).rejects.toThrow(/counter-0/);
+  });
+  it("rejects a frame from a different session (per-session keys)", async () => {
+    const a = await deriveDirKeys(S, TH);
+    const b = await deriveDirKeys(S, TH2);
+    const frame = await seal(a.keyH2C, { sendCtr: 0n }, 0, TH, packEnvelope({ t: "req" }));
+    // different key AND different AAD → fails
+    await expect(open(b.keyH2C, frame, TH2, { lastSeen: -1n })).rejects.toThrow();
+  });
+});
+
+describe("anti-replay (mandatory)", () => {
+  it("rejects a replayed frame and an out-of-order frame", async () => {
+    const { keyH2C } = await deriveDirKeys(S, TH);
+    const send = { sendCtr: 0n };
+    const recv = { lastSeen: -1n };
+    const f0 = await seal(keyH2C, send, 0, TH, packEnvelope({ n: 0 }));
+    const f1 = await seal(keyH2C, send, 0, TH, packEnvelope({ n: 1 }));
+    await open(keyH2C, f0, TH, recv); // counter 0 ok
+    await open(keyH2C, f1, TH, recv); // counter 1 ok
+    await expect(open(keyH2C, f1, TH, recv)).rejects.toThrow(/replay/); // replay counter 1
+    await expect(open(keyH2C, f0, TH, recv)).rejects.toThrow(/replay/); // reorder back to 0
+  });
+});
+
+describe("computeTranscriptHash", () => {
+  it("matches across ends with offer/answer swapped", async () => {
+    const local = sdp(FP_A, "actpass", "ufragLOCAL");
+    const remote = sdp(FP_B, "active", "ufragREMOTE");
+    // host: offer=local, answer=remote ; client: offer=remote(as seen), answer=local
+    const host = await computeTranscriptHash(local, remote);
+    const client = await computeTranscriptHash(local, remote);
+    expect(Buffer.from(host).toString("hex")).toBe(Buffer.from(client).toString("hex"));
+    // a different fingerprint changes the hash
+    const other = await computeTranscriptHash(
+      sdp(FP_A, "actpass", "ufragLOCAL"),
+      sdp(FP_A, "active", "x"),
+    );
+    expect(Buffer.from(other).toString("hex")).not.toBe(Buffer.from(host).toString("hex"));
+  });
+  it("fails closed on a missing fingerprint", async () => {
+    const noFp = "v=0\r\na=setup:active\r\na=ice-ufrag:u";
+    await expect(computeTranscriptHash(sdp(FP_A, "actpass", "u"), noFp)).rejects.toThrow(
+      /fingerprint/,
+    );
+  });
+  it("fails closed on a non-sha-256 fingerprint (downgrade)", async () => {
+    const sha1 = sdp("sha-1 AA:BB:CC", "active", "u");
+    await expect(computeTranscriptHash(sdp(FP_A, "actpass", "u"), sha1)).rejects.toThrow(/sha-256/);
+  });
+});
+
+describe("parseSecret marker grammar (strict, fail-closed)", () => {
+  it("parses v2 encrypted links", () => {
+    expect(parseSecret("e1." + S)).toEqual({ s: S, v2: true });
+  });
+  it("treats a bare 64-hex token and a pid as legacy (caller gates)", () => {
+    expect(parseSecret(S)).toEqual({ s: S, v2: false });
+    expect(parseSecret("12345")).toEqual({ s: "12345", v2: false });
+  });
+  it("rejects an unknown version marker (update required)", () => {
+    expect(() => parseSecret("e2." + S)).toThrow(/update required/);
+    expect(() => parseSecret("e10." + S)).toThrow(/update required/);
+  });
+  it("rejects marker-shaped-but-malformed tokens (never legacy)", () => {
+    expect(() => parseSecret("e1." + "z".repeat(64))).toThrow(/malformed/);
+    expect(() => parseSecret("e1." + "a".repeat(63))).toThrow(/malformed/);
+    expect(() => parseSecret("e1" + S)).toThrow(/malformed/); // marker-like, no dot
+    expect(() => parseSecret("E1." + S)).toThrow(/malformed/); // wrong case is not v2
+  });
+});
+
+describe("randomHex", () => {
+  it("returns n bytes of hex and varies", () => {
+    expect(randomHex(16)).toMatch(/^[0-9a-f]{32}$/);
+    expect(randomHex(16)).not.toBe(randomHex(16));
+  });
+});