@botiverse/porthole 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/annotate/types.d.ts +42 -4
  2. package/dist/annotate/types.js +6 -1
  3. package/dist/annotate/validate.d.ts +16 -1
  4. package/dist/annotate/validate.js +33 -3
  5. package/dist/bridge/bridge.js +1 -51
  6. package/dist/bridge/unseen.d.ts +18 -0
  7. package/dist/bridge/unseen.js +71 -0
  8. package/dist/check/page-source.js +1 -1
  9. package/dist/conformance/behavior.js +107 -68
  10. package/dist/conformance/clipboard.js +16 -14
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/conformance/limits.js +117 -64
  13. package/dist/conformance/probes.js +66 -49
  14. package/dist/conformance/served.js +66 -63
  15. package/dist/host/create-host.js +75 -3
  16. package/dist/platform/types.d.ts +12 -1
  17. package/dist/platform/web.js +8 -0
  18. package/dist/react/frame.d.ts +6 -2
  19. package/dist/shell/annotate.d.ts +10 -3
  20. package/dist/shell/annotate.js +610 -39
  21. package/docs/ADOPTING.md +76 -0
  22. package/docs/ARCHITECTURE.md +2 -1
  23. package/docs/DECISIONS.md +516 -1
  24. package/docs/DESIGN.md +178 -20
  25. package/docs/THREAT_MODEL.md +92 -9
  26. package/package.json +1 -1
  27. package/src/annotate/types.ts +39 -5
  28. package/src/annotate/validate.ts +39 -3
  29. package/src/bridge/bridge.ts +1 -60
  30. package/src/bridge/unseen.ts +82 -0
  31. package/src/conformance/behavior.ts +221 -69
  32. package/src/conformance/clipboard.ts +44 -14
  33. package/src/conformance/limits.ts +169 -76
  34. package/src/conformance/probes.ts +97 -49
  35. package/src/conformance/served.ts +112 -63
  36. package/src/host/create-host.ts +75 -3
  37. package/src/platform/types.ts +9 -1
  38. package/src/platform/web.ts +10 -0
  39. package/src/react/frame.tsx +6 -2
  40. package/src/shell/annotate.ts +610 -39
package/docs/DESIGN.md CHANGED
@@ -931,12 +931,12 @@ closed like a strict host's (`leak/inherited-policy.spec.ts`).
931
931
 
932
932
  | # | Channel | Mechanism | Probes | Negative control → fails (Chromium / WebKit / Firefox) |
933
933
  |---|---------|-----------|--------|------------------------------------------|
934
- | 1 | fetch, XHR, WebSocket, EventSource, `sendBeacon`, `fetchLater`, a blob worker's fetch | CSP `connect-src` = the allowlist only (`'none'` by default) | `1.connect` (with an allowed origin as positive control) | `connect-src` → `1.connect` (all three); `8.prefetch` too on Chromium |
934
+ | 1 | fetch, XHR, WebSocket, EventSource, `sendBeacon`, `fetchLater`, a blob worker's fetch | CSP `connect-src` = the allowlist only (`'none'` by default) | `1.connect` (with an allowed origin as positive control) | `connect-src` → `1.connect`, `14.silent` (all three; `8.prefetch` no longer on Chromium: the shell's hint guard holds it, measured 0.7.0) |
935
935
  | 2 | images, CSS images, SVG `<image>`/`<use>`, media and posters, `input type=image`, stylesheets, `@import`, fonts, scripts, `import()`, workers, manifests, icons | CSP `img/media/font/style/script-src` = the allowlist only; `worker-src blob:` | `2.resources` (an allowed image as positive control) | — (the same CSP as item 1) |
