@botiverse/porthole 0.9.0 → 0.12.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 (65) hide show
  1. package/dist/annotate/types.d.ts +21 -7
  2. package/dist/annotate/validate.d.ts +18 -3
  3. package/dist/annotate/validate.js +29 -5
  4. package/dist/bridge/bridge.js +1 -51
  5. package/dist/bridge/unseen.d.ts +18 -0
  6. package/dist/bridge/unseen.js +71 -0
  7. package/dist/check/files.d.ts +2 -0
  8. package/dist/check/files.js +67 -50
  9. package/dist/check/lint.d.ts +8 -1
  10. package/dist/check/lint.js +18 -0
  11. package/dist/check/markup.d.ts +7 -0
  12. package/dist/check/markup.js +49 -0
  13. package/dist/check/page-source.js +1 -1
  14. package/dist/check/scroll.d.ts +100 -0
  15. package/dist/check/scroll.js +1429 -0
  16. package/dist/conformance/behavior.js +107 -68
  17. package/dist/conformance/clipboard.js +16 -14
  18. package/dist/conformance/harness-source.js +1 -1
  19. package/dist/conformance/limits.js +117 -64
  20. package/dist/conformance/probes.js +66 -49
  21. package/dist/conformance/runtime.js +6 -0
  22. package/dist/conformance/served.js +66 -63
  23. package/dist/guide/guide.js +1 -1
  24. package/dist/guide/runtime.js +2 -2
  25. package/dist/host/create-host.js +46 -4
  26. package/dist/index.d.ts +1 -1
  27. package/dist/platform/types.d.ts +4 -2
  28. package/dist/react/frame.d.ts +2 -1
  29. package/dist/runtime/requests.d.ts +5 -0
  30. package/dist/runtime/requests.js +16 -1
  31. package/dist/runtime/types.generated.js +1 -1
  32. package/dist/shell/annotate.d.ts +6 -3
  33. package/dist/shell/annotate.js +474 -104
  34. package/dist/shell/use.js +9 -1
  35. package/docs/ADOPTING.md +99 -1
  36. package/docs/ARCHITECTURE.md +2 -1
  37. package/docs/DECISIONS.md +764 -14
  38. package/docs/DESIGN.md +192 -42
  39. package/docs/THREAT_MODEL.md +109 -27
  40. package/package.json +1 -1
  41. package/src/annotate/types.ts +22 -7
  42. package/src/annotate/validate.ts +32 -6
  43. package/src/bridge/bridge.ts +1 -60
  44. package/src/bridge/unseen.ts +82 -0
  45. package/src/check/files.ts +68 -54
  46. package/src/check/lint.ts +24 -0
  47. package/src/check/markup.ts +53 -0
  48. package/src/check/scroll.ts +1757 -0
  49. package/src/conformance/behavior.ts +221 -69
  50. package/src/conformance/clipboard.ts +44 -14
  51. package/src/conformance/limits.ts +169 -76
  52. package/src/conformance/probes.ts +97 -49
  53. package/src/conformance/runtime.ts +9 -0
  54. package/src/conformance/served.ts +112 -63
  55. package/src/guide/guide.ts +1 -0
  56. package/src/guide/runtime.ts +2 -2
  57. package/src/host/create-host.ts +50 -4
  58. package/src/index.ts +1 -0
  59. package/src/platform/types.ts +4 -2
  60. package/src/react/frame.tsx +2 -1
  61. package/src/runtime/requests.ts +23 -1
  62. package/src/runtime/types.generated.ts +1 -1
  63. package/src/shell/annotate.ts +474 -104
  64. package/src/shell/use.ts +9 -1
  65. package/types/runtime/v1/comments.d.ts +14 -4
package/docs/DESIGN.md CHANGED
@@ -628,7 +628,9 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
628
628
  over the size, a document where a fragment goes that has no body, nested frames and plugins,
629
629
  `document.write`. Warnings for the rest: a document sent as a widget (taken as its body,
630
630
  `fragmentOf`), the clipboard, dialogs, forms, hosts outside egress, unpinned CDN libraries,
631
- `position: fixed` in a flow layout, new windows without `openLink`.
631
+ `position: fixed` in a flow layout, new windows without `openLink`, the page's own styles
632
+ holding it to one screen (P106: `src/check/scroll.ts`, a cascade of html, body and the root's
633
+ overflow, height and position; `lintFiles` reads the version's linked stylesheets too).
632
634
  - **`admitContent(config, content, { refuseOn })`**: the show tool's gate. It refuses errors by
633
635
  default with a text that says what to change; otherwise it shows the content (a widget's
634
636
  document taken as its body) and returns the warnings as a note.
@@ -931,12 +933,12 @@ closed like a strict host's (`leak/inherited-policy.spec.ts`).
931
933
 
932
934
  | # | Channel | Mechanism | Probes | Negative control → fails (Chromium / WebKit / Firefox) |
933
935
  |---|---------|-----------|--------|------------------------------------------|
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 |
936
+ | 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
937
  | 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 |
938
+ | 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) |
939
+ | 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. |
940
+ | 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) |
941
+ | 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
942
  | 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
943
  | 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
944
  | 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 +958,10 @@ official App SDK connects under the inline, artifact and MCP Apps presets
956
958
  | 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
959
  | 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
960
  | 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 |
961
+ | 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
962
  | 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
963
  | 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` |
964
+ | 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
965
  | 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
966
 
965
967
  Measured: a click in the frame gives the host page user activation (it propagates to
@@ -981,13 +983,14 @@ for that to lapse and click with raw input.
981
983
  | 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
984
  | 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
985
  | 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` |
986
+ | 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
987
  | 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
988
  | 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
989
  | 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) |
988
990
  | Live data: a kept result is a read (P094) | a result the host pushed (`changed(result)`), or read after a stale answer, answers the frame's next read only past every gate a read has (level, names, rate, gesture, consent, confirm), with no new upstream call | `test/audit-gates.test.ts`; `leak/served/runtime.spec.ts`: "a read above the viewer's level: a result the host pushed is refused as a cold read is" | `live-held-read` → that case (all three) |
989
991
  | The runtime: per-user data (P088) | `dbAccess`: `me` is the host's id; another's `data/users/<id>`, or anything else under `data`, refused at every level, in the bridge and the host | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "a person's own data is theirs" | `db-private` → that case (all three) |
990
992
  | The runtime: comments write-only (P090) | the bridge answers `comments` with `true` only for a handler's `true`; no read method | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "comments are write-only" | `comments-result` → that case (all three) |
993
+ | The runtime: a comment's draft is visible text (P108) | the bridge refuses a draft that isn't a string, is blank, past 2,000 characters, or holds what a person can't see (`unseen`), before any handler | `test/runtime.test.ts`: "a draft (P108)"; `leak/served/runtime.spec.ts`: "a comment's draft is the host's to check" | `comment-draft` → that case (all three) |
991
994
  | The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
992
995
  | Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
993
996
 
@@ -1004,7 +1007,7 @@ ancestors), and shows them what went on it.
1004
1007
 
1005
1008
  | # | Channel | Mechanism | Probes | Negative control → fails |
1006
1009
  |---|---------|-----------|--------|--------------------------|
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) |
1010
+ | 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
1011
  | 13 | `execCommand("copy")`/`("cut")` of the content's own selected text | the shell refuses the commands | `13.clipboard-command` | `clipboard` → all three |
1009
1012
  | 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
1013
  | 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,14 +1030,14 @@ chooses), and the annotation runtime is in the shell only then.
1027
1030
  |-----------|---------|--------|
1028
1031
  | 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
1032
  | host → frame | `porthole/annotate.stop` | — |
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) |
1033
+ | host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], 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); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
1031
1034
  | host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
1032
1035
  | host → frame | `porthole/annotate.clear` | — |
1033
- | frame → host | `porthole/annotate.selected` | `{ anchor, rect }` |
1036
+ | 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
1037
  | frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
