Skip to content

HTML attachments: a page's own script cannot move the Inbox; no network for pages from outside the project (port of #2511) - #3469

Open
backnotprop wants to merge 7 commits into
mainfrom
fix/html-viewer-hardening-port
Open

backnotprop wants to merge 7 commits into
mainfrom
fix/html-viewer-hardening-port

Conversation

@backnotprop

@backnotprop backnotprop commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Supersedes #2511. It brings that fix onto today's viewer by hand instead of merging the old branch. After review, the link channel was redesigned (see "Design after review").

The hole

An HTML attachment in the Inbox can move the window to another thread by its own script, with no click. The bridge sent a followed link to the parent as a window-wide postMessage, and the parent accepted any link-click whose source was the frame's window. The page's own script runs in that same window, so it can post the same message. In the Inbox, onOpenLink follows thread links in place, so the page could move the window to any thread. On main this test is marked test.fixme('its own script, with no click, does not move the window').

The second hole: since 0.28.41, an HTML document outside the session's roots gets connect-src 'none' only when the asset route serves it by URL. When the viewer renders the same document as a srcdoc, it has no response header, and the viewer removes the page's own CSP tags. So its scripts could fetch, open an XHR or a WebSocket, or send a beacon.

What #2511 decided

  • Link clicks never ride the window: the host takes link-click only on a private MessagePort, and ignores a link-click posted on the window. Link clicks still go out only for a trusted click.
  • BRIDGE_PROTOCOL_VERSION goes from 1 to 2. A stale cached bridge-script.asset.js shows the existing version-mismatch banner instead of silently losing links.
  • No network for outside pages. rewriteHtmlAssetReferences gets noNetwork, which adds <meta name="plannotator-network" content="none"> (HTML_NO_NETWORK_MARKER, packages/shared/html-assets.ts). The Bun registry and Pi's mirror set it for an outside-root document, including on the rewrite's error path. When rawHtml carries the marker, the viewer puts <meta http-equiv="Content-Security-Policy" content="connect-src 'none'"> right after the doctype, before every page script. The policy has no script-src.

Design after review

#2511 handed a fresh port to the frame after every ready. Review showed a body script can make sure its own code receives that port: move the frame to the asset route's bare copy of the page (no bridge there) or call document.open() (which drops the bridge's listeners), then forge ready. A script in <head> could also take the port first. This PR now uses a different shape:

  • A link guard runs first in the document (packages/ui/components/html-viewer/linkGuard.ts). It is injected before the sandbox shim and before every script of the page, <head> included. It creates the MessageChannel, keeps one end in its closure, and offers the other end to the host in a single plannotator-bridge-link-offer message with this load's key.
  • The host accepts one offer per load it started, with that load's key (armLinkOffer in useHtmlAnnotation, armed by HtmlViewer). It refuses and closes every later offer. It never posts a port to the frame, so a forged ready gets nothing.
  • A new key for every load. A srcdoc's key is written into its guard script. A served frame's key (frameUrl, the Inbox, and every frame.reload) rides its address as __pnk, which the guard reads and removes with replaceState before any page script runs, so location.search is still the page's own.
  • The guard sends only for a person's click. It sends on its port only while a trusted click is being dispatched, and only for the clicked link's own href (never javascript:). For a form, the click must be on a button or input, and the address must be a query with no fragment. The bridge hands clicks to window.__plannotatorLinkGuard.follow (frozen, not replaceable). The built-ins it uses are captured before any page script runs.

Why this is sounder than one offer per load alone: with only "one offer per load", the old document can post an offer at the moment the host re-arms. A page can trigger that moment itself (a forged "page gone" message makes the Inbox re-serve the frame), or it happens after a reload a person caused. A per-load key that the old document cannot know closes that race: the new key is only in the new srcdoc text or the new address. What each hostile case gets:

  • Self-navigation to the asset copy: the guard has already made the only accepted offer, so the copy's offer is a second offer and is refused.
  • document.open(): the same; its new offer is a second offer.
  • A forged or repeated ready: nothing, because the host never sends ports.
  • A <head> script: it runs after the guard. It cannot get the port, and it cannot send anything without a person's click.

Limit, stated in the README, HANDOFF and guide. A page script can still act during a person's click:

  • On a link, it can make a Cmd/Ctrl-click follow the link instead of pinning it.
  • On a button or input, it can choose the query address that is sent. That address never has a fragment, so it can never be #thread=.

On the bridgeScriptUrl path (an opt-in host option that Plannotator does not use), the bridge asset runs the guard at the end of <head>. There, a script that the page puts earlier in <head> can take the guard's place.

How it works with #3162's link clicks

#3162 (owner approval html-link-click) made a person's click do more: a link that is only a query (?variant=2) reloads the served page in place, the prototype window follows links, and with pageNavigation a GET form is reported as <action>?<fields>. All of these reach the host as the same link-click, so all of them now go through the guard's port:

  • The bridge's two link-click senders, the link interceptor and submitPageForm, hand the click to the guard. Both are still registered only outside live mode, so Inbox: let people click and navigate inside an agent's prototype page #3162's guard test (two senders, both inside !LIVE) holds as it was.
  • The Inbox's served frame carries the guard inline and gets its own key in its address. frame.reload(search, hash) arms a new key and puts it in the new address. The page still sees exactly the query it was reloaded with.
  • onOpenLink(href, frame) and frame.reload are unchanged. The host still calls them, now from the port's handler.
  • What changed for a person: nothing. A real click, an Enter on a link, a tap, a GET form submit and a hash link all behave as before. No trade-off was needed.
  • The Inbox's own asset registry has no isInsideRoots, so its attachments never get the no-network marker. Their network policy (INBOX_PAGE_CSP) is unchanged.
  • Nothing here loosens the sandbox, the allowed schemes, a CSP or the asset-path checks.

What changed from the original PR

  • The link channel: the guard and one keyed offer per load, described above, replace "a new port on every ready". The link-port message is gone.
  • The no-network marker on the rewrite's error path now goes after a leading doctype (prependNoNetworkMarker), in both runtimes. The page no longer drops into quirks mode.
  • submitPageForm (new in Inbox: let people click and navigate inside an agent's prototype page #3162) goes through the guard. bridgePageNavigation.test.ts passes its sender to the form handler it runs.
  • In HtmlViewer, the CSP goes on after injectSandboxShim, injectPrintDefaults and the guard, so it is still the first thing after the doctype.
  • Pi vendors linkGuard.ts next to the bridge script (apps/pi-extension/vendor.sh), as it does the sandbox shim.
  • A packages/ui/HANDOFF.md entry for the protocol bump, next to Inbox: let people click and navigate inside an agent's prototype page #3162's entry.

packages/ui surface changes

  • BRIDGE_PROTOCOL_VERSION is 2.
  • New frame-to-host message plannotator-bridge-link-offer {key} with one transferred port. The host no longer posts any message or port to the frame.
  • A window link-click is ignored. onOpenLink and onLinkClick fire only from the accepted port.
  • On the inline path, an inline guard <script> comes first in <head>.
  • Served frame addresses carry __pnk, which the guard removes.
  • window.__plannotatorLinkGuard exists in the frame.
  • The bridgeScriptUrl tag gains data-plannotator-link-key.
  • A document that carries the marker renders with connect-src 'none'.
  • Internal only (not in index.ts or the exports map):
    • linkGuard.ts.
    • The srcdoc.ts helpers injectLinkGuard, hasNoNetworkMarker, NO_NETWORK_CSP_META and injectNoNetworkCsp.
    • A linkKey option on buildBridgeScriptTag and buildSrcdocInjection.
    • The hook's armLinkOffer.
    • The test helper test-setup/bridgeLinkPort.ts.
  • shared: HTML_NO_NETWORK_MARKER, RewriteHtmlAssetOptions.noNetwork and prependNoNetworkMarker.
  • No props, sandbox or exports changed.

Tests

  • tests/e2e/inbox-links-in-place.spec.ts, each in a real browser with no click unless stated:
    • "its own script, with no click, does not move the window" is now a real test, not fixme.
    • New: a page that moves its frame to its bare asset copy, then forges ready and offers ports with every key it could read (its load address from the navigation entry, the inline key, and a made-up key), plus a window link-click.
    • New: a page that calls document.open(), then forges ready and offers again, several times.
    • New: a <head> script that steals any posted port, calls the guard with no click, forges offers and readys, and, during a person's click, asks the guard for another thread. It then clicks the page's own link, which still goes to that link's thread.
    • Each of the hostile cases first checks that the page really did what it set out to do (the bare copy shows, the rewritten page shows). Repeated forging covers the second forged ready and offer.
  • tests/e2e/annotate-added-folder.spec.ts: an HTML page in a folder outside the project, opened from the Files sidebar, has its fetch refused with a connect-src violation.
  • linkGuard.test.ts (new, DOM): the guard's shipped string, run in a window with a fake parent. It checks:
    • one offer, with the key and a port, that the page never sees;
    • a person's click follows;
    • the page's own call and a.click() send nothing;
    • another href or a javascript: link sends nothing;
    • a click cannot be reused after dispatch;
    • the form rules;
    • a page listener that stops the click does not hide it from the guard;
    • the guard cannot be replaced, and a second run makes no second offer;
    • withLinkKey keeps the page's query.
  • htmlLinkProtocol.test.tsx:
    • the guard comes before the shim and the page's head script;
    • the offer with the load key is taken;
    • a window link-click is ignored;
    • a forged ready (twice) gets no port;
    • a second offer with the right key is refused, and the first port keeps working;
    • a wrong or missing key is refused and does not use up the load;
    • a new document re-keys, drops the old port and refuses the old key;
    • a served frame takes one offer.
    • Bounds, armed, read-only and Inbox: let people click and navigate inside an agent's prototype page #3162's frame/reload case go through the port.
    • The test that pinned "every ready gets a fresh port" is removed.
  • srcdoc.test.ts:
    • a person's click goes to the guard as a link and never on the window;
    • the guard is placed first in head, before a script ahead of <head>, with no head, and after the CSP;
    • the no-network block.
  • HtmlViewer.bridgeAsset.test.tsx: the URL-path tag carries the key.
  • HtmlViewer.sandbox.test.tsx: no-network placement.
  • packages/shared/html-assets.test.ts: the error-path marker keeps the doctype first.
  • doc-any-path.scenarios.ts: marker checks, run in both runtimes.
  • App.htmlLinkDraft.test.tsx and packages/inbox/htmlLinks.test.tsx simulate the guard's offer through test-setup/bridgeLinkPort.ts.

Run locally, each file by itself (DOM ones with DOM_TESTS=1 --isolate), all passed:

  • linkGuard (11)
  • htmlLinkProtocol (20)
  • srcdoc (142)
  • HtmlViewer.bridgeAsset (15)
  • bridgeAsset (9)
  • bridgePageNavigation (6)
  • HtmlViewer.sandbox (8)
  • HtmlViewer.frameUrl (5)
  • htmlLiveProtocol (39)
  • htmlPinpointProtocol (80)
  • prototypeWindow (5)
  • App.htmlLinkDraft (3)
  • the other neighbouring HtmlViewer.* and bridge DOM files
  • packages/shared/html-assets.test.ts (29)

tsc is clean for shared, server, ui, ui strict-consumer and inbox.

e2e: tests/e2e/inbox-links-in-place.spec.ts, tests/e2e/annotate-added-folder.spec.ts, tests/e2e/inbox-html-links.spec.ts, tests/e2e/annotate-html-links.spec.ts, tests/e2e/inbox-prototype-navigation.spec.ts, tests/e2e/inbox-pages-only.spec.ts, tests/e2e/inbox-html-phone.spec.ts, tests/e2e/inbox-html-fit.spec.ts, tests/e2e/inbox-attachments.spec.ts, tests/e2e/surface.spec.ts

Not verified locally

  • No browser runs locally. The e2e specs above, including the new hostile cases, run only in CI (ci:e2e).
  • packages/inbox/htmlLinks.test.tsx starts an Inbox test server, so it was not run locally.
  • apps/pi-extension/server/doc-any-path.test.ts needs the vendored generated/ folder, so it was not run locally. The Pi change is the same as the Bun change, line for line.
  • The bridgeScriptUrl path's guard (from the asset) is covered by unit tests only. No e2e uses that path.

…rk for pages from outside the project

Port of #2511 onto today's viewer.

- Link clicks (a link, or a pageNavigation GET form's address) travel only
  on a private MessagePort the viewer hands the bridge after each ready, in
  srcdoc and served frames alike. A link-click posted on the window, which a
  page's own script can do, is ignored. BRIDGE_PROTOCOL_VERSION 1 -> 2.
- A document opened outside the session's roots is marked by /api/doc
  (HTML_NO_NETWORK_MARKER, both runtimes) and the viewer puts
  connect-src 'none' right after its doctype.
- inbox-links-in-place: the fixme for a page's own script is a real test.
@backnotprop backnotprop added the ci:e2e Run the full browser suite (Inbox window e2e) on this PR label Nov 16, 2026
Review fixes for the port of #2511.

- A link guard runs first in the frame's document (before the sandbox shim
  and any page script, <head> included). It creates the channel, offers one
  end to the host with this load's key, and sends a link only while a
  person's click is being dispatched, for the clicked link's own href.
- The host takes one offer per load it started, only with that load's key
  (new for every srcdoc, served address and frame.reload; a served frame's
  key rides its address as __pnk and the guard removes it). It never posts
  a port to the frame: a forged ready, a second offer, a page that moved its
  frame to the bare asset copy or rewrote itself with document.open get
  nothing.
- On the bridgeScriptUrl path the asset runs the guard at the end of <head>;
  the limit for a <head> script there is documented.
- Error path: the no-network marker goes after a leading doctype, in both
  runtimes.
- Tests: the guard in a frame; one offer per load, keys, forged ready and
  second offers in htmlLinkProtocol; e2e hostile pages (bare asset copy,
  document.open, <head> script) in inbox-links-in-place.
// a page's own head script included: it owns the only port the host takes
// links on, and a script before it could take that port.
describe("link guard placement", () => {
const KEY = "0123456789abcdef0123456789abcdef";

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:e2e Run the full browser suite (Inbox window e2e) on this PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants