@botiverse/porthole 0.14.6 → 0.14.8

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 (53) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/dist/check/files.js +2 -0
  3. package/dist/check/lint.js +82 -3
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/compile/policy.d.ts +17 -6
  6. package/dist/compile/policy.js +22 -7
  7. package/dist/config/schema.d.ts +13 -0
  8. package/dist/config/validate.js +15 -0
  9. package/dist/conformance/harness-source.js +1 -1
  10. package/dist/conformance/kit.d.ts +5 -0
  11. package/dist/conformance/kit.js +21 -0
  12. package/dist/conformance/limits.js +10 -5
  13. package/dist/conformance/probes.js +139 -28
  14. package/dist/conformance/served.js +43 -14
  15. package/dist/guide/limits.js +8 -1
  16. package/dist/host/create-host.js +35 -4
  17. package/dist/index.d.ts +1 -1
  18. package/dist/index.js +1 -1
  19. package/dist/presets/presets.d.ts +6 -0
  20. package/dist/presets/presets.js +6 -0
  21. package/dist/server/files.js +4 -3
  22. package/dist/server/index.js +2 -1
  23. package/dist/server/server.js +89 -37
  24. package/dist/server/types.d.ts +23 -0
  25. package/dist/shell/plan.d.ts +5 -0
  26. package/dist/shell/plan.js +2 -0
  27. package/dist/shell/runtime.d.ts +30 -1
  28. package/dist/shell/runtime.js +785 -104
  29. package/docs/ADOPTING.md +36 -0
  30. package/docs/DECISIONS.md +341 -0
  31. package/docs/DESIGN.md +7 -4
  32. package/docs/THREAT_MODEL.md +30 -5
  33. package/docs/insertion-entry-points.md +95 -0
  34. package/package.json +1 -1
  35. package/src/check/files.ts +2 -0
  36. package/src/check/lint.ts +97 -8
  37. package/src/compile/policy.ts +23 -6
  38. package/src/config/schema.ts +13 -0
  39. package/src/config/validate.ts +16 -0
  40. package/src/conformance/kit.ts +22 -0
  41. package/src/conformance/limits.ts +10 -5
  42. package/src/conformance/probes.ts +149 -28
  43. package/src/conformance/served.ts +43 -14
  44. package/src/guide/limits.ts +9 -1
  45. package/src/host/create-host.ts +37 -4
  46. package/src/index.ts +1 -0
  47. package/src/presets/presets.ts +15 -0
  48. package/src/server/files.ts +8 -2
  49. package/src/server/index.ts +2 -1
  50. package/src/server/server.ts +116 -46
  51. package/src/server/types.ts +25 -0
  52. package/src/shell/plan.ts +7 -0
  53. package/src/shell/runtime.ts +788 -104
