@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.
- package/CHANGELOG.md +60 -0
- package/dist/check/files.js +2 -0
- package/dist/check/lint.js +82 -3
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +17 -6
- package/dist/compile/policy.js +22 -7
- package/dist/config/schema.d.ts +13 -0
- package/dist/config/validate.js +15 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/kit.d.ts +5 -0
- package/dist/conformance/kit.js +21 -0
- package/dist/conformance/limits.js +10 -5
- package/dist/conformance/probes.js +139 -28
- package/dist/conformance/served.js +43 -14
- package/dist/guide/limits.js +8 -1
- package/dist/host/create-host.js +35 -4
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +6 -0
- package/dist/server/files.js +4 -3
- package/dist/server/index.js +2 -1
- package/dist/server/server.js +89 -37
- package/dist/server/types.d.ts +23 -0
- package/dist/shell/plan.d.ts +5 -0
- package/dist/shell/plan.js +2 -0
- package/dist/shell/runtime.d.ts +30 -1
- package/dist/shell/runtime.js +785 -104
- package/docs/ADOPTING.md +36 -0
- package/docs/DECISIONS.md +341 -0
- package/docs/DESIGN.md +7 -4
- package/docs/THREAT_MODEL.md +30 -5
- package/docs/insertion-entry-points.md +95 -0
- package/package.json +1 -1
- package/src/check/files.ts +2 -0
- package/src/check/lint.ts +97 -8
- package/src/compile/policy.ts +23 -6
- package/src/config/schema.ts +13 -0
- package/src/config/validate.ts +16 -0
- package/src/conformance/kit.ts +22 -0
- package/src/conformance/limits.ts +10 -5
- package/src/conformance/probes.ts +149 -28
- package/src/conformance/served.ts +43 -14
- package/src/guide/limits.ts +9 -1
- package/src/host/create-host.ts +37 -4
- package/src/index.ts +1 -0
- package/src/presets/presets.ts +15 -0
- package/src/server/files.ts +8 -2
- package/src/server/index.ts +2 -1
- package/src/server/server.ts +116 -46
- package/src/server/types.ts +25 -0
- package/src/shell/plan.ts +7 -0
- 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]` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -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.
|
|
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
|
|