@botiverse/porthole 0.14.16 → 0.14.18
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 +29 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/pages-of-set.d.ts +3 -1
- package/dist/host/pages-of-set.js +17 -3
- package/dist/isolation/served.d.ts +8 -0
- package/dist/isolation/served.js +16 -0
- package/dist/protocol/mcp-apps.d.ts +5 -3
- package/dist/protocol/mcp-apps.js +5 -3
- package/dist/protocol/shell-adapter.js +5 -0
- package/dist/server/host.d.ts +14 -1
- package/dist/server/host.js +8 -3
- package/dist/server/nested.d.ts +5 -4
- package/dist/server/nested.js +8 -6
- package/dist/server/pages.d.ts +16 -2
- package/dist/server/pages.js +51 -16
- package/dist/server/server.js +26 -2
- package/dist/server/types.d.ts +8 -0
- package/dist/shell/frame.d.ts +6 -0
- package/dist/shell/frame.js +16 -3
- package/dist/shell/runtime.js +13 -3
- package/docs/ADOPTING.md +12 -3
- package/docs/DECISIONS.md +210 -4
- package/docs/DESIGN.md +2 -1
- package/docs/THREAT_MODEL.md +21 -4
- package/package.json +1 -1
- package/src/host/pages-of-set.ts +18 -3
- package/src/isolation/served.ts +21 -0
- package/src/protocol/mcp-apps.ts +5 -3
- package/src/protocol/shell-adapter.ts +5 -0
- package/src/server/host.ts +22 -4
- package/src/server/nested.ts +13 -5
- package/src/server/pages.ts +72 -18
- package/src/server/server.ts +32 -1
- package/src/server/types.ts +8 -0
- package/src/shell/frame.ts +22 -3
- package/src/shell/runtime.ts +13 -3
package/dist/shell/runtime.js
CHANGED
|
@@ -318,10 +318,11 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
318
318
|
// A page of a set that a navigation opened (not its ticket's answer) says so as it arrives
|
|
319
319
|
// (P098), below, once the shell can speak: the notice its last page sent as it left can reach
|
|
320
320
|
// the host after this page's load, or never (Chromium forwards a cross-process message from a
|
|
321
|
-
// task of the sending document's, which a navigation that commits first drops).
|
|
322
|
-
|
|
321
|
+
// task of the sending document's, which a navigation that commits first drops). With or without
|
|
322
|
+
// the Navigation API (P142): where there is none, the leaving page sends nothing, and this is the
|
|
323
|
+
// page's only word.
|
|
324
|
+
const arrived = filesBase !== null && typeof plan.files.address !== "string";
|
|
323
325
|
if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
|
|
324
|
-
arrived = filesBase !== null && typeof plan.files.address !== "string";
|
|
325
326
|
navigationApi.addEventListener("navigate", (event) => {
|
|
326
327
|
const destination = applyOf(destinationOf, event, []);
|
|
327
328
|
if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
|
|
@@ -1632,6 +1633,15 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1632
1633
|
if (arrived) {
|
|
1633
1634
|
notice(location.href, { arrived: true });
|
|
1634
1635
|
}
|
|
1636
|
+
// A navigation within the document (a fragment, history between its entries) says the page
|
|
1637
|
+
// stayed (P142): WebKit fires the frame's load for one (measured, 18.2 and 26.6: a link to
|
|
1638
|
+
// #bottom, the first in a document), which the host would otherwise take for content that left.
|
|
1639
|
+
// Listened for now, before any content runs; each is the content's word, as every notice is.
|
|
1640
|
+
if (filesSet !== null && filesBase !== null) {
|
|
1641
|
+
const stayed = () => notice(location.href, { same: true });
|
|
1642
|
+
window.addEventListener("popstate", stayed, true);
|
|
1643
|
+
window.addEventListener("hashchange", stayed, true);
|
|
1644
|
+
}
|
|
1635
1645
|
// A sealed files' address opens the page's files on its own for a while (P083): renewed before
|
|
1636
1646
|
// it ends, the page moved to the new one in place (the same page, the same history entry). Its
|
|
1637
1647
|
// modules keep the address they loaded from; the server serves their own loads till the session
|
package/docs/ADOPTING.md
CHANGED
|
@@ -745,6 +745,15 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
|
|
|
745
745
|
- **`Response.redirect` needs an absolute URL** outside a browser (Node throws on `/login`).
|
|
746
746
|
- **`reserved`** is only for labels your app itself serves on the content domain (previews of a
|
|
747
747
|
dev server, `p-*`). Labels nothing serves need nothing: they are a 404 there.
|
|
748
|
+
- **`framedBy`** (P141): where another app frames yours (a dashboard that embeds your app in an
|
|
749
|
+
iframe), its origins: `framedBy: ["https://dashboard.example.com"]`. `frame-ancestors` names every
|
|
750
|
+
ancestor, so without it each of your frames is blank inside that app. Each may then be an
|
|
751
|
+
ancestor of every frame Porthole serves, after `appOrigins`, and is never a host: no frame hears
|
|
752
|
+
or tells it, it isn't in `data-porthole-hosts`, and redirect entry and the handoff stay
|
|
753
|
+
`appOrigins`' alone. Exact https origins (`http://` on loopback), none an app origin. Your own
|
|
754
|
+
page between them is still the frame's parent, and its `frame-ancestors` is yours to set. A
|
|
755
|
+
content Worker of your own passes the same list to `statusPage`, `doorResponse`,
|
|
756
|
+
`doorStatusResponse` and `nestedShellResponse` (`framedBy`).
|
|
748
757
|
- **No content domain** (self-hosted without one): still make the host, with `domain: null` (or
|
|
749
758
|
`""`). That is the supported setup: no secret is needed, `GET /porthole/meta` answers
|
|
750
759
|
`{ served: false }`, and pages show every kind opaque (a url kind, its fallback) instead of
|
|
@@ -919,7 +928,7 @@ no frame), `nestedShellResponse` throws for another origin, and the shell runs n
|
|
|
919
928
|
|
|
920
929
|
| Request | Answer |
|
|
921
930
|
| --- | --- |
|
|
922
|
-
| `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
|
|
931
|
+
| `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, framedBy, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins> <framedBy>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
|
|
923
932
|
| `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy`: `nestedFileCsp("page", fileSetCspDirectives(compiled.cspDirectives, "<origin>/__porthole/f/"))` then `; frame-ancestors ` and `nestedAncestors("<origin>", "<host origins>")`: the page's directives, its files' prefix opened, and `sandbox allow-scripts` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
|
|
924
933
|
| `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin` (`nestedFileCsp(fileTypeOf(path).role, directives)`, then the `frame-ancestors` above): a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
|
|
925
934
|
| `<origin>/__porthole/f/<token>/__porthole/renew` | Only the shell's own fetch (`Sec-Fetch-Site: same-origin`, not a navigation): `{ "base": "<origin>/__porthole/f/<new token>/", "expires": <epoch ms> }`, `no-store`; anything else 403. The shell renews 5 minutes before `expires` and moves the page to the new base. |
|
|
@@ -1145,8 +1154,8 @@ A **content Worker of your own** (one that answers the content origins itself, i
|
|
|
1145
1154
|
`/server`) serves the door too: `issue` mints the door ticket and returns `door: { url }`, and the
|
|
1146
1155
|
Worker routes `DOOR_PATH + <key>` (`/__porthole/door/<key>`) on every label — take the door ticket
|
|
1147
1156
|
(`TicketRecord.door === true`, bound to the label and key), run the same access, document and entry
|
|
1148
|
-
checks the content route runs for that grant, then answer `doorResponse({ hostOrigins })` (open) or
|
|
1149
|
-
`doorStatusResponse({ status, reason, code?, hostOrigins })` (401 `session` / 403 `denied` / 404
|
|
1157
|
+
checks the content route runs for that grant, then answer `doorResponse({ hostOrigins, framedBy })` (open) or
|
|
1158
|
+
`doorStatusResponse({ status, reason, code?, hostOrigins, framedBy })` (401 `session` / 403 `denied` / 404
|
|
1150
1159
|
`not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d/`, and serve no door on a nested
|
|
1151
1160
|
page's shell label. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
|
|
1152
1161
|
`@botiverse/porthole/server`.
|
package/docs/DECISIONS.md
CHANGED
|
@@ -2703,7 +2703,7 @@ moved 56 minutes on, and the page goes on loading its files), on Chromium, WebKi
|
|
|
2703
2703
|
**Revisit when** WebKit keeps partitioned cookies in frames (then the cookie, stable addresses and
|
|
2704
2704
|
the shared cache), or hosts need a version's files cached across sessions (a seal per day).
|
|
2705
2705
|
|
|
2706
|
-
## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted; amended by P098
|
|
2706
|
+
## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted; amended by P098, P142
|
|
2707
2707
|
|
|
2708
2708
|
**Decision.** Amends P079 (no navigation to another document) and P031 (a navigated frame is
|
|
2709
2709
|
started again) for served pages with files. The shell's plan names the version's files' address
|
|
@@ -2738,7 +2738,7 @@ subscriptions a page left keep running until the display ends.
|
|
|
2738
2738
|
artifact's display, not one sent eleven seconds before the load, and never for a widget's).
|
|
2739
2739
|
**Revisit when** hosts annotate multi-page artifacts (give the marks to each page), or an engine
|
|
2740
2740
|
Porthole supports lacks the Navigation API (then `frame-src` is the wall, and a set's pages restart
|
|
2741
|
-
the display).
|
|
2741
|
+
the display; since P142 they don't: the arriving page's word is sent without the API).
|
|
2742
2742
|
|
|
2743
2743
|
## P085 · 2026-10-18 · The capability runtime: one global, `porthole.use(name)`, under a contract pinned per artifact · Accepted; amended by P091, P139
|
|
2744
2744
|
|
|
@@ -4061,7 +4061,7 @@ origin check stays, for frames on one host page); when an engine stops sending `
|
|
|
4061
4061
|
metadata where this relies on them; or when a previewed app needs a write from another site (an
|
|
4062
4062
|
opt-in per display, with its test).
|
|
4063
4063
|
|
|
4064
|
-
## P098 · 2026-10-19 · A set's page is taken as one when its notice is late or lost; tests that measure, not wait · Accepted
|
|
4064
|
+
## P098 · 2026-10-19 · A set's page is taken as one when its notice is late or lost; tests that measure, not wait · Accepted; amended by P142
|
|
4065
4065
|
|
|
4066
4066
|
The 2026-10-19 audit's flaky tests (baseline 264b12fa), which a release that waits for all of CI
|
|
4067
4067
|
(P097) can no longer shrug off. Amends P084 (the notice) and P025 (how the suite knows which
|
|
@@ -4084,7 +4084,8 @@ browsers keep a framed cookie).
|
|
|
4084
4084
|
the access the page is served for; not secret);
|
|
4085
4085
|
- the shell of a page a navigation opened (a page of files that is not its ticket's answer)
|
|
4086
4086
|
says `porthole/navigating` with `arrived: true` as it starts. Set inside the guard's own
|
|
4087
|
-
block, so `navigate-guard` (the guard taken out) removes it with every other notice
|
|
4087
|
+
block, so `navigate-guard` (the guard taken out) removes it with every other notice (since
|
|
4088
|
+
P142 set outside it, with or without the Navigation API; `navigate-guard` still removes it);
|
|
4088
4089
|
- which loads are the set's own pages is decided by `pagesOfSet` (`host/pages-of-set.ts`) on
|
|
4089
4090
|
the frame's surface, before anything the frame says reaches the display. The leaving page's
|
|
4090
4091
|
notice is taken for the next load within ten seconds, as before; the arriving page's too (the
|
|
@@ -8653,3 +8654,208 @@ it fails at the second pick.
|
|
|
8653
8654
|
|
|
8654
8655
|
**Revisit when** a host needs the pick kept without following it (a host that draws its own
|
|
8655
8656
|
highlight from `selected`), or a host is seen confused by `orphaned` after an upgrade.
|
|
8657
|
+
|
|
8658
|
+
|
|
8659
|
+
## P141 · 2026-11-09 · An app framed by another: its outer page may be an ancestor of its frames, never their host (`framedBy`) · Accepted
|
|
8660
|
+
|
|
8661
|
+
From Raft (task #botiverse-raft-deployment:#245, Tenny): Deck (`https://deck.raft.build`, and
|
|
8662
|
+
`https://deck-aws-dev.raft.build` on staging) frames the Raft app (`app.raft.build`) in an iframe.
|
|
8663
|
+
|
|
8664
|
+
**Context.** `frame-ancestors` is checked against every ancestor, not only the parent: a frame the
|
|
8665
|
+
app shows inside Deck has Deck above the app, and every policy Porthole sends names the host
|
|
8666
|
+
origins alone (`appOrigins`, `hostOrigins`), so each of the app's frames went blank inside Deck.
|
|
8667
|
+
The same list is also who a frame hears and tells: the shell's and the nested shell's message
|
|
8668
|
+
origins, the pages' and doors' `data-porthole-hosts`, the host kit's checks for redirect entry and
|
|
8669
|
+
the handoff. Adding Deck to `appOrigins` would let it frame content *and* speak to it as its host:
|
|
8670
|
+
answer a shell's `ui/initialize`, call host functions on the bridge's word, hear what a frame says
|
|
8671
|
+
to its host. The app frames content; Deck frames the app. Only the first is a host.
|
|
8672
|
+
|
|
8673
|
+
**Decision.**
|
|
8674
|
+
|
|
8675
|
+
1. **`framedBy: readonly string[]`**, on `createServer` and `createContentHost` (and on the helpers
|
|
8676
|
+
a content Worker of its own answers with: `statusPage`, `doorResponse`, `doorStatusResponse`
|
|
8677
|
+
and `nestedShellResponse` take it too), names origins that may be an **ancestor** of every
|
|
8678
|
+
frame Porthole serves, above a host origin's page. Default none: every response is as before,
|
|
8679
|
+
byte for byte.
|
|
8680
|
+
2. **They are in every `frame-ancestors` and nowhere else**: after the host origins, in each
|
|
8681
|
+
policy `/server` sends (a shell, an artifact page, a file set's pages and files and their own
|
|
8682
|
+
frames, a nested page's shell, page and files, the MCP Apps proxy, a door and a door that doesn't
|
|
8683
|
+
open, the status, entry and tab-only pages, assets, a renewal, a url-mode app's answers: one
|
|
8684
|
+
list in `createServer`, `frameAncestors`) and in
|
|
8685
|
+
the host kit's authorize route's pages. Never a message origin of a shell, a nested shell, a
|
|
8686
|
+
door or a page; never in `data-porthole-hosts` or a shell's plan; never a host origin for
|
|
8687
|
+
`entry.authorizeUrl`, the handoff's `Origin` check (still `appOrigins` alone) or the content
|
|
8688
|
+
domain's clash rules, which they are checked against apart.
|
|
8689
|
+
3. **They are checked as host origins are, more narrowly**: exact origins, `https://host[:port]`
|
|
8690
|
+
(`http://` on loopback alone, for development), lowercase, no path, no wildcard, no keyword, never
|
|
8691
|
+
`"null"` or a desktop scheme (an outer page is a web page); none a host origin (one origin is a
|
|
8692
|
+
host or an outer page, never both); none on, or maybe the same site as, the content domain.
|
|
8693
|
+
A bad one throws (`framedBy: …`), as a bad host origin does, before anything goes into a header;
|
|
8694
|
+
the host kit's fallback makes it a lasting `misconfigured`, as it does a bad app origin.
|
|
8695
|
+
4. **The direct parent must still be a host origin, and Porthole holds it so where it can.**
|
|
8696
|
+
`frame-ancestors` can't say "an ancestor but not the parent": with `framedBy`, an outer page
|
|
8697
|
+
that frames content directly is let in by the browser. Such a frame gets no host:
|
|
8698
|
+
- *Heard:* the shell, the nested shell and a door take a message only from a host origin
|
|
8699
|
+
(`event.origin` in its plan's `origins`): the outer page's `ui/initialize` answer is dropped,
|
|
8700
|
+
the handshake ends with no host (`data-porthole-host="none"`, P139), `porthole.use` is null,
|
|
8701
|
+
and the bridge never runs: no host function is called on its word.
|
|
8702
|
+
- *Told:* Porthole's own words go to each web host origin by name, so only a host origin as the
|
|
8703
|
+
parent receives them. The one exception was the `*` fallback where a desktop scheme is a host
|
|
8704
|
+
origin (P070, its item 6), whose premise ("these pages are framable only by the host origins,
|
|
8705
|
+
so their parent is one") `framedBy` breaks. Now, where a page's `frame-ancestors` names anyone
|
|
8706
|
+
beyond its host origins (`data-porthole-strict-parent` on the status, entry and door pages;
|
|
8707
|
+
`strictParent` in a nested shell's plan), `*` goes only to a parent the engine names
|
|
8708
|
+
(`location.ancestorOrigins[0]`, not masked as `"null"`) as one of the host origins: an outer
|
|
8709
|
+
page as the parent, or a parent the engine doesn't name, is never told. Without `framedBy`
|
|
8710
|
+
the rule is P070's, unchanged.
|
|
8711
|
+
|
|
8712
|
+
**What it re-opens (PRINCIPLE 1).** An outer page may now be an ancestor of content, which no
|
|
8713
|
+
origin but the host's could be.
|
|
8714
|
+
- *Clickjacking and framing the app's content from another app*: bounded to the origins the host
|
|
8715
|
+
names, each exact; the host's own page between them stays the host's (its `frame-ancestors` is
|
|
8716
|
+
the app's to set: Raft's in Terraform, not Porthole's).
|
|
8717
|
+
- *An outer page framing content directly*: it needs an address to frame. Tickets come from the
|
|
8718
|
+
host's issue endpoint and are used once; a clean address in a frame is the tab-only page (P125);
|
|
8719
|
+
a sealed address is in the frame's own document. If it has one, the frame loads, but as above it
|
|
8720
|
+
is no host. It hears what content says to its parent with `*` itself: the content shell's own
|
|
8721
|
+
notices (its runtime posts to `*`, P053: the content shares that realm and could post anything
|
|
8722
|
+
itself), annotation and find reports. That is the content's word, which any parent of a frame
|
|
8723
|
+
could always hear, and which the outer page must treat as untrusted; on a nested page the shell
|
|
8724
|
+
passes the page's words to host origins alone, by name, so an outer parent hears none of them.
|
|
8725
|
+
- *Partitioned cookies*: a frame below the outer page is keyed to the top-level site, the outer
|
|
8726
|
+
page's (CHIPS), as any embedding is. Where the outer page is another site than the app, a
|
|
8727
|
+
session made inside it is that partition's alone; where it is the same site (Deck at
|
|
8728
|
+
`deck.raft.build`, the app at `app.raft.build`: both `raft.build`), it is the partition the app's
|
|
8729
|
+
own tab uses too, as for any page of that site. No sharing is added across sites.
|
|
8730
|
+
|
|
8731
|
+
**Rejected.**
|
|
8732
|
+
- *Adding the outer page to `appOrigins`*: it would be a host: heard, told, an origin for entry
|
|
8733
|
+
and the handoff. Exactly what Tenny ruled out.
|
|
8734
|
+
- *A wildcard, or any https origin*: an outer page is one product's, named.
|
|
8735
|
+
- *Refusing an outer page as the parent outright*: no header can, and a shell that refused to draw
|
|
8736
|
+
where `ancestorOrigins[0]` is an outer page would decide nothing on Firefox's masked `"null"`
|
|
8737
|
+
(measured: Firefox masks a `no-referrer` frame's ancestors, Chromium names them), while it is no
|
|
8738
|
+
host already.
|
|
8739
|
+
- *The outer origins in the pages' bodies, for the `*` check*: one boolean (`strict`) says enough
|
|
8740
|
+
(the parent must be named, and a host origin), and keeps them out of everything but the header.
|
|
8741
|
+
|
|
8742
|
+
**Tested.** `test/framed-by.test.ts`: `framedBy` taken (https, loopback http) and refused (a
|
|
8743
|
+
wildcard, a path, uppercase, `*`, `'self'`, a list, a CSP injection, `"null"`, a desktop scheme,
|
|
8744
|
+
plain http, a host origin, the content domain and its site), in `createServer`, the helpers and
|
|
8745
|
+
the host kit; **the bound**: every answer of 23 (a shell and its used ticket, a 404, a door and a
|
|
8746
|
+
used door, an artifact page, the MCP Apps proxy, two file sets' tickets, pages, scripts, files and
|
|
8747
|
+
refused renewals, one of them with its own frames, a nested page's shell, page, script and ended
|
|
8748
|
+
access, a url-mode app's entry page and answer), under host origins with a desktop scheme and one
|
|
8749
|
+
`framedBy`, names it in `frame-ancestors` after the host origins, every
|
|
8750
|
+
framed document has `frame-ancestors`, and none says the outer origin in another header or its body
|
|
8751
|
+
(not in `data-porthole-hosts`, not in a plan's `origins`); without `framedBy` none is strict and
|
|
8752
|
+
none names it; the helpers' defaults are as before; the host kit's content and authorize route's pages name it,
|
|
8753
|
+
and the handoff refuses its `Origin` (403) where the app's own is taken. Assets and the tab-only
|
|
8754
|
+
page take the same one list (`frameAncestors`), untested apart. **The negative controls**: the status script, strict, says `*` only
|
|
8755
|
+
to a parent named as a host origin (desktop: yes; the outer page, `"null"`, unnamed: no), and not
|
|
8756
|
+
strict says it as before; the nested shell's script, given `framedBy`, says no `*` to an outer
|
|
8757
|
+
parent and passes none of its words to the page, while a host's word passes. Taking the strict
|
|
8758
|
+
condition out fails both. `leak/served/framed-by.spec.ts` (Chromium and Firefox here; WebKit not
|
|
8759
|
+
run on this machine): below the outer page, the app's frame shows and is answered by the app; below
|
|
8760
|
+
a foreign page it is refused; the outer page framing content itself sees the frame load and its
|
|
8761
|
+
`ui/initialize` answer refused, the handshake ending `"none"`; a door framed by the app tells it
|
|
8762
|
+
`open`, framed by the outer page says nothing to it (with the strict condition taken out it says
|
|
8763
|
+
`*`, and the probe fails). No weakening in `leak/weakenings.ts`: the probes above are the
|
|
8764
|
+
control, run as mutations.
|
|
8765
|
+
|
|
8766
|
+
**Revisit when** an outer page needs to speak to a frame (then it is a host, and needs
|
|
8767
|
+
`appOrigins`), browsers give a policy for the parent alone, or a host wants an outer page to frame
|
|
8768
|
+
content without its own page between them.
|
|
8769
|
+
|
|
8770
|
+
## P142 · 2026-11-09 · A set's pages without the Navigation API, and a page that stays at a link within it · Accepted
|
|
8771
|
+
|
|
8772
|
+
From Raft (task #proj-workspace:#251, InNOut): on staging, in a multi-page served artifact, WebKit
|
|
8773
|
+
18.2 (Playwright 1.49.1, Safari 18's engine, no Navigation API) started the display again at its
|
|
8774
|
+
entry on every link to another page of the set, and on a link to `#bottom` in the same page. Then
|
|
8775
|
+
on WebKit 26.6 (Playwright 1.63, with the API): pages fine, `#bottom` started it again about 2.5 s
|
|
8776
|
+
after the click. Chromium: both fine. Amends P084 and P098 (its "Revisit when": an engine without
|
|
8777
|
+
the Navigation API).
|
|
8778
|
+
|
|
8779
|
+
**Measured** (the leak harness; WebKit r2104 = 18.2 run with Playwright 1.49.1 and Ubuntu 24.04's
|
|
8780
|
+
libraries, WebKit 26.6, Chromium and Firefox 155 with Playwright 1.63; "without the API" is the
|
|
8781
|
+
frame with `navigation` and every `Navigat*` interface deleted before the shell runs, and WebKit
|
|
8782
|
+
18.2 itself):
|
|
8783
|
+
- *A link to another page, without the API.* The shell said nothing. The leaving page's notice
|
|
8784
|
+
comes from the guard's `navigate` listener (P084), and the arriving page's `arrived: true` was
|
|
8785
|
+
set inside the guard's own block (P098, so `navigate-guard` would take it out). Neither exists
|
|
8786
|
+
without the API. The frame's click handler still opens the page (`location.assign`). The new
|
|
8787
|
+
page's load reached `pagesOfSet` with no notice, and its `ui/initialize` ended the wait at once
|
|
8788
|
+
("a hello before any notice"): started again at once (failed on Chromium without the API and on
|
|
8789
|
+
WebKit 18.2).
|
|
8790
|
+
- *A link to `#bottom`.* Not a navigate event the shell announces: the guard passes a
|
|
8791
|
+
same-document navigation without a word, and the frame's click handler leaves a `#` link to the
|
|
8792
|
+
browser. Not the shell treating `hashchange` as navigation: nothing listened for it. It is a
|
|
8793
|
+
`load`. **WebKit fires the `<iframe>` element's `load` for the first navigation within the
|
|
8794
|
+
frame's document**: a listener on the host page's iframe saw it, no request reached the server,
|
|
8795
|
+
and the document stayed (its globals, its scroll, `location.hash`). On 18.2 the load comes before
|
|
8796
|
+
the frame's `popstate` and `hashchange`; on 26.6 after them. Chromium and Firefox fire none. The
|
|
8797
|
+
web platform takes any load after the first as the content navigating away (P031), and
|
|
8798
|
+
`pagesOfSet` waited `LATE_NOTICE_MS` (2 s) for a notice. None came, so the display started
|
|
8799
|
+
again: the 2.5 s InNOut saw. With the API or without it.
|
|
8800
|
+
|
|
8801
|
+
**Decision.**
|
|
8802
|
+
1. **A set's page that a navigation opened says `arrived: true` as it starts, with or without the
|
|
8803
|
+
Navigation API.** `arrived` is set outside the guard's block, from the plan alone (files, and
|
|
8804
|
+
no ticket's address). Without the API it is the page's only word, and P098 already takes it on
|
|
8805
|
+
either side of the load. No click fallback for the leaving notice: P098 takes the arriving
|
|
8806
|
+
page's word without one, and a click handler would cover links only, not `location`. So
|
|
8807
|
+
`arrived` alone covers it, and the tests show it does. `navigate-guard` (P079's control) also
|
|
8808
|
+
takes `arrived` out, so it still takes out every notice of a set's pages.
|
|
8809
|
+
2. **A navigation within a page's document says the page stayed**: `porthole/navigating
|
|
8810
|
+
{ url, same: true, set }` on each `popstate` and `hashchange` (window listeners the shell adds
|
|
8811
|
+
before content runs), in a set's page (files and their version), with or without the API. It is
|
|
8812
|
+
never a page change. `pagesOfSet` takes it for the load it came after, or for the next one within
|
|
8813
|
+
`LATE_NOTICE_MS` only (not P084's ten seconds: it is no page to come). It never shortens a
|
|
8814
|
+
page's notice already given, and is taken however often the same address comes again. Like
|
|
8815
|
+
`arrived`, it must name the mounted version: another version's, or none, ends a wait at once,
|
|
8816
|
+
started again. The shell adapter forgets nothing for it (the page's watches and subscriptions go
|
|
8817
|
+
on). A display whose pages never come with files is as before: every load after the first starts
|
|
8818
|
+
it again at once.
|
|
8819
|
+
|
|
8820
|
+
**What stays the accepted limit** (P079, P099, unchanged). Without the Navigation API the guard
|
|
8821
|
+
gets no events. A served frame can navigate itself to another content origin (`frame-src` lets it
|
|
8822
|
+
in), and a page on a tab can navigate itself away, or to a `blob:` document of its own. Every
|
|
8823
|
+
other navigation without the API is as before. Another path of its origin, a file that isn't a
|
|
8824
|
+
page, an outside site (`frame-src` stops it): the display starts again (or, on Firefox, an outside
|
|
8825
|
+
site leaves the document as it was). A single-document served artifact (no files, so no version in
|
|
8826
|
+
its notices), and every display that isn't an artifact with files, still starts again at a load
|
|
8827
|
+
after the first. On WebKit that includes the first link within the page. A frame can't tell the host
|
|
8828
|
+
a load is no new document without a version to name, and none of those waits for a notice
|
|
8829
|
+
(P031).
|
|
8830
|
+
|
|
8831
|
+
**Threat (PRINCIPLE 1): nothing loosened.** No CSP, sandbox, guard rule, gate or origin changed;
|
|
8832
|
+
the guard stops what it stopped, where it has events. The host takes a notice as before: only for
|
|
8833
|
+
a display whose pages may come with files, from the frame's window and origin, naming the mounted
|
|
8834
|
+
version, within its window. Both notices are the content's word. Content could always send
|
|
8835
|
+
`porthole/navigating` itself (P084: it only spares a restart, which P031 says is no wall).
|
|
8836
|
+
`arrived` without the API, or `same` from a listener, gives it nothing it lacked. A `same`
|
|
8837
|
+
notice's grant is shorter than the one content could already ask for. The wall against a
|
|
8838
|
+
navigated document running is the embedding page's `frame-src`, as P031 has it.
|
|
8839
|
+
|
|
8840
|
+
**Tested.** `leak/served/files.spec.ts`:
|
|
8841
|
+
- with the API: a link down the entry page and down a page a link opened. The page scrolls, the
|
|
8842
|
+
document stays, the display goes on, the frame announces no page change (only `same`), and the
|
|
8843
|
+
host blocks nothing.
|
|
8844
|
+
- without the API: a link to another page and back (one outcome, nothing blocked), and the link
|
|
8845
|
+
down the page as above.
|
|
8846
|
+
- the negative controls: a file that isn't a page and another path of the origin still start the
|
|
8847
|
+
display again at its entry, and an outside site hears nothing.
|
|
8848
|
+
|
|
8849
|
+
All pass on Chromium, WebKit 26.6 and Firefox 155, and on WebKit 18.2 itself. Before the fix, the
|
|
8850
|
+
page link failed on Chromium without the API and on WebKit 18.2, and the link down the page failed
|
|
8851
|
+
on WebKit 18.2 and 26.6 (started again). `test/pages-of-set.test.ts`: `same` before or after its
|
|
8852
|
+
load; again at the same address; no grant past `LATE_NOTICE_MS`; a page's grant kept; another
|
|
8853
|
+
version, or none, ends the wait; nothing for displays without files. `test/runtime-review.test.ts`:
|
|
8854
|
+
a `same` notice ends no watch (it failed before). Controls: `same-document-notice` (the listeners
|
|
8855
|
+
out) fails both link-down cases on all three engines (the frame says nothing; on WebKit the display
|
|
8856
|
+
starts again too). `navigate-guard` now also fails the page link without the API and both link-down
|
|
8857
|
+
cases, whose second page is opened by a link.
|
|
8858
|
+
|
|
8859
|
+
**Revisit when** an engine stops firing a frame's load for a navigation within its document
|
|
8860
|
+
(the `same` notice then has no load to explain), single-document served artifacts need it (give
|
|
8861
|
+
their notices the version), or hosts need Safari before 26 on a tab (P099's limit stands).
|
package/docs/DESIGN.md
CHANGED
|
@@ -1590,7 +1590,8 @@ control the tables above name to the registry):
|
|
|
1590
1590
|
| `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`, `every attached mark's place in the document comes with the scroll it was read at, offscreen ones too, and the followed mark's as the document scrolls (P132)`, `a selection's and a mark's last line come in the document's coordinates with the scroll, offscreen ones too; rect stays clamped (P133)` | — | — |
|
|
1591
1591
|
| `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` | — |
|
|
1592
1592
|
| `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
|
|
1593
|
-
| `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)` | — | — |
|
|
1593
|
+
| `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)`, `without the Navigation API, a link to another page of the set opens it in the frame; the display goes on`, `a link down the page scrolls it; the document stays, and so does the display`, `without the Navigation API, a link down the page scrolls it; the document stays, and so does the display`, `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)` | — | — |
|
|
1594
|
+
| `same-document-notice` | `served/files.spec.ts` | `a link down the page scrolls it; the document stays, and so does the display`, `without the Navigation API, a link down the page scrolls it; the document stays, and so does the display` | — | — |
|
|
1594
1595
|
| `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` | — | — |
|
|
1595
1596
|
| `window-open` | `served/tab.spec.ts` | nothing | — | the CSP's sandbox stops a window first (`tab-sandbox,window-open`) |
|
|
1596
1597
|
| `tab-sandbox,window-open` | `served/tab.spec.ts` | `served.domain.tab-escapes`, `served.domain.tab-opener`, `a file set's page on a tab of its own opens its own pages, and no window, link in a new window or download`, `a frame's sealed address opened on a tab of its own is sandboxed as its frame is`, `served.domain.tab-window-open` | — | — |
|
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.18 (2026-11-09). 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
|
|
@@ -43,7 +43,14 @@ word 100 ms old or more; no wall moves. 0.14.15: P138 lets the host follow the c
|
|
|
43
43
|
(`selectionTracked`, the same boxes as `tracked`, on its budget, only while asked) and keeps what was
|
|
44
44
|
picked lit; no wall moves. 0.14.16: P139 has a shell on a tab of its own ask no host; P140 narrows P138: a pick stays lit, and a
|
|
45
45
|
selection is kept in the frame, only for a host that follows the selection (`keepSelection`), and a
|
|
46
|
-
host that follows none drops `selectionTracked` unread (§7).
|
|
46
|
+
host that follows none drops `selectionTracked` unread (§7). 0.14.17: P141 lets a host name the
|
|
47
|
+
origins of an outer page that frames its app (`framedBy`): each may be an ancestor of every frame,
|
|
48
|
+
above the host's own page, so it is in every `frame-ancestors`, and nowhere else; it is never a
|
|
49
|
+
host a frame hears or tells, and a page's `*` fallback is held to a parent named as a host origin
|
|
50
|
+
(§6 "What every host must do", S3). 0.14.18: P142 keeps a set's pages and links within a page from
|
|
51
|
+
starting the display again where there is no Navigation API, and where WebKit fires a frame's load
|
|
52
|
+
for a link within its document: the arriving page's notice is sent without the API, and a page
|
|
53
|
+
says it stayed; no wall moves, and the limit without the API is P079's, unchanged.
|
|
47
54
|
|
|
48
55
|
## 1. Two layers
|
|
49
56
|
|
|
@@ -266,7 +273,16 @@ Whatever the use:
|
|
|
266
273
|
`display.focus()` inside a key's own handler moves nothing: call it from a task (measured on a
|
|
267
274
|
nested page). Nothing leaks either way: the keyboard stays out of the page.
|
|
268
275
|
- List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
|
|
269
|
-
and only those are checked against the content
|
|
276
|
+
only those are a frame's host (heard and told), and only those are checked against the content
|
|
277
|
+
domain for a shared site.
|
|
278
|
+
- Where another app frames yours (P141), name its origins in `framedBy`, never in `appOrigins`: it
|
|
279
|
+
may then be an ancestor of your frames, above your own page, and is never their host. Your page
|
|
280
|
+
must still be the frame's parent: an outer page that frames content directly (with an address it
|
|
281
|
+
got from somewhere) is let in by the browser, but the frame takes nothing from it (no handshake,
|
|
282
|
+
no host function), Porthole's own pages and a nested page's shell tell it nothing, and what it
|
|
283
|
+
can hear is the content's own word to its parent (`*`), which it must treat as untrusted. Your
|
|
284
|
+
app page's own `frame-ancestors` is yours to set; Porthole never sends it. Name exact origins of
|
|
285
|
+
that one product, and drop them when it stops framing you.
|
|
270
286
|
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
271
287
|
|
|
272
288
|
### S1. Inline widgets in a conversation
|
|
@@ -419,7 +435,8 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
|
419
435
|
another label's session is never read as this one's, under https or on loopback (P101).
|
|
420
436
|
- Pages, files and status pages carry their CSP in headers and `X-Robots-Tag: noindex`, and
|
|
421
437
|
`frame-ancestors` names the app's origins only (with `nestedFrames: "own"`, P128, a file set's
|
|
422
|
-
files below its base name the page's own origin too, so its pages frame them)
|
|
438
|
+
files below its base name the page's own origin too, so its pages frame them), then the host's
|
|
439
|
+
`framedBy`, if any (P141): ancestors above the app's page, never its host.
|
|
423
440
|
- Files: from the version's manifest only, typed by Porthole's table, `nosniff`; files other than
|
|
424
441
|
pages are `Cross-Origin-Resource-Policy: same-origin`; a file set never registers a service
|
|
425
442
|
worker; a page's CSP opens its own version's path, not its whole origin.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.18",
|
|
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/host/pages-of-set.ts
CHANGED
|
@@ -26,6 +26,8 @@ export interface FileSetRef {
|
|
|
26
26
|
interface Notice {
|
|
27
27
|
readonly url: string;
|
|
28
28
|
readonly arrived: boolean;
|
|
29
|
+
/** The page is where it was: a navigation within its document (P142). */
|
|
30
|
+
readonly same: boolean;
|
|
29
31
|
/** Whether it names the mounted version (`ok`), another (`other`), or none (a shell before P098). */
|
|
30
32
|
readonly set: "ok" | "other" | "none";
|
|
31
33
|
}
|
|
@@ -42,6 +44,7 @@ function noticeOf(raw: unknown, mounted: FileSetRef): Notice | null {
|
|
|
42
44
|
return {
|
|
43
45
|
url: typeof params.url === "string" ? params.url : "",
|
|
44
46
|
arrived: params.arrived === true,
|
|
47
|
+
same: params.same === true,
|
|
45
48
|
set:
|
|
46
49
|
named === undefined
|
|
47
50
|
? "none"
|
|
@@ -62,7 +65,9 @@ const isHello = (raw: unknown): boolean =>
|
|
|
62
65
|
* A notice (`porthole/navigating`, from the frame's window and content origin: the transport
|
|
63
66
|
* takes nothing else) names a page and the version its files are. The leaving page's notice is
|
|
64
67
|
* taken for the next load within `PAGE_OF_SET_MS`; the arriving page's (`arrived`) too, or for the
|
|
65
|
-
* load it came after. A
|
|
68
|
+
* load it came after. A page whose document stayed (`same`, a navigation within it: WebKit fires
|
|
69
|
+
* the frame's load for one, P142) is taken for the load it came after, or for the next one within
|
|
70
|
+
* `LATE_NOTICE_MS` only. A load no notice explained waits `LATE_NOTICE_MS`, holding the frame
|
|
66
71
|
* (`HELD_MOST` messages each way at most; past them, started again): nothing it says reaches the
|
|
67
72
|
* display (no call is answered, no report taken), nothing is sent to it, and once the wait is
|
|
68
73
|
* over without a notice for the
|
|
@@ -137,21 +142,31 @@ export function pagesOfSet(options: {
|
|
|
137
142
|
}
|
|
138
143
|
const notice = noticeOf(message, set);
|
|
139
144
|
if (notice !== null) {
|
|
140
|
-
if (notice.set === "other" || (notice.arrived && notice.set !== "ok")) {
|
|
145
|
+
if (notice.set === "other" || ((notice.arrived || notice.same) && notice.set !== "ok")) {
|
|
141
146
|
// Another version's page, or one that won't say which: never this display's.
|
|
142
147
|
if (waiting > 0) {
|
|
143
148
|
leave();
|
|
144
149
|
}
|
|
145
150
|
return;
|
|
146
151
|
}
|
|
147
|
-
if (waiting === 0 && notice.url === current) {
|
|
152
|
+
if (waiting === 0 && notice.url === current && !notice.same) {
|
|
148
153
|
// A late copy for the page the frame is on (its leaving page's, or its own): no new page.
|
|
154
|
+
// (A document that stayed says so for each navigation within it, the same address again
|
|
155
|
+
// too: each may come with a load.)
|
|
149
156
|
return;
|
|
150
157
|
}
|
|
151
158
|
if (waiting > 0) {
|
|
152
159
|
if (notice.set === "ok") {
|
|
153
160
|
taken(notice.url);
|
|
154
161
|
}
|
|
162
|
+
} else if (notice.same) {
|
|
163
|
+
// A document that stayed is no page to come: its word is for a load at hand (WebKit fires
|
|
164
|
+
// it with the navigation within the document, before or after the frame's word, P142),
|
|
165
|
+
// and never shortens a page's word already given.
|
|
166
|
+
if (grantUntil <= Date.now()) {
|
|
167
|
+
grantUntil = Date.now() + LATE_NOTICE_MS;
|
|
168
|
+
grantFor = notice.url;
|
|
169
|
+
}
|
|
155
170
|
} else {
|
|
156
171
|
// Either page's notice, for the next load within P084's ten seconds: the host hears the
|
|
157
172
|
// frame's load only once its images and modules have loaded, which can be seconds after
|
package/src/isolation/served.ts
CHANGED
|
@@ -78,6 +78,27 @@ export function hostOriginProblem(origin: unknown): string | null {
|
|
|
78
78
|
return `${JSON.stringify(origin)} is not an exact origin (scheme://host[:port], lowercase, no path)`;
|
|
79
79
|
}
|
|
80
80
|
|
|
81
|
+
const LOOPBACK_HOST = (host: string): boolean =>
|
|
82
|
+
host === "localhost" || host.endsWith(".localhost") || host === "127.0.0.1" || host === "[::1]";
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Why `origin` can't be one of a host's `framedBy` (P141): an outer page that may be an
|
|
86
|
+
* ancestor of every frame the host shows, above the host's own page, and never a host origin. An
|
|
87
|
+
* exact web origin, `https://host[:port]` (lowercase, no path, no wildcard), or `http://` on
|
|
88
|
+
* loopback alone (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`) for development: never a
|
|
89
|
+
* desktop scheme, `"null"`, a CSP keyword or a list. Null if it can be.
|
|
90
|
+
*/
|
|
91
|
+
export function framedByProblem(origin: unknown): string | null {
|
|
92
|
+
const parsed = typeof origin === "string" && isHostOrigin(origin) ? parseOrigin(origin) : null;
|
|
93
|
+
if (
|
|
94
|
+
parsed === null ||
|
|
95
|
+
!(parsed.scheme === "https" || (parsed.scheme === "http" && LOOPBACK_HOST(parsed.host)))
|
|
96
|
+
) {
|
|
97
|
+
return `${JSON.stringify(origin)} is not an exact https origin (https://host[:port], lowercase, no path; http only on loopback)`;
|
|
98
|
+
}
|
|
99
|
+
return null;
|
|
100
|
+
}
|
|
101
|
+
|
|
81
102
|
/**
|
|
82
103
|
* Whether two hosts may be the same site. Without the public-suffix list this errs one way only:
|
|
83
104
|
* it says "same site" whenever the hosts are equal or share their last two labels, so a pair it
|
package/src/protocol/mcp-apps.ts
CHANGED
|
@@ -150,9 +150,11 @@ export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
|
|
|
150
150
|
/**
|
|
151
151
|
* Porthole's own notification from the shell (P084): a page that came with files is opening
|
|
152
152
|
* another page of its set, `{ url }`, in the frame; and, as it arrives, the page a navigation
|
|
153
|
-
* opened says so, `{ url, arrived: true }` (P098)
|
|
154
|
-
*
|
|
155
|
-
*
|
|
153
|
+
* opened says so, `{ url, arrived: true }` (P098), with or without the Navigation API (P142); and a
|
|
154
|
+
* navigation within a page's document, `{ url, same: true }` (P142: WebKit fires the frame's load
|
|
155
|
+
* for one). The host takes the frame's next load (or the load it came after, within
|
|
156
|
+
* `LATE_NOTICE_MS`) for that page rather than for content that left (P031). The content's word: it
|
|
157
|
+
* only spares a restart.
|
|
156
158
|
*/
|
|
157
159
|
export const NAVIGATING_METHOD = "porthole/navigating";
|
|
158
160
|
|
|
@@ -301,6 +301,11 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
301
301
|
calls.unwatch(params);
|
|
302
302
|
return;
|
|
303
303
|
case NAVIGATING_METHOD:
|
|
304
|
+
// A navigation within the page's document (P142): the page, its calls and what it
|
|
305
|
+
// follows stay.
|
|
306
|
+
if (params.same === true) {
|
|
307
|
+
return;
|
|
308
|
+
}
|
|
304
309
|
// Another page of the set opens in the frame (P084): its next load is that page, which
|
|
305
310
|
// follows nothing yet.
|
|
306
311
|
forget();
|
package/src/server/host.ts
CHANGED
|
@@ -12,7 +12,7 @@ import {
|
|
|
12
12
|
} from "./domain.ts";
|
|
13
13
|
import { reservedLabels, type Naming } from "./naming.ts";
|
|
14
14
|
import { peerAddress } from "./peer.ts";
|
|
15
|
-
import { appStatusPage, tabOnlyPage } from "./pages.ts";
|
|
15
|
+
import { ancestorsOf, appStatusPage, tabOnlyPage } from "./pages.ts";
|
|
16
16
|
import { createServer } from "./server.ts";
|
|
17
17
|
import type {
|
|
18
18
|
Access,
|
|
@@ -105,8 +105,21 @@ type Awaitable<T> = T | Promise<T>;
|
|
|
105
105
|
export interface ContentHostOptions<V> {
|
|
106
106
|
/** `content.example.com`, `content.localhost:8790`; empty: content off. Or parsed settings. */
|
|
107
107
|
readonly domain: string | null | undefined | ContentDomainInfo;
|
|
108
|
-
/**
|
|
108
|
+
/**
|
|
109
|
+
* The app's own origins: they frame content (`frame-ancestors`), are the only origins its frames
|
|
110
|
+
* hear and tell, and are checked for clashes.
|
|
111
|
+
*/
|
|
109
112
|
readonly appOrigins: readonly string[];
|
|
113
|
+
/**
|
|
114
|
+
* Origins of an outer page that frame the app itself (P141): each may be an ancestor of every frame
|
|
115
|
+
* the app shows, above an app origin's page, so it is in every `frame-ancestors` Porthole sends
|
|
116
|
+
* (content, nested pages, doors, status and entry pages, the authorize route's pages) after
|
|
117
|
+
* `appOrigins`, and nowhere else. Never an origin a frame hears or tells, never an app origin for
|
|
118
|
+
* redirect entry or the handoff; the app's own page must still be the frame's parent. Exact https
|
|
119
|
+
* origins (`http://` on loopback), none an app origin, none the content domain's site. The app's
|
|
120
|
+
* own `frame-ancestors` (its page's, which Porthole doesn't send) is the app's to set.
|
|
121
|
+
*/
|
|
122
|
+
readonly framedBy?: readonly string[];
|
|
110
123
|
/** At least 32 random bytes (or a string of at least 32 bytes). */
|
|
111
124
|
readonly secret: Uint8Array | string;
|
|
112
125
|
readonly tickets?: TicketStore;
|
|
@@ -636,6 +649,8 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
636
649
|
let server: PortholeServer | null = null;
|
|
637
650
|
let view: ContentHealthView = { state: "off" };
|
|
638
651
|
let configs: Readonly<Record<string, PortholeConfig>> = {};
|
|
652
|
+
// Who may frame the authorize route's pages: the app origins, and the outer pages' once checked.
|
|
653
|
+
let appAncestors = options.appOrigins.join(" ");
|
|
639
654
|
|
|
640
655
|
try {
|
|
641
656
|
domain =
|
|
@@ -676,6 +691,7 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
676
691
|
}),
|
|
677
692
|
secret,
|
|
678
693
|
hostOrigins: options.appOrigins,
|
|
694
|
+
...(options.framedBy === undefined ? {} : { framedBy: options.framedBy }),
|
|
679
695
|
configs,
|
|
680
696
|
...(options.source === undefined ? {} : { artifacts: { get: options.source } }),
|
|
681
697
|
...(options.assets === undefined
|
|
@@ -714,6 +730,8 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
714
730
|
},
|
|
715
731
|
}),
|
|
716
732
|
});
|
|
733
|
+
// createServer checked them (P141): only then in a header of the app's.
|
|
734
|
+
appAncestors = ancestorsOf(options.appOrigins, options.framedBy);
|
|
717
735
|
view = gate === undefined ? { state: "healthy" } : { state: "checking" };
|
|
718
736
|
}
|
|
719
737
|
} catch (error) {
|
|
@@ -1308,7 +1326,7 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
1308
1326
|
status,
|
|
1309
1327
|
title,
|
|
1310
1328
|
detail,
|
|
1311
|
-
|
|
1329
|
+
appAncestors,
|
|
1312
1330
|
reason,
|
|
1313
1331
|
options.appOrigins,
|
|
1314
1332
|
link,
|
|
@@ -1337,7 +1355,7 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
1337
1355
|
// sign-in or refusal there, and says nothing to the page that frames it.
|
|
1338
1356
|
const dest = request.headers.get("sec-fetch-dest");
|
|
1339
1357
|
if (dest === "iframe" || dest === "frame") {
|
|
1340
|
-
return tabOnlyPage(
|
|
1358
|
+
return tabOnlyPage(appAncestors, method);
|
|
1341
1359
|
}
|
|
1342
1360
|
const clean = `${domain.originOf(state.label)}${state.path}`;
|
|
1343
1361
|
if (state.expired) {
|