@botiverse/porthole 0.14.5 → 0.14.6
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 +53 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -1
- package/dist/compile/policy.d.ts +6 -0
- package/dist/compile/policy.js +6 -0
- package/dist/conformance/entry.d.ts +25 -6
- package/dist/conformance/entry.js +69 -18
- package/dist/conformance/harness/page.d.ts +12 -0
- package/dist/conformance/harness/page.js +95 -51
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +39 -13
- package/dist/conformance/served.js +140 -0
- package/dist/files/paths.d.ts +2 -2
- package/dist/files/paths.js +12 -2
- package/dist/host/client.d.ts +8 -0
- package/dist/host/client.js +47 -17
- package/dist/host/create-host.d.ts +10 -0
- package/dist/host/create-host.js +124 -10
- package/dist/host/door.d.ts +41 -0
- package/dist/host/door.js +55 -0
- package/dist/host/locate.js +2 -0
- package/dist/host/locator.d.ts +55 -3
- package/dist/host/locator.js +152 -42
- package/dist/host/outcome.d.ts +54 -1
- package/dist/host/outcome.js +33 -8
- package/dist/host/types.d.ts +10 -2
- package/dist/isolation/served.d.ts +1 -1
- package/dist/isolation/served.js +35 -0
- package/dist/isolation/types.d.ts +20 -2
- package/dist/isolation/types.js +2 -0
- package/dist/platform/types.d.ts +22 -0
- package/dist/platform/web.js +55 -12
- package/dist/react/view.d.ts +13 -0
- package/dist/react/view.js +101 -2
- package/dist/server/files.d.ts +11 -0
- package/dist/server/files.js +26 -4
- package/dist/server/host.js +106 -28
- package/dist/server/index.d.ts +2 -1
- package/dist/server/index.js +6 -1
- package/dist/server/pages.d.ts +32 -0
- package/dist/server/pages.js +82 -6
- package/dist/server/server.js +140 -11
- package/dist/server/types.d.ts +15 -1
- package/dist/transport/post-message.d.ts +1 -9
- package/dist/transport/post-message.js +2 -8
- package/docs/ADOPTING.md +57 -4
- package/docs/DECISIONS.md +198 -0
- package/docs/DESIGN.md +24 -18
- package/docs/THREAT_MODEL.md +79 -13
- package/package.json +1 -1
- package/src/check/page.ts +6 -1
- package/src/compile/policy.ts +7 -0
- package/src/conformance/entry.ts +129 -24
- package/src/conformance/harness/page.ts +112 -49
- package/src/conformance/host-kit.ts +53 -16
- package/src/conformance/served.ts +175 -0
- package/src/files/paths.ts +11 -2
- package/src/host/client.ts +59 -22
- package/src/host/create-host.ts +144 -18
- package/src/host/door.ts +97 -0
- package/src/host/locate.ts +2 -0
- package/src/host/locator.ts +208 -57
- package/src/host/outcome.ts +41 -9
- package/src/host/types.ts +10 -2
- package/src/isolation/served.ts +40 -1
- package/src/isolation/types.ts +19 -2
- package/src/platform/types.ts +21 -0
- package/src/platform/web.ts +55 -20
- package/src/react/view.tsx +149 -2
- package/src/server/files.ts +37 -5
- package/src/server/host.ts +131 -46
- package/src/server/index.ts +6 -1
- package/src/server/pages.ts +101 -6
- package/src/server/server.ts +186 -19
- package/src/server/types.ts +16 -1
- package/src/transport/post-message.ts +1 -9
package/docs/DECISIONS.md
CHANGED
|
@@ -6771,6 +6771,204 @@ 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.
|
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:
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
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
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
| `
|
|
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]` | — | — |
|
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.6 (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).
|
|
174
|
-
|
|
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
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
the
|
|
652
|
-
|
|
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.
|
|
3
|
+
"version": "0.14.6",
|
|
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
|
-
|
|
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;
|
package/src/compile/policy.ts
CHANGED
|
@@ -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,
|