package/docs/ADOPTING.md CHANGED
@@ -586,6 +586,26 @@ entry: {
586
586
  })` to run it, and the manual's Files section where a kind serves files. Show a set served: an
587
587
  opaque frame has no origin to serve its files from.
588
588
 
589
+ ### A page's own nested frames (opt-in)
590
+
591
+ By default the shell refuses every nested frame content makes: markup frames are removed, and a
592
+ script that creates a frame-like element (`createElement("iframe")`, `object`, `embed`, …) gets a
593
+ `NotSupportedError` at that line (P130), so tell your users' agents to build pages without them (the
594
+ manual and the lint already do). Pasting or dropping formatted content into an editable element
595
+ inserts its plain text only. `nestedFrames: "own"` (P128) on a
596
+ kind's `options` lets a page keep an `<iframe>` of one of its version's own files (a relative
597
+ `src`, served kinds) or with `srcdoc` (every kind), as Claude's Artifacts do; frames of other
598
+ sites, `<object>` and `<embed>` stay out, and the manual and the lint say so:
599
+
600
+ ```ts
601
+ artifact: { preset: "artifact", options: { layout: { kind: "fill" }, nestedFrames: "own" } },
602
+ ```
603
+
604
+ It is a weakening: a nested frame is a realm of its own where the shell's defenses never ran, so
605
+ content there has WebRTC (a way out past `connect-src`) and can put text on the clipboard from a
606
+ click, with no notice. The CSP still governs every frame's loads and navigations. Not for url mode,
607
+ nested pages or live widgets (refused). Turn it on only where your product accepts that.
608
+
589
609
  ### Nested pages: the page below Porthole's shell
590
610
 
591
611
  `nested: true` (P111) on an artifact kind served by the host kit puts the page in a frame of its
@@ -874,6 +894,22 @@ checks the content route runs for that grant, then answer `doorResponse({ hostOr
874
894
  page's shell label. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
875
895
  `@botiverse/porthole/server`.
876
896
 
897
+ **A host that signs its own tickets** (P126) — its server mints its own ticket for a display and its
898
+ content Worker verifies it, so the Worker holds no Porthole ticket when the door is asked — answers
899
+ the door with **`server.doorAnswer(instance, grant, request?)`**, on the object `createServer`
900
+ returns. Raft's shape: the Worker routes its door path (`/__porthole/door/_raft`, say), verifies
901
+ its own ticket (signature, single use, bound to the label and the instance, and a door's, never its
902
+ content's), admits the request and recovers the grant it was signed for, then returns `await
903
+ server.doorAnswer(instance, grant, request)`. The answer is exactly what `/server`'s own door route
904
+ gives once it has taken its ticket: the host's `authorize` check (`denied` with its code), the
905
+ document and version, a file set's entry being a page (`not-found`), `doorResponse` or
906
+ `doorStatusResponse` with the door's CSP and no cookie. It never takes a ticket and checks nothing
907
+ about the request but its method: **you must have authenticated the request and established the
908
+ grant yourself**, as before `issue`. Pass the request so `authorize.check` sees it, and `{ page }`
909
+ as the fourth argument for a frame that opens at a file set's page below its version. It throws for
910
+ an instance with no door (a nested page, a url-mode app) and for an instance or grant `issue` would
911
+ refuse. The content route still takes its own ticket and checks again (P050).
912
+
877
913
  `porthole.config(kind)` is the served config while frames are served, the opaque one while they
878
914
  aren't, and null until the meta is known, so a frame never starts opaque and then restarts
879
915
  served. The client's functions take no `this`: pass them bare
package/docs/DECISIONS.md CHANGED
@@ -6972,3 +6972,344 @@ it.
6972
6972
  **Revisit when** a host needs a later block told in a display with files (then: start it again on a
6973
6973
  dropped status, its next run's first door says it), url mode gets a shell of Porthole's on the app's
6974
6974
  origin, or the parallel-mount variant is measured and chosen.
6975
+
6976
+ ## P126 · 2026-10-30 · The door's answer for a grant: hosts that sign their own tickets · Accepted
6977
+
6978
+ **Amends P125.** P125's door is answered by `/server` (`serveDoor`) once it takes the door's own
6979
+ ticket, or by a host's content Worker that takes that ticket itself. Raft signs its own tickets on
6980
+ its server and verifies them in its content Worker: at request time it holds no Porthole ticket, so
6981
+ it can neither present one to `serveDoor` nor reproduce the door's checks without copying them
6982
+ (Tenny and Remy, #wg-opensource, 2026-10-30).
6983
+
6984
+ **Decision.** `PortholeServer.doorAnswer(instance, grant, request?, at?)` — a function on the
6985
+ object `createServer` returns, **not a route** — returns exactly the Response `serveDoor` answers
6986
+ for that instance and grant once its ticket step is done: the content route's checks for the grant
6987
+ (the host's `authorize` check → 403 `denied` with its code; the document and its version, a file
6988
+ set's entry being a page, the page `at` names → 404 `not-found`; a failure → 500 `error`; a method
6989
+ other than GET/HEAD → 405), answered with `doorResponse` (open) or `doorStatusResponse`, with the
6990
+ door's CSP (`sandbox allow-scripts`, `frame-ancestors` the host origins), `no-store` and no cookie.
6991
+ `serveDoor` now takes and checks its ticket (single use, bound to label and key, a door ticket,
6992
+ never an entry or hop ticket, no door on a nested page's label: all as in P125) and then answers
6993
+ through the same code (`answerDoor`), so there is one answer, not two kept in step. `doorAnswer`
6994
+ never takes a ticket; it validates the instance and grant as `issue` does, and throws for an
6995
+ instance with no door (a nested page, a url-mode app). `request` is what `authorize.check` is
6996
+ handed; default, a GET of the door on the instance's origin.
6997
+
6998
+ **Threat.** None re-opened. The ticket is how `/server` knows a request was admitted; `doorAnswer`
6999
+ is for a caller that has authenticated the request and established the grant itself (its own
7000
+ ticket, verified in its Worker), as a host does before it calls `issue`. Nothing reaches it from
7001
+ the network that the host didn't route there, and its answer is the one `serveDoor` gives for the
7002
+ same grant, so the door says no more to its frame than P125's does. A host that calls it for a
7003
+ request it didn't admit tells a request `open` that its content route then still refuses (P050:
7004
+ the content route takes its own ticket and checks again), the same as a door ticket handed out
7005
+ wrongly would.
7006
+
7007
+ **Conformance.** `served.domain.door`'s check (4) no longer builds a content URL from the door
7008
+ path's last segment (a host's door path need not end in the content's key: Raft's is
7009
+ `/__porthole/door/_raft`): it swaps the `ticket` parameters between one location's own `url` and
7010
+ `door.url`, each path kept, and expects both refused (401), as before.
7011
+
7012
+ **Tested.** `test/server.test.ts` ("doorAnswer"): an allowed grant is open with the door's exact
7013
+ CSP; denied with the host's code (the check handed the caller's request); not-found for a missing
7014
+ version and for a file set whose entry isn't a page; HEAD and 405; what it throws; and `serveDoor`
7015
+ and `doorAnswer` give byte-identical status, headers and body for the same grant (open for each
7016
+ kind, denied, not-found, a page below a base). Reverse checks (2026-10-30): `serveDoor` answering
7017
+ `open` inline without the checks, and `serveDoor` running the same checks inline but answering
7018
+ with one more frame ancestor, each turn the identity test red (the second, that test alone).
7019
+
7020
+ **Revisit when** a host needs the door's answer to differ from its content route's (it must not:
7021
+ P125's invariant), or Porthole verifies a host's own tickets itself.
7022
+
7023
+ ## P127 · 2026-11-01 · A frame's size is taken at most once an animation frame after its first, and only when it changed · Accepted
7024
+
7025
+ From the audit of 2026-10-29 (C-1): `resize` has no gate (`capabilities.ts`), and the host applied
7026
+ every `size-changed` a frame sent: `setHeight` (a reflow of the host's page, for a display not in
7027
+ fill mode) and a `resize` to its listeners (the React binding re-renders on each). Porthole's shell
7028
+ already measures once an animation frame and only when the height changed; content that speaks the
7029
+ protocol itself need not, and could send thousands a second. Its reach is the tab showing it: it
7030
+ reads nothing and touches no other display, but it can make that tab slow.
7031
+
7032
+ **Decision.** A run's first size is taken at once (until then its frame has no height of its own:
7033
+ waiting a frame for it left the frame 0 px tall a frame longer than before, which the leak suite saw
7034
+ on WebKit). After it, the host keeps the last size a frame sent and takes it on the next animation
7035
+ frame of the container's window (at once where there is none): one `setHeight` and one `resize` an
7036
+ animation frame at most, and none for a size the same as the last one taken (height and width). A
7037
+ run started again drops a size still waiting and takes the new run's first size at once. Not a rate:
7038
+ a rate would refuse an honest page's sizes during an animation, where taking the last one per frame
7039
+ loses nothing a person can see.
7040
+
7041
+ **Threat.** None re-opened; a gate added. `resize` still has no `defaultGates`: what bounds it is the
7042
+ host, for every config.
7043
+
7044
+ **Revisit when** a host needs every intermediate size (none does: the frame's height is all the host
7045
+ draws), or `resize` gets a gate of its own.
7046
+
7047
+ ## P128 · 2026-11-01 · A page's own nested frames, opted into: `nestedFrames: "own"` · Accepted
7048
+
7049
+ xxchan (product owner, Raft #proj-workspace:04df2a51, message 14100c19, 2026-11-01): Raft's
7050
+ Artifacts should let a page have nested frames of its own, as Claude's Artifacts do. That means an
7051
+ `<iframe>` of a file of the same artifact (the same version's files, by a relative address) and a
7052
+ `srcdoc` frame load and run; frames of other sites stay blocked. He accepted the trade-off below
7053
+ (a nested frame is a realm of its own that the shell's hardening never reaches, so WebRTC is
7054
+ there; Claude has the same). It weakens a security default, so it is **opt-in per config**, and
7055
+ every other host keeps today's behaviour without changing anything. Amends P006 (the shell's
7056
+ defenses for channels a CSP doesn't cover: nested frames), P030 (guarded elements) and P082 (a set
7057
+ page's `frame-src`), for configs that opt in only.
7058
+
7059
+ **Decision.**
7060
+ - **The switch.** `PortholeConfig.nestedFrames: "none" | "own"` (`presets.*({ nestedFrames })`,
7061
+ a display kind's `options`). Absent or `"none"` is the default: the plan, the CSPs, the manual
7062
+ and the lint are the same as before. `"own"` is refused for url mode (no shell), for a nested page
7063
+ (`nested: true`, P111: its page is an opaque origin, which no `frame-ancestors` source matches, so
7064
+ none of its own files could be framed; not measured), and by `presets.liveWidget` (P079: no
7065
+ network of its own, and a child frame has WebRTC).
7066
+ - **The shell** (`plan.nestedFrames: "own"`, step 3 of the runtime) keeps an `<iframe>` (HTML
7067
+ namespace) with a `srcdoc` attribute (which wins over any `src`), or whose `src`, resolved by the
7068
+ platform's URL parser against the document's base, is under the version's own files' address
7069
+ (`plan.files.base`, P082). Everything else is removed as before: `frame`, `frameset`, `object`,
7070
+ `embed`, `portal`, `fencedframe`; an iframe without `src` or `srcdoc` (its `about:blank`), or of
7071
+ another path of the origin, another origin, `data:`, `blob:` or `javascript:`. The rule is one
7072
+ pure function (`OWN_FRAME`, spliced into the runtime as `HELD_BACK` is) that uses no prototype
7073
+ method content could replace, given the attributes and the base through the platform's own
7074
+ getters, kept before content runs. A frame that is kept can't become one that isn't: a change to
7075
+ it (an attribute, an IDL setter such as `src`, an attribute node or map, `toggleAttribute`) that
7076
+ would make it so first takes it out of the document, synchronously, as P030 does for a link or
7077
+ meta; the observer watches `src` and `srcdoc` as the backstop. Opaque frames and single pages
7078
+ have no files: there only `srcdoc` frames are kept.
7079
+ - **The CSP.** The frame's own policy is unchanged (`frame-src 'none'`): a `srcdoc` frame needs no
7080
+ source (P033 measured it loads under the embedding page's `frame-src 'none'`). A page of a file
7081
+ set opens `frame-src` to its version's files, the same source its scripts load from
7082
+ (`fileSetDirectives(config)`, `fileSetCspDirectives(…, opened)`): never another origin, never
7083
+ `'self'`, and not `child-src` (every engine Porthole supports reads frames from `frame-src`,
7084
+ P038). The embedding page's `frame-src` is unchanged.
7085
+ - **The server.** Below a file set's base, `frame-ancestors` names the page's own origin before
7086
+ the app's, so the set's pages frame its files (`frame-ancestors` names every ancestor). The
7087
+ ticket's answer, the shell's own pages and every other display keep the app's origins alone.
7088
+ Every page of a set is served in the shell (P081), so a page of the set in a child frame has its
7089
+ own shell: it takes messages only from the host origins, which its parent isn't. That child
7090
+ realm is same-origin with its parent, which is content, so the parent can reach the child's
7091
+ built-ins before the child's shell captures them; the shell's "captured before content runs"
7092
+ hardening (P129) is not guaranteed there, which is part of what opting in gives up (below).
7093
+ - **The lint.** `nested-frame` stays an error; under `"own"` it names only what never loads: a
7094
+ `<frame>`, `<object>` or `<embed>`, an iframe of another site (any scheme, `//`), of the origin's
7095
+ root (`/`), or with neither `src` nor `srcdoc`, and one with a relative `src` where there are no
7096
+ files. Its message says what does load. `lintFiles` looks an iframe's `src` up in the set.
7097
+ - **The manual** says which frames load ("an <iframe> of one of the page's own files (a relative
7098
+ src) or with srcdoc loads, set before it is added"), from the same config
7099
+ (`test/agreement.test.ts`).
7100
+ - **Raft** opts in on its artifact kind: `defineDisplays({ artifact: { preset: "artifact",
7101
+ options: { …, nestedFrames: "own" } } })` (`raftContentDisplays.ts` in the content Worker, and
7102
+ the web's `RAFT_ARTIFACT_DISPLAYS`, kept equal).
7103
+
7104
+ **Threat it re-opens** (for a config that opts in; accepted by xxchan).
7105
+ - **A child frame is a realm of its own, where the shell never ran** (steps 1, 2, 5 and 6 of the
7106
+ runtime): in a `srcdoc` frame, and in the `about:blank` document every new iframe starts with
7107
+ (which a same-origin page reaches in the task that added it), the WebRTC constructors are there,
7108
+ so content can reach any STUN or TURN server outside `connect-src` and carry what it holds out
7109
+ (`webrtc 'block'` stops it only in an engine that honors it); resource hints there are not
7110
+ removed (a `dns-prefetch` or `preconnect` reaches any host); `document.write` works. In a served
7111
+ page (`allow-same-origin`), its kept frames are its own origin, so it reaches their realms
7112
+ directly; in an opaque frame, a child is a new opaque origin (the sandbox is inherited) whose own
7113
+ script still runs. In short: a page that opts in has WebRTC, and egress is closed only as far as
7114
+ CSP closes it (P006's other walls are the CSP's, and they hold in the child: it inherits its
7115
+ parent's policy, or, a page of the set, is served with its own).
7116
+ - **The clipboard** (P051): the frame's `allow` denies `clipboard-read` and `clipboard-write`,
7117
+ and a child's features are its parent's at most, so the async Clipboard API stays closed. But
7118
+ the shell's guards don't run there: `execCommand("copy")` from a click in the child, and its
7119
+ copy and cut listeners, can put text the person didn't select on their clipboard
7120
+ (pastejacking), without `copyText` and the host's notice.
7121
+ - **Navigation.** A child frame's navigations, its own or its parent's of it, are governed by its
7122
+ embedding document's `frame-src` (the page's): a set's page frames only its version's path, an
7123
+ opaque frame nothing. So a child carries data out by navigating only to its own version's path,
7124
+ which reaches the host's content server, as a fetch there does (P082, P084). A child that
7125
+ navigates the page itself is stopped by the page's navigation guard and the app's `frame-src`,
7126
+ as before (P079). The sandbox is inherited: no popups, forms, downloads, modals or top
7127
+ navigation in a child.
7128
+ - **No new reach into the host.** A child is on the content's origin (or an opaque one); a
7129
+ file set's files now name that origin in `frame-ancestors`, which is the page's own: anything on
7130
+ it is already same-origin with the page.
7131
+
7132
+ **Why.** Pages people make with agents frame their own pages (a slide in a deck, a chart page in a
7133
+ report) and draw demos in `srcdoc` frames, which Claude's Artifacts run; removing them breaks those
7134
+ pages in Raft. Frames of other sites stay out: each would be a channel to its site.
7135
+
7136
+ **Rejected.** On by default (CLAUDE.md: never weaken a default silently; other hosts keep the
7137
+ strict rule). Running Porthole's shell in `srcdoc` children: the page reaches a child's realm
7138
+ before any script of ours could (its `about:blank`), so it would cost the page its frames' markup
7139
+ and buy nothing against content that wants out. An allowlist of other origins (as MCP Apps'
7140
+ `frameDomains`): not asked for, and each origin is a channel out.
7141
+
7142
+ **Tested** (written 2026-11-01, not yet run: run `pnpm check`, `pnpm test:leak` on Chromium, WebKit
7143
+ and Firefox, and `test:controls own-frame-rule` and `frame-guard,sync-guard` before release).
7144
+ Unit: `test/config.test.ts` (default off in every preset and plan; the refusals; a display kind's
7145
+ option reaches its served and opaque configs), `test/shell.test.ts` (`OWN_FRAME`'s rule, case by
7146
+ case; the plan), `test/files.test.ts` (a set's page frames its version's path only; served, its
7147
+ files' `frame-ancestors` and the ticket's; `lintFiles`), `test/check.test.ts` (the lint),
7148
+ `test/agreement.test.ts` (shell ↔ CSP ↔ manual, for a Raft-shaped and an inline config). Browser:
7149
+ probes `4.own-external` (another site, a relative `src` with no files, `data:`, a plugin, an empty iframe:
7150
+ none stays, the canary hears nothing), `4.own-turned` (a kept frame turned elsewhere by a setter,
7151
+ an attribute, a map, `toggleAttribute` leaves), `4.own-default` (the same frames, without the
7152
+ option: none runs), and `leak/served/files.spec.ts`'s "a page's own frames" (its own file, with its
7153
+ shell, a srcdoc and a frame it made run; another site, `/`, `/__porthole/d/…`, `../../`, plugins
7154
+ stay out; by default none). Negative control `own-frame-rule` (the rule keeps every iframe) fails
7155
+ `4.own-external` and `4.own-turned`; `frame-guard,sync-guard` fails the three
7156
+ probes that need a frame removed. Measured (CI, all three engines): under an opaque inline widget
7157
+ a `srcdoc` child's scripts don't run (it inherits the frame's nonce policy), so there the option
7158
+ keeps only frames that stay inert; on a served page (Raft's Artifacts) a `srcdoc` frame and a frame
7159
+ of its own files load and run. The served case's frames of elsewhere stand on two walls, each
7160
+ with its control: the shell's rule takes them out of the tree (`own-frame-rule` fails "stays out
7161
+ of the tree"), and the page's `frame-src` (its version's path; a `srcdoc` child inherits it)
7162
+ stops what a frame left there would load (`own-frame-rule,own-frame-src` fails "loads nothing"
7163
+ too; the rule alone out, `frame-src` holds it). A served page's shell and CSP are made in the
7164
+ served harness's process, so the two weakenings reach it there (the rule in `SERVED`, the header
7165
+ rewritten by the harness): an earlier run edited only the sources the browser loads, so neither
7166
+ reached a served page and the case looked held by "more than one wall" (CI, 9843f99: the combined
7167
+ control blind on Chromium). `navigate-guard` and `file-self` alone leave it held, by the rule.
7168
+
7169
+ Also accepted (Tenny's review): a same-origin `srcdoc` child has its own realm's untouched natives
7170
+ (`Document.prototype.write`, `Element.prototype.setHTMLUnsafe`, …) and can call them on the
7171
+ parent's document, so the parent shell's own hooks (the `document.write` lock, the declarative
7172
+ shadow DOM check) can be bypassed too, not only absent in the child. The CSP still closes the
7173
+ network the same way, so no way out is added beyond those named above, but "the parent page's
7174
+ guards stay whole" does not hold under `"own"`. A host's content origin must be the artifact's
7175
+ alone (Raft: `w-<uuid>.<content domain>`, one per artifact), since a file set's `frame-ancestors`
7176
+ names it.
7177
+
7178
+ **Revisit when** a host asks for frames of other origins (an allowlist, with its own channel
7179
+ accepted), a nested page (P111) needs frames of its own, Claude's Artifacts change their rule, or
7180
+ every engine closes WebRTC through CSP in every realm (then the trade-off is the clipboard's only).
7181
+
7182
+ ## P129 · 2026-11-04 · The shell's guards call only built-ins captured before content runs · Accepted
7183
+
7184
+ **Decision.** Step 3's frame guard and its MutationObserver, the before-change backstop, and the
7185
+ synchronous insertion and HTML-parse guards (`strip`, `admit`, the insertion wrappers, `watched`,
7186
+ `beforeChange`, the `innerHTML`/`outerHTML`/`insertAdjacentHTML`/`execCommand` wrappers, the
7187
+ attribute-turn guards) read every built-in they use through references captured before any content
7188
+ runs, and call each one only through `callOf` — the DOM `nodeType`, `isConnected`, `parentNode`,
7189
+ `childNodes`, `shadowRoot`, `localName`, `namespaceURI`, `baseURI` getters; `querySelectorAll` (by
7190
+ node type), `remove`, `cloneNode`, `createTextNode`, `createElement(NS)`, `setAttributeNS`,
7191
+ `removeAttribute`, `attachShadow`, the kept insertion methods; the `NodeList` `length` getter;
7192
+ `WeakSet` `has`/`add`, `WeakMap` `get`/`set`; `MutationObserver.observe`; the `MutationRecord`
7193
+ `addedNodes`/`type`/`target` and `Attr` `name`/`namespaceURI`/`value`/`ownerElement` getters. It
7194
+ calls none of them as a member on an object content controls, and reaches none through
7195
+ `Function.prototype.call`/`apply`/`bind`: `callOf` is `Reflect.apply` itself, kept before content
7196
+ and invoked directly, so what the guard calls and with what is never seen by anything content later
7197
+ puts on `Function.prototype`. It also walks and decides without any replaceable `Array`/`Object`
7198
+ prototype method: live collections are indexed loops over the captured length getter (never
7199
+ `Array.from`, `for…of`, or the spread, whose `Array.prototype[Symbol.iterator]` is replaceable), the
7200
+ arguments it passes on are prototype-less lists given to `callOf`, and the positional decision in the
7201
+ insertion wrappers is a lookup built before content, not `Array.prototype.indexOf`. This extends
7202
+ P128's rule (which already read `matches`, `OWN_FRAME`'s inputs and the navigation getters this way)
7203
+ and P030's guard to every built-in the guard touches. Default behaviour is unchanged; no config,
7204
+ CSP, plan or manual moves.
7205
+
7206
+ **Why.** The guard inspects objects content controls, so it must not depend on anything content can
7207
+ replace first — a prototype method or getter, the global `Array.from` or array iterator,
7208
+ `Array.prototype.indexOf`, or `Function.prototype.apply`/`call`/`bind` — otherwise a page could make
7209
+ the guard overlook a frame-like element it must remove. The invariant — **the shell's guards call
7210
+ only built-ins captured before content runs** — is the property the fix establishes, and
7211
+ `test/shell.test.ts` asserts it generically (the guard captures each built-in once, `callOf` is
7212
+ `Reflect.apply` captured first, and the whole guard-and-wrapper region of the source makes no live
7213
+ `.call(`, `.apply(`, `.bind(`, `.querySelectorAll(`, `.remove()`, `Array.from(`, `.cloneNode(`,
7214
+ `.indexOf(`, `.forEach(` or `document.createTextNode(` call).
7215
+
7216
+ **Rejected.** Capturing only `matches` (P128's extent), or only the walk's getters and methods: the
7217
+ insertion wrappers still reached built-ins through `.apply`, `.call` and `Array.prototype.indexOf`,
7218
+ which content can replace to the same end. Leaving the walk on `Array.from`/`for…of`/the spread:
7219
+ `Array.from` and `Array.prototype[Symbol.iterator]` are replaceable too. Checking a value and then
7220
+ forwarding the original argument: the platform reads the argument again, so a value that converts
7221
+ to a benign string when checked and a guarded one when the platform reads it would slip past; each
7222
+ inspected name or value is pinned to a single conversion (`once`) and that reading is both checked
7223
+ and forwarded.
7224
+
7225
+ **Where this does not reach.** The invariant is for a shell in its own realm, which runs first
7226
+ there. Under `nestedFrames: "own"` (P128), a kept child frame is a realm the shell shares with
7227
+ content that can reach it first: a page of a set in a child frame is same-origin with its parent,
7228
+ and the parent is content, so it can touch that realm's built-ins before the child's shell captures
7229
+ them. There the "captured before content runs" ordering is not guaranteed — as P128 records, a
7230
+ config that opts in gives up the shell's defenses inside its own frames and stands on the CSP there.
7231
+ This fix changes nothing about that trade-off; it holds for the top-level shell every config has.
7232
+
7233
+ **Tested** (written 2026-11-04; run `pnpm check` and `pnpm test:leak` on Chromium, WebKit and
7234
+ Firefox before release). Unit: `test/shell.test.ts` (the capture table and the no-live-call
7235
+ invariant). The leak suite's frame and hint probes (item 4, the served "own" cases) stand as the
7236
+ behavioural check; a probe that replaces each captured built-in before inserting a nested frame,
7237
+ with its negative control, belongs with the leak suite when the egress-probe harness is next
7238
+ extended.
7239
+
7240
+ **Revisit when** a new built-in is used anywhere in the guard or a new guarded channel is added
7241
+ (capture it the same way and extend the invariant test), or the leak suite gains the
7242
+ per-built-in replacement probe.
7243
+
7244
+ ## P130 · 2026-11-04 · Every insertion entry point is guarded, every subtree producer strips, and by default no frame-like element can be made · Accepted
7245
+
7246
+ **Decision.** The shell's frame guard (step 3, P030, P129) holds one invariant: **every insertion
7247
+ entry point is guarded, every subtree producer strips before returning, and under the default
7248
+ configuration no frame-capable element can exist in a content-reachable tree.** The list of entry
7249
+ points and how each is guarded is [insertion-entry-points.md](insertion-entry-points.md);
7250
+ `test/shell.test.ts` checks every row against the runtime.
7251
+ - **Insertion.** Every DOM method or setter that connects a node runs its node arguments through
7252
+ the same synchronous `admit`/`strip`, whatever the parent (connected or detached), on built-ins
7253
+ captured before content runs and called through `callOf` (P129): the P030 methods, `moveBefore`
7254
+ where an engine has it, `HTMLSelectElement.add` and `HTMLOptionsCollection.add`, and the
7255
+ `document.body` and `HTMLTableElement` `tHead`/`tFoot`/`caption` setters (a refused value refuses
7256
+ the set: a setter has no harmless stand-in).
7257
+ - **Producers.** Every API that hands content a subtree it can insert later strips it
7258
+ synchronously before it returns: `DOMParser.parseFromString` (every MIME type),
7259
+ `Document.parseHTMLUnsafe` and `Document.parseHTML`, `HTMLTemplateElement.content` (and what a
7260
+ template's `innerHTML` fills), `DOMImplementation.createHTMLDocument`/`createDocument`,
7261
+ `Range.createContextualFragment`, `XSLTProcessor.transformToFragment`/`transformToDocument`,
7262
+ `XMLHttpRequest` `responseXML` and a document `response`, `Document.importNode` (the clone) and
7263
+ `adoptNode` (the node; one that is itself frame-like is refused). `strip` enters what
7264
+ `querySelectorAll` doesn't: each template's content and each open shadow root's tree, at any
7265
+ depth (a work list, not recursion).
7266
+ - **Creation, under the default configuration.** `createElement` and `createElementNS` refuse a
7267
+ `FRAMES` name (any case, any namespace, the local name after a prefix included) with a neutral
7268
+ error, as `document.write` is refused; so does `CustomElementRegistry.define` with an `extends`
7269
+ naming one (its constructor would make one). With the parsers stripped, nothing else makes a
7270
+ frame-like element (`cloneNode` and `importNode` copy trees that hold none; `Option`, `Image`
7271
+ and `Audio` make their own kinds), so the indexed setters that can't be wrapped
7272
+ (`select[i] = …`, `options[i] = …`, `length`) have nothing to connect. Under `nestedFrames:
7273
+ "own"` (P128) creation stays open and the guards decide when a frame is connected or changed.
7274
+ The manual says so from the same config ("making one in script throws", default only).
7275
+ - **Markup methods the shell doesn't know** (one a later engine adds, on Element, ShadowRoot,
7276
+ Document, DocumentFragment or Range, with `HTML` in its name) are refused.
7277
+ - **Editing.** A `beforeinput` listener the shell registers before content runs (on `window`,
7278
+ capturing, with the platform's own getters) cancels a paste, a drop, a replacement or a yank
7279
+ (`insertFromPaste`, `insertFromPasteAsQuotation`, `insertFromDrop`, `insertReplacementText`,
7280
+ `insertFromYank`) whose data carries any type but `text/plain`, and inserts its plain text
7281
+ through the editor's `insertText`, which carries no markup. Only the browser's own events are
7282
+ acted on. Composition events can't be cancelled and carry text alone.
7283
+ - **Read once.** Every value a guard inspects and forwards passes as it is only if it is a string,
7284
+ number, boolean, bigint, `null` or `undefined` itself (`value === undefined`); anything else is
7285
+ converted once, and that reading is both checked and forwarded; a symbol, or a conversion that
7286
+ throws, is refused (`PASSES_AS_IS`, `ONCE`). `attachShadow`'s `init` is read field by field,
7287
+ once, into a fresh object with no prototype, which is all the platform is given.
7288
+
7289
+ **Why.** A guard that covers most entry points is as strong as the one it doesn't: the invariant
7290
+ is stated over all of them, producers included, so a subtree can't reach the document by a route
7291
+ the list doesn't name. Refusing creation makes the invariant hold for trees content builds by hand
7292
+ too, where no producer is involved. Under the default configuration no page needs a frame-like
7293
+ element: the lint already reports every one (`nested-frame`), and the guard removes them.
7294
+
7295
+ **Rejected.** Covering the indexed setters by stripping at the producers alone: a tree built by
7296
+ hand is no producer's. Replacing a refused element with a placeholder at creation: a page would
7297
+ get an element that silently isn't what it asked for; a refusal says why. Letting editing insert
7298
+ markup and relying on the observer: the editor connects it before the observer's microtask.
7299
+
7300
+ **Under `nestedFrames: "own"`** the creation refusal doesn't apply, and P128's trade-offs stand.
7301
+
7302
+ **Tested** (written 2026-11-04, not yet run: run `pnpm check`, `pnpm test:leak` on Chromium,
7303
+ WebKit and Firefox, and `test:controls` before release). Unit: `test/shell.test.ts` (every entry
7304
+ of the list found in the runtime, the doc's rows and statuses matching; `PASSES_AS_IS` and `ONCE`
7305
+ in isolation, fail-closed cases included; the creation refusal only under the default
7306
+ configuration), `test/agreement.test.ts` (the manual's sentence, default only). The `sync-guard` negative control also takes out the creation refusal and the
7307
+ producers' strips. The conformance probes that build a frame-like element with `createElement`
7308
+ (4.light-dom, 4.sync-realm, the shadow-root and plugin cases, 4.own-default, 7.base-plugins,
7309
+ 14.shell, and the served egress case) count a refusal at creation under the default configuration
7310
+ as the guard holding, and record it ("refused at creation"); with the refusal taken out (the
7311
+ `sync-guard` control) they build the element as before.
7312
+
7313
+ **Revisit when** an engine adds an insertion or parsing entry point (add it to the list, the
7314
+ runtime and the test), the default configuration is to allow frames, or the leak suite's probes
7315
+ cover each row.
package/docs/DESIGN.md CHANGED
@@ -990,6 +990,7 @@ for that to lapse and click with raw input.
990
990
  | 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) |
991
991
  | 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 | — |
992
992
  | 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) |
993
+ | A page's own nested frames, opt-in (P128) | `nestedFrames: "own"` (off by default): the shell keeps an iframe with `srcdoc` or whose `src` is under `files.base` (`OWN_FRAME`, through the platform's getters) and removes every other frame and plugin as before; a kept frame leaves before a change would point it elsewhere (P030's guard; the observer watches `src`/`srcdoc`); a set's page has `frame-src` its version's path, its files `frame-ancestors` its own origin and the app's; refused for url mode, nested pages, live widgets. Inside a child frame none of the shell's defenses run (accepted) | `4.own-external`, `.own-turned`, `.own-default` (opaque: a srcdoc child's scripts don't run there, measured); `leak/served/files.spec.ts` "a page's own frames": its file (with its shell), a srcdoc and a made frame run; another site, `/`, `/__porthole/d/…`, `../../`, plugins stay out; by default none runs; `test/shell.test.ts`, `test/files.test.ts`, `test/check.test.ts` | `own-frame-rule` → `4.own-external`, `4.own-turned`, the served "stays out of the tree"; `own-frame-rule,own-frame-src` → that and "loads nothing" (the page's `frame-src`, the second wall); `frame-guard,sync-guard` → `4.own-external`, `4.own-turned`, `4.own-default` |
993
994
  | 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` |
994
995
  | 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) |
995
996
  | 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) |
@@ -1263,7 +1264,7 @@ how content behaves, each one line derived from the config (`manualLimits`, P064
1263
1264
  | `workers` | blob: Web Workers work; no service workers; no WebRTC | always | `14.workers`, `3.webrtc` |
1264
1265
  | `sound` | sound plays only from a click | always | `14.sound` |
1265
1266
  | `address` | about:srcdoc (opaque) or its own address with Porthole's ticket (domain) | always | `14.address`, `served.domain.address` |
1266
- | `shell` | document.write/open throw; nested frames removed; full screen and clipboard closed | always | `14.shell`, `4.document-write`, `4.light-dom` |
1267
+ | `shell` | document.write/open throw; nested frames removed (with `nestedFrames: "own"`, P128: but `srcdoc` ones and frames of the page's own files); full screen and clipboard closed | always | `14.shell`, `4.document-write`, `4.light-dom`, `4.own-external` |
1267
1268
  | `storage` (interactive topic) | per isolation; in domain mode reads and writes can throw: try/catch | always | `14.storage`, `served.domain.storage-scope` |
1268
1269
 
1269
1270
  Three more limits sit outside the list:
@@ -1422,10 +1423,12 @@ control the tables above name to the registry):
1422
1423
  |---------|----------|-----------------------|---------------|-----------------------------|
1423
1424
  | `connect-src` | `leak.spec.ts` | `[1.connect]`, `[14.silent]` | — | — |
1424
1425
  | `webrtc` | `leak.spec.ts` | `[3.webrtc]`, `[14.workers]` | — | — |
1425
- | `frame-guard` | `leak.spec.ts` | nothing | — | the synchronous guard drops what the observer would (`frame-guard,sync-guard`) |
1426
- | `attach-shadow` | `leak.spec.ts` | nothing | — | the synchronous guard reaches a closed shadow root's frames as they connect (`attach-shadow,sync-guard`) |
1426
+ | `frame-guard` | `leak.spec.ts` | nothing | — | the synchronous guard drops what the observer would, or refuses it at creation (P130) (`frame-guard,sync-guard`) |
1427
+ | `attach-shadow` | `leak.spec.ts` | nothing | — | the synchronous guard refuses the frame at creation (P130), and reaches a closed shadow root's frames as they connect (`attach-shadow,sync-guard`) |
1427
1428
  | `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`) |
1428
- | `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]` | — |
1429
+ | `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]`, `[4.own-external]`, `[4.own-turned]`, `[4.own-default]` | WebKit: `[8.preconnect]` | — |
1430
+ | `own-frame-rule` | `leak.spec.ts`, `served/files.spec.ts` | `[4.own-external]`, `[4.own-turned]`, `a page's own frames, opted in (P128): a frame of another site, of another path of its origin, or a plugin stays out of the tree` | — | — |
1431
+ | `own-frame-rule,own-frame-src` | `served/files.spec.ts` | `a page's own frames, opted in (P128): a frame of another site, of another path of its origin, or a plugin stays out of the tree`, `a page's own frames, opted in (P128): a frame of another site or of another path of its origin loads nothing` | — | — |
1429
1432
  | `attach-shadow,sync-guard` | `leak.spec.ts` | `[4.closed-shadow]`, `[4.shadow-nested]` | WebKit: `[8.preconnect]` | — |
1430
1433
  | `declarative-shadow` | `leak.spec.ts` | `[4.declarative-shadow]` | — | — |
1431
1434
  | `parser-entry-points` | `leak.spec.ts` | `[4.document-write]`, `[14.shell]` | — | — |
@@ -5,7 +5,7 @@ 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.14.6 (2026-10-30). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.8 (2026-11-04). A review on 2026-10-19 found gaps, and every decision it led to
9
9
  has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
10
10
  and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
11
11
  annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
@@ -22,7 +22,10 @@ person, not the page, pressed in it (§7 "The keyboard", `comments`); and P112's
22
22
  additions for a host's comment modes (hints, as every report is, §7). 0.14.1: P114
23
23
  (porthole#56) serves a nested page's shell on a label of its own, on which nothing but nested
24
24
  pages' shells, their pages, those pages' files and status pages is ever served, so no other
25
- display of the scope is same-origin with the shell (S3).
25
+ display of the scope is same-origin with the shell (S3). Unreleased: P128 lets a host opt a config
26
+ into a page's own nested frames (`nestedFrames: "own"`, off by default): its `srcdoc` frames and
27
+ frames of its own files load and run, in realms the shell's hardening never reaches (WebRTC, the
28
+ clipboard's guards: S1, S3); frames of other sites stay out.
26
29
 
27
30
  ## 1. Two layers
28
31
 
@@ -77,7 +80,9 @@ the agent, but it is not a wall.
77
80
  Isolation doesn't stop content from sending out what it was given, or from drawing a fake. So:
78
81
  - its network is closed by default: the frame's CSP, the shell's defenses for channels a CSP
79
82
  doesn't cover (WebRTC, nested frames, resource hints), and the embedding page's `frame-src`
80
- against the frame navigating itself away;
83
+ against the frame navigating itself away. A host that opts into a page's own frames
84
+ (`nestedFrames: "own"`, P128) gives up the shell's defenses inside them: there, the CSP alone
85
+ closes the network;
81
86
  - everything beyond drawing is a host function the config declares, behind gates: a user
82
87
  gesture, a person's confirmation, consent, a rate;
83
88
  - the host draws its confirmations and consent outside the frame, where content can't draw over
@@ -231,7 +236,10 @@ Whatever the use:
231
236
  capability or the egress config names an origin), `form-action 'none'`, `frame-src 'none'`,
232
237
  `base-uri 'none'`, `object-src 'none'` and `webrtc 'block'`, and no `'self'` anywhere. Before
233
238
  content runs, the shell removes the `RTC*` constructors, drops nested frames, plugins and
234
- resource hints as they are inserted, and makes `document.open` and `write` throw.
239
+ resource hints as they are inserted, and makes `document.open` and `write` throw. Where the host
240
+ opts into the content's own frames (`nestedFrames: "own"`, P128; off by default), the shell keeps
241
+ `srcdoc` iframes (an inline widget has no files of its own) and drops every other frame and
242
+ plugin as before, a kept frame included once a change would point it elsewhere.
235
243
  - While it streams, drafts are drawn inert (no scripts, handlers or navigation); the whole runs
236
244
  once.
237
245
  - Only the host functions the config declares exist, each behind its default gates:
@@ -278,6 +286,11 @@ Whatever the use:
278
286
  **Not guaranteed**
279
287
 
280
288
  - On a page without that `frame-src`, a widget can send out whatever it was shown.
289
+ - With `nestedFrames: "own"` (P128, the host's choice), a widget's `srcdoc` frame is a realm where
290
+ none of the shell's defenses ran: it has WebRTC (a way out past `connect-src`, closed only where
291
+ an engine honors `webrtc 'block'`), resource hints, `document.write`, and `execCommand("copy")`
292
+ and copy listeners from a click in it (text the person didn't choose on their clipboard, with no
293
+ notice). The frame's CSP, which it inherits, still holds for everything else.
281
294
  - `copyText` needs only a gesture, not a confirmation: a widget can put text the person didn't
282
295
  choose on their clipboard when they click in it (pastejacking). The notice above is what tells
283
296
  them.
@@ -360,10 +373,17 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
360
373
  no other label can set; the entered mark names its label. A session names its scope, signed, so
361
374
  another label's session is never read as this one's, under https or on loopback (P101).
362
375
  - Pages, files and status pages carry their CSP in headers and `X-Robots-Tag: noindex`, and
363
- `frame-ancestors` names the app's origins only.
376
+ `frame-ancestors` names the app's origins only (with `nestedFrames: "own"`, P128, a file set's
377
+ files below its base name the page's own origin too, so its pages frame them).
364
378
  - Files: from the version's manifest only, typed by Porthole's table, `nosniff`; files other than
365
379
  pages are `Cross-Origin-Resource-Policy: same-origin`; a file set never registers a service
366
380
  worker; a page's CSP opens its own version's path, not its whole origin.
381
+ - A page's nested frames are removed, a `srcdoc` one and one of its own files alike, unless the
382
+ host opts in (`nestedFrames: "own"`, P128). Then an iframe of one of its version's own files or
383
+ with `srcdoc` loads and runs (a page of the set with its own shell), and every other frame
384
+ (another site, another path of the origin, a scheme, an empty one) and plugin is removed: the
385
+ page's `frame-src` opens its version's path alone, which also governs every navigation of its
386
+ frames. Not for a nested page (refused).
367
387
  - With a per-request check (`authorize`), the host decides again on every request; a deny is a
368
388
  403 that says `denied`.
369
389
  - A nested page (`nested: true`, P111): the framed address answers Porthole's shell alone, its
@@ -444,6 +464,11 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
444
464
  - A revocation reaches the next request. It doesn't reach a page already running, an open
445
465
  WebSocket, pinned files the browser cached (immutable for a year), or assets in bearer mode
446
466
  (§7).
467
+ - With `nestedFrames: "own"` (P128), a page has WebRTC: every iframe it keeps starts as an
468
+ `about:blank` of its own origin, which it reaches before anything loads there, and a `srcdoc`
469
+ frame runs none of the shell's defenses (resource hints, `document.write`, and a click's
470
+ `execCommand("copy")` and copy listeners, which put text on the clipboard with no notice). Its
471
+ frames can't navigate out of its version's path, and their sandbox is the page's.
447
472
 
448
473
  ### S4. Public links, and pages that are apps
449
474