936
- | 3 | WebRTC (ICE gathering reaches the network outside `connect-src`) | CSP `webrtc 'block'` **and** the shell removes every `RTC*`/`webkitRTC*` constructor, fixed in place, before content runs | `3.webrtc` (an unsandboxed peer connection as positive control: it sends STUN on both engines) | `webrtc` → `3.webrtc` (all three; Firefox's positive control needs `media.peerconnection.ice.loopback`, set in the suite's Firefox project, P035) |
937
- | 4 | a nested frame: a fresh realm where item 3's removal never happened | the shell drops frame-like elements (`iframe, frame, frameset, object, embed, portal, fencedframe`) synchronously wherever content connects a node (P030), and an observer removes any that arrive another way, in the document and every shadow root (`attachShadow` is wrapped so closed ones are reached too); documents are rendered inert and imported, never written; `document.open/write` throw; declarative shadow roots can't be built (P029); CSP `frame-src 'none'` | `4.light-dom`, `.sync-realm`, `.open-shadow`, `.closed-shadow`, `.shadow-nested`, `.declarative-shadow`, `.parse-html-unsafe`, `.domparser`, `.document-write`, `.plugins`, `.foreign-object`, `.template-clone`, `.static` (each: the child never runs, no STUN, no frame left) | `frame-guard,sync-guard` → light-dom, sync-realm, plugins, foreign-object, template-clone; `attach-shadow,sync-guard` → closed-shadow, shadow-nested; `declarative-shadow` → declarative-shadow; `parser-entry-points` → document-write (each on all three engines). Either guard alone is covered by the other. |
938
- | 5 | self-navigation out, with data in the URL (`location`, `replace`, `open(…, "_self")`, meta refresh, a link clicked past the shell, an SVG link), to the host's own origin, or to a `blob:`/`data:` document of its own (a fresh realm) | the **embedding page's** `frame-src` (`embedderCsp`: `'none'` for opaque content, P033; frames only, so the host's own workers are untouched, P038): a frame's own CSP cannot stop its own navigation; the shell sends link clicks out through `openLink` and drops refreshes (P030); a display whose frame navigates is started again, at most three times (P031). A served frame's page must let it reach the content origins, so there the shell cancels every navigation the frame starts to another document (the Navigation API's `navigate` event; reloads and same-document ones go on, P079), and tells the host (`navigationBlocked`, P080); an opaque frame gets no navigate events | `5.location`, `.replace`, `.open-self`, `.refresh`, `.anchor`, `.svg-link`, `.host-origin`, `.blob`, `.data` (no request reaches the canary or the host; a navigated document never runs: a witness origin hears nothing); served: `leak/served/live.spec.ts` (`location`, `replace`, `open(…, "_self")`, `navigation.navigate` to another content origin and to an outside site: no request reaches either, the document stays, the host is told the sibling's address), and the served conformance case `served.domain.self-navigation` (a click sends the frame to another content origin, then an outside site: the document stays, no request reaches the canary; on a tab of its own, `served.domain.tab-navigation`, P099) | `embedder-csp` → location, replace, open-self, anchor, svg-link, blob, data, `6.remote-download` (all three; `.refresh` holds: the synchronous guard drops the refresh; Firefox also holds `.data` by itself, P035; the navigation guard has no events in these opaque frames); `embedder-self` → `5.host-origin`; `navigate-guard` → the four served navigation cases (each reaches another content origin), `served.domain.self-navigation` and `served.domain.tab-navigation` (all three) |
939
- | 6 | forms, popups, downloads, top and parent navigation | `sandbox="allow-scripts"` only; CSP `form-action 'none'` | `6.submit`, `.request-submit`, `.blank-form`, `.open`, `.blank-link`, `.download`, `.remote-download`, `.top`, `.top-link`, `.parent` | `sandbox` → open, blank-link, top, top-link, parent (all three), download (Chromium; WebKit and Firefox started no download either way). Form submits still fail: `form-action` is a second wall |
936
+ | 3 | WebRTC (ICE gathering reaches the network outside `connect-src`) | CSP `webrtc 'block'` **and** the shell removes every `RTC*`/`webkitRTC*` constructor, fixed in place, before content runs | `3.webrtc` (an unsandboxed peer connection as positive control: it sends STUN on both engines) | `webrtc` → `3.webrtc`, `14.workers` (all three; Firefox's positive control needs `media.peerconnection.ice.loopback`, set in the suite's Firefox project, P035) |
937
+ | 4 | a nested frame: a fresh realm where item 3's removal never happened | the shell drops frame-like elements (`iframe, frame, frameset, object, embed, portal, fencedframe`) synchronously wherever content connects a node (P030), and an observer removes any that arrive another way, in the document and every shadow root (`attachShadow` is wrapped so closed ones are reached too); documents are rendered inert and imported, never written; `document.open/write` throw; declarative shadow roots can't be built (P029); CSP `frame-src 'none'` | `4.light-dom`, `.sync-realm`, `.open-shadow`, `.closed-shadow`, `.shadow-nested`, `.declarative-shadow`, `.parse-html-unsafe`, `.domparser`, `.document-write`, `.plugins`, `.foreign-object`, `.template-clone`, `.static` (each: the child never runs, no STUN, no frame left) | `frame-guard,sync-guard` → light-dom, sync-realm, plugins, foreign-object, template-clone, `14.shell`; `attach-shadow,sync-guard` → closed-shadow, shadow-nested; `declarative-shadow` → declarative-shadow; `parser-entry-points` → document-write, `14.shell` (each on all three engines; with `sync-guard`, WebKit's `8.preconnect` too). Either guard alone is covered by the other: `frame-guard` and `attach-shadow` alone fail nothing. |
938
+ | 5 | self-navigation out, with data in the URL (`location`, `replace`, `open(…, "_self")`, meta refresh, a link clicked past the shell, an SVG link), to the host's own origin, or to a `blob:`/`data:` document of its own (a fresh realm) | the **embedding page's** `frame-src` (`embedderCsp`: `'none'` for opaque content, P033; frames only, so the host's own workers are untouched, P038): a frame's own CSP cannot stop its own navigation; the shell sends link clicks out through `openLink` and drops refreshes (P030); a display whose frame navigates is started again, at most three times (P031). A served frame's page must let it reach the content origins, so there the shell cancels every navigation the frame starts to another document (the Navigation API's `navigate` event; reloads and same-document ones go on, P079), and tells the host (`navigationBlocked`, P080); an opaque frame gets no navigate events | `5.location`, `.replace`, `.open-self`, `.refresh`, `.anchor`, `.svg-link`, `.host-origin`, `.blob`, `.data` (no request reaches the canary or the host; a navigated document never runs: a witness origin hears nothing); served: `leak/served/live.spec.ts` (`location`, `replace`, `open(…, "_self")`, `navigation.navigate` to another content origin and to an outside site: no request reaches either, the document stays, the host is told the sibling's address), and the served conformance case `served.domain.self-navigation` (a click sends the frame to another content origin, then an outside site: the document stays, no request reaches the canary; on a tab of its own, `served.domain.tab-navigation`, P099) | `embedder-csp` → location, replace, open-self, anchor, svg-link, host-origin, blob, data, `6.remote-download` (all three; `.refresh` holds: the synchronous guard drops the refresh; Firefox no longer holds `.data` by itself (Firefox 155; P035 measured it did); `.blob` and `.data` see the document run by its first act, a beacon, which outlasts the display's restart (P096); the navigation guard has no events in these opaque frames); `embedder-self` → `5.host-origin`; `navigate-guard` → the four served navigation cases (each reaches another content origin), `served.domain.self-navigation` and `served.domain.tab-navigation` (all three) |
939
+ | 6 | forms, popups, downloads, top and parent navigation | `sandbox="allow-scripts"` only; CSP `form-action 'none'` | `6.submit`, `.request-submit`, `.blank-form`, `.open`, `.blank-link`, `.download`, `.remote-download`, `.top`, `.top-link`, `.parent` | `sandbox` → open, blank-link, top, top-link, parent, `14.dialogs`, `14.windows` (all three), `14.print` (Chromium, Firefox: WebKit prints nothing from a frame either way), download (Chromium; WebKit and Firefox started no download either way). Form submits still fail: `form-action` is a second wall |
940
940
  | 7 | `<base>` hijack, plugins | CSP `base-uri 'none'`, `object-src 'none'`; plugins removed as frames | `7.base-plugins` | `base-uri` → `7.base-plugins` (all three); `frame-guard,sync-guard` too (plugins left in place) |
941
941
  | 8 | resource hints and speculation rules | CSP for those an engine governs (`prefetch`, `preload`, `modulepreload`); for the rest the shell drops `dns-prefetch`, `preconnect`, `prefetch`, `prerender` links, speculation rules, refreshes and `x-dns-prefetch-control` metas synchronously, and refuses changes that would make a connected link one (P030); `x-dns-prefetch-control: off` | `8.preconnect`, `.dns-prefetch`, `.prefetch`, `.prerender`, `.preload`, `.modulepreload`, `.speculation-rules` (each in markup, inserted, and switched on by attribute change; no request, no connection) | `sync-guard` → `8.preconnect` (WebKit: it preconnects synchronously, outside CSP). Measured: Chromium and Firefox opened no preconnect even unsandboxed. `dns-prefetch` has no out-of-band oracle here (DNS isn't observed); the element is refused before it connects |
942
942
  | 9 | the host's DOM, storage, cookies, credentials; another display | opaque origin (no `allow-same-origin`); nothing secret is sent into the frame; the shell takes messages only from its parent | `9.host`, `9.siblings` (a display can't navigate or drive another) | — (the sandbox is the platform's; measured: a new frame's realm is cross-origin even in the task that made it, both engines) |
@@ -956,10 +956,10 @@ official App SDK connects under the inline, artifact and MCP Apps presets
956
956
  | 11 | auto-size | the shell reports its height (`size-changed`) as it changes; the host clamps it to `minHeightPx`..`maxHeightPx` and sizes the frame; past the cap the content scrolls inside | `11.size` (grows, shrinks, stops at the cap and scrolls, floors at the minimum; events carry the clamped height), `11.size-document` (a whole page's height; its own `load` fires; its title kept) | — |
957
957
  | 11 | theming | `setTheme(scheme)`: the host sends the resolved variables (the host's live values over the defaults, P028), the shell sets them in place, with `data-theme` and `color-scheme`, then fires the config's theme event once, only when the scheme or a value changed (never at mount, never for a host re-sending what the content has, P061); the frame element's `color-scheme` follows | `11.theme-flip` (no event at mount or for the same scheme; in place: content state kept, the event fired once per flip, back and forth), `11.theme-host-values` (live values for standard and own names; undeclared names dropped) | — |
958
958
  | 11 | base styles | plain CSS at zero specificity (`:where`): native buttons, inputs, selects and text areas take the theme's borders, radius, colors and focus ring, 44 px tall (the manual's touch size); the manual says so for inline widgets | `11.base-styles` (themed; content's own CSS overrides them) | — |
959
- | 12 | `sendPrompt` | the shell refuses a call without a gesture; the host refuses one without its page's user activation, then asks `confirm` with the whole text; declines count toward a mute | `12.prompt-gesture-confirm` (a call on load is refused; a click asks; a no sends nothing; a yes reaches the handler), `12.raw-message` (a raw `ui/message` around the shell, no click: refused by the host), `12.mute`, `12.no-confirm` | `confirm-gate` → prompt-gesture-confirm, link, mute, no-confirm; `shell-gesture` → prompt-gesture-confirm, mute; `host-gesture` → raw-message |
959
+ | 12 | `sendPrompt` | the shell refuses a call without a gesture; the host refuses one without its page's user activation, then asks `confirm` with the whole text; declines count toward a mute | `12.prompt-gesture-confirm` (a call on load is refused; a click asks; a no sends nothing; a yes reaches the handler), `12.raw-message` (a raw `ui/message` around the shell, no click: refused by the host), `12.mute`, `12.no-confirm` | `confirm-gate` → prompt-gesture-confirm, link, mute, no-confirm, `14.windows`; `shell-gesture` → prompt-gesture-confirm, mute, copy-text; `host-gesture` → raw-message |
960
960
  | 12 | live data (`readData`, `subscribeData`, P079) | MCP `resources/read`, `resources/subscribe`/`unsubscribe`, `notifications/resources/updated`; the `consent` gate asks the host once per display before the first data call (a no refuses them all; none refuses, fail closed), then the rate; a subscribed read may be answered from the host's cache, marked stale, the fresh one following as an update; a refusal tells content why (`data: { code, message }`, P080) | `test/live-data.test.ts`, `test/refusals.test.ts`; `leak/served/live.spec.ts` (read and followed, consent asked once; cached then fresh; a viewer's no refuses both, no handler runs, `denied` with its sentence; a host refusing all without handlers; a handler's `Refused`) | — |
961
961
  | 12 | `openLink` | link clicks go out through `openLink`; the bridge takes http(s) only, without credentials in the URL; confirmed | `12.link` (a web link asks and opens; `javascript:` links and `openLink("javascript:…")` do nothing and are refused) | `link-scheme` → `12.link` |
962
- | 14 | error reports (`reportError`, S05, P095) | the adapters hand the bridge what content logged as it came; the bridge counts reportError's rate before reading it, then makes bounded text of it (`boundedText`: each object once, `[Circular]`/`[Repeated]`; 1,000 values, 16 levels, 8,000 characters; a BigInt as `"5n"`), scrubs sealed addresses and cuts to 2,000; nothing a log holds throws out of an adapter | `14.error-shapes` (a cycle, a BigInt and a 20-level shared graph from an inline widget and from an MCP Apps view, each reported as bounded text); `test/log-bounds.test.ts` (undeclared or past its rate: nothing of it read) | `report-unbounded` → `14.error-shapes` |
962
+ | 14 | error reports (`reportError`, S05, P095) | the adapters hand the bridge what content logged as it came; the bridge counts reportError's rate before reading it, then makes bounded text of it (`boundedText`: each object once, `[Circular]`/`[Repeated]`; 1,000 values, 16 levels, 8,000 characters; a BigInt as `"5n"`), scrubs sealed addresses and cuts to 2,000; nothing a log holds throws out of an adapter | `14.error-shapes` (a cycle, a BigInt and a 20-level shared graph from an inline widget and from an MCP Apps view, each reported as bounded text); `test/log-bounds.test.ts` (undeclared or past its rate: nothing of it read) | `report-unbounded` → `14.error-shapes`, `14.silent` (its blocked-load report read as the text it was), on both host pages (P096) |
963
963
  | 12 | model context (`setModelContext`, S5, P100) | the `show` gate by default: the bridge hands the host's `show` the whole update (text blocks rebuilt, structured content P095's JSON data, at most `MAX_CONTEXT_CHARS`, no character the person can't see: format characters, variation selectors, private use, lone surrogates, controls but `\n` and `\t`, save the selectors and joiners of real emoji and the joiners that shape Arabic, Indic and Myanmar letters) after every other gate and before the handler; no `show`, or one that throws, refuses it (`no-show`, `not_allowed`), and `close` ends its wait; the manual calls it the content's unconfirmed text, never instructions, and says what is refused; the React provider's default `show` draws `ContextNotice`, whole, and lets a call go once its own update is on the page (one replaced before it was drawn is refused); named gates without `show` and without `withoutShow: true` earn a `ConfigWarning` | `12.model-context` (a raw `ui/update-model-context`: shown whole, then handled; a host without `show`: refused, no handler); `test/model-context.test.ts` (both adapters, the order, the shapes, the size, each invisible character in text, values and keys, the warning); `leak/react.spec.ts` (the default notice is drawn before the handler runs, with its size; two updates in one task: only the drawn one goes; stacked displays all reachable; no provider: refused) | `model-context-show` → `12.model-context` (all three, `scripts/controls.ts`; the kit's harness is built unweakened), and both React cases (measured on Chromium) |
964
964
 
965
965
  Measured: a click in the frame gives the host page user activation (it propagates to
@@ -981,7 +981,7 @@ for that to lapse and click with raw input.
981
981
  | Files: the version's own path in the CSP (P082) | `fileSetCspDirectives`: `<origin><base>` (tab) or `<origin>/__porthole/f/` (frame) in the seven loading directives; never `'self'` | `leak/served/files.spec.ts`: a page loads no other version's files; a way out past the base is blocked | `file-self` → those two cases (another version's data and module load; `%2e%2e` past the base reaches the server; all three) |
982
982
  | Files in a frame: access in the path (P083) | the ticket's answer is the entry; `/__porthole/f/<AES-GCM sealed session>/`; `history.replaceState` before anything loads; the host's check per file; an address opens on its own for an hour (then only the running page's own same-origin loads, till the session ends), renewed by the shell; reported as `./`, never whole | `test/files.test.ts` (sealed: no viewer or subject in it; another origin, a tampered or ended one: 401; revoked: 403; its hour, the page's own loads after it, renewal; redaction); `test/workers.test.ts` (workerd); every framed case of `leak/served/files.spec.ts` on WebKit (no cookie in frames), its reports never naming the address, its renewal under a moved clock | — |
983
983
  | Files: pages navigate within the set (P084, P098) | the guard lets a navigation to a page under `files.base` go, after `porthole/navigating`, and the page it opened says so as it arrives, each naming its version; the host takes the next load as that page, or the load the notice came after: a load no notice for the mounted version explained waits `LATE_NOTICE_MS` holding the frame (nothing it says reaches the display), then starts it again | `leak/served/files.spec.ts`: a link opens another page in the frame, the display goes on, also with the leaving page's notice dropped or every notice late; a non-page file, `/`, `/__porthole/d/…` never open; `test/pages-of-set.test.ts`: another version's notice or a hello first restarts at once, nothing is answered during the wait | `navigate-guard` → the three link cases, "opens nothing else" and the sealed-address reports case (all three; the last measured failing before P098 too) |
984
- | A page on a tab of its own (P099) | every served page's CSP header carries the frame's sandbox (`sandbox allow-scripts allow-same-origin`, `servedSandboxDirective`) and its `Permissions-Policy` denies what the frame's `allow` doesn't grant (`servedPermissionsPolicy`); on a tab the shell answers `window.open` with null (but `_self`), refuses picture-in-picture windows, devices, location, full screen, passkeys, the share sheet, payments (Apple Pay too) and a video's full screen; its navigation guard (P079) stops the page navigating itself, and `navigation.navigate()` and a tab's `open(…, "_self")` ask its rule before they start (the address read once, through the platform's own functions); a tab's links are followed by the shell as clicked (cancelled in its first listener, found through the composed path, closed shadow roots made open to it), never by the browser; a lock that can't take says so (`data-porthole-unfixed`, a report to the host) | `test/server.test.ts`, `test/files.test.ts`, `test/policy.test.ts`, `test/agreement.test.ts` (every served page, in a frame, on a tab, without fetch metadata; never a script, a url-mode app or Porthole's own pages; the header held to the frame's `allow`); served conformance `served.domain.tab-window-open`, `.tab-escapes` (a target=_blank link clicked past the shell, forms, a blob download, `prompt`), `.tab-opener` (its opener sent elsewhere), `.tab-navigation` (a `blob:` document of its own and an outside site, each from a fresh tab by `location`, `assign`, `replace`, a link past the shell, `navigation.navigate()` and `open(…, "_self")`, the last two given a two-faced address too, a link and `navigate()` with the built-ins lying), `.tab-links` (a link's `href`, `target` or `download` changed after the shell read it, a link in an open or closed shadow root; a fragment link still jumps, a cancelled one goes nowhere), `.tab-devices` (location, camera and microphone granted by the browser, full screen after a click), `.tab-prompts` (a passkey, a payment to a canary method, a share, a video's full screen: each refused at once); `test/permissions-policy.test.ts` (the denied list against Chromium's, checked in); `leak/served/tab.spec.ts`: those five, a file set's page on a tab (its module, fetch and links to its own pages work; nothing else opens), a frame's sealed address opened on a tab | `tab-sandbox` → tab-escapes, tab-opener, the file set's and the sealed address's cases (all three); `tab-sandbox,window-open` → those and tab-window-open (all three; picture-in-picture opens on Chromium and Firefox, absent on WebKit); `permissions-policy,device-locks` → tab-devices (all three), tab-prompts (Chromium, Firefox; WebKit refused each at once here either way); `device-locks` alone → tab-devices on WebKit and Firefox (they don't apply the header; Chromium holds), tab-prompts on Firefox; `window-open` or `permissions-policy` alone → none; `navigate-guard` → tab-navigation (all three); `navigate-ask` (the rule asked first, alone) → tab-navigation and tab-links on WebKit (Chromium and Firefox hold by the event); `link-rule` (the browser follows links again) → tab-links and tab-navigation on WebKit; `scripts/controls.ts` |
984
+ | A page on a tab of its own (P099) | every served page's CSP header carries the frame's sandbox (`sandbox allow-scripts allow-same-origin`, `servedSandboxDirective`) and its `Permissions-Policy` denies what the frame's `allow` doesn't grant (`servedPermissionsPolicy`); on a tab the shell answers `window.open` with null (but `_self`), refuses picture-in-picture windows, devices, location, full screen, passkeys, the share sheet, payments (Apple Pay too) and a video's full screen; its navigation guard (P079) stops the page navigating itself, and `navigation.navigate()` and a tab's `open(…, "_self")` ask its rule before they start (the address read once, through the platform's own functions); a tab's links are followed by the shell as clicked (cancelled in its first listener, found through the composed path, closed shadow roots made open to it), never by the browser; a lock that can't take says so (`data-porthole-unfixed`, a report to the host) | `test/server.test.ts`, `test/files.test.ts`, `test/policy.test.ts`, `test/agreement.test.ts` (every served page, in a frame, on a tab, without fetch metadata; never a script, a url-mode app or Porthole's own pages; the header held to the frame's `allow`); served conformance `served.domain.tab-window-open`, `.tab-escapes` (a target=_blank link clicked past the shell, forms, a blob download, `prompt`), `.tab-opener` (its opener sent elsewhere), `.tab-navigation` (a `blob:` document of its own and an outside site, each from a fresh tab by `location`, `assign`, `replace`, a link past the shell, `navigation.navigate()` and `open(…, "_self")`, the last two given a two-faced address too, a link and `navigate()` with the built-ins lying), `.tab-links` (a link's `href`, `target` or `download` changed after the shell read it, a link in an open or closed shadow root; a fragment link still jumps, a cancelled one goes nowhere), `.tab-devices` (location, camera and microphone granted by the browser, full screen after a click), `.tab-prompts` (a passkey, a payment to a canary method, a share, a video's full screen: each refused at once); `test/permissions-policy.test.ts` (the denied list against Chromium's, checked in); `leak/served/tab.spec.ts`: those five, a file set's page on a tab (its module, fetch and links to its own pages work; nothing else opens), a frame's sealed address opened on a tab | `tab-sandbox` → tab-escapes, tab-opener, the file set's and the sealed address's cases (all three); `tab-sandbox,window-open` → those and tab-window-open (all three; picture-in-picture opens on Chromium and Firefox, absent on WebKit); `permissions-policy,device-locks` → tab-devices (all three), tab-prompts (Chromium, Firefox; WebKit refused each at once here either way); `device-locks` alone → tab-devices on WebKit and Firefox (they don't apply the header; Chromium holds), tab-prompts on Firefox; `window-open` or `permissions-policy` alone → none; `navigate-guard` → tab-navigation, tab-links (all three; P096 measured the second); `navigate-ask` (the rule asked first, alone) → tab-navigation and tab-links on WebKit (Chromium and Firefox hold by the event); `link-rule` (the browser follows links again) → tab-links and tab-navigation on WebKit; `scripts/controls.ts` |
985
985
  | The runtime: a page's declaration (P086) | the bridge refuses a capability the page didn't declare (`undeclared`), on `porthole/call` and 0.6's requests alike, before any handler | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "an undeclared capability: null from use, refused when sent anyway, its handler never asked" | `runtime-declaration` → that case (all three) |
986
986
  | The runtime: levels (P087) | each method's least level against the host's viewer, before any handler | `test/runtime.test.ts`, `test/assets.test.ts` (the grant's level to the bridge); `leak/served/runtime.spec.ts`: "a method above the viewer's level: forbidden, its handler never asked" | `runtime-level` → that case, and P094's "a read above the viewer's level: a result the host pushed is refused as a cold read is", whose reads stand on it (all three) |
987
987
  | The runtime: a page's data names (P086, P094) | the bridge refuses a resource or tool the page's `data` doesn't name (`undeclared`), with a viewer and without one, before any handler | `test/audit-gates.test.ts`, `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "a resource outside the page's data names: refused with a viewer and without one, its handler never asked" | `runtime-data-names` → that case (all three) |
@@ -1004,7 +1004,7 @@ ancestors), and shows them what went on it.
1004
1004
 
1005
1005
  | # | Channel | Mechanism | Probes | Negative control → fails |
1006
1006
  |---|---------|-----------|--------|--------------------------|
1007
- | 13 | the async Clipboard API in a click (`writeText`, `write`, `readText`) | the shell's lock; Chromium also by the `allow` denial | `13.clipboard-api` | `clipboard` → WebKit, Firefox (Chromium holds by the `allow` denial) |
1007
+ | 13 | the async Clipboard API in a click (`writeText`, `write`, `readText`) | the shell's lock; Chromium also by the `allow` denial | `13.clipboard-api` | `clipboard` → WebKit, Firefox, with `14.shell`'s clipboard (Chromium holds by the `allow` denial) |
1008
1008
  | 13 | `execCommand("copy")`/`("cut")` of the content's own selected text | the shell refuses the commands | `13.clipboard-command` | `clipboard` → all three |
1009
1009
  | 13 | a copy listener swapping what the person copies (`clipboardData.setData`) | copy and cut events stopped at the window, first | `13.clipboard-event` (the person's own copy works: positive control) | `clipboard` → all three |
1010
1010
  | 12 | `copyText` | a click (shell and host), 30 a minute, the host's handler | `12.copy-text` (refused on load; the whole text reaches the handler from a click) | — |
@@ -1027,13 +1027,14 @@ chooses), and the annotation runtime is in the shell only then.
1027
1027
  |-----------|---------|--------|
1028
1028
  | host → frame | `porthole/annotate.start` | `{ elements, text }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects) |
1029
1029
  | host → frame | `porthole/annotate.stop` | — |
1030
- | host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes |
1030
+ | host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999) also gets a marker (P104) |
1031
1031
  | host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
1032
1032
  | host → frame | `porthole/annotate.clear` | — |
1033
- | frame → host | `porthole/annotate.selected` | `{ anchor, rect }` |
1033
+ | frame → host | `porthole/annotate.selected` | `{ anchor, rect }`; after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
1034
1034
  | frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
1035
1035
  | frame → host | `porthole/annotate.cancelled` | — (Escape) |
1036
- | frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect? }] }`: every mark after `show`, the one after `focus`, and when the content changed, only if a state did |
1036
+ | frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect? }] }`: every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a `count`, once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
1037
+ | frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker; `rect` is the marker's (P104); taken only while the host's page has transient activation (P105) |
1037
1038
 
1038
1039
  - **Anchors** are W3C Web Annotation selectors, at most one of each:
1039
1040
  `CssSelector` (unique: the nearest id, else a path of `nth-of-type` steps),
@@ -1046,17 +1047,58 @@ chooses), and the annotation runtime is in the shell only then.
1046
1047
  element anchor by its selector if its text still starts with its words (or the
1047
1048
  selector is an id, or it has no words), else the element holding its words. What
1048
1049
  can't be found is `orphaned`, said so; a host keeps the comment and shows it apart.
1049
- - **Rects** are in the frame's viewport, CSS px: add the frame element's position.
1050
+ - **Rects** are in the frame's viewport, CSS px: add the frame element's position
1051
+ (and map them through the frame's transform, where the host scales it). They are
1052
+ the page's word: `createHost` clamps each to the frame's viewport before the host
1053
+ hears it (P104); a box wholly outside becomes one of no size on the nearest edge
1054
+ (a mark below the fold: `y` at the viewport's height, no height). A platform whose
1055
+ `viewport()` answers no size or throws gets nothing at the corner (P105).
1056
+ - **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
1057
+ above 99; 0 the bubble alone) on an element's top right corner, inside the frame's
1058
+ width, and beside a text anchor's last line, centred on it (P105, #36): in the
1059
+ line's gutter, just past the right edge of the anchor's block; at the frame's right
1060
+ edge where the frame is too narrow for that; just past the line's last word where
1061
+ something else is beside the block (a table's next cell, a card in a row). Each
1062
+ place must be clear of that line's words and of anything of the content's but a box
1063
+ holding the anchor, between the words and the marker too (the shell hit-tests it).
1064
+ Markers ending on one line go together, in the order their words end; where the
1065
+ bubble with its glyph fits nowhere, its number alone does (compact); where neither
1066
+ does (two anchors on one full line of a phone), they go over the line's end. The
1067
+ pointer on a marker lights its words. Placing costs a bounded number of hit tests
1068
+ per marker in view (the layer's own boxes out of the way meanwhile), none for one
1069
+ out of view, and its line's end is read only as far as the line goes (P105: 300
1070
+ marks with counts in view, about 20 ms a change). An element's mark with a marker
1071
+ is a thin line. The layer takes no pointer but on markers: a press on one, and the pointer's
1072
+ moves over it, are stopped in the shell's first window listener, read through the
1073
+ platform's own functions kept before content runs (P105), and a trusted click is
1074
+ reported `activated`; a tap too, on WebKit as well, since each marker has a click
1075
+ listener of its own (WebKit makes a tap a click only on such an element, P105). Against content that patches none of the built-ins, none of
1076
+ its handlers, nor what is under the marker, gets them; content that patches others
1077
+ can reach the layer's nodes (P105). Either way the content can tell a press
1078
+ happened, by `:active`, `relatedTarget` and user activation. Markers step aside
1079
+ while elements are picked. No tab stop, and the layer stays `aria-hidden`: the
1080
+ host's own list of marks is the keyboard path.
1081
+ - **Following** (P104), only while a mark has a `count`. Each mark keeps what the
1082
+ host was last told (state and box); a settled scroll or resize (any scroller), or
1083
+ a quiet run of content changes (one the deadline cut short is checked once quiet),
1084
+ reports only what moved. A selection the host was told is told again after a
1085
+ settled scroll only if its box moved (P105, with or without counts). Both share one
1086
+ clock, at most one report a second (the latest), so honest scrolling takes at most
1087
+ half of the bridge's 120 a minute.
1050
1088
  - **Settled.** Nothing is reported before the content is in place (marks shown
1051
1089
  before it arrives are anchored once it has), nor while a run of changes settles; a
1052
1090
  `focus` asked for meanwhile waits for anchoring, then scrolls and reports, so a
1053
1091
  focus right after `show` says where the mark is, never `orphaned` first (P057).
1054
1092
  - **Trust.** The shell shares its realm with the content, which can interfere with
1055
- all of it or fake any report. The host takes a selection only while it asked for
1056
- that kind, a cancel only while picking, results only for its own marks; it
1057
- rebuilds each from known fields within `ANNOTATION_LIMITS` and drops the rest,
1058
- through the bridge's rate limit. UI hints only, never permissions: what a
1059
- report says decides where a comment is drawn, never who may see or do anything.
1093
+ all of it, read what `show` sends (ids, anchors, counts), or fake any report. The
1094
+ host takes a selection only while it asked for that kind, a cancel only while
1095
+ picking, results only for its own marks, a marker's click only for a mark it shows
1096
+ with a count and only within a gesture (P105); it rebuilds each from known fields
1097
+ within `ANNOTATION_LIMITS` (a label without what the person can't see, P105) and
1098
+ drops the rest, through the bridge's rate limit. UI hints only, never
1099
+ permissions: what a report says decides where a comment is drawn, never who may
1100
+ see or do anything. A view a report opens or moves guards its presses
1101
+ (THREAT_MODEL §6).
1060
1102
  - **Host API.** `display.annotations.start(mode?)`, `stop()`, `show(marks)`,
1061
1103
  `focus(id)`, `clear()`, and the `annotation` event (`AnnotationReport`); the state
1062
1104
  is given to every frame the display runs. `parseAnchor` checks an anchor a host
@@ -1069,7 +1111,31 @@ view, one orphaned, all cleared; re-anchoring on a revised page (by id, by words
1069
1111
  moved, by words respaced, one deleted and orphaned); live changes reported only as
1070
1112
  they change; an MCP Apps view; and a hostile page faking every report (not asked,
1071
1113
  malformed, too large, the wrong kind, no such mark, a flood), whose negative
1072
- control is `annotation-checks`.
1114
+ control is `annotation-checks`. Markers (P104): drawn with their numbers, a click
1115
+ reported with its id and box and heard by none of the content's listeners, nor a
1116
+ double, right or middle click (`marker-click` → those two cases), focus and
1117
+ selection kept, a drag from a marker too (`marker-prevent` → the press case), none
1118
+ without a count, stepping aside while picking, drawn whole at the frame's top; a
1119
+ run of scrolls reported with only the marks that moved, a fixed one never; marks
1120
+ without counts told nothing after a scroll (`follow-count`); a long honest scroll
1121
+ session in comment mode, a selection made, leaving a marker's click its budget,
1122
+ and then, by when each arrives, the selection's re-reports and the marks'
1123
+ follow-ups a second apart however fast the machine (`follow-throttle`,
1124
+ `selection-follow`); a content change that moves one mark
1125
+ reports it alone, even when the deadline cut its run short; a hostile page faking a
1126
+ marker's click for no mark, an unknown id or a mark without a marker, or clicking
1127
+ the layer itself (`annotation-activated`, `annotation-activated-count`,
1128
+ `marker-trusted` → that case), or by itself, without a gesture
1129
+ (`annotation-activated-gesture`); and a page that patches `Event`'s and
1130
+ `MouseEvent`'s prototypes neither hearing a marker's press nor stopping its report
1131
+ (`marker-originals`; `marker-click` too); a tap on a marker reported on each
1132
+ engine, a touch screen and a phone's emulation (iPhone 13, Pixel 5), content hearing
1133
+ none of it (`marker-tap` → WebKit; `marker-click` too); on a 640 px column and a phone page's lines
1134
+ with one marker each, no marker covering a word (`marker-place`, the marker just
1135
+ past its words as 0.9.0 had it); and ADOPTING.md's `guardPresses`, as written
1136
+ there, taking no press within 500 ms of its view opening (a release on a menu item,
1137
+ a double click's second press on a button or a trigger, a press held past the
1138
+ arming) and the person's own press or key after.
1073
1139
 
1074
1140
  ## The shell runtime
1075
1141
 
@@ -1281,10 +1347,102 @@ embedding CSP `embedderCsp` derives): `pnpm test:leak` runs Chromium, WebKit and
1281
1347
  Firefox;
1282
1348
  `PORTHOLE_LEAK_ENGINES=chromium` runs a subset where an engine's system libraries
1283
1349
  are missing; `PORTHOLE_LEAK_WEAKEN=<control>[,<control>]` serves the core with
1284
- defenses taken out (P032; the table above lists what each must fail).
1350
+ defenses taken out (P032; § The negative controls lists what each must fail).
1285
1351
  `ConformanceHost.launch` called twice on one page shows two displays side by side
1286
1352
  (`9.siblings`).
1287
1353
 
1354
+ ### The negative controls
1355
+
1356
+ Every control the suite has is in one registry (`leak/controls.ts`, P096): the specs it
1357
+ is run with and the tests it must fail on each engine, each named exactly (a probe's
1358
+ `[id]`, a served case's id, or a test's whole title). `pnpm --filter @botiverse/porthole
1359
+ test:controls` (`scripts/controls.ts`; in CI, a job per engine) runs each of them and
1360
+ requires its tests to fail by their verdicts, on every engine asked, and every other test
1361
+ of its specs to pass. A probe's verdict is its deciding `expect`, whose message starts
1362
+ `probe: ` (in the shipped probes and in the spec tests the registry names); a failure of
1363
+ its setup or of a positive control is no failure of the wall. A run that didn't happen, an
1364
+ engine missing from the report, a probe skipped, never run, timed out or failed by anything
1365
+ but its verdict, or a test declared to fail (`test.fail`) that passes, fails the check. A
1366
+ control that fails nothing on an engine says why: another wall holds, shown by a combined
1367
+ control that takes both out and fails something there, or no probe can see the wall; one
1368
+ that fails "every other test" takes out what all of them stand on (`nonce`: the shell),
1369
+ and none of them may pass. No control runs `kit.spec.ts`: the kit's reference app runs
1370
+ Porthole in Node, where no weakening reaches (`UNWEAKENED`). In CI a whole engine's controls
1371
+ outlast a job, so each job runs one of four shards of the registry (`--shard k/4`, split by
1372
+ measured weight, stable for a registry), and the `controls` job checks every shard's verdicts
1373
+ (`--summary`): every control ran and held on every engine. The table is the registry's
1374
+ (`node scripts/controls.ts --table` prints it; `test/controls.test.ts` holds them equal,
1375
+ every weakening to a control, every control that fails nothing to its reason, and every
1376
+ control the tables above name to the registry):
1377
+
1378
+ | Control | Run with | Fails on every engine | Fails only on | Where it fails nothing, why |
1379
+ |---------|----------|-----------------------|---------------|-----------------------------|
1380
+ | `connect-src` | `leak.spec.ts` | `[1.connect]`, `[14.silent]` | — | — |
1381
+ | `webrtc` | `leak.spec.ts` | `[3.webrtc]`, `[14.workers]` | — | — |
1382
+ | `frame-guard` | `leak.spec.ts` | nothing | — | the synchronous guard drops what the observer would (`frame-guard,sync-guard`) |
1383
+ | `attach-shadow` | `leak.spec.ts` | nothing | — | the synchronous guard reaches a closed shadow root's frames as they connect (`attach-shadow,sync-guard`) |
1384
+ | `sync-guard` | `leak.spec.ts` | nothing | WebKit: `[8.preconnect]` | on Chromium and Firefox the observer removes what the synchronous guard would, and no preconnect opens even unsandboxed (measured) (`frame-guard,sync-guard`) |
1385
+ | `frame-guard,sync-guard` | `leak.spec.ts` | `[4.light-dom]`, `[4.sync-realm]`, `[4.plugins]`, `[4.foreign-object]`, `[4.template-clone]`, `[7.base-plugins]`, `[14.shell]` | WebKit: `[8.preconnect]` | — |
1386
+ | `attach-shadow,sync-guard` | `leak.spec.ts` | `[4.closed-shadow]`, `[4.shadow-nested]` | WebKit: `[8.preconnect]` | — |
1387
+ | `declarative-shadow` | `leak.spec.ts` | `[4.declarative-shadow]` | — | — |
1388
+ | `parser-entry-points` | `leak.spec.ts` | `[4.document-write]`, `[14.shell]` | — | — |
1389
+ | `embedder-csp` | `leak.spec.ts` | `[5.location]`, `[5.replace]`, `[5.open-self]`, `[5.anchor]`, `[5.svg-link]`, `[5.host-origin]`, `[5.blob]`, `[5.data]`, `[6.remote-download]` | — | — |
1390
+ | `embedder-self` | `leak.spec.ts` | `[5.host-origin]` | — | — |
1391
+ | `sandbox` | `leak.spec.ts` | `[6.open]`, `[6.blank-link]`, `[6.top]`, `[6.top-link]`, `[6.parent]`, `[14.dialogs]`, `[14.windows]` | Chromium: `[6.download]`, `[14.print]`; Firefox: `[14.print]` | — |
1392
+ | `base-uri` | `leak.spec.ts` | `[7.base-plugins]` | — | — |
1393
+ | `self` | `leak.spec.ts` | nothing | — | no probe can see it: an opaque frame's 'self' matches no origin, so 'self' in its CSP reaches nothing of the host on any engine (measured, P022); kept out because nothing needs it, and its run checks that it still opens nothing |
1394
+ | `style-split` | `leak.spec.ts` | `[0.app-sdk-inline]`, `[0.app-sdk-artifact]`, `[0.app-sdk-mcp-app]` | — | — |
1395
+ | `draft-inert` | `leak.spec.ts` | `[11.streaming]` | — | — |
1396
+ | `document-theme` | `leak.spec.ts` | `[11.document-theme]`, `[14.theme-never]` | — | — |
1397
+ | `confirm-gate` | `leak.spec.ts` | `[12.prompt-gesture-confirm]`, `[12.link]`, `[12.mute]`, `[12.no-confirm]`, `[14.windows]` | — | — |
1398
+ | `shell-gesture` | `leak.spec.ts` | `[12.prompt-gesture-confirm]`, `[12.mute]`, `[12.copy-text]` | — | — |
1399
+ | `host-gesture` | `leak.spec.ts` | `[12.raw-message]` | — | — |
1400
+ | `model-context-show` | `leak.spec.ts` | `[12.model-context]` | — | — |
1401
+ | `link-scheme` | `leak.spec.ts` | `[12.link]` | — | — |
1402
+ | `clipboard` | `leak.spec.ts` | `[13.clipboard-command]`, `[13.clipboard-event]` | WebKit, Firefox: `[13.clipboard-api]`, `[14.shell]` | — |
1403
+ | `report-unbounded` | `leak.spec.ts`, `strict-csp.spec.ts` | `[14.error-shapes]`, `[14.silent]` | — | — |
1404
+ | `nonce` | `strict-csp.spec.ts` | `the shell runs on a host page whose script-src is its nonce alone (P054)`, and every other test | — | — |
1405
+ | `annotation-checks` | `annotate.spec.ts` | `a hostile page fakes reports: the host takes none it didn't ask for, nothing malformed, and not a flood` | — | — |
1406
+ | `annotation-activated` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
1407
+ | `annotation-activated-count` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
1408
+ | `marker-trusted` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
1409
+ | `marker-click` | `annotate.spec.ts` | `markers: a mark with a count gets a numbered bubble; its click is reported and never reaches the content`, `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection`, `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)`, `a tap on a marker is reported on every engine, and the content hears none of it (P105)` | — | — |
1410
+ | `marker-prevent` | `annotate.spec.ts` | `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection` | — | — |
1411
+ | `marker-place` | `annotate.spec.ts` | `text markers cover no word: on a column page, and on a phone's lines with one marker each (P105, #36)` | — | — |
1412
+ | `marker-tap` | `annotate.spec.ts` | nothing | WebKit: `a tap on a marker is reported on every engine, and the content hears none of it (P105)` | no probe can see it on Chromium and Firefox: they make a tap a click on the marker without a listener of its own (measured, P105) |
1413
+ | `marker-originals` | `annotate.spec.ts` | `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)` | — | — |
1414
+ | `follow-throttle` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
1415
+ | `selection-follow` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
1416
+ | `follow-count` | `annotate.spec.ts` | `following: a host that gives no counts hears no follow-up after a scroll, as before markers` | — | — |
1417
+ | `annotation-activated-gesture` | `annotate.spec.ts` | `a hostile page's marker click with no gesture is dropped; one on the person's own press is the host's view to guard (P105)` | — | — |
1418
+ | `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved` | — | — |
1419
+ | `authorize` | `served/authorize.spec.ts` | `a revoked subject's ticket opens nothing: a page and an app are denied, and the host is told`, `in a tab of its own, a revoked app and page are denied from the next request on` | Chromium, Firefox: `a framed app mid-session: its next request after revocation is denied, and its next load tells the host`, `a framed page mid-session: its next load after revocation is denied where the engine keeps its cookie` | — |
1420
+ | `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
1421
+ | `navigate-guard` | `served/live.spec.ts`, `served/files.spec.ts`, `served/served.spec.ts`, `served/tab.spec.ts` | `served.domain.self-navigation`, `served.domain.tab-navigation`, `served.domain.tab-links`, `can't navigate itself away (location): to a site, or to another content origin`, `can't navigate itself away (replace): to a site, or to another content origin`, `can't navigate itself away (open-self): to a site, or to another content origin`, `can't navigate itself away (navigation-api): to a site, or to another content origin`, `a link to another page of the set opens it in the frame; the display goes on`, `a link to another page of the set opens it in the frame when the leaving page's notice is dropped (P098)`, `a link to another page of the set opens it in the frame when the leaving page's notice is late (P098)`, `a page opens nothing else: not a file that isn't a page, not another path of its origin`, `no report, content error or blocked navigation names the frame's sealed address (P083)` | — | — |
1422
+ | `tab-sandbox` | `served/tab.spec.ts` | `served.domain.tab-escapes`, `served.domain.tab-opener`, `a file set's page on a tab of its own opens its own pages, and no window, link in a new window or download`, `a frame's sealed address opened on a tab of its own is sandboxed as its frame is` | — | — |
1423
+ | `window-open` | `served/tab.spec.ts` | nothing | — | the CSP's sandbox stops a window first (`tab-sandbox,window-open`) |
1424
+ | `tab-sandbox,window-open` | `served/tab.spec.ts` | `served.domain.tab-escapes`, `served.domain.tab-opener`, `a file set's page on a tab of its own opens its own pages, and no window, link in a new window or download`, `a frame's sealed address opened on a tab of its own is sandboxed as its frame is`, `served.domain.tab-window-open` | — | — |
1425
+ | `navigate-ask` | `served/tab.spec.ts` | nothing | WebKit: `served.domain.tab-navigation`, `served.domain.tab-links` | on Chromium and Firefox the navigate event cancels what the rule would have (`navigate-guard`) |
1426
+ | `link-rule` | `served/tab.spec.ts` | nothing | WebKit: `served.domain.tab-links`, `served.domain.tab-navigation` | on Chromium and Firefox the navigate event cancels a link the browser follows (`link-rule,navigate-guard`) |
1427
+ | `link-rule,navigate-guard` | `served/tab.spec.ts` | `served.domain.tab-navigation`, `served.domain.tab-links` | — | — |
1428
+ | `permissions-policy` | `served/tab.spec.ts` | nothing | — | the shell's locks deny what the header would (`permissions-policy,device-locks`) |
1429
+ | `device-locks` | `served/tab.spec.ts` | nothing | WebKit: `served.domain.tab-devices`; Firefox: `served.domain.tab-devices`, `served.domain.tab-prompts` | Chromium applies the Permissions-Policy header, which denies them first (`permissions-policy,device-locks`) |
1430
+ | `permissions-policy,device-locks` | `served/tab.spec.ts` | `served.domain.tab-devices` | Chromium, Firefox: `served.domain.tab-prompts` | — |
1431
+ | `url-origin` | `served/served.spec.ts` | nothing | Chromium, Firefox: `served.url.siblings` | no probe can see it on WebKit here: it keeps no cookie in a cross-site frame (P025), and the reference serving's labels are cross-site, so no request of another origin rides the app's cookie |
1432
+ | `service-worker` | `served/files.spec.ts` | `no service worker ever registers` | — | — |
1433
+ | `file-corp` | `served/files.spec.ts` | `another origin reads none of the files: not another artifact's page, not a page elsewhere` | — | — |
1434
+ | `file-self` | `served/files.spec.ts` | `a page loads no other version's files, though the browser may open both (P082)`, `a file outside the set is a 404, and so is every spelling of a way out` | — | — |
1435
+ | `runtime-declaration` | `served/runtime.spec.ts` | `an undeclared capability: null from use, refused when sent anyway, its handler never asked` | — | — |
1436
+ | `runtime-level` | `served/runtime.spec.ts` | `a method above the viewer's level: forbidden, its handler never asked`, `a read above the viewer's level: a result the host pushed is refused as a cold read is` | — | — |
1437
+ | `runtime-data-names` | `served/runtime.spec.ts` | `a resource outside the page's data names: refused with a viewer and without one, its handler never asked` | — | — |
1438
+ | `live-held-read` | `served/runtime.spec.ts` | `a read above the viewer's level: a result the host pushed is refused as a cold read is` | — | — |
1439
+ | `db-private` | `served/runtime.spec.ts` | `a person's own data is theirs: another person's is refused, never reaching the service` | — | — |
1440
+ | `comments-result` | `served/runtime.spec.ts` | `comments are write-only: the composer opens from a click, content hears only that` | — | — |
1441
+ | `blob-script` | `served/runtime.spec.ts` | nothing | — | an untrusted script asset is served as a download (`blob-script,blob-trusted`) |
1442
+ | `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
1443
+ | `blob-script,blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'`, `scripts load from /_blob/ only where uploads are the admins' (a tab, its session)` | — | — |
1444
+ | `blob-inert` | `served/runtime.spec.ts` | `an asset opened on its own runs nothing, on a tab with the artifact's session` | — | — |
1445
+
1288
1446
  ## Milestones
1289
1447
 
1290
1448
  The core (this repository's lead work), in order; each lands when its tests pass:
@@ -5,10 +5,11 @@ What Porthole protects, from whom, and where that protection ends. For each way
5
5
  guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
6
  [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
7
 
8
- **Status.** This describes Porthole 0.8.0 (2026-10-20). A review on 2026-10-19 found gaps, and every
9
- decision it led to has merged but P096. A note **open until P096** means the gap exists in 0.8.0 and
10
- P096 is its planned fix; once it merges, the note becomes a guarantee. [§8](#8-fixes-in-flight)
11
- lists the decisions.
8
+ **Status.** This describes Porthole 0.10.0 (2026-10-21). A review on 2026-10-19 found gaps, and every
9
+ decision it led to has merged. P096 changed the negative-control runner and CI, and the shipped
10
+ conformance probes' messages and timing, not what they check. P104 (0.9.0's annotation markers) had
11
+ a review of its own, and P105, in 0.10.0, is what it led to. [§8](#8-fixes-in-flight) lists the
12
+ decisions.
12
13
 
13
14
  ## 1. Two layers
14
15
 
@@ -77,9 +78,9 @@ viewer and any declaration.
77
78
 
78
79
  The leak suite attempts each channel in DESIGN.md's table from inside the content, on Chromium,
79
80
  WebKit and Firefox, and most defenses have a negative control that takes the defense out to show
80
- its probes then fail (DESIGN.md § "Egress hardening, each with its test"). CI runs the negative
81
- controls of the runtime only, and its runner can count a control that didn't run as passed (open
82
- until P096).
81
+ its probes then fail (DESIGN.md § "Egress hardening, each with its test"). CI runs every negative
82
+ control on all three engines, and a control passes only when its marked probes failed by their own
83
+ assertion (P096).
83
84
 
84
85
  ## 5. Out of scope
85
86
 
@@ -142,6 +143,18 @@ Whatever the use:
142
143
  host's own UI. A copy notice of its own shows what went on the clipboard (S1).
143
144
  - Show the text content reports (its errors, a blocked navigation's address, an annotation's
144
145
  quoted text) only as text, never as HTML.
146
+ - Take what the frame reports about annotations as UI hints (where to draw, what to open), never
147
+ as permissions, and put nothing in a mark the page may not know (§7).
148
+ - Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`: a
149
+ comment's bubble, a composer). The content chooses when it appears and where, so it can bring it
150
+ under a press the person meant for the content (a double click on the content's own button whose
151
+ second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
152
+ appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
153
+ themselves on a release), ignores a press that began before that, opens beside the frame rather
154
+ than over the report's box where the layout allows, takes no focus when it opens, and puts no
155
+ destructive action (resolve, delete) one click away. Its menus and popovers are part of it,
156
+ portaled ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it
157
+ arms).
145
158
  - List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
146
159
  and only those are checked against the content domain for a shared site.
147
160
  - Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
@@ -526,6 +539,76 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
526
539
  **The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
527
540
  effects are its own), and group displays by page (S7).
528
541
 
542
+ **Annotations** (`annotate`, P053, P104). The shell that draws marks and reports anchors shares
543
+ its realm with the content, so:
544
+
545
+ - *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
546
+ where the content can listen: each mark's id, anchor and, where given, `count` (the number on
547
+ its marker). A host gives ids that say nothing (never a person's name or a comment's words), and
548
+ a count only where the page may know how many there are. Who commented and what they wrote stay
549
+ in the host's own UI, outside the frame.
550
+ - *What content can fake.* Any report: a selection while the host asks for one, where marks are,
551
+ and a marker's click (`activated`) for any mark the host shows with a count, without a click on
552
+ it and with any box. It can draw look-alike markers, or lay its own elements over Porthole's.
553
+ The host takes each report only for what it asked for and its own shown ids, rebuilt within
554
+ `ANNOTATION_LIMITS`, at 120 a minute; `activated` for a mark without a marker, or an id it
555
+ doesn't show, is dropped (negative control `annotation-activated`). `activated` is also taken
556
+ only while the host's page has transient user activation, which a real marker click or tap gives
557
+ it (P105, measured on all three engines; control `annotation-activated-gesture`). That stops a
558
+ page opening the host's view with no gesture at all, nothing more: activation lasts 5 s after any
559
+ gesture anywhere on the page (a click on the host's own UI, typing in the content, the click that
560
+ opened the display), and a fake posted then, on a timer or a scroll, is taken; one posted on the
561
+ person's own press in the content lands under their pointer. The guard on the host's view (§6) is
562
+ the defence, not this. Where the platform can't tell (a custom one whose `userActivation()`
563
+ answers undefined), the report passes, as the gesture gate does.
564
+ - *Labels.* An anchor's `label` is the page's text: the words selected, or an element's own words,
565
+ else its `alt`, `aria-label` or `title`, which the person never sees on the page. The host takes
566
+ out of every label everything a person can't see (every format character, bidi controls and
567
+ zero-width ones among them, every default-ignorable code point, variation selector, tag,
568
+ private-use character and control: P105, with none of P100's exceptions for emoji and shaped
569
+ letters, whose surroundings a page can fake), so what it shows is what it has. A text
570
+ anchor's quote (`exact`) keeps them, to be found again: a host that hands a quote or a label to
571
+ a model hands it the page's words, to be read as that, never as instructions.
572
+ - *Boxes.* Every box a report carries (`selected`, `activated`, `anchored`) is the page's word.
573
+ Porthole clamps each to the frame's viewport as it is when the report arrives, before the host
574
+ hears it: the part inside is kept, and a box wholly outside becomes one of no size on the
575
+ nearest edge (control `annotation-rect-clamp`). So a page can't make the host place its own UI
576
+ over the rest of the app. It still chooses any point inside its own frame: a box is a
577
+ positioning hint, never a fact about the content. The box is in the frame's own CSS px, its
578
+ layout size: a host that scales or transforms the frame (a thumbnail, a zoomed preview) maps the
579
+ box through that transform before placing anything by it. A platform's `viewport()` that answers
580
+ no size, or throws, clamps every box to nothing at the frame's corner (P105). The frame's size is
581
+ read for every report the host takes, before the report's rate: a forced layout of the host's
582
+ page per message, which a repeated `ui/initialize` already causes (accepted, P105).
583
+ - *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
584
+ press or click on a marker reaches none of the content's handlers (the shell's first listener
585
+ stops it; control `marker-click`) and moves neither focus nor a selection (control
586
+ `marker-prevent`), so content can't act on it or cancel it; nor can it read or reach inside the
587
+ shell's layer (a closed shadow root). Content can still tell that a marker was pressed, and
588
+ roughly where: the pointer leaving its own element names the layer, the layer matches `:hover`
589
+ and `:active`, and the frame gets user activation.
590
+ - *What doesn't hold against content that does.* The shell shares the content's realm. It reads
591
+ and stops a marker's press through the platform's own functions and getters, kept before
592
+ content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
593
+ prototypes no longer lets content hear a press or make the shell misread one. But the layer's
594
+ nodes pass through built-ins content can replace (the shell's insertion guards call
595
+ `Element.prototype.matches` on them), so content can reach the closed shadow root that way,
596
+ read the markers and rewrite them (the review of P104, on all three engines). Nothing in the
597
+ layer is secret: it holds only what `show` sent, which the content can read anyway.
598
+ - *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
599
+ layer's style, lay elements over it, or transform the page it sits in), change its words so a
600
+ mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
601
+ shell's own work dear by its layout: finding marks again and placing markers after a change of
602
+ the content runs in the frame, once per quiet run of changes, and each marker in view is placed
603
+ by a bounded number of hit tests (measured with 300 marks with counts in view: about 20 ms a
604
+ change; 200 in a 3,000-line block: 25 to 50 ms; P105). In an opaque frame that shares the host's
605
+ process, that time is the host's too ([§5](#5-out-of-scope)). An honest page's
606
+ follow-up reports, of the marks (while one has a marker) and of the person's selection after a
607
+ scroll, share one clock: at most one a second together, each only when its box moved (P105).
608
+ - So `activated` opens the host's own view of a mark it already shows, placed within the frame's
609
+ box (better: beside it), guarded as §6 says, and never acts on it (no resolve, delete or reply);
610
+ an anchor or a rect decides where something is drawn, never who may see or do anything.
611
+
529
612
  ### The app runtime
530
613
 
531
614
  What it is: `config.runtime: "1"`, for inline widgets and artifact pages. A page reaches the
@@ -584,7 +667,7 @@ section.
584
667
 
585
668
  ## 8. Fixes in flight
586
669
 
587
- The decisions below come from the 2026-10-19 review. "Planned" means not in 0.8.0: the gap its
670
+ The decisions below come from the 2026-10-19 review. "Planned" means not in 0.9.0: the gap its
588
671
  row names exists today, and the sections it cites say "open until" that decision. Each merged row
589
672
  says what was wrong, what holds now, and the limit its decision accepts, if any.
590
673
 
@@ -594,7 +677,7 @@ says what was wrong, what holds now, and the limit its decision accepts, if any.
594
677
  | P093 | Merged | `intersectDeclarations` compared rules name by name, so a current wildcard didn't narrow a version's named rule, and a collection named `__proto__` was lost. Now the result allows exactly what both sides allow. | §7 |
595
678
  | P094 | Merged | Without a viewer, a page's declared `data` names weren't held; a pushed result answered a read past `readData`'s gates; `db.batch` and `db.watch` skipped their inner methods' `methodGates`. Now each holds. | §4, S2, S4, §7 |
596
679
  | P095 | Merged | What content sent was read before its gate: a log or error report was serialized whole first; waiting confirmations had no cap. Now the bridge reads it after the gate into bounded text, nothing a page sends throws out of an adapter, and at most 10 confirmations wait per display. | §5, S1, S5 |
597
- | P096 | Planned | The negative-control runner counts a control that didn't run as passed, and CI runs the runtime's controls only. | §4 |
680
+ | P096 | Merged | The negative-control runner counts a control that didn't run as passed, and CI runs the runtime's controls only. | §4 |
598
681
  | P097 | Merged | A release waits for the same commit's CI. No guarantee here depends on it. | |
599
682
  | P098 | Merged | A set's page whose notice came late was taken for a navigation away (red on Chromium since 0.6.0), and tests that waited a fixed time. Accepted: a files display may hold a frame that did navigate away for up to 2 s before starting it again, delivering nothing while it waits. | S1 |
600
683
  | P099 | Merged | A served page in a tab had no sandbox: `window.open` sent input out, it could navigate its opener, open a picture-in-picture window, and ask for the camera, location or full screen. Now its headers carry its frame's sandbox and deny what its frame's `allow` doesn't grant, and the shell closes those on a tab too; the served suite probes self-navigation in frames and tabs. A browser without the Navigation API is an accepted limit. | S4 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.8.0",
3
+ "version": "0.10.0",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * Annotations (P053): a person points at part of a display (an element, or text they select) to
3
- * comment on it, and the host marks the anchors already made. The host drives the shell with
3
+ * comment on it, and the host marks the anchors already made, each with a clickable marker and a
4
+ * number where it gives a count (P104). The host drives the shell with
4
5
  * Porthole's own messages (`porthole/annotate.*`); the shell answers with anchors and where they
5
6
  * are. An anchor is a set of W3C Web Annotation selectors, so it can be found again after the
6
7
  * content changes; finding it is best-effort, and says so (`orphaned`).
@@ -46,7 +47,13 @@ export interface AnnotationAnchor {
46
47
  readonly label: string;
47
48
  }
48
49
 
49
- /** A box in the frame's viewport, CSS px: add the frame element's position to place it on the page. */
50
+ /**
51
+ * A box in the frame's viewport, CSS px: add the frame element's position to place it on the page.
52
+ * The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
53
+ * outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
54
+ * own layout px: a host that scales or transforms the frame maps it through that transform too
55
+ * (P105).
56
+ */
50
57
  export interface AnnotationRect {
51
58
  readonly x: number;
52
59
  readonly y: number;
@@ -62,10 +69,21 @@ export interface AnnotateMode {
62
69
  readonly text?: boolean;
63
70
  }
64
71
 
65
- /** An anchor the host marks in the frame, under its own id. */
72
+ /**
73
+ * An anchor the host marks in the frame, under its own id. Everything here is sent into the
74
+ * frame, so the content can read it: give ids that say nothing (never a person's name or the
75
+ * comment's words).
76
+ */
66
77
  export interface AnnotationMark {
67
78
  readonly id: string;
68
79
  readonly anchor: AnnotationAnchor;
80
+ /**
81
+ * A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
82
+ * `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
83
+ * text anchor and the top right of an element. The person can click it: the frame reports
84
+ * `activated`. The content can read the number; give one only where the page may know it.
85
+ */
86
+ readonly count?: number;
69
87
  }
70
88
 
71
89
  /** Whether a mark's anchor was found in the content as it is now. */
@@ -90,8 +108,20 @@ export type AnnotationReport =
90
108
  | { readonly type: "unselected" }
91
109
  /** The person pressed Escape while picking an element. */
92
110
  | { readonly type: "cancelled" }
93
- /** Where the marked anchors are now, after `show`, `focus`, or a change of the content. */
94
- | { readonly type: "anchored"; readonly results: readonly AnchorResult[] };
111
+ /**
112
+ * Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
113
+ * every mark when the content changed one's state, and, while any mark has a `count`, once a
114
+ * scroll, a resize or a change of the content has settled, only the marks that moved since the
115
+ * host was last told, at most once a second (P104).
116
+ */
117
+ | { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
118
+ /**
119
+ * The person clicked the marker of a mark the host shows with a `count` (P104); `rect` is the
120
+ * marker's box, to open the host's own UI beside it. The content can fake it for any mark the
121
+ * host shows with a count, and can tell a real one happened: open the host's own view of that
122
+ * mark, never act on it.
123
+ */
124
+ | { readonly type: "activated"; readonly id: string; readonly rect: AnnotationRect };
95
125
 
96
126
  /** Porthole's own messages for annotations (own-prefixed, P002). */
97
127
  export const ANNOTATE_METHODS = {
@@ -110,6 +140,8 @@ export const ANNOTATE_METHODS = {
110
140
  unselected: "porthole/annotate.unselected",
111
141
  cancelled: "porthole/annotate.cancelled",
112
142
  anchored: "porthole/annotate.anchored",
143
+ /** Frame → host: a mark's marker was clicked (P104). */
144
+ activated: "porthole/annotate.activated",
113
145
  } as const;
114
146
 
115
147
  /** The most of each part of an anchor or report the host takes. */
@@ -123,4 +155,6 @@ export const ANNOTATION_LIMITS = {
123
155
  id: 128,
124
156
  position: 50_000_000,
125
157
  coordinate: 10_000_000,
158
+ /** The largest `count` a mark's marker takes (P104). */
159
+ count: 999,
126
160
  } as const;