1035
1038
  | 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`, 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 (P104) |
1037
- | frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker; `rect` is the marker's (P104) |
1039
+ | 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 marker (a `count` or a draft, P107), 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) |
1040
+ | 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) |
1038
1041
 
1039
1042
  - **Anchors** are W3C Web Annotation selectors, at most one of each:
1040
1043
  `CssSelector` (unique: the nearest id, else a path of `nth-of-type` steps),
@@ -1047,25 +1050,53 @@ chooses), and the annotation runtime is in the shell only then.
1047
1050
  element anchor by its selector if its text still starts with its words (or the
1048
1051
  selector is an id, or it has no words), else the element holding its words. What
1049
1052
  can't be found is `orphaned`, said so; a host keeps the comment and shows it apart.
1050
- - **Rects** are in the frame's viewport, CSS px: add the frame element's position.
1051
- They are the page's word: `createHost` clamps each to the frame's viewport before
1052
- the host hears it (P104); a box wholly outside becomes one of no size on the
1053
- nearest edge (a mark below the fold: `y` at the viewport's height, no height).
1053
+ - **Rects** are in the frame's viewport, CSS px: add the frame element's position
1054
+ (and map them through the frame's transform, where the host scales it). They are
1055
+ the page's word: `createHost` clamps each to the frame's viewport before the host
1056
+ hears it (P104); a box wholly outside becomes one of no size on the nearest edge
1057
+ (a mark below the fold: `y` at the viewport's height, no height). A platform whose
1058
+ `viewport()` answers no size or throws gets nothing at the corner (P105).
1054
1059
  - **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
1055
- above 99; 0 the bubble alone) at the end of a text anchor's last line, raised, or on
1056
- an element's top right corner, inside the frame's width; its element mark is then a
1057
- thin line. The layer takes no pointer but on markers: a press on one, and the
1058
- pointer's moves over it, are stopped in the shell's first window listener (none of
1059
- the content's handlers, nor what is under it, gets them; the content can still tell
1060
- a press happened, by `:active`, `relatedTarget` and user activation) and a trusted
1061
- click is reported `activated`. Markers step aside
1060
+ above 99; 0 the bubble alone) on an element's top right corner, inside the frame's
1061
+ width, and beside a text anchor's last line, centred on it (P105, #36): in the
1062
+ line's gutter, just past the right edge of the anchor's block; at the frame's right
1063
+ edge where the frame is too narrow for that; just past the line's last word where
1064
+ something else is beside the block (a table's next cell, a card in a row). Each
1065
+ place must be clear of that line's words and of anything of the content's but a box
1066
+ holding the anchor, between the words and the marker too (the shell hit-tests it).
1067
+ Markers ending on one line go together, in the order their words end; where the
1068
+ bubble with its glyph fits nowhere, its number alone does (compact); where neither
1069
+ does (two anchors on one full line of a phone), they go over the line's end. The
1070
+ pointer on a marker lights its words. Placing costs a bounded number of hit tests
1071
+ per marker in view (the layer's own boxes out of the way meanwhile), none for one
1072
+ out of view, and its line's end is read only as far as the line goes (P105: 300
1073
+ marks with counts in view, about 20 ms a change). An element's mark with a marker
1074
+ is a thin line. The layer takes no pointer but on markers: a press on one, and the pointer's
1075
+ moves over it, are stopped in the shell's first window listener, read through the
1076
+ platform's own functions kept before content runs (P105), and a trusted click is
1077
+ reported `activated`; a tap too, on WebKit as well, since each marker has a click
1078
+ 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
1079
+ its handlers, nor what is under the marker, gets them; content that patches others
1080
+ can reach the layer's nodes (P105). Either way the content can tell a press
1081
+ happened, by `:active`, `relatedTarget` and user activation. Markers step aside
1062
1082
  while elements are picked. No tab stop, and the layer stays `aria-hidden`: the
1063
1083
  host's own list of marks is the keyboard path.
1064
- - **Following** (P104), only while a mark has a `count`. Each mark keeps what the
1065
- host was last told (state and box); a settled scroll or resize (any scroller), or
1084
+ - **Drafts** (P107). A mark with `kind: "draft"` (a comment not yet posted) has a
1085
+ marker whether or not it has a count, placed as a posted one's, and drawn apart: a
1086
+ dashed underline (a dashed outline on an element), a lighter fill, and a hollow
1087
+ marker (a light bubble with a dashed edge and the glyph's outline) with no number.
1088
+ `checkMarks` sends a posted mark as before (no `kind`), a draft without its count,
1089
+ and throws on any other kind; the shell draws no number for a draft and drops a
1090
+ mark of a kind it doesn't know. Its click is `activated`, its place `anchored`,
1091
+ and it is followed after a scroll, as a posted marker's.
1092
+ - **Following** (P104), only while a mark has a marker (a `count`, or a draft:
1093
+ P107). Each mark keeps what the host was last told (state and box); a settled
1094
+ scroll or resize (any scroller), or
1066
1095
  a quiet run of content changes (one the deadline cut short is checked once quiet),
1067
- reports only what moved, at most once a second (the latest), so honest scrolling
1068
- takes at most half of the bridge's 120 a minute.
1096
+ reports only what moved. A selection the host was told is told again after a
1097
+ settled scroll only if its box moved (P105, with or without counts). Both share one
1098
+ clock, at most one report a second (the latest), so honest scrolling takes at most
1099
+ half of the bridge's 120 a minute.
1069
1100
  - **Settled.** Nothing is reported before the content is in place (marks shown
1070
1101
  before it arrives are anchored once it has), nor while a run of changes settles; a
1071
1102
  `focus` asked for meanwhile waits for anchoring, then scrolls and reports, so a
@@ -1074,10 +1105,12 @@ chooses), and the annotation runtime is in the shell only then.
1074
1105
  all of it, read what `show` sends (ids, anchors, counts), or fake any report. The
1075
1106
  host takes a selection only while it asked for that kind, a cancel only while
1076
1107
  picking, results only for its own marks, a marker's click only for a mark it shows
1077
- with a count; it
1078
- rebuilds each from known fields within `ANNOTATION_LIMITS` and drops the rest,
1079
- through the bridge's rate limit. UI hints only, never permissions: what a
1080
- report says decides where a comment is drawn, never who may see or do anything.
1108
+ with a marker (a count or a draft) and only within a gesture (P105); it rebuilds
1109
+ each from known fields within `ANNOTATION_LIMITS` (a label without what the person can't see, P105) and
1110
+ drops the rest, through the bridge's rate limit. UI hints only, never
1111
+ permissions: what a report says decides where a comment is drawn, never who may
1112
+ see or do anything. A view a report opens or moves guards its presses
1113
+ (THREAT_MODEL §6).
1081
1114
  - **Host API.** `display.annotations.start(mode?)`, `stop()`, `show(marks)`,
1082
1115
  `focus(id)`, `clear()`, and the `annotation` event (`AnnotationReport`); the state
1083
1116
  is given to every frame the display runs. `parseAnchor` checks an anchor a host
@@ -1092,14 +1125,36 @@ they change; an MCP Apps view; and a hostile page faking every report (not asked
1092
1125
  malformed, too large, the wrong kind, no such mark, a flood), whose negative
1093
1126
  control is `annotation-checks`. Markers (P104): drawn with their numbers, a click
1094
1127
  reported with its id and box and heard by none of the content's listeners, nor a
1095
- double, right or middle click, focus and selection kept (`marker-click` → those
1096
- two cases), none without a count, stepping aside while picking, drawn whole at the
1097
- frame's top; a run of scrolls reported with only the marks that moved, a fixed one
1098
- never; a long honest scroll session leaving a marker's click its budget; a content
1099
- change that moves one mark reports it alone, even when the deadline cut its run
1100
- short; and a hostile page faking a marker's click for no mark, an unknown id or a
1101
- mark without a marker, or clicking the layer itself (`annotation-activated`,
1102
- `annotation-activated-count`, `marker-trusted` → that case).
1128
+ double, right or middle click (`marker-click` → those two cases), focus and
1129
+ selection kept, a drag from a marker too (`marker-prevent` → the press case), none
1130
+ without a count, stepping aside while picking, drawn whole at the frame's top; a
1131
+ run of scrolls reported with only the marks that moved, a fixed one never; marks
1132
+ without counts told nothing after a scroll (`follow-count`); a long honest scroll
1133
+ session in comment mode, a selection made, leaving a marker's click its budget,
1134
+ and then, by when each arrives, the selection's re-reports and the marks'
1135
+ follow-ups a second apart however fast the machine (`follow-throttle`,
1136
+ `selection-follow`); a content change that moves one mark
1137
+ reports it alone, even when the deadline cut its run short; a hostile page faking a
1138
+ marker's click for no mark, an unknown id or a mark without a marker, or clicking
1139
+ the layer itself (`annotation-activated`, `annotation-activated-count`,
1140
+ `marker-trusted` → that case), or by itself, without a gesture
1141
+ (`annotation-activated-gesture`); and a page that patches `Event`'s and
1142
+ `MouseEvent`'s prototypes neither hearing a marker's press nor stopping its report
1143
+ (`marker-originals`; `marker-click` too); a tap on a marker reported on each
1144
+ engine, a touch screen and a phone's emulation (iPhone 13, Pixel 5), content hearing
1145
+ none of it (`marker-tap` → WebKit; `marker-click` too); on a 640 px column and a phone page's lines
1146
+ with one marker each, no marker covering a word (`marker-place`, the marker just
1147
+ past its words as 0.9.0 had it); drafts (P107) drawn apart from posted marks on the
1148
+ same anchors (the frame's pixels and the words' own differ; on Chromium every draft's
1149
+ marker and line drawn as a draft's, no number though given a count), a draft's and a
1150
+ posted marker's clicks reported beside each other, none reaching the content
1151
+ (`marker-click` too), the
1152
+ page reading a draft's kind and never its count (`draft-count`), a raw `show` past
1153
+ `checkMarks` drawing a draft given a count without a number and dropping a mark of
1154
+ an unknown kind (`draft-shell-checks`), and drafts alone followed after a scroll; and ADOPTING.md's `guardPresses`, as written
1155
+ there, taking no press within 500 ms of its view opening (a release on a menu item,
1156
+ a double click's second press on a button or a trigger, a press held past the
1157
+ arming) and the person's own press or key after.
1103
1158
 
1104
1159
  ## The shell runtime
1105
1160
 
@@ -1311,10 +1366,105 @@ embedding CSP `embedderCsp` derives): `pnpm test:leak` runs Chromium, WebKit and
1311
1366
  Firefox;
1312
1367
  `PORTHOLE_LEAK_ENGINES=chromium` runs a subset where an engine's system libraries
1313
1368
  are missing; `PORTHOLE_LEAK_WEAKEN=<control>[,<control>]` serves the core with
1314
- defenses taken out (P032; the table above lists what each must fail).
1369
+ defenses taken out (P032; § The negative controls lists what each must fail).
1315
1370
  `ConformanceHost.launch` called twice on one page shows two displays side by side
1316
1371
  (`9.siblings`).
1317
1372
 
1373
+ ### The negative controls
1374
+
1375
+ Every control the suite has is in one registry (`leak/controls.ts`, P096): the specs it
1376
+ is run with and the tests it must fail on each engine, each named exactly (a probe's
1377
+ `[id]`, a served case's id, or a test's whole title). `pnpm --filter @botiverse/porthole
1378
+ test:controls` (`scripts/controls.ts`; in CI, a job per engine) runs each of them and
1379
+ requires its tests to fail by their verdicts, on every engine asked, and every other test
1380
+ of its specs to pass. A probe's verdict is its deciding `expect`, whose message starts
1381
+ `probe: ` (in the shipped probes and in the spec tests the registry names); a failure of
1382
+ its setup or of a positive control is no failure of the wall. A run that didn't happen, an
1383
+ engine missing from the report, a probe skipped, never run, timed out or failed by anything
1384
+ but its verdict, or a test declared to fail (`test.fail`) that passes, fails the check. A
1385
+ control that fails nothing on an engine says why: another wall holds, shown by a combined
1386
+ control that takes both out and fails something there, or no probe can see the wall; one
1387
+ that fails "every other test" takes out what all of them stand on (`nonce`: the shell),
1388
+ and none of them may pass. No control runs `kit.spec.ts`: the kit's reference app runs
1389
+ Porthole in Node, where no weakening reaches (`UNWEAKENED`). In CI a whole engine's controls
1390
+ outlast a job, so each job runs one of four shards of the registry (`--shard k/4`, split by
1391
+ measured weight, stable for a registry), and the `controls` job checks every shard's verdicts
1392
+ (`--summary`): every control ran and held on every engine. The table is the registry's
1393
+ (`node scripts/controls.ts --table` prints it; `test/controls.test.ts` holds them equal,
1394
+ every weakening to a control, every control that fails nothing to its reason, and every
1395
+ control the tables above name to the registry):
1396
+
1397
+ | Control | Run with | Fails on every engine | Fails only on | Where it fails nothing, why |
1398
+ |---------|----------|-----------------------|---------------|-----------------------------|
1399
+ | `connect-src` | `leak.spec.ts` | `[1.connect]`, `[14.silent]` | — | — |
1400
+ | `webrtc` | `leak.spec.ts` | `[3.webrtc]`, `[14.workers]` | — | — |
1401
+ | `frame-guard` | `leak.spec.ts` | nothing | — | the synchronous guard drops what the observer would (`frame-guard,sync-guard`) |
1402
+ | `attach-shadow` | `leak.spec.ts` | nothing | — | the synchronous guard reaches a closed shadow root's frames as they connect (`attach-shadow,sync-guard`) |
1403
+ | `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`) |
1404
+ | `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]` | — |
1405
+ | `attach-shadow,sync-guard` | `leak.spec.ts` | `[4.closed-shadow]`, `[4.shadow-nested]` | WebKit: `[8.preconnect]` | — |
1406
+ | `declarative-shadow` | `leak.spec.ts` | `[4.declarative-shadow]` | — | — |
1407
+ | `parser-entry-points` | `leak.spec.ts` | `[4.document-write]`, `[14.shell]` | — | — |
1408
+ | `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]` | — | — |
1409
+ | `embedder-self` | `leak.spec.ts` | `[5.host-origin]` | — | — |
1410
+ | `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]` | — |
1411
+ | `base-uri` | `leak.spec.ts` | `[7.base-plugins]` | — | — |
1412
+ | `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 |
1413
+ | `style-split` | `leak.spec.ts` | `[0.app-sdk-inline]`, `[0.app-sdk-artifact]`, `[0.app-sdk-mcp-app]` | — | — |
1414
+ | `draft-inert` | `leak.spec.ts` | `[11.streaming]` | — | — |
1415
+ | `document-theme` | `leak.spec.ts` | `[11.document-theme]`, `[14.theme-never]` | — | — |
1416
+ | `confirm-gate` | `leak.spec.ts` | `[12.prompt-gesture-confirm]`, `[12.link]`, `[12.mute]`, `[12.no-confirm]`, `[14.windows]` | — | — |
1417
+ | `shell-gesture` | `leak.spec.ts` | `[12.prompt-gesture-confirm]`, `[12.mute]`, `[12.copy-text]` | — | — |
1418
+ | `host-gesture` | `leak.spec.ts` | `[12.raw-message]` | — | — |
1419
+ | `model-context-show` | `leak.spec.ts` | `[12.model-context]` | — | — |
1420
+ | `link-scheme` | `leak.spec.ts` | `[12.link]` | — | — |
1421
+ | `clipboard` | `leak.spec.ts` | `[13.clipboard-command]`, `[13.clipboard-event]` | WebKit, Firefox: `[13.clipboard-api]`, `[14.shell]` | — |
1422
+ | `report-unbounded` | `leak.spec.ts`, `strict-csp.spec.ts` | `[14.error-shapes]`, `[14.silent]` | — | — |
1423
+ | `nonce` | `strict-csp.spec.ts` | `the shell runs on a host page whose script-src is its nonce alone (P054)`, and every other test | — | — |
1424
+ | `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` | — | — |
1425
+ | `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` | — | — |
1426
+ | `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` | — | — |
1427
+ | `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` | — | — |
1428
+ | `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)`, `drafts (P107): a dashed line and a hollow marker with no number, apart from posted marks; their clicks are reported the same` | — | — |
1429
+ | `marker-prevent` | `annotate.spec.ts` | `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection` | — | — |
1430
+ | `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)` | — | — |
1431
+ | `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) |
1432
+ | `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)` | — | — |
1433
+ | `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` | — | — |
1434
+ | `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` | — | — |
1435
+ | `follow-count` | `annotate.spec.ts` | `following: a host that gives no counts hears no follow-up after a scroll, as before markers` | — | — |
1436
+ | `draft-count` | `annotate.spec.ts` | `what the page reads of a draft (P107): that it is one, never its count; a posted mark as before` | — | — |
1437
+ | `draft-shell-checks` | `annotate.spec.ts` | `the shell's own checks on a raw show (P107): a draft draws no number, a kind it doesn't know is no mark` | — | — |
1438
+ | `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)` | — | — |
1439
+ | `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` | — | — |
1440
+ | `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` | — |
1441
+ | `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
1442
+ | `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)` | — | — |
1443
+ | `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` | — | — |
1444
+ | `window-open` | `served/tab.spec.ts` | nothing | — | the CSP's sandbox stops a window first (`tab-sandbox,window-open`) |
1445
+ | `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` | — | — |
1446
+ | `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`) |
1447
+ | `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`) |
1448
+ | `link-rule,navigate-guard` | `served/tab.spec.ts` | `served.domain.tab-navigation`, `served.domain.tab-links` | — | — |
1449
+ | `permissions-policy` | `served/tab.spec.ts` | nothing | — | the shell's locks deny what the header would (`permissions-policy,device-locks`) |
1450
+ | `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`) |
1451
+ | `permissions-policy,device-locks` | `served/tab.spec.ts` | `served.domain.tab-devices` | Chromium, Firefox: `served.domain.tab-prompts` | — |
1452
+ | `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 |
1453
+ | `service-worker` | `served/files.spec.ts` | `no service worker ever registers` | — | — |
1454
+ | `file-corp` | `served/files.spec.ts` | `another origin reads none of the files: not another artifact's page, not a page elsewhere` | — | — |
1455
+ | `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` | — | — |
1456
+ | `runtime-declaration` | `served/runtime.spec.ts` | `an undeclared capability: null from use, refused when sent anyway, its handler never asked` | — | — |
1457
+ | `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` | — | — |
1458
+ | `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` | — | — |
1459
+ | `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` | — | — |
1460
+ | `db-private` | `served/runtime.spec.ts` | `a person's own data is theirs: another person's is refused, never reaching the service` | — | — |
1461
+ | `comments-result` | `served/runtime.spec.ts` | `comments are write-only: the composer opens from a click, content hears only that` | — | — |
1462
+ | `comment-draft` | `served/runtime.spec.ts` | `a comment's draft is the host's to check: past the limit, holding what a person can't see, or not text, it opens no composer (P108)` | — | — |
1463
+ | `blob-script` | `served/runtime.spec.ts` | nothing | — | an untrusted script asset is served as a download (`blob-script,blob-trusted`) |
1464
+ | `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
1465
+ | `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)` | — | — |
1466
+ | `blob-inert` | `served/runtime.spec.ts` | `an asset opened on its own runs nothing, on a tab with the artifact's session` | — | — |
1467
+
1318
1468
  ## Milestones
1319
1469
 
1320
1470
  The core (this repository's lead work), in order; each lands when its tests pass: