@botiverse/porthole 0.14.5 → 0.14.7

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 (76) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/dist/check/page-source.js +1 -1
  3. package/dist/check/page.js +5 -1
  4. package/dist/compile/policy.d.ts +6 -0
  5. package/dist/compile/policy.js +6 -0
  6. package/dist/conformance/entry.d.ts +25 -6
  7. package/dist/conformance/entry.js +69 -18
  8. package/dist/conformance/harness/page.d.ts +12 -0
  9. package/dist/conformance/harness/page.js +95 -51
  10. package/dist/conformance/harness-source.js +1 -1
  11. package/dist/conformance/host-kit.js +39 -13
  12. package/dist/conformance/served.js +148 -0
  13. package/dist/files/paths.d.ts +2 -2
  14. package/dist/files/paths.js +12 -2
  15. package/dist/host/client.d.ts +8 -0
  16. package/dist/host/client.js +47 -17
  17. package/dist/host/create-host.d.ts +10 -0
  18. package/dist/host/create-host.js +124 -10
  19. package/dist/host/door.d.ts +41 -0
  20. package/dist/host/door.js +55 -0
  21. package/dist/host/locate.js +2 -0
  22. package/dist/host/locator.d.ts +55 -3
  23. package/dist/host/locator.js +152 -42
  24. package/dist/host/outcome.d.ts +54 -1
  25. package/dist/host/outcome.js +33 -8
  26. package/dist/host/types.d.ts +10 -2
  27. package/dist/isolation/served.d.ts +1 -1
  28. package/dist/isolation/served.js +35 -0
  29. package/dist/isolation/types.d.ts +20 -2
  30. package/dist/isolation/types.js +2 -0
  31. package/dist/platform/types.d.ts +22 -0
  32. package/dist/platform/web.js +55 -12
  33. package/dist/react/view.d.ts +13 -0
  34. package/dist/react/view.js +101 -2
  35. package/dist/server/files.d.ts +11 -0
  36. package/dist/server/files.js +26 -4
  37. package/dist/server/host.js +106 -28
  38. package/dist/server/index.d.ts +2 -1
  39. package/dist/server/index.js +7 -1
  40. package/dist/server/pages.d.ts +32 -0
  41. package/dist/server/pages.js +82 -6
  42. package/dist/server/server.js +194 -16
  43. package/dist/server/types.d.ts +38 -1
  44. package/dist/transport/post-message.d.ts +1 -9
  45. package/dist/transport/post-message.js +2 -8
  46. package/docs/ADOPTING.md +73 -4
  47. package/docs/DECISIONS.md +245 -0
  48. package/docs/DESIGN.md +24 -18
  49. package/docs/THREAT_MODEL.md +79 -13
  50. package/package.json +1 -1
  51. package/src/check/page.ts +6 -1
  52. package/src/compile/policy.ts +7 -0
  53. package/src/conformance/entry.ts +129 -24
  54. package/src/conformance/harness/page.ts +112 -49
  55. package/src/conformance/host-kit.ts +53 -16
  56. package/src/conformance/served.ts +184 -0
  57. package/src/files/paths.ts +11 -2
  58. package/src/host/client.ts +59 -22
  59. package/src/host/create-host.ts +144 -18
  60. package/src/host/door.ts +97 -0
  61. package/src/host/locate.ts +2 -0
  62. package/src/host/locator.ts +208 -57
  63. package/src/host/outcome.ts +41 -9
  64. package/src/host/types.ts +10 -2
  65. package/src/isolation/served.ts +40 -1
  66. package/src/isolation/types.ts +19 -2
  67. package/src/platform/types.ts +21 -0
  68. package/src/platform/web.ts +55 -20
  69. package/src/react/view.tsx +149 -2
  70. package/src/server/files.ts +37 -5
  71. package/src/server/host.ts +131 -46
  72. package/src/server/index.ts +7 -1
  73. package/src/server/pages.ts +101 -6
  74. package/src/server/server.ts +266 -32
  75. package/src/server/types.ts +41 -1
  76. package/src/transport/post-message.ts +1 -9
package/docs/DECISIONS.md CHANGED
@@ -6771,6 +6771,251 @@ one PRINCIPLE 5 can't prove. Starting a display again on a dropped status, so th
6771
6771
  server: content could make a display start again at will (bounded by P031's count, as navigating
6772
6772
  away is), for a block the frame already shows.
6773
6773
 
6774
+ **After the audit of 0.14.5** (2026-10-30, Ferryman; Chromium's headless shell and Firefox, WebKit
6775
+ not run). Rule 2 holds against a display's own content: no route was found to a first word in its
6776
+ own run (navigating, reloading, redirecting, history, its own frames, a nested child posting to
6777
+ `top`). It doesn't hold against another display of its scope.
6778
+ - **P124-1 (P1). A served display of the same scope can speak first in another's run.** A scope's
6779
+ displays share one origin (P114: "the scope's other displays run content there with
6780
+ `allow-same-origin`"). A running display reaches every frame on the host's page (`top[i]`), and
6781
+ a new display's first document is same-origin to it as soon as it commits, before its shell's
6782
+ hello. It can add a script there that posts a frame status: the host takes it as the run's first
6783
+ word, with the sibling's reason and code, and hears no `frame-status` host error. Or it can stop
6784
+ or rewrite that document, so the shell never runs and the host infers `blocked: framing` from
6785
+ silence (P040). It needn't wait for a mount: a `location.reload()` it puts into a running display
6786
+ passes the shell's navigation guard and starts a new run (P031), up to three times. Every run, on
6787
+ both engines.
6788
+ - **Exposed:** any host that shows two served, non-nested displays of one scope on a page (an
6789
+ artifact's versions in one chat, a card beside its full view, a session's widgets and files).
6790
+ A view through the sandbox proxy is on its scope's origin too (not probed).
6791
+ - **Not exposed:** a nested page (its shell is on the `porthole-` label, P114), and a page with
6792
+ one display of its scope.
6793
+ - **Until it is closed**, THREAT_MODEL §4, §6, §7 and ADOPTING say the limit, and that such a
6794
+ host nests those displays, or takes a `blocked` outcome of one whose scope has another display
6795
+ running as unconfirmed. P125 will close it: either nested pages gain `served.storage`,
6796
+ `assets` and `egress.libraries` (so every served display can be nested), or a non-nested
6797
+ display's first document is served on a label no content runs on, before its content runs.
6798
+ - **P124-2 (P2, since P081). A file set whose entry is no page never speaks.** `checkFileSet` asks
6799
+ only that the entry is one of the set's files. An entry such as `note.txt` or `pic.svg` is served
6800
+ inert, no shell loads, and the host infers `blocked: framing` (P040): the agent chooses one of
6801
+ Porthole's fallbacks. Planned: the entry must be a page (`checkFileSet`, `admitFiles` and
6802
+ `lintFiles` refuse another), and a ticket's answer for one is Porthole's status page.
6803
+ - **P124-3 (P3, tests). No leak probe sees rule 1 alone.** The opaque forger speaks after its
6804
+ shell's hello, so rule 2 drops it already; the control `frame-status` takes out both rules at
6805
+ once, which hides that. Rule 1 is proven by `test/outcome.test.ts` only (DESIGN's row now says
6806
+ so). Planned: split the control in two, one per rule.
6807
+
6774
6808
  **Revisit when** a host needs a later block told in a display with files (then: start it again on a
6775
6809
  dropped status, its next run's first document says it), or url mode gets a shell of Porthole's on
6776
6810
  the app's origin.
6811
+
6812
+ ## P125 · 2026-10-30 · A served display's word comes from a door no content of its scope can reach · Accepted
6813
+
6814
+ **Amends P040, P050, P124.** After the audit of 0.14.5 (2026-10-30): P124's "a frame status is
6815
+ the word of Porthole's pages" held against a display's own content, but not against another display
6816
+ of its scope. A scope's displays share one origin (P114), and a served display that isn't nested is
6817
+ framed there, where the scope's others run content with `allow-same-origin`. One of them reaches a
6818
+ new document of another's before its first script runs, and can speak a frame status (taken, no
6819
+ host error), or stop or rewrite it so its silence reads as `framing` (P124-1); a reload it puts into
6820
+ a running display starts a new run it can speak first in. So Porthole's word for such a display
6821
+ can't come from its own frame at all.
6822
+
6823
+ **The rule.** A non-nested served frame's frame status is never taken by the host; blocked or
6824
+ allowed is said either by the door frame or by the host asking `issue` before it builds the frame.
6825
+
6826
+ **Decision.** For a served display that isn't nested (a served shell, a page, a view through the
6827
+ sandbox proxy), the host first makes a hidden **door**: a page of Porthole's server on the same
6828
+ origin, in a frame of the host's own that no content can reach — `sandbox="allow-scripts"` (an
6829
+ opaque origin, a fresh one each run), `allow=""`, `referrerpolicy="no-referrer"`, `aria-hidden`,
6830
+ `tabindex=-1`, `inert`, 0×0, `visibility:hidden`, and **no `name`** (nothing targets it). The door
6831
+ is at `<origin>/__porthole/door/<instance key>?ticket=<door ticket>`. Its one frame status decides:
6832
+ a new state **`open`** (not `entering`, so it never meets url mode's `loads >= 2` rule) → the host
6833
+ removes the door and makes the content frame as before; **`blocked`** (reason, status, code) → that
6834
+ is the outcome, and no content frame is made; the door `load` then `SETTLE_MS` of silence →
6835
+ `blocked: framing` (now trustworthy: only the door was ever in that frame).
6836
+
6837
+ The content frame of such a display is then **strict**: no frame status from it is ever taken (each
6838
+ run, the first is dropped with one `frame-status` host error), and `framing` is never inferred from
6839
+ its silence — a load with no hello is a `timeout`, decided early (load + `SETTLE_MS`). Every
6840
+ reload or navigation (`navigatedAway` → `run()`) starts again with a new door, counted against
6841
+ `MAX_RESTARTS`. **Every display ends with an outcome** (the host's contract): a restart doesn't
6842
+ start the clock again (one `loadTimeoutMs` per loading episode, from its first run until it has an
6843
+ outcome; an outcome, or the host's `reload()`, begins a new one), and a frame stopped once its
6844
+ restarts ran out is `blocked: error` (its `contentError` as before). Before, a sibling that wiped a
6845
+ display again and again left it with no outcome and no timeout (Cato, on WebKit, 2026-10-30). **On
6846
+ WebKit the sibling probes' attack lands only sometimes** (measured in CI, 2026-10-30): in most runs
6847
+ every `document.open` A tried into B's loading document threw, and in some A got in (under the
6848
+ `door-silence` control it wiped B, and B was `blocked: framing`, the weakening caught). So
6849
+ `[sibling-inject]`, `[sibling-reload]`, `[sibling-wipe]` and `[proxy]` check their positive control
6850
+ on every run (`requireReach`): A's write counts only into a document still being parsed (`loading`;
6851
+ by `interactive` B's inline shell has run and may have spoken: on WebKit `[proxy]` got in that late);
6852
+ when A got in in time they are judged as on every engine (unweakened: pass;
6853
+ under a control: fail); when every try was refused they skip with the measurement, never pass, and
6854
+ their controls take that skip as held on WebKit (`measured`, `leak/controls.ts`; Tenny and Cato).
6855
+ P125's rule doesn't depend on any of this — no frame status of a served non-nested frame is taken
6856
+ on any engine — and WebKit's refusal is never a premise of it. Retest with each WebKit version. Nested displays (their shell is on a label of its own, P114), url mode and opaque
6857
+ frames are unchanged: a nested page's shell keeps P124's ordering rule, a url-mode app's word is
6858
+ taken as before (S6), an opaque frame's every status is the content's (rule 1).
6859
+
6860
+ **Server.** `issue` mints the content ticket as today **plus a door ticket** (`TicketRecord.door:
6861
+ true`, same grant and TTL, a JSON field, no D1 migration) for those kinds, and returns `door: { url
6862
+ }` in the `FrameLocation`. `/__porthole/door/<key>` → `serveDoor`: takes the door ticket (single
6863
+ use, bound to label and key, `record.door === true`, refusing an entry or hop ticket), then runs
6864
+ the **same** `denied`/authorize, document and entry checks `serveDocument` runs for the same grant,
6865
+ and answers `doorPage` (`open`) or `doorStatusPage` (401 session / 403 denied+code / 404 not-found /
6866
+ 500 error). Both carry `default-src 'none'; script-src 'sha256-…'; base-uri 'none'; form-action
6867
+ 'none'; sandbox allow-scripts; frame-ancestors <hostOrigins>`, `no-store`, `no-referrer`, `nosniff`,
6868
+ `noindex`, and no cookie (the inline script by hash, since `'self'` is unreliable in an opaque
6869
+ document). **Invariant: the door and the content route run the same checks for the same grant** —
6870
+ `serveDocument` keeps taking its own ticket and running `authorize` and the document checks itself
6871
+ (P050, its data's wall), so the door only reports. `serveDocument` refuses a door ticket; the door
6872
+ refuses a content, entry or hop ticket; a nested page's label serves no door.
6873
+
6874
+ **Before any frame: the host asks `issue`.** A clean address (P068) is for a top-level tab. A host
6875
+ that shows what one names in a frame resolves it first through its issue endpoint (`{ address }`:
6876
+ `client.resolve(address)`, `<PortholeView address>`), which maps the address as its tab's
6877
+ authorize would (the naming's `scopeOf`, `entry.at`, then `access`) and answers before any frame: a
6878
+ location with its door (and, for a file set's page below its version, a frame that opens at that
6879
+ page, the door checking the same page), or the refusal the tab would get. A refusal from the host's
6880
+ own issue endpoint is the display's outcome, one to one with the status pages it replaces, the
6881
+ fallback's wording unchanged: **401 → `blocked: sign-in`, 403 → `blocked: denied` (with the host's
6882
+ reason code, only from the answer's own `error.reason`), 404 → `blocked: not-found`**, with no host
6883
+ error. Every other failure (a 5xx, a network error, a malformed answer) is the host's own: `blocked:
6884
+ locate` and a `locate` host error, never `denied`; a backend that never answers within
6885
+ `loadTimeoutMs` is a `timeout`. This applies to every locate, an instance's too. No frame is made
6886
+ for any of them. In a frame, `cookies`, an expired entry state and redeem's `session`/`denied` no
6887
+ longer occur: an issued frame carries its access in its ticket and sealed address (P025, P083).
6888
+
6889
+ **A location with no door is refused.** For a served, non-nested config, `createHost` builds no
6890
+ frame for a location without a `door` (an older server, a locator that drops it, a clean address
6891
+ someone framed): `blocked: locate`, and a host error of kind **`door`** naming the fix ("a served
6892
+ display needs a door from issue; a clean address is for a tab: resolve it with `client.resolve` or
6893
+ `<PortholeView address>`"). One rule for both cases; nothing infers a door's word from anything
6894
+ else. The door's load-bearing check is that it is on the display's own origin (the one its issue
6895
+ located) and came with that issue; its path is pinned to `/__porthole/door/` for now, in a check of
6896
+ its own, so relaxing the path later (a content Worker's own route) can't drop the origin check.
6897
+
6898
+ **Compatibility.**
6899
+
6900
+ | Host \ server | Old (no `door`) | New (`door`, `issue { address }`) |
6901
+ | --- | --- | --- |
6902
+ | Old (P124) | P124 as before (exposed, P124-1) | `door` ignored (its ticket expires unused): P124 as before; a framed clean address gets a page with no status at all |
6903
+ | New (P125) | **refused before any frame**: `blocked: locate`, `door` host error | P125 |
6904
+
6905
+ No fallback to P124's rule, no option, no knob (PRINCIPLES 1, 8). **Deploy order: the server/Worker
6906
+ first, then the host** (a hard requirement in ADOPTING). A custom locator must pass `door` through,
6907
+ and must issue anew for every run. No grace release for a framed clean address: no documented flow
6908
+ (`portholeClient`, `PortholeView`, the examples) ever framed one, and the one undocumented way
6909
+ (`createHost` given a hand-built clean URL) is refused with a message naming the fix (CHANGELOG).
6910
+
6911
+ **Removed from here on.** P068's in-frame branch: the content origin answers a clean address asked
6912
+ from a frame (`Sec-Fetch-Dest: iframe` or `frame`) with Porthole's "open this in a new tab" page,
6913
+ never a trip to the app, and so does the app's authorize route asked from a frame; that page carries
6914
+ the status pages' policy (`default-src 'none'`, `frame-ancestors` the host origins) with no
6915
+ `script-src` and no script at all. And the transport's `also` channel (a frame's status heard from
6916
+ the host's own origin, P068): a frame is heard from its own window and its located origin alone. No
6917
+ negative control needs either (`content-status` takes out the strict rule, not a channel).
6918
+
6919
+ **A `load` event is not a committed document** (required reading for any future timing exception).
6920
+ Before choosing the issue-first rule, an exception was weighed for a framed clean address: take a
6921
+ frame status from the host's own origin, on the frame's first load, before anything else. It fails:
6922
+ a document wiped and navigated while it parses never fires `load`. Measured on Chromium (a framed
6923
+ document that runs `document.open(); location.href = <a host-origin page that posts a status>`
6924
+ during parse): the status arrived with `loadsSoFar=0`, then `load#1`. So a same-scope sibling that
6925
+ writes into a signed-in clean-address display before its shell's hello could send it to another
6926
+ clean address of the scope, and the host's honest page there (`sign-in`, `denied`) would be taken as
6927
+ this display's first word. A host can count `load` events; it can't see committed documents. Any
6928
+ rule that reads "the first load" as "the first document" re-opens P124-1.
6929
+
6930
+ **Folded in.** P124-2: `checkFileSet`/`admitFiles`/`lintFiles` refuse an entry that isn't `.html`
6931
+ or `.htm` (code `entry`); a stored set whose entry isn't a page answers Porthole's `not-found`
6932
+ status page, and the door says `not-found` (so an old host, which has no door, still gets Porthole's
6933
+ word, not an inert file that says nothing). P124-3: the one `frame-status` control is split per the
6934
+ design's §4 table (`content-status`, `door-status`, `door-silence`, `door-opaque`,
6935
+ `frame-status-order`).
6936
+
6937
+ **What holds the door (after the audit of P125, Ferryman).** A sibling of the scope does get the
6938
+ live door's `WindowProxy` while it loads (`top[i]`): it can read its `length` and post to it
6939
+ (nothing listens). The wall is three things, each measured: reading the door's document throws a
6940
+ `SecurityError` (it is opaque: the frame's `sandbox` attribute and the door answer's CSP `sandbox`
6941
+ each make it so on its own); setting or replacing its `location` throws a `SecurityError` (the
6942
+ sibling's own sandbox sets the sandboxed navigation flag: it navigates no frame that isn't its own);
6943
+ and the door has no name, so `window.open(url, name)`, a link's or a form's `target` reach nothing.
6944
+ Behind them, the host takes the door's word from the opaque origin (`"null"`) alone. One slip
6945
+ changes nothing: removing one sandbox token leaves the other; removing both makes every served
6946
+ display `framing` (the honest door then speaks from the content origin, which the host doesn't hear:
6947
+ fail closed). Only opacity and the `"null"` check removed together let displays work while a sibling
6948
+ reads the live door and rewrites it into Porthole's own status page, which then says `blocked:
6949
+ session` from the door's window: that is the `door-opaque` control, and `[door-reach]` (which does
6950
+ exactly that, with a lingering door) fails under it. An earlier draft of this entry said a sibling
6951
+ never meets a live door; it does. `[sibling-reload]` is Ferryman's reload probe (a sibling reloads a
6952
+ loaded display and speaks first in its next run), red under `door-status` and `content-status`.
6953
+
6954
+ **A locator issues anew for every run.** A door ticket opens one door. A host whose locator returns
6955
+ the same location every run used to restart through the session cookie; now its restart's door says
6956
+ `blocked: session`, and a sibling could force that by reloading the display. `createHost` tells the
6957
+ host (`hostError` kind `locate`, "a locator must issue anew for every run") when a run is located at
6958
+ an address an earlier run used; the outcome is unchanged, the server's word (ADOPTING, CHANGELOG).
6959
+
6960
+ **Costs accepted** (THREAT_MODEL S7, the premise being a scope its author controls): one extra
6961
+ request and a ~1 KB document per mount, and about one RTT of added latency (sequential). A sibling
6962
+ of a scope can still spend a display's three restarts, force it to a timeout ("This is taking too
6963
+ long", no link), deface it, and read a sandbox-proxy view's HTML once it is sent — the known costs
6964
+ of sharing a scope, not a forged sign-in with a link out.
6965
+
6966
+ **Planned, not in this release:** a host-only **parallel-mount** variant (the door and the content
6967
+ frame opened together, the door's `blocked` winning even after `loaded`, door silence meaning
6968
+ `framing` only before a hello, content statuses still never taken), measured against the sequential
6969
+ default before either is chosen. It is a later commit; nothing of the server or the wire changes for
6970
+ it.
6971
+
6972
+ **Revisit when** a host needs a later block told in a display with files (then: start it again on a
6973
+ dropped status, its next run's first door says it), url mode gets a shell of Porthole's on the app's
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.
package/docs/DESIGN.md CHANGED
@@ -488,11 +488,12 @@ a link sent to someone with access.
488
488
  A request on a clean address without a cookie for it gets a 302 to the app's authorize route
489
489
  with a signed state (label, path, nonce, five minutes), and a cookie holding the nonce on the
490
490
  content origin (partitioned in a frame, `Lax` on a tab, like the session cookie).
491
- 2. `authorize` asks `entry.at(scope, path)` and `access`. No viewer: on a tab, the app's own
492
- sign-in (`signIn(returnTo, request, entry)`), which comes back to the same route; **in a
493
- frame, never the sign-in**: a plain page asking for a new tab (`blocked: sign-in`). No
494
- access: the app's refusal on a tab (`refusal(status, request, entry)`; nothing returned:
495
- Porthole's page), a plain page in a frame; never content. Both hooks get the address decoded
491
+ 2. `authorize` asks `entry.at(scope, path)` and `access`. No viewer: the app's own sign-in
492
+ (`signIn(returnTo, request, entry)`), which comes back to the same route. No access: the app's
493
+ refusal (`refusal(status, request, entry)`; nothing returned: Porthole's page); never content.
494
+ **Redirect entry is for a tab alone (P125):** a clean address asked from a frame
495
+ (`Sec-Fetch-Dest: iframe`/`frame`), and the authorize route asked from one, answer Porthole's
496
+ "open this in a new tab" page (the status pages' policy, no script), never a trip to the app. Both hooks get the address decoded
496
497
  (`EntryContext`: label, scope, path, clean URL, the instance, framed). `returnTo` (and
497
498
  `entry.spa`'s `next`) is `authorizeUrl` with the request's query: the app as it is reached,
498
499
  never the request's own URL, whose scheme and host behind a TLS edge or a dev proxy are
@@ -502,14 +503,15 @@ a link sent to someone with access.
502
503
  the nonce's cookie, sets the session (bound to the path) and 303s to the clean address. The
503
504
  code is in an address for that one hop (gone from history), every redirect sends
504
505
  `no-referrer`, and Porthole never logs it.
505
- 4. A browser that keeps no cookie in a frame (WebKit, P025) has no nonce at the redeem: it gets
506
- the "open in a new tab" outcome (`blocked: cookies`), and an entered path whose session still
507
- didn't come back is caught on the second bounce. No loops.
508
-
509
- Use tickets (`issue` → `FrameLocation`) for frames: no extra round trip, and no dependence on the
510
- app's own cookie reaching its authorize route inside a frame (measured: Firefox and WebKit don't
511
- send a `Lax` app cookie on a frame navigation that came through a cross-site redirect; Chromium
512
- does). Use clean addresses for tabs, links, bookmarks and reloads: a host's "open in a new tab"
506
+ 4. A path whose session didn't come back is caught on the second bounce (`blocked: cookies`, the
507
+ loop guard): on a tab only, since a frame never enters (P125).
508
+
509
+ Frames use tickets (`issue` → `FrameLocation`, with its door): no extra round trip, and no
510
+ dependence on the app's own cookie reaching its authorize route inside a frame. To frame what a
511
+ clean address names, the host resolves it through `issue` first (`{ address }`, `client.resolve`,
512
+ `<PortholeView address>`, P125); a refusal there is the outcome, with no frame. (Why frames never
513
+ entered, measured before P125: Firefox and WebKit don't send a `Lax` app cookie on a frame
514
+ navigation that came through a cross-site redirect; Chromium does.) Use clean addresses for tabs, links, bookmarks and reloads: a host's "open in a new tab"
513
515
  and "copy link" use `urlOf`, never a ticket. The first open of an instance per browser costs one
514
516
  extra round trip through the app.
515
517
 
@@ -978,8 +980,8 @@ for that to lapse and click with raw input.
978
980
 
979
981
  | What | Mechanism | Tests (all three engines unless noted) | Negative control → fails |
980
982
  |------|-----------|-------|------------------|
981
- | The host's check (P050) | `authorize.check` after a ticket or cookie verifies, before anything is served; a deny is a 403 page saying `denied` and the host's code, and the display's `outcome` says so (after `loaded` too in url mode; a frame that speaks is told by its next run's first document, P124) | `leak/served/authorize.spec.ts`: a revoked subject's ticket (a page, an app); a framed app's next request and reload mid-session (Chromium, Firefox: WebKit keeps no framed cookie, P025); a framed page's next load; an app and a page in a tab | `authorize` → every case but WebKit's framed page (`session` either way) |
982
- | Who may say how loading went (P124) | a frame status (`porthole/notifications/frame-status`) draws the host's fallback, so it is taken only where content can't have said it: never from an opaque frame (no page of Porthole's server loads there); in a frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell), only before anything else is heard from it in the run, since Porthole's word (the shell's hello, the proxy's ready) opens every document that holds content, before content runs, and a status page says nothing but its status; a url-mode app's, as before (S6). One not taken is dropped, and the host hears a `hostError` of kind `frame-status`, once a run | `test/outcome.test.ts` ("who may say how loading went (P124)", and through `createHost`); `leak/served/outcome.spec.ts`: a served shell's content, a served page as it loads, an opaque widget and a nested page (through its shell and past it) each say `blocked` (`sign-in`, `denied`, a code) at once and again: the outcome stays `loaded`, the host hears one `frame-status` error | `frame-status` → those four cases (all three) |
983
+ | The host's check (P050) | `authorize.check` after a ticket or cookie verifies, before anything is served; a deny is a 403 page saying `denied` and the host's code, and the display's `outcome` says so (after `loaded` too in url mode; a served display that isn't nested is told by its next run's door, which takes a fresh ticket, P125) | `leak/served/authorize.spec.ts`: a revoked subject's ticket (a page, an app); a framed app's next request and reload mid-session (Chromium, Firefox: WebKit keeps no framed cookie, P025); a framed page's next load (every engine: its next run's door); an app and a page in a tab | `authorize` → every case but WebKit's framed app (no framed cookie) |
984
+ | Who may say how loading went (P124, P125) | a frame status (`porthole/notifications/frame-status`) draws the host's fallback, so it is taken only where content can't have said it. **A served display that isn't nested** (a served shell, a page, a view through the sandbox proxy) is framed on its scope's origin, where the scope's others run content: **no frame status from its frame is ever taken** (one `frame-status` host error a run), and its silence is a `timeout`, never `framing`. Its **door** said how loading went first, from a frame of the host's that no content can reach (`open`, or `blocked` and why, P125). A **nested page's shell** (on a label of its own, P114) keeps the ordering rule: a status only before anything else is heard, since its runtime's hello opens every document that holds content. An **opaque frame**'s every status is the content's. A **url-mode app**'s is taken, as before (S6). A served non-nested location **without a door** (an older server) raises a `hostError` of kind `door` once a mount and is strict (no status taken) | `test/outcome.test.ts` ("who may say how loading went (P124)", "a served display that isn't nested takes no frame status (P125)", and through `createHost`: the door hand-off, a door block with its code, door silence, a restart's new door); `leak/served/siblings-status.spec.ts`: a same-scope sibling that injects, reloads, stops, wipes a display, attacks the proxy, or reaches for the door, each on all three; `leak/served/outcome.spec.ts`: a served shell's content, a served page, an opaque widget and a nested page each say `blocked` and are shown nothing (the opaque and served-non-nested cases are the ordering rule / the door rule; the opaque rule 1 is proven by `test/outcome.test.ts` only, P124-3; the door's opacity, its namelessness and the sibling's navigation flag by the static sandbox test and `[door-reach]`) | `content-status` → the two served-content cases, `[sibling-inject]`, `[sibling-reload]`, `[proxy]`; `door-status` → `[sibling-inject]`, `[sibling-reload]`, `[proxy]`; `door-silence` → `[sibling-wipe]`; `door-opaque` → `[door-reach]`; `frame-status-order` → the nested case |
983
985
  | Url-mode delegation (P049) | `allow` from `permissions`, `""` by default | `leak/served/permissions.spec.ts`: full screen follows it on all three; clipboard writes on Chromium only (WebKit and Firefox let any frame write in a click) | `url-permissions` → the default case (all three) |
984
986
  | Siblings on the content domain (P101) | over https only `__Host-porthole-` names are read (a sibling sets any other name for the whole domain, never a `__Host-` one), names trimmed of spaces and tabs only; the entered mark is its label's and path's, read from a nonce cookie only; a url-mode app's request rides its cookie only from its own origin (`Origin`; `Sec-Fetch-Site` `same-origin` or `none`) or as a GET/HEAD navigation, else a 403 before the upstream and the host's check; a socket (`access`, `nodeHost`'s `appSocket`, a Worker's upgrade path) from its own origin only | `test/siblings.test.ts` (planted names, the mark on another label, every kind of request and socket, `nodeHost` over a real socket); `test/workers.test.ts` (workerd: a sibling's POST and socket refused, the app's own open); `served.url.siblings`: another app's frame (Chromium, Firefox: WebKit keeps no framed cookie, P025) or tab loading the app's script is refused, its own loads; `leak/kit.spec.ts`: the app's own WebSocket opens through `nodeHost`, a same-site sibling's doesn't; prod shape: a session copied under an unprefixed name and planted with `Domain=` opens nothing, and the socket case over wss | `url-origin` → `served.url.siblings` on the reference serving (Chromium, Firefox; its labels are cross-site on `*.localhost`, so only the framed half rides a cookie) |
985
987
  | Porthole's libraries (P079) | `egress.libraries` (domain isolation; on in `presets.liveWidget`): `script-src <content origin>/__porthole/lib/`; `/server` serves Chart.js 4.5.1 and D3 7.9.0, npm's bytes, on every content origin, without a ticket, immutable | `test/libraries.test.ts` (npm's bytes, pinned, licenses; headers; nothing else under the path); `leak/served/live.spec.ts` (both load and draw in a live widget whose every other load and fetch reaches no oracle) | — (rows 1–2) |
@@ -1416,7 +1418,7 @@ measured weight, stable for a registry), and the `controls` job checks every sha
1416
1418
  every weakening to a control, every control that fails nothing to its reason, and every
1417
1419
  control the tables above name to the registry):
1418
1420
 
1419
- | Control | Run with | Fails on every engine | Fails only on | Where it fails nothing, why |
1421
+ | Control | Run with | Fails on every engine | Fails only on | Where it fails nothing, or may skip, why |
1420
1422
  |---------|----------|-----------------------|---------------|-----------------------------|
1421
1423
  | `connect-src` | `leak.spec.ts` | `[1.connect]`, `[14.silent]` | — | — |
1422
1424
  | `webrtc` | `leak.spec.ts` | `[3.webrtc]`, `[14.workers]` | — | — |
@@ -1459,7 +1461,7 @@ control the tables above name to the registry):
1459
1461
  | `draft-shell-checks` | `annotate.spec.ts` | `the shell's own checks on a raw show (P107): a draft draws no number, a kind it doesn't know is no mark` | — | — |
1460
1462
  | `annotation-activated-gesture` | `annotate.spec.ts` | `a hostile page's marker click with no gesture is dropped; one on the person's own press is the host's view to guard (P105)` | — | — |
1461
1463
  | `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved` | — | — |
1462
- | `authorize` | `served/authorize.spec.ts` | `a revoked subject's ticket opens nothing: a page and an app are denied, and the host is told`, `in a tab of its own, a revoked app and page are denied from the next request on` | Chromium, Firefox: `a framed app mid-session: its next request after revocation is denied, and its next load tells the host`, `a framed page mid-session: its next load after revocation is denied where the engine keeps its cookie` | — |
1464
+ | `authorize` | `served/authorize.spec.ts` | `a revoked subject's ticket opens nothing: a page and an app are denied, and the host is told`, `in a tab of its own, a revoked app and page are denied from the next request on`, `a framed page mid-session: its next load after revocation is denied where the engine keeps its cookie` | Chromium, Firefox: `a framed app mid-session: its next request after revocation is denied, and its next load tells the host` | — |
1463
1465
  | `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
1464
1466
  | `navigate-guard` | `served/live.spec.ts`, `served/files.spec.ts`, `served/served.spec.ts`, `served/tab.spec.ts` | `served.domain.self-navigation`, `served.domain.tab-navigation`, `served.domain.tab-links`, `can't navigate itself away (location): to a site, or to another content origin`, `can't navigate itself away (replace): to a site, or to another content origin`, `can't navigate itself away (open-self): to a site, or to another content origin`, `can't navigate itself away (navigation-api): to a site, or to another content origin`, `a link to another page of the set opens it in the frame; the display goes on`, `a link to another page of the set opens it in the frame when the leaving page's notice is dropped (P098)`, `a link to another page of the set opens it in the frame when the leaving page's notice is late (P098)`, `a page opens nothing else: not a file that isn't a page, not another path of its origin`, `no report, content error or blocked navigation names the frame's sealed address (P083)` | — | — |
1465
1467
  | `tab-sandbox` | `served/tab.spec.ts` | `served.domain.tab-escapes`, `served.domain.tab-opener`, `a file set's page on a tab of its own opens its own pages, and no window, link in a new window or download`, `a frame's sealed address opened on a tab of its own is sandboxed as its frame is` | — | — |
@@ -1489,7 +1491,11 @@ control the tables above name to the registry):
1489
1491
  | `order-check` | `annotate.spec.ts` | `every found mark's place in the document comes with its box, offscreen ones too; a place that isn't one is no report (P112)` | — | — |
1490
1492
  | `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
1491
1493
  | `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
1492
- | `frame-status` | `served/outcome.spec.ts` | `a served shell's content that says it is blocked is told nothing and shown nothing (P124)`, `a served artifact page that says it is blocked as it loads is told nothing and shown nothing (P124)`, `an opaque widget that says it is blocked is told nothing and shown nothing (P124)`, `a nested page that says it is blocked, through its shell or past it, is told nothing and shown nothing (P124)` | — | — |
1494
+ | `content-status` | `served/outcome.spec.ts`, `served/siblings-status.spec.ts` | `a served shell's content that says it is blocked is told nothing and shown nothing (P124)`, `a served artifact page that says it is blocked as it loads is told nothing and shown nothing (P124)`, `[sibling-inject]`, `[sibling-reload]`, `[proxy]` | — | WebKit: `[sibling-inject]`, `[sibling-reload]`, `[sibling-wipe]`, `[proxy]` may skip instead, measured (their attack lands only sometimes there) |
1495
+ | `door-status` | `served/siblings-status.spec.ts` | `[sibling-inject]`, `[sibling-reload]`, `[proxy]` | — | WebKit: `[sibling-inject]`, `[sibling-reload]`, `[sibling-wipe]`, `[proxy]` may skip instead, measured (their attack lands only sometimes there) |
1496
+ | `door-silence` | `served/siblings-status.spec.ts` | `[sibling-wipe]` | — | WebKit: `[sibling-inject]`, `[sibling-reload]`, `[sibling-wipe]`, `[proxy]` may skip instead, measured (their attack lands only sometimes there) |
1497
+ | `door-opaque` | `served/siblings-status.spec.ts` | `[door-reach]` | — | — |
1498
+ | `frame-status-order` | `served/outcome.spec.ts` | `a nested page that says it is blocked, through its shell or past it, is told nothing and shown nothing (P124)` | — | — |
1493
1499
  | `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
1494
1500
  | `shell-label,nested-host-label,nested-shell-origin` | `served/nested-siblings.spec.ts` | `[nested-siblings]`, `[nested-label]` | — | — |
1495
1501
  | `nested-host-label` | `served/nested-siblings.spec.ts` | `[nested-label]` | — | — |
@@ -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.5 (2026-10-29). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.7 (2026-10-30). 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
@@ -84,7 +84,11 @@ the agent, but it is not a wall.
84
84
  them;
85
85
  - the host's fallback for a frame that showed nothing ("open this in a new tab to sign in",
86
86
  "you no longer have access", with a link) is drawn from Porthole's pages' word only, never
87
- from what the content says (P124; a url-mode app aside, S6).
87
+ from what the content says (P124, P125; a url-mode app aside, S6). For a served display that
88
+ isn't nested — where a same-scope sibling could otherwise speak for it ([§7](#the-display-layer)) —
89
+ that word comes from a **door**: a page of Porthole's on the display's origin, in a hidden
90
+ opaque frame of the host's that no content can reach, taken before the content is framed. The
91
+ content frame's own word is then never taken, and its silence is a timeout, never a fallback.
88
92
 
89
93
  The app runtime adds a third: **the host's API is the wall for its data.** The bridge refuses a
90
94
  call the page didn't declare (`undeclared`), or that the viewer's level doesn't allow, before any
@@ -170,8 +174,16 @@ Whatever the use:
170
174
  - Draw a frame's fallback (what `frameFallback` words, or your own) from its `outcome` alone, never
171
175
  from a message of your own reading off the frame's window: a `blocked` outcome is the word of a
172
176
  page of Porthole's server, a gateway or your own pages, never of an opaque frame or of content in
173
- a frame that speaks (P124). Hear the `frame-status` host error as a display trying to speak as
174
- Porthole: log it, and show nothing for it. A url-mode app can still say any outcome (S6).
177
+ a frame that speaks (P124, P125). For a served display that isn't nested, that word is its
178
+ **door**'s (a page of Porthole's on the display's origin, framed hidden and opaque before the
179
+ content, which a same-scope sibling can't reach, P125); its content frame's own word is never
180
+ taken, and its silence is a `timeout`. A `blocked` before any frame (`sign-in`, `denied`,
181
+ `not-found`) is your own issue endpoint's refusal, mapped by `createHost` (P125): its word is
182
+ your backend's, so what it says is as trustworthy as that endpoint. Hear the `frame-status` host
183
+ error as a display trying to speak as Porthole, and the `door` host error as a served display
184
+ refused for having no door (an out-of-date server, a locator that drops it, or a clean address
185
+ framed as it is: upgrade the server/Worker first, resolve clean addresses through issue, P125):
186
+ log them, show nothing for them. A url-mode app can still say any outcome (S6).
175
187
  - Take what the frame reports about annotations as UI hints (where to draw, what to open), never
176
188
  as permissions, and put nothing in a mark the page may not know (§7).
177
189
  - Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
@@ -484,6 +496,11 @@ the attacker (c), and its readers are strangers.
484
496
  - Check pages for secrets before publishing them: `lintContent` has no rule for credentials.
485
497
  - Pass Porthole's `Content-Security-Policy` and `Permissions-Policy` headers on as they are,
486
498
  through any edge or proxy: on a tab they are the page's sandbox.
499
+ - Treat a public link's clean address as a tab's (P125): to show what one names in a frame, resolve
500
+ it through your issue endpoint (`client.resolve`, `<PortholeView address>`). Its refusals (signed
501
+ out, denied, not found) are your backend's word, drawn as the fallback with no frame built: keep
502
+ that endpoint's answers as honest as its access decision, since a `blocked` there is yours, not
503
+ Porthole's door's.
487
504
 
488
505
  **Not guaranteed**
489
506
 
@@ -579,6 +596,10 @@ the attacker (c), and its readers are strangers.
579
596
  cookies included: send the app the headers `upstreamHeaders.request(…, { websocket: true })`
580
597
  makes (Porthole's cookies removed, the upgrade's own headers kept).
581
598
  - Keep previews off pages with displays that read data (S7).
599
+ - Expect a served (domain) display's `blocked` from two sources only (P125): its door, or, before
600
+ any frame, your own issue endpoint's refusal (`sign-in`, `denied`, `not-found`). Neither is the
601
+ previewed app's word; a url-mode app's frame status still is (above), so never put a preview's
602
+ outcome in the same place in your UI as a served display's.
582
603
 
583
604
  **Not guaranteed**
584
605
 
@@ -619,6 +640,27 @@ can be handed to the display with the widest network.
619
640
  - An opaque frame also inherits the page's own CSP, so a strict page narrows its opaque frames
620
641
  further (P058). A served frame has only its own policy.
621
642
 
643
+ **What sharing a scope costs, which Porthole does not stop** (the premise is a scope its author
644
+ controls — one person's artifact and its versions, one session's widgets — not a scope shared across
645
+ people who distrust each other). A scope's displays that aren't nested share one origin and run
646
+ content there with `allow-same-origin`, so one reaches another's document (`top[i]`) and its storage.
647
+ P125 stops a sibling speaking Porthole's word for another display (its door says how loading went,
648
+ unreachably), but a sibling of the scope can still, against another display of it:
649
+
650
+ - spend its three restarts (`MAX_RESTARTS`) by reloading or wiping it, so its outcome is a
651
+ `timeout` or, once the restarts run out, `blocked: error` (a fallback, no link) the person may
652
+ read as the display's own. It always has an outcome: restarts don't start its clock again (one
653
+ `loadTimeoutMs` per loading episode, from its first run until an outcome), and a frame stopped
654
+ after its restarts is `blocked: error` (found by Cato on WebKit during P125: before, it was
655
+ stopped with no outcome at all, an empty box);
656
+ - deface it — rewrite its document — since they share an origin;
657
+ - read a sandbox-proxy view's HTML once the host has sent it into the view.
658
+
659
+ These are the costs of putting displays an author controls in one scope. To deny them, put displays
660
+ that distrust each other in **different scopes** (different origins), or nest them (`nested: true`),
661
+ whose shell and page a sibling can't reach (P114). What a sibling cannot do is forge Porthole's own
662
+ fallback (a sign-in prompt with a link out): that is the door's wall (P125).
663
+
622
664
  ## 7. The display layer and the app runtime
623
665
 
624
666
  ### The display layer
@@ -642,14 +684,36 @@ tab to sign in", "You can't open this anymore") with a link out of the page: UI
642
684
  for the host's and Porthole's, which content must not be able to summon. A `blocked` comes from a
643
685
  frame status (`porthole/notifications/frame-status`), and nothing in that message says who sent
644
686
  it: Porthole's status pages are documents of the frame's own window and origin, as content is. So
645
- the host takes one only where content can't have said it: never from an opaque frame (no page of
646
- Porthole's loads there), and in a frame that speaks (a served shell, a view through the sandbox
647
- proxy, a nested page's shell) only before anything else is heard from it in the run, since
648
- Porthole's own word opens every document that holds content, before the content runs, and a status
649
- page says nothing else. What it drops is no outcome and no code; the host hears a `frame-status`
650
- host error, once a run (control `frame-status`). What follows: in a display with files, a page of
651
- the set answered by a status page (access revoked) shows the server's words in the frame, and the
652
- host isn't told until the next mount. Not covered: a url-mode app (S6).
687
+ the host takes one only where content can't have said it. **A served display that isn't nested** (a
688
+ served shell, a page, a view through the sandbox proxy) is framed on its scope's origin, where the
689
+ scope's others run content with `allow-same-origin`: one of them reaches a new document there before
690
+ its first script runs and could speak for it, so **no frame status from its own frame is ever
691
+ taken** (each run, the first is dropped with one `frame-status` host error), and its silence is a
692
+ `timeout`, never a fallback. Its word comes from its **door** instead (P125): a page of Porthole's
693
+ on the same origin, in a hidden opaque frame of the host's own (`sandbox="allow-scripts"`, no name,
694
+ `inert`, 0×0) that no content shares an origin with and no sandboxed sibling can navigate, taken
695
+ before the content frame is made — `open`, or `blocked` and why. A **nested page's shell** (on a
696
+ label of its own, P114) keeps the ordering rule (its runtime's word opens every document that holds
697
+ content). An **opaque frame**'s every status is the content's; a **url-mode app**'s is taken (S6).
698
+
699
+ This closes the audit of 2026-10-30 (P124-1): before P125, a served display that isn't nested could
700
+ be spoken for by a same-scope sibling — the sibling reached a new document of its scope (`top[i]`,
701
+ same origin before the shell ran), posted a frame status taken as the run's first word, or stopped
702
+ or rewrote it so its silence read as `framing`, or reloaded a running one into a new run it spoke
703
+ first in. The door closes every route: the sibling can't read, navigate or speak from it (it is
704
+ opaque, unnamed, host-sandboxed), and the content frame's own word and silence are no longer taken.
705
+ P124-2 is closed too: a file set's entry must be a page (`.html`/`.htm`; `checkFileSet`,
706
+ `admitFiles`, `lintFiles` refuse another), and a set stored before that rule answers Porthole's
707
+ `not-found` status page — the door says `not-found`, never an inert file that says nothing.
708
+
709
+ The known costs that remain are the costs of sharing a scope (S7). A served non-nested location
710
+ without a door (a server older than the host, a locator that drops it, a clean address framed as it
711
+ is) is refused before any frame: `blocked: locate` and a `door` host error (P125). A clean address
712
+ is for a tab: in a frame the content origin answers it with a page that has no script and goes
713
+ nowhere, never the app's authorize or sign-in. To show what a clean address names in a frame, the
714
+ host resolves it through its issue endpoint first, and a refusal there (signed out, denied, not
715
+ found) is the display's outcome with no frame built. P125 also records why no timing rule can stand
716
+ in for that: a `load` event is not a committed document (DECISIONS P125).
653
717
 
654
718
  **Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
655
719
  its realm with the content (a nested page's too: its marks are drawn by the runtime in the page's
@@ -982,7 +1046,9 @@ what was wrong, what holds now, and the limit its decision accepts, if any. Late
982
1046
  are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
983
1047
  of 0.12.0's drafts), P111 (a nested page, S3; in 0.14.0), P114 (a nested page's shell on a label of
984
1048
  its own, after porthole#56; in 0.14.1), P124 (a frame status is the word of Porthole's pages, after
985
- the audit raft-security-audit#16; in 0.14.5: §4, §6, §7, S6).
1049
+ the audit raft-security-audit#16; in 0.14.5: §4, §6, §7, S6), P125 (a served display that isn't
1050
+ nested takes its word from a door no same-scope content can reach, after the audit of 2026-10-30
1051
+ found P124 held only for a nested display or one alone in its scope; in 0.14.6: §4, §6, §7, S7).
986
1052
 
987
1053
  | Decision | State | What it closes | Sections |
988
1054
  | --- | --- | --- | --- |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.5",
3
+ "version": "0.14.7",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
package/src/check/page.ts CHANGED
@@ -62,6 +62,9 @@ const NOBODY: PlatformHost = {
62
62
  const surface = webPlatform.createSurface(container, spec);
63
63
  return { ...surface, userActivation: () => false };
64
64
  },
65
+ // A served display's door (P125), as the web platform makes it: a platform without doors frames
66
+ // no served display that isn't nested.
67
+ createDoor: (container, spec) => webPlatform.createDoor!(container, spec),
65
68
  };
66
69
 
67
70
  /** A handler for each host function the config declares: it notes the call and answers no. */
@@ -107,7 +110,9 @@ interface Run {
107
110
  const runs = new Map<number, Run>();
108
111
  let next = 0;
109
112
 
110
- const frameOf = (run: Run) => run.box.querySelector("iframe");
113
+ /** A run's frame: the display's own, never its door (P125), which is gone once it said its word. */
114
+ const frameOf = (run: Run) =>
115
+ run.box.querySelector<HTMLIFrameElement>("iframe:not([data-porthole-door])");
111
116
 
112
117
  addEventListener("message", (event: MessageEvent) => {
113
118
  const data = event.data as { portholeCheck?: unknown; data?: unknown } | null;
@@ -251,6 +251,13 @@ export function servedSandboxDirective(config: PortholeConfig): CspDirective | n
251
251
  */
252
252
  export const PAGE_SANDBOX_TOKENS: readonly string[] = ["allow-scripts"];
253
253
 
254
+ /**
255
+ * A served display's door's sandbox (P125): its frame's attribute, which the host writes, and its
256
+ * answer's CSP header's. Scripts only: an opaque origin, a new one each time, that no content of
257
+ * the scope is the same origin as, so none reaches the door's document or speaks from its window.
258
+ */
259
+ export const DOOR_SANDBOX_TOKENS: readonly string[] = ["allow-scripts"];
260
+
254
261
  /** A served page's CSP header: the page's directives, then its sandbox (P099). */
255
262
  export function servedDocumentCsp(
256
263
  config: PortholeConfig,