security: route scoped snapshot through envelope sentinel escape

[garagon]

Summary

browse/src/content-security.ts defines a trust boundary envelope around page content that gets handed to the LLM:

═══ BEGIN UNTRUSTED WEB CONTENT ═══
...page text...
═══ END UNTRUSTED WEB CONTENT ═══

The wrap path (wrapUntrustedPageContent, the one used by text / html / full-page commands) already splices a zero-width space through the word CONTENT whenever those sentinels appear inside the content itself. That's the defense: a page that renders the literal sentinel string still goes through as visible text, but no longer matches the envelope grep the LLM anchors on.

The scoped-token path in browse/src/snapshot.ts (splitForScoped, used by snapshot and resume for scoped clients) builds the envelope by hand and skips that escape. It just does:

parts.push('═══ BEGIN UNTRUSTED WEB CONTENT ═══');
parts.push(...untrustedLines);   // no escape
parts.push('═══ END UNTRUSTED WEB CONTENT ═══');

So a page whose accessibility tree renders the literal ═══ END UNTRUSTED WEB CONTENT ═══ closes the envelope early, and the attacker can forge a new INTERACTIVE ELEMENTS (trusted …) block with any @eN reference they want. The LLM consuming that output sees a fake trusted @ref that doesn't exist in the real ref map, and if it tries to click/fill it on the rendered page it lands on whatever element the attacker chose to alias.

Reproduction (before the fix)

Stripped-down PoC — runs the two helper functions verbatim against the same hostile input:

bun run report/evidence/poc-f006-confusion-protocol-bypass.ts

Output shows splitForScoped emitting two BEGIN and two END sentinels on the same string (envelope breached), while wrapUntrustedPageContent emits exactly one of each (envelope intact).

Fix

One change, applied in two small steps so each side stays easy to audit.

1. Extract the existing escape into a named export. content-security.ts now has escapeEnvelopeSentinels(content: string): string — same two .replace() calls, no behavior change on the wrap path. wrapUntrustedPageContent calls it internally.
2. Use it in the scoped path. snapshot.ts imports escapeEnvelopeSentinels and maps it over untrustedLines in the splitForScoped branch before pushing the BEGIN sentinel.

// browse/src/snapshot.ts — splitForScoped branch
const safeUntrusted = untrustedLines.map(escapeEnvelopeSentinels);
parts.push('═══ BEGIN UNTRUSTED WEB CONTENT ═══');
parts.push(...safeUntrusted);
parts.push('═══ END UNTRUSTED WEB CONTENT ═══');

No changes to sentinel strings, no per-request nonce, no change to the scoped-ref map, no change to wrapUntrustedPageContent output bytes for any non-hostile content. The scoped path now behaves exactly like the wrap path with respect to in-content sentinel escape.

Sibling review

Greped browse/src/ for every emission of ═══ BEGIN UNTRUSTED WEB CONTENT ═══:

Location	Source of content	Escape	Status
content-security.ts wrapUntrustedPageContent	full page content string	was: inline, now: escapeEnvelopeSentinels	unchanged bytes
snapshot.ts splitForScoped branch	untrustedLines from accessibility tree	was: none	fixed
Any other BEGIN emission in browse/src/	n/a	n/a	n/a

No other call site emits the sentinel. Both paths now funnel untrusted text through the same escape helper.

Tests

browse/test/content-security.test.ts — a new Envelope sentinel escape describe block with 6 cases:

• escapeEnvelopeSentinels defuses a BEGIN marker inside content.
• escapeEnvelopeSentinels defuses an END marker inside content.
• escapeEnvelopeSentinels leaves normal text untouched (identity on non-sentinel lines).
• wrapUntrustedPageContent emits exactly one real envelope around hostile content that carries a forged BEGIN + END pair (regression for the already-protected wrap path).
• snapshot.ts imports escapeEnvelopeSentinels from ./content-security.
• The scoped-snapshot branch in snapshot.ts calls escapeEnvelopeSentinels before pushing the BEGIN sentinel (source-level lock; if a future refactor drops the escape or reorders the calls, the test trips before the diff reaches review).

bun test browse/test/content-security.test.ts: 53 pass, 0 fail.

Negative control

Reverting browse/src/snapshot.ts + browse/src/content-security.ts to origin/main and rerunning the same file:

• escapeEnvelopeSentinels import fails first (not exported yet).
• The two source-level regression tests on snapshot.ts fail.

Applying the fix: 53/53 pass.

What stayed the same

• Sentinel strings unchanged (no new format, no nonce).
• wrapUntrustedPageContent output bytes unchanged on any input that doesn't contain the sentinel.
• No change to the scoped @eN ref resolver, no change to splitForScoped's public signature, no change to how scoped snapshots are routed through the CLI.
• No new dependencies.
• Instruction block (SECURITY: section in the agent preamble) unchanged. The envelope it tells the LLM to trust is now genuinely one envelope on both code paths.

Files

 browse/src/content-security.ts       | 25 ++++++++++---
 browse/src/snapshot.ts               |  9 ++++-
 browse/test/content-security.test.ts | 71 +++++++++++++++++++++++++++++++++++-
 3 files changed, 98 insertions(+), 7 deletions(-)

How to verify

git checkout security/snapshot-envelope-escape
bun install
bun test browse/test/content-security.test.ts   # 53 pass
bun test                                           # full suite, exit 0