@botiverse/porthole 0.5.1 → 0.6.0
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/README.md +25 -0
- package/dist/bridge/bridge.js +8 -5
- package/dist/bridge/navigation.d.ts +1 -6
- package/dist/bridge/navigation.js +11 -0
- package/dist/check/check.d.ts +12 -3
- package/dist/check/check.js +54 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/lint.js +27 -10
- package/dist/check/page-source.js +1 -1
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +25 -0
- package/dist/compile/policy.d.ts +15 -0
- package/dist/compile/policy.js +32 -0
- package/dist/config/schema.d.ts +8 -0
- package/dist/config/validate.js +8 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -0
- package/dist/guide/guide.js +11 -1
- package/dist/host/create-host.js +21 -0
- package/dist/index.d.ts +6 -3
- package/dist/index.js +8 -3
- package/dist/protocol/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/shell-adapter.js +5 -1
- package/dist/server/files.d.ts +44 -0
- package/dist/server/files.js +244 -0
- package/dist/server/host.d.ts +38 -1
- package/dist/server/host.js +37 -2
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +4 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -0
- package/dist/server/server.js +287 -22
- package/dist/server/types.d.ts +49 -5
- package/dist/shell/document.d.ts +19 -0
- package/dist/shell/document.js +30 -0
- package/dist/shell/runtime.d.ts +2 -1
- package/dist/shell/runtime.js +85 -4
- package/docs/ADOPTING.md +56 -4
- package/docs/ARCHITECTURE.md +13 -3
- package/docs/DECISIONS.md +304 -4
- package/docs/DESIGN.md +31 -3
- package/package.json +1 -1
- package/src/bridge/bridge.ts +8 -5
- package/src/bridge/navigation.ts +12 -0
- package/src/check/check.ts +92 -14
- package/src/check/files.ts +384 -0
- package/src/check/lint.ts +29 -10
- package/src/check/tools.ts +50 -0
- package/src/compile/policy.ts +38 -0
- package/src/config/schema.ts +8 -0
- package/src/config/validate.ts +8 -1
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/guide.ts +20 -0
- package/src/host/create-host.ts +21 -0
- package/src/index.ts +32 -0
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/shell-adapter.ts +5 -0
- package/src/server/files.ts +312 -0
- package/src/server/host.ts +72 -3
- package/src/server/index.ts +19 -0
- package/src/server/keys.ts +53 -0
- package/src/server/server.ts +353 -24
- package/src/server/types.ts +56 -4
- package/src/shell/document.ts +53 -0
- package/src/shell/runtime.ts +85 -4
package/dist/shell/runtime.js
CHANGED
|
@@ -20,7 +20,8 @@
|
|
|
20
20
|
* 6. cancels every navigation the frame starts to another document (P079), before it sends a
|
|
21
21
|
* request: a navigation carries data out in its URL, and the embedding page's `frame-src`,
|
|
22
22
|
* the wall for that, must let served frames reach their own content origins. (Opaque frames
|
|
23
|
-
* get no navigate events: there `frame-src` is the wall.)
|
|
23
|
+
* get no navigate events: there `frame-src` is the wall.) A page that comes with files may
|
|
24
|
+
* open its set's other pages, under its version's own address, and nothing else (P084).
|
|
24
25
|
* A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
|
|
25
26
|
* imported, and its scripts run in order, as a fragment's are.
|
|
26
27
|
*
|
|
@@ -35,6 +36,13 @@
|
|
|
35
36
|
export const SHELL_RUNTIME = String.raw `(() => {
|
|
36
37
|
"use strict";
|
|
37
38
|
const plan = __PLAN__;
|
|
39
|
+
// A page that came with files, answered at its ticket's address (P083): its own address first,
|
|
40
|
+
// before anything loads, so its relative addresses are its files' (and the ticket leaves).
|
|
41
|
+
if (plan.files && typeof plan.files.address === "string" && location.href !== plan.files.address) {
|
|
42
|
+
try {
|
|
43
|
+
history.replaceState(null, "", plan.files.address);
|
|
44
|
+
} catch (_) {}
|
|
45
|
+
}
|
|
38
46
|
// The embedding page's nonce, where it gave one (a srcdoc frame inherits its policy): every
|
|
39
47
|
// script the shell runs for the content carries it.
|
|
40
48
|
const nonce = document.currentScript && document.currentScript.nonce ? document.currentScript.nonce : "";
|
|
@@ -88,6 +96,31 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
88
96
|
// frame) are none of this document's. Each one stopped is told to the host (P080), as an error
|
|
89
97
|
// report: below, once the shell can speak.
|
|
90
98
|
let navigationBlocked = (_url) => {};
|
|
99
|
+
// A page that comes with files (P084): another page of its own set, under the version's own
|
|
100
|
+
// address, is a page of the same content and opens in the frame (the host is told first, so it
|
|
101
|
+
// takes the next load for that page, not for content that left). Anything else stays stopped:
|
|
102
|
+
// another path of the origin, a file that isn't a page, another origin.
|
|
103
|
+
let navigating = (_url) => {};
|
|
104
|
+
let filesBase = plan.files && typeof plan.files.base === "string" ? plan.files.base : null;
|
|
105
|
+
// Every address the page's files had (P083: a sealed one is renewed): what reports say as "./".
|
|
106
|
+
const filesBases = filesBase === null ? [] : [filesBase];
|
|
107
|
+
// A frame's sealed files' address is its access: nothing the shell reports names it (P083).
|
|
108
|
+
const SEALED = /(?:https?:\/\/[^\s"'<>\/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//g;
|
|
109
|
+
const ownAddresses = (text) => {
|
|
110
|
+
let out = String(text);
|
|
111
|
+
for (const base of filesBases) {
|
|
112
|
+
out = out.split(base).join("./");
|
|
113
|
+
}
|
|
114
|
+
return out.replace(SEALED, "./");
|
|
115
|
+
};
|
|
116
|
+
const ownPage = (url) => {
|
|
117
|
+
if (filesBase === null || typeof url !== "string" || url.indexOf(filesBase) !== 0) {
|
|
118
|
+
return false;
|
|
119
|
+
}
|
|
120
|
+
const path = url.slice(filesBase.length).split("#")[0].split("?")[0];
|
|
121
|
+
const last = path.slice(path.lastIndexOf("/") + 1);
|
|
122
|
+
return last === "" || last.indexOf(".") < 0 || /\.html?$/i.test(last);
|
|
123
|
+
};
|
|
91
124
|
const navigationApi = window.navigation;
|
|
92
125
|
const getterOf = (proto, name) => {
|
|
93
126
|
const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
|
|
@@ -105,8 +138,13 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
105
138
|
navigationApi.addEventListener("navigate", (event) => {
|
|
106
139
|
const destination = applyOf(destinationOf, event, []);
|
|
107
140
|
if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
|
|
141
|
+
const url = urlOf === null ? "" : String(applyOf(urlOf, destination, []));
|
|
142
|
+
if (ownPage(url)) {
|
|
143
|
+
navigating(url);
|
|
144
|
+
return;
|
|
145
|
+
}
|
|
108
146
|
applyOf(preventNavigation, event, []);
|
|
109
|
-
navigationBlocked(
|
|
147
|
+
navigationBlocked(url);
|
|
110
148
|
}
|
|
111
149
|
}, true);
|
|
112
150
|
}
|
|
@@ -479,7 +517,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
479
517
|
return;
|
|
480
518
|
}
|
|
481
519
|
reported += 1;
|
|
482
|
-
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data:
|
|
520
|
+
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: ownAddresses(message).slice(0, 2000) } });
|
|
483
521
|
};
|
|
484
522
|
// Nothing secret is ever said from here, so any parent may hear it; what it hears is the
|
|
485
523
|
// content's word, which the host gates before it acts on it.
|
|
@@ -500,8 +538,41 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
500
538
|
return;
|
|
501
539
|
}
|
|
502
540
|
reported += 1;
|
|
503
|
-
post({ method: "porthole/navigation-blocked", params: { url: url.slice(0, 4096) } });
|
|
541
|
+
post({ method: "porthole/navigation-blocked", params: { url: ownAddresses(url).slice(0, 4096) } });
|
|
542
|
+
};
|
|
543
|
+
// Another page of the set opening in the frame (P084): the host takes the next load for it.
|
|
544
|
+
navigating = (url) => {
|
|
545
|
+
post({ method: "porthole/navigating", params: { url: ownAddresses(url).slice(0, 4096) } });
|
|
504
546
|
};
|
|
547
|
+
// A sealed files' address opens the page's files on its own for a while (P083): renewed before
|
|
548
|
+
// it ends, the page moved to the new one in place (the same page, the same history entry). Its
|
|
549
|
+
// modules keep the address they loaded from; the server serves their own loads till the session
|
|
550
|
+
// ends.
|
|
551
|
+
if (filesBase !== null && typeof plan.files.expires === "number") {
|
|
552
|
+
const nativeFetch = window.fetch.bind(window);
|
|
553
|
+
const replace = History.prototype.replaceState;
|
|
554
|
+
const renewIn = (expires) => Math.max(30000, expires - Date.now() - 300000);
|
|
555
|
+
const renew = () => {
|
|
556
|
+
nativeFetch(filesBase + "__porthole/renew", { credentials: "omit", cache: "no-store" })
|
|
557
|
+
.then((answer) => (answer.ok ? answer.json() : null))
|
|
558
|
+
.then((renewed) => {
|
|
559
|
+
if (!renewed || typeof renewed.base !== "string" || typeof renewed.expires !== "number" || renewed.base.indexOf(location.origin + "/__porthole/f/") !== 0 || renewed.base.slice(-1) !== "/") {
|
|
560
|
+
return;
|
|
561
|
+
}
|
|
562
|
+
const here = location.href;
|
|
563
|
+
if (here.indexOf(filesBase) === 0) {
|
|
564
|
+
try {
|
|
565
|
+
applyOf(replace, history, [history.state, "", renewed.base + here.slice(filesBase.length)]);
|
|
566
|
+
} catch (_) {}
|
|
567
|
+
}
|
|
568
|
+
filesBase = renewed.base;
|
|
569
|
+
filesBases.push(renewed.base);
|
|
570
|
+
setTimeout(renew, renewIn(renewed.expires));
|
|
571
|
+
})
|
|
572
|
+
.catch(() => setTimeout(renew, 60000));
|
|
573
|
+
};
|
|
574
|
+
setTimeout(renew, renewIn(plan.files.expires));
|
|
575
|
+
}
|
|
505
576
|
|
|
506
577
|
// A parsed tree's scripts are held (each replaced by a numbered marker) and run later, in order,
|
|
507
578
|
// as the page's parser would run them: each made again, live, in its marker's place, and each
|
|
@@ -923,6 +994,16 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
923
994
|
try {
|
|
924
995
|
url = new URL(href, document.baseURI).href;
|
|
925
996
|
} catch (_) {}
|
|
997
|
+
// A page of the set opens in the frame, whatever its target (P084); any other file of the
|
|
998
|
+
// set never opens: its address carries the frame's access.
|
|
999
|
+
if (ownPage(url)) {
|
|
1000
|
+
location.assign(url);
|
|
1001
|
+
return;
|
|
1002
|
+
}
|
|
1003
|
+
if (filesBase !== null && url.indexOf(filesBase) === 0) {
|
|
1004
|
+
navigationBlocked(url);
|
|
1005
|
+
return;
|
|
1006
|
+
}
|
|
926
1007
|
if (/^https?:/i.test(url) && typeof window.openLink === "function") {
|
|
927
1008
|
window.openLink(url).catch(() => {});
|
|
928
1009
|
}
|
package/docs/ADOPTING.md
CHANGED
|
@@ -50,10 +50,10 @@ data (fetch, WebSocket). Every preset starts closed, and a kind opens more only
|
|
|
50
50
|
|
|
51
51
|
| Level | Config (`options`) | What it opens | The risk it re-opens | Typical host | The agent's manual says | Why | Tested by |
|
|
52
52
|
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
53
|
-
| **Closed** (the default) | nothing to write | Nothing from outside the frame: content runs on what it carries (inline code, `data:` and `blob:` URLs). | None. | Widgets that draw their own SVG and CSS; any host that hasn't decided yet. | `Network: none. Nothing loads from outside` (and `write everything inline`) | [P006](DECISIONS.md#p006--2026-10-11--egress-is-closed-by-default-including-channels-a-frame-csp-doesnt-cover--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted) | probes `1.connect`, `2.resources`, `3.webrtc`, `4.*` (nested frames), `5.*` (navigating out), `8.*` (resource hints), `10.self`; served `served.domain.egress` |
|
|
54
|
-
| **Library CDNs** (`LIBRARY_CDNS`, plus script hosts of your own) | `egress: LIBRARY_CDNS`; more script hosts: `egress: { ...LIBRARY_CDNS, script: [...LIBRARY_CDNS.script, "https://cdn.example.com"] }` | Scripts, styles, fonts, images and data from cdnjs, jsDelivr, unpkg and esm.sh; Google Fonts; scripts only from three libraries' own CDNs (Tailwind's Play CDN, jQuery, Plotly). Nothing else. | Code you don't control runs in the frame (a compromised or look-alike package), still inside the sandbox and egress; and a path requested from a CDN is a narrow channel out, read by the CDN's operator. The manual tells agents to pin versions. | Ferry's widgets, Raft Artifacts' pages: agents load Chart.js, ECharts, d3, Mermaid, Tailwind, jQuery, Plotly. | `scripts, styles, fonts, images and data (fetch, WebSocket) from https://cdnjs.cloudflare.com` …, `scripts from https://cdn.tailwindcss.com, https://code.jquery.com, https://cdn.plot.ly` and `pin an exact version` | [P078](DECISIONS.md#p078--2026-10-13--library_cdns-adds-tailwinds-jquerys-and-plotlys-own-cdns-for-scripts-only--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted), [P048](DECISIONS.md#p048--2026-10-11--artifact-pages-reach-library-cdns-only-by-the-hosts-config--accepted) | `leak/cdn.spec.ts` (a CDN library loads only when the config opens it, opaque and served; another origin never; the libraries' own CDNs serve scripts and nothing else); probes `1.connect`, `2.resources` (an allowed origin loads, no other does) |
|
|
53
|
+
| **Closed** (the default) | nothing to write | Nothing from outside the frame: content runs on what it carries (inline code, `data:` and `blob:` URLs). | None. | Widgets that draw their own SVG and CSS; any host that hasn't decided yet. | `Network: none. Nothing loads from outside` (and `write everything inline`) | [P006](DECISIONS.md#p006--2026-10-11--egress-is-closed-by-default-including-channels-a-frame-csp-doesnt-cover--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082) | probes `1.connect`, `2.resources`, `3.webrtc`, `4.*` (nested frames), `5.*` (navigating out), `8.*` (resource hints), `10.self`; served `served.domain.egress` |
|
|
54
|
+
| **Library CDNs** (`LIBRARY_CDNS`, plus script hosts of your own) | `egress: LIBRARY_CDNS`; more script hosts: `egress: { ...LIBRARY_CDNS, script: [...LIBRARY_CDNS.script, "https://cdn.example.com"] }` | Scripts, styles, fonts, images and data from cdnjs, jsDelivr, unpkg and esm.sh; Google Fonts; scripts only from three libraries' own CDNs (Tailwind's Play CDN, jQuery, Plotly). Nothing else. | Code you don't control runs in the frame (a compromised or look-alike package), still inside the sandbox and egress; and a path requested from a CDN is a narrow channel out, read by the CDN's operator. The manual tells agents to pin versions. | Ferry's widgets, Raft Artifacts' pages: agents load Chart.js, ECharts, d3, Mermaid, Tailwind, jQuery, Plotly. | `scripts, styles, fonts, images and data (fetch, WebSocket) from https://cdnjs.cloudflare.com` …, `scripts from https://cdn.tailwindcss.com, https://code.jquery.com, https://cdn.plot.ly` and `pin an exact version` | [P078](DECISIONS.md#p078--2026-10-13--library_cdns-adds-tailwinds-jquerys-and-plotlys-own-cdns-for-scripts-only--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082), [P048](DECISIONS.md#p048--2026-10-11--artifact-pages-reach-library-cdns-only-by-the-hosts-config--accepted) | `leak/cdn.spec.ts` (a CDN library loads only when the config opens it, opaque and served; another origin never; the libraries' own CDNs serve scripts and nothing else); probes `1.connect`, `2.resources` (an allowed origin loads, no other does) |
|
|
55
55
|
| **Passive from any https site** (`anyHttps`, on top of either) | `egress: { ...LIBRARY_CDNS, anyHttps: ["img"] }`; closed but for them: `egress: { anyHttps: ["img"] }` | The passive kinds you name (`img`, `media`, `font`) from any https site. Never scripts, styles, data, workers or frames, and never `http:`: a config naming another kind is refused. | Any site an image names learns that someone viewed the content, and from which address; content can send data out in an image URL to a server of its choosing (the channel P006 closes); whoever owns an image controls what it shows, inside the frame. | A host showing content that already exists, with hotlinked media: Raft's HTML attachment previews, reports whose `<img>` point at other sites (the case P059 was written for). | `images from any https site` (`fonts, images, audio and video from any https site` for all three) | [P059](DECISIONS.md#p059--2026-10-11--passive-content-may-load-from-any-https-site-by-the-hosts-explicit-choice--accepted), [P062](DECISIONS.md#p062--2026-10-11--serveddomainegress-holds-a-host-to-its-own-configs-egress--accepted) | `leak/cdn.spec.ts` (a hotlinked image loads; a script, a stylesheet and a fetch to the same site never reach it; without the flag, nothing does); served `served.domain.egress` (the image must reach an https canary; scripts, styles, fetches and frames never), `leak/served/any-https.spec.ts` |
|
|
56
|
-
| **Porthole's libraries** (`egress.libraries`, served kinds only; on in `presets.liveWidget`) | `egress: { libraries: true }` with `isolation: "domain"` | Chart.js 4.5.1 and D3 7.9.0 as scripts, from the frame's own origin (`/__porthole/lib/…`, served by `/server` on every content origin). Nothing from outside. | None from outside: the requests reach your content server, which serves fixed, pinned files. | Live widgets, which read your data and must have no network of their own (P079). | `Libraries, served from this frame's own address` with a `<script>` line for each | [P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted) | `test/libraries.test.ts`; `leak/served/live.spec.ts` (they load and draw; an external script, a stylesheet, an image and every fetch reach no oracle) |
|
|
56
|
+
| **Porthole's libraries** (`egress.libraries`, served kinds only; on in `presets.liveWidget`) | `egress: { libraries: true }` with `isolation: "domain"` | Chart.js 4.5.1 and D3 7.9.0 as scripts, from the frame's own origin (`/__porthole/lib/…`, served by `/server` on every content origin). Nothing from outside. | None from outside: the requests reach your content server, which serves fixed, pinned files. | Live widgets, which read your data and must have no network of their own (P079). | `Libraries, served from this frame's own address` with a `<script>` line for each | [P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084) | `test/libraries.test.ts`; `leak/served/live.spec.ts` (they load and draw; an external script, a stylesheet, an image and every fetch reach no oracle) |
|
|
57
57
|
|
|
58
58
|
How to decide: **start closed; add `LIBRARY_CDNS` if agents use libraries; add passive `anyHttps`
|
|
59
59
|
only for existing content with hotlinks**, and only the kinds it hotlinks (usually `img`). An
|
|
@@ -89,7 +89,7 @@ export const displays = defineDisplays({
|
|
|
89
89
|
### Live widgets: content that reads your data
|
|
90
90
|
|
|
91
91
|
A live widget shows your data, current, read as the person viewing it, with no network of its own
|
|
92
|
-
([P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted)).
|
|
92
|
+
([P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084)).
|
|
93
93
|
Its only way out is your host: `readData` (MCP `resources/read`) and `subscribeData` (MCP
|
|
94
94
|
`resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`).
|
|
95
95
|
|
|
@@ -272,6 +272,58 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
|
|
|
272
272
|
- **Health:** `health: { probe: nodeProbe(), onServedChange: (served) => … }` checks the content
|
|
273
273
|
domain over the real network and falls back to opaque frames while it doesn't answer.
|
|
274
274
|
|
|
275
|
+
### Pages made of many files
|
|
276
|
+
|
|
277
|
+
A stored version may be a set of files (a build's output, a report with its images; P081). The
|
|
278
|
+
store answers a manifest and the bytes by path; `{ html }` stays one page:
|
|
279
|
+
|
|
280
|
+
```js
|
|
281
|
+
import { checkFileSet, fileLimits, versionBase, versionedAddress } from "@botiverse/porthole/server";
|
|
282
|
+
|
|
283
|
+
// When a version is published: every path canonical, within your page kind's limits.
|
|
284
|
+
const problems = checkFileSet(manifest, { limits: fileLimits(pageConfig.limits) }); // [] to take it
|
|
285
|
+
|
|
286
|
+
source: async (id, version) => {
|
|
287
|
+
const stored = await myStore.version(id, version); // { files: { path: { size, sha256 } }, entry? }
|
|
288
|
+
return stored.html !== undefined
|
|
289
|
+
? { html: stored.html }
|
|
290
|
+
: { files: stored.files, entry: stored.entry, spa: stored.spa, read: (path) => myStore.bytes(stored.files[path].sha256) };
|
|
291
|
+
},
|
|
292
|
+
entry: {
|
|
293
|
+
// "/" and "/<file>" are the latest, "/v/<n>/<file>" version n: answer the version's own address.
|
|
294
|
+
at: async (scope, path) => {
|
|
295
|
+
const at = versionedAddress(path);
|
|
296
|
+
const version = at === null ? null : (at.version ?? (await latestOf(scope)));
|
|
297
|
+
return version === null ? null : { instance: pageOf(scope, version), base: versionBase(version), file: at.file, pinned: true };
|
|
298
|
+
},
|
|
299
|
+
pathOf: (instance) => versionBase(instance.document.version),
|
|
300
|
+
},
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
- **Each file is served from the manifest only**, typed by its extension (Porthole's table, never
|
|
304
|
+
the type it was published with), `nosniff`, with a CSP that opens the version's own path and
|
|
305
|
+
nothing else of the origin (P082). Files are immutable at a version's address; pages revalidate
|
|
306
|
+
(the host's check runs on every load). `read` returns the whole file (`Uint8Array` or a
|
|
307
|
+
stream); Porthole cuts ranges.
|
|
308
|
+
- **A page never mixes versions.** The latest's address (`/`, `/style.css`) goes to the version's
|
|
309
|
+
own (`/v/3/`, `/v/3/style.css`) before the page loads anything, so a version published while it
|
|
310
|
+
loads never reaches it. Answer `entry.at` with the version's `base`, and `pinned: true` when that
|
|
311
|
+
base names one version only (its files are then immutable); a plain instance is served at a
|
|
312
|
+
frame's address instead. A base's segments are letters, digits and `. _ : ~ -`.
|
|
313
|
+
- **An artifact's versions share an origin**, so they are one trust domain (P082): give versions
|
|
314
|
+
that must stay apart scopes of their own.
|
|
315
|
+
- **Each version is a directory of its origin** (`/v/<n>/`). Keep `/_blob/` (`ASSET_LIBRARY_PATH`)
|
|
316
|
+
free: it is reserved for an asset library across versions (not built yet); `versionedAddress`
|
|
317
|
+
names nothing there.
|
|
318
|
+
- **In a frame**, the files' address carries the frame's access (WebKit keeps no cookie there,
|
|
319
|
+
P083): the frame's URL is `/__porthole/f/<sealed>/`, good for the session. A host's
|
|
320
|
+
`issue` and its locator don't change.
|
|
321
|
+
- **Every page of the set is in the shell**, and a set's pages open each other in the frame (P084).
|
|
322
|
+
Service workers never register.
|
|
323
|
+
- **The agent's side:** `lintFiles` and `admitFiles` before you take a version, `checkPage({ files
|
|
324
|
+
})` to run it, and the manual's Files section where a kind serves files. Show a set served: an
|
|
325
|
+
opaque frame has no origin to serve its files from.
|
|
326
|
+
|
|
275
327
|
### The page
|
|
276
328
|
|
|
277
329
|
```js
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -84,7 +84,10 @@ Pure mechanism, no product policy, no host or vendor types.
|
|
|
84
84
|
comes from the theme variables, never from a component vocabulary (P015).
|
|
85
85
|
- **Serving.** For served modes, a request handler a host's backend mounts: it
|
|
86
86
|
serves documents on their own origins with their CSP in headers, and turns a
|
|
87
|
-
one-time ticket the host minted into a cookie of that origin only.
|
|
87
|
+
one-time ticket the host minted into a cookie of that origin only. A stored
|
|
88
|
+
version may be one page or a set of files: each file is looked up in the
|
|
89
|
+
version's manifest only, typed by Porthole's own table, and served under that
|
|
90
|
+
version's own address, so a page's relative addresses are its version's.
|
|
88
91
|
|
|
89
92
|
### Preset policy layer
|
|
90
93
|
|
|
@@ -179,6 +182,10 @@ transparent to the view and the host.
|
|
|
179
182
|
The content is served as a real document at a URL on a separate registrable
|
|
180
183
|
domain with its CSP in HTTP headers; the host embeds that URL in a frame whose
|
|
181
184
|
`frame-ancestors` names the host. No code injection, and the shell is optional.
|
|
185
|
+
A page may come with files of its own (stylesheets, scripts, data, images, other
|
|
186
|
+
pages): they are served beside it, under its version's own address, and its CSP
|
|
187
|
+
opens that path and nothing else of its origin; every page of the set gets the
|
|
188
|
+
shell.
|
|
182
189
|
Access is gated by a one-time ticket exchanged for a scoped cookie. Where the host
|
|
183
190
|
holds the page and needs no stable origin, the shell writes it into an opaque
|
|
184
191
|
frame instead.
|
|
@@ -208,7 +215,9 @@ only the declared content origins.
|
|
|
208
215
|
says so.
|
|
209
216
|
|
|
210
217
|
2. **Content ↔ the outside network.** Closed by default and opened only to the
|
|
211
|
-
origins the config's capabilities declare
|
|
218
|
+
origins the config's capabilities declare (and, for a served page with files,
|
|
219
|
+
its own version's path on its own origin: the host's own server, P082). Two
|
|
220
|
+
kinds of attacker matter:
|
|
212
221
|
- *Attacking the host* (steal credentials, read other data, escape the
|
|
213
222
|
sandbox): stopped by origin isolation — the content is a stranger to the
|
|
214
223
|
host origin.
|
|
@@ -259,7 +268,8 @@ only the declared content origins.
|
|
|
259
268
|
- **Served content.** A host plugs its own policy and infrastructure into `/server`:
|
|
260
269
|
who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
|
|
261
270
|
how origins are named (`content.name`, other servers' `reserved` namespaces),
|
|
262
|
-
and where apps and artifact versions come from (`upstream`, `artifacts
|
|
271
|
+
and where apps and artifact versions come from (`upstream`, `artifacts`: a page, or a
|
|
272
|
+
manifest of files and their bytes), and which address means which version (`entry.at`). It runs
|
|
263
273
|
on any runtime with web-standard `Request`/`Response` (Node, Workers).
|
|
264
274
|
|
|
265
275
|
## How a new protocol or platform plugs in
|
package/docs/DECISIONS.md
CHANGED
|
@@ -353,7 +353,7 @@ wall.
|
|
|
353
353
|
**Revisit when** a gate needs to depend on the call's arguments (then the host's
|
|
354
354
|
`confirm` decides, as it does for tool calls today).
|
|
355
355
|
|
|
356
|
-
## P022 · 2026-10-11 · Every preset starts with egress closed; library CDNs are a one-line opt-in · Accepted
|
|
356
|
+
## P022 · 2026-10-11 · Every preset starts with egress closed; library CDNs are a one-line opt-in · Accepted; amended by P082
|
|
357
357
|
|
|
358
358
|
**Decision.** Every preset's base egress is empty: nothing loads from outside and
|
|
359
359
|
every fetch fails. `LIBRARY_CDNS` (cdnjs, jsDelivr, unpkg, esm.sh for scripts,
|
|
@@ -397,7 +397,7 @@ agreement test keeps the shell and the manual on the same name.
|
|
|
397
397
|
**Revisit when** MCP Apps standardizes error reporting or theme-change events for
|
|
398
398
|
views.
|
|
399
399
|
|
|
400
|
-
## P025 · 2026-10-11 · A served document comes with its ticket's answer; the cookie serves what follows · Accepted
|
|
400
|
+
## P025 · 2026-10-11 · A served document comes with its ticket's answer; the cookie serves what follows · Accepted; amended by P083
|
|
401
401
|
|
|
402
402
|
**Decision.** Refines P016's ticket flow. `/server` names each storage scope's origin
|
|
403
403
|
`<label>.<content domain>` (24 base32 characters of an HMAC of the scope, keyed from the
|
|
@@ -568,7 +568,7 @@ Chromium measured no preconnect from a frame here, but harden for the weakest en
|
|
|
568
568
|
**Revisit when** WebKit applies the CSP to preconnect (then the observer suffices), or a
|
|
569
569
|
DOM insertion API is added (wrap it, and add its probe).
|
|
570
570
|
|
|
571
|
-
## P031 · 2026-10-11 · A display whose content navigates its frame is started again, at most three times · Accepted
|
|
571
|
+
## P031 · 2026-10-11 · A display whose content navigates its frame is started again, at most three times · Accepted; amended by P084
|
|
572
572
|
|
|
573
573
|
**Decision.** The web platform counts its frame's loads; any after the first means the
|
|
574
574
|
content navigated the frame. The display is started again from its content (an event
|
|
@@ -2213,7 +2213,7 @@ refused, and reported as a problem, on every engine (`leak/check.spec.ts`).
|
|
|
2213
2213
|
loads (its follow-up) proposes more hosts, such as mirrors reachable from mainland China.
|
|
2214
2214
|
|
|
2215
2215
|
|
|
2216
|
-
## P079 · 2026-10-15 · Live widgets: no network of their own, Porthole's libraries on their origin, the host's data behind the viewer's consent, and frames that never navigate away · Accepted
|
|
2216
|
+
## P079 · 2026-10-15 · Live widgets: no network of their own, Porthole's libraries on their origin, the host's data behind the viewer's consent, and frames that never navigate away · Accepted; amended by P084
|
|
2217
2217
|
|
|
2218
2218
|
**Decision.** Content that shows its host's data, current, read as the person viewing it (a
|
|
2219
2219
|
dashboard tile, a kept widget) gets a preset of its own and the mechanisms it needs. 0.5.0.
|
|
@@ -2433,3 +2433,303 @@ told why, nothing started again on re-render); `leak/check.spec.ts` (a served wi
|
|
|
2433
2433
|
navigates is told so, without the query). On Chromium, WebKit and Firefox.
|
|
2434
2434
|
**Revisit when** MCP or MCP Apps standardizes error data for refused requests (follow it), or a
|
|
2435
2435
|
host needs the navigation without `reportError`.
|
|
2436
|
+
|
|
2437
|
+
## P081 · 2026-10-18 · A version may be many files: the store's contract, addresses that pin a version, and how each file is served · Accepted
|
|
2438
|
+
|
|
2439
|
+
Task #124: an artifact is what an agent made, as it made it, and that is often a directory (a
|
|
2440
|
+
build's output, a report with its images, a dashboard that reads its data). 0.6.0, additive: a
|
|
2441
|
+
0.5 host's store, `{ html }`, is served as before.
|
|
2442
|
+
|
|
2443
|
+
**Decision.**
|
|
2444
|
+
- **The store.** `ArtifactStore.get(id, version)` answers `{ html }` (one page, as in 0.5) or a
|
|
2445
|
+
`StoredFiles`: `files` (`path → { size, sha256, type? }`), `entry` (default `index.html`), `spa`
|
|
2446
|
+
(default false) and `read(path)` (a `Uint8Array` or a `ReadableStream`, whole; Porthole cuts the
|
|
2447
|
+
range a request asks for). The type a file was published with is the host's to keep (a file list),
|
|
2448
|
+
never served.
|
|
2449
|
+
- **Paths, when a version is published** (`filePathProblem`, `checkFileSet`, a host calls them):
|
|
2450
|
+
relative, `/`-separated, case-sensitive; no empty, `.` or `..` segment; none of `\ % ? #`, a
|
|
2451
|
+
control character or a format character (`Cc`, `Cf`: a right-to-left override or a zero-width
|
|
2452
|
+
space would make a path read as another); Unicode NFC; no segment that starts or ends with a space; at most 512
|
|
2453
|
+
characters and 255 a segment; not under `__porthole/`; no two paths that differ only in case, no
|
|
2454
|
+
path that is both a file and a directory; the entry one of them.
|
|
2455
|
+
- **Paths, when a file is asked for** (`requestFilePath`, `lookupFile`): the path below the
|
|
2456
|
+
version's base, decoded once; a segment that decodes to a separator, an escape, a control
|
|
2457
|
+
character or a dot segment names nothing (the URL parser has resolved the dot segments it
|
|
2458
|
+
sees). Looked up in the manifest only, never a filesystem: `""` is the entry (an entry in a
|
|
2459
|
+
directory: there); `dir/` is `dir/index.html`; `name` is `name`, else `name.html`, else `name/`
|
|
2460
|
+
(307) when `name/index.html` exists. What finds nothing: for a navigation, the entry when the
|
|
2461
|
+
version is a single-page app (`spa`), else the nearest `404.html` (status 404); else a plain 404.
|
|
2462
|
+
- **Limits**, the config's (`limits.maxFiles`, `maxFileBytes`, `maxVersionBytes`; 1,000, 25 MiB,
|
|
2463
|
+
100 MiB by default): the manual states them, and `checkFileSet` and `lintFiles` hold a version
|
|
2464
|
+
to them. The server serves what the host stored.
|
|
2465
|
+
- **Addresses on a tab** (P068). `entry.at` may answer a `FileAddress`, `{ instance, base, file }`:
|
|
2466
|
+
the version's own address (`/v/3/`) and the file the address asks for below it. The session the
|
|
2467
|
+
entry buys serves every path under `base`, and an address that isn't under it (`/`,
|
|
2468
|
+
`/style.css`: the latest) is redeemed to `base` + `file`. A base is a path ending in `/` whose
|
|
2469
|
+
segments are letters, digits and `. _ : ~ -`, never `.` or `..` (it goes into a CSP header as
|
|
2470
|
+
it is); `file` holds no dot segment, backslash, `?`, `#` or control character, and the address
|
|
2471
|
+
it makes must still be under `base`. `pinned: true` says `base` names that version and no
|
|
2472
|
+
other: only then are its files immutable (`/latest/` isn't pinned; its files revalidate). Where
|
|
2473
|
+
sessions' bases nest, the most specific serves. A request on a clean address with no session for
|
|
2474
|
+
it begins an entry only when a page opens (`Sec-Fetch-Mode: navigate`, a document's destination,
|
|
2475
|
+
or a client that sends no fetch metadata): a subresource gets a plain 401, `no-store`, with no
|
|
2476
|
+
nonce cookie. `versionedAddress(path)` reads the convention both first hosts
|
|
2477
|
+
use (`/v/<n>/<file>` pinned, any other path the latest's; a version is never `.` or `..`), and
|
|
2478
|
+
`versionBase(n)` is `/v/<n>/`. Each version is a directory of its origin, as Claude's content
|
|
2479
|
+
origin does it (`/_f/<version id>/`, measured on claude.ai 2026-10-18). `/_blob/`
|
|
2480
|
+
(`ASSET_LIBRARY_PATH`) is kept free outside every version for an asset library that lives
|
|
2481
|
+
across versions (task #124 phase 4, not built): `versionedAddress` names nothing there; it will
|
|
2482
|
+
need a CSP source and an access of its own, decided then. A file set's page answered as a plain
|
|
2483
|
+
instance is served as a frame's is (P083).
|
|
2484
|
+
- **Answers.** Each file is typed by Porthole's table by its extension (`fileTypeOf`); one it
|
|
2485
|
+
doesn't know is `application/octet-stream` with `content-disposition: attachment`; every answer
|
|
2486
|
+
is `nosniff`. Every answer carries its CSP: a page and a script (a worker's policy is its
|
|
2487
|
+
script's) the page's (P082), any other file `default-src 'none'; sandbox` (an SVG or XML file
|
|
2488
|
+
opened on its own runs nothing). A page is `private, no-cache` with an ETag of the bytes served
|
|
2489
|
+
(so the host's check runs on every navigation, P050); any other file `private,
|
|
2490
|
+
max-age=31536000, immutable` with its `sha256` as a strong ETag; `If-None-Match` gets a 304; one
|
|
2491
|
+
`bytes=` range a 206 (a range past the end a 416; several ranges the whole file). Files (not
|
|
2492
|
+
pages) are `Cross-Origin-Resource-Policy: same-origin`. A service worker's script request
|
|
2493
|
+
(`Service-Worker`, `Sec-Fetch-Dest: serviceworker`) is refused.
|
|
2494
|
+
- **Every page of a set is in the shell**, fetched or opened: its hardening, its host functions,
|
|
2495
|
+
its theme (P029: parsed inert, its scripts replayed, a module's relative `src` resolving from
|
|
2496
|
+
the page's address). Each page still writes its own skeleton (`<!doctype html>`, its head), as
|
|
2497
|
+
on Claude, where only the main page is wrapped in a skeleton at publish time: a skeleton is
|
|
2498
|
+
markup, Porthole's shell is the frame's hardening, which a page can't go without.
|
|
2499
|
+
- **The agent's side.** `lintFiles(config, files)` lints each page as `lintContent` does, holds the
|
|
2500
|
+
set to the path rules and limits, and looks every relative reference up in the set (markup,
|
|
2501
|
+
CSS `url()` and `@import`, module imports, `new URL(…, import.meta.url)`, workers, fetches);
|
|
2502
|
+
`admitFiles` refuses what certainly fails (a path or limit the server won't take, no entry, a
|
|
2503
|
+
page `admitContent` would refuse, a page's reference that starts with `/`) and warns on the
|
|
2504
|
+
rest. Its scans run in linear time whatever the text (each pattern bounded and stopped at its
|
|
2505
|
+
own delimiters, a page's markup read tag by tag, line numbers by a search, at most 2,000
|
|
2506
|
+
references of a kind and 2 MiB of a file looked at), and a set over a limit, or a page over its
|
|
2507
|
+
own, is said so and not read further. `checkPage({ files })` serves the whole set from the
|
|
2508
|
+
check's own server and runs its entry; files are named by their path in its report. The manual's widget topic gets a Files
|
|
2509
|
+
section where a config serves them (`servesFiles`: an artifact with domain isolation).
|
|
2510
|
+
|
|
2511
|
+
**Why.**
|
|
2512
|
+
- Packing a directory into one page costs a third more bytes in base64, the agent's tokens to
|
|
2513
|
+
write it, and a whole re-upload for one changed line. Every static host serves a set of files
|
|
2514
|
+
(Netlify, Cloudflare, Vercel, Firebase, GitHub Pages), and so does Claude's own content origin
|
|
2515
|
+
("fetch() of files published alongside the page works with relative URLs").
|
|
2516
|
+
- The serving rules are theirs (task124-industry-practice.md, items 7–11): Cloudflare's slash
|
|
2517
|
+
policy and 404 rules, a server-side type table with `nosniff` (MDN, Go's `ServeContent`), pinned
|
|
2518
|
+
addresses immutable, an ETag on the hash (web.dev's HTTP cache guide).
|
|
2519
|
+
- A page loaded as the latest must not load a newer version's file published while it loads (the
|
|
2520
|
+
chunk-load errors SPAs hit after a deploy; Vercel's Skew Protection exists for them). The
|
|
2521
|
+
address that pins it must be the page's own, not the browser's: a cookie is shared by every tab
|
|
2522
|
+
and replaced when the next version is entered, so the redeem goes to the version's own address
|
|
2523
|
+
before the page loads anything.
|
|
2524
|
+
- Every page in the shell: a page opened without it would run without its in-frame defenses (a
|
|
2525
|
+
nested frame's fresh realm, WebRTC where `webrtc 'block'` isn't honored), and without its host.
|
|
2526
|
+
- `same-origin` resource policy: without the public suffix list (P047, P066) sibling content
|
|
2527
|
+
origins are one site, so on a tab another artifact's page could embed this one's script with the
|
|
2528
|
+
viewer's `Lax` cookie; nothing but the version's own pages needs to load its files (the app
|
|
2529
|
+
frames the page, never a file).
|
|
2530
|
+
|
|
2531
|
+
**Rejected.**
|
|
2532
|
+
- A `<base>` the shell sets on the latest address (`/`, base `/v/3/`): every `#anchor` link then
|
|
2533
|
+
resolves to `/v/3/#anchor`, another document, and `base-uri 'none'` would have to open.
|
|
2534
|
+
- Serving the latest's files at the latest address by the session (`/style.css` from the version the
|
|
2535
|
+
cookie entered): two tabs, or a newer version entered while a page loads, mix versions.
|
|
2536
|
+
- `Cross-Origin-Resource-Policy: cross-origin` for media (task #124's plan): it would let any page
|
|
2537
|
+
embed a version's media, siblings with the viewer's cookie; nothing needs it.
|
|
2538
|
+
- Only the entry in the shell, the other pages as they are (Claude's way): a page the frame opens
|
|
2539
|
+
would run without the frame guard (a nested frame's fresh realm, P006), WebRTC's removal (where
|
|
2540
|
+
`webrtc 'block'` isn't honored), the navigate guard (P079), `document.write`'s and declarative
|
|
2541
|
+
shadow roots' closing (P029) and the clipboard walls (P051), none of which a CSP gives; and
|
|
2542
|
+
without its host functions and theme. Raw HTML to a fetch (`Sec-Fetch-Dest: empty`): a page
|
|
2543
|
+
served without its shell could be replayed as a document (a prefetch cache, a worker's answer).
|
|
2544
|
+
HTML in a set is a page; data that is HTML goes as another type.
|
|
2545
|
+
- `max-age=0` for the latest's files: the latest's address never serves a file, it goes to the
|
|
2546
|
+
version's own.
|
|
2547
|
+
- The uploader's type, or sniffing (a `.txt` holding HTML would run).
|
|
2548
|
+
- Ranges read by the host (`read(path, range)`): one whole-body contract first.
|
|
2549
|
+
- Service workers: one answers its origin's requests with documents it makes, outside the shell
|
|
2550
|
+
and the CSP, and outlives the page.
|
|
2551
|
+
|
|
2552
|
+
**Measured** (Playwright 1.63: Chromium, WebKit, Firefox; `leak/served/files.spec.ts`): a page of
|
|
2553
|
+
many files loads its stylesheet, a classic script, a module and its import, an image, a fetch and
|
|
2554
|
+
a worker (whose own fetch resolves from it) by relative path, framed and on a tab; the committed
|
|
2555
|
+
Vite + React build (`leak/fixtures/vite-react/out`, 143 KB: React 18.3.1, Vite 8.3.4, `base:
|
|
2556
|
+
"./"`) runs as built, its lazy chunk included; a page keeps its own version's data and lazy module
|
|
2557
|
+
when a newer version is published while it runs (framed, and on a tab opened at the latest's
|
|
2558
|
+
address); every spelling of a way out (`..%2f`, `%252e%252e`, `%5c`, `%2f`, a backslash, `%2e%2e`
|
|
2559
|
+
past the base) is a 404 or blocked; an `.html` published as `.txt` is `text/plain`, `nosniff`, and
|
|
2560
|
+
runs nothing opened on its own; another artifact's page loads none of the files (its CSP stops
|
|
2561
|
+
them before any request) and a page elsewhere can't read or run them (no CORS; CORP); no service
|
|
2562
|
+
worker registers. Negative controls (P032): `service-worker` (the harness passes a worker's script
|
|
2563
|
+
request on as a script's) → a service worker registers on a tab on all three engines;
|
|
2564
|
+
`file-corp` (no resource policy) → a page elsewhere runs the set's script on all three.
|
|
2565
|
+
|
|
2566
|
+
**Security review (2026-10-18, of the first cut).** No critical or high finding; the changes above
|
|
2567
|
+
for: format characters in paths, quadratic lint patterns (72 KB of `import a ` took 3.9 s; a
|
|
2568
|
+
megabyte of any adversarial text now takes under 30 ms), a subresource that began an entry (a 302
|
|
2569
|
+
and a nonce cookie for each), and bases (any base was immutable; `; , '` and dot segments passed).
|
|
2570
|
+
The sealed address in reports and its lifetime: P083; a set's pages' notice: P084; versions on a
|
|
2571
|
+
tab: P082.
|
|
2572
|
+
|
|
2573
|
+
**Tested.** `test/files.test.ts` (the path rules, `checkFileSet`, decoding, lookup; the type table;
|
|
2574
|
+
the CSP; framed: the ticket's answer, headers per type, ETag and 304, ranges from bytes and
|
|
2575
|
+
streams, 404s and `404.html`, traversal, service workers, a version's access serves that version,
|
|
2576
|
+
an access is its origin's and ends, the host's check per file, `spa`, a 0.5 page unchanged; on a
|
|
2577
|
+
tab: the latest goes to the version's own, a newer version doesn't reach a page, `versionedAddress`;
|
|
2578
|
+
`lintFiles` and `admitFiles`, the Vite build lints clean; after the review: format characters; the
|
|
2579
|
+
traversal inputs against a decoder that decodes twice (the control: they then reach above the
|
|
2580
|
+
version) and a store that would answer any path (read is asked for manifest paths only); a
|
|
2581
|
+
megabyte of adversarial text linted in under 200 ms, nothing read past a limit; a subresource on a
|
|
2582
|
+
tab refused with no state; immutable only where pinned, the most specific base; bases and files
|
|
2583
|
+
that say something else refused); `test/workers.test.ts` (on workerd:
|
|
2584
|
+
the entry, a streamed file, a range); `test/agreement.test.ts` (the Files section exactly where
|
|
2585
|
+
files are served, with the config's limits); `leak/served/files.spec.ts`; `leak/check.spec.ts`
|
|
2586
|
+
(a set checked whole; a missing script told by its path).
|
|
2587
|
+
**Revisit when** a host stores large media where ranged reads pay (R2: `read(path, range)`),
|
|
2588
|
+
content needs offline (a service worker of Porthole's own making), the conformance runner
|
|
2589
|
+
(`defineHostConformance`) is pointed at an app with file sets (add these cases to it), or the
|
|
2590
|
+
content domain joins the public suffix list (then siblings are other sites, and CORP is defense in
|
|
2591
|
+
depth only).
|
|
2592
|
+
|
|
2593
|
+
## P082 · 2026-10-18 · A served page with files loads its own version's files, by their path; never `'self'` · Accepted
|
|
2594
|
+
|
|
2595
|
+
**Decision.** Amends P022 for served pages with files. Their pages and scripts get the frame's CSP
|
|
2596
|
+
with one source added to `script-src`, `style-src`, `font-src`, `img-src`, `media-src`,
|
|
2597
|
+
`connect-src` and `worker-src` (`fileSetCspDirectives`, `FILE_SET_DIRECTIVES`; `'none'` dropped
|
|
2598
|
+
where it was the only source): the version's own files' path on its origin, `<origin>/v/3/` on a
|
|
2599
|
+
tab (the session's base), `<origin>/__porthole/f/` in a frame (the prefix every sealed path of the
|
|
2600
|
+
scope shares, P083). Nothing else changes: `default-src`, `frame-src`, `object-src`, `base-uri` and
|
|
2601
|
+
`form-action` stay `'none'`, the config's own CSP (`compile(config).csp`) has no such source, and
|
|
2602
|
+
an opaque frame or a page without files keeps P022 whole: never `'self'`.
|
|
2603
|
+
**Threat it re-opens.** Content may now make requests to its own origin, under its version's path:
|
|
2604
|
+
- its requests' paths and queries reach the host's own content server (its logs), which already
|
|
2605
|
+
sees every request the frame makes; nothing reaches another origin;
|
|
2606
|
+
- any file of the version runs as a script or a worker: they are the same author's;
|
|
2607
|
+
- in a frame, a page could load another live sealed path of its scope, if it knew one: it knows
|
|
2608
|
+
only its own, and same-origin frames on one page are one trust domain already (one scope, one
|
|
2609
|
+
storage, each other's DOM through `parent.frames`).
|
|
2610
|
+
Bounded: another version's path, Porthole's own paths (`/__porthole/d/`, `/__porthole/session`)
|
|
2611
|
+
and a url-mode app's stay closed to its loads; the `file-self` control (the harness puts `'self'` where the CSP
|
|
2612
|
+
names the version's path) makes a page on a tab load another version's data and module, and a
|
|
2613
|
+
frame's `%2e%2e` past its base reach the server, on all three engines.
|
|
2614
|
+
**Why.** Relative files are the point of a set, and they live on the page's own origin; the
|
|
2615
|
+
industry's own content origins open it: claudeusercontent.com sends `default-src
|
|
2616
|
+
https://www.claudeusercontent.com` (its own origin, observed), MCP Apps' baseline is `script-src
|
|
2617
|
+
'self'`. Porthole opens less, its version's path: on a tab another version is another path.
|
|
2618
|
+
P022's reason for never `'self'` (an opaque frame's `'self'` may be the embedding page's origin)
|
|
2619
|
+
doesn't hold on an origin of the scope's own, and stays for opaque frames.
|
|
2620
|
+
- Live widgets (P079) are shells, not artifacts: no files, unchanged. Porthole's libraries keep
|
|
2621
|
+
their own source, `<origin>/__porthole/lib/`, under no base. Per-scope labels (P047): the source is
|
|
2622
|
+
the scope's origin, so another scope's files never match.
|
|
2623
|
+
- A CSP ignores a source's path after a redirect: Porthole's redirects under a base stay under it
|
|
2624
|
+
(`dir` → `dir/`), and every other answer on the origin that redirects goes to the app's origin
|
|
2625
|
+
(redirect entry), which no file directive allows.
|
|
2626
|
+
**An artifact's versions are one trust domain** (decided after the review): one origin, one storage,
|
|
2627
|
+
the same writers; a person who may see one version sees its history. The version's path in the CSP
|
|
2628
|
+
keeps a page's loads to its own version, so versions never mix (P081); it is no wall between
|
|
2629
|
+
versions. On a tab (no sandbox there), a page can open another version's address in a window it
|
|
2630
|
+
then scripts (`window.open("/v/1/")`, under that version's CSP) or read the origin's storage another
|
|
2631
|
+
version wrote; a frame can't open windows (no `allow-popups`). Hosts that need versions apart (a
|
|
2632
|
+
version written by someone else, kept from viewers of another) give each its own scope, and so
|
|
2633
|
+
its own origin; Porthole doesn't make popups `noopener`, which would close one path of several.
|
|
2634
|
+
**Rejected.** `'self'` (every version, every Porthole path of the origin); the exact sealed path in
|
|
2635
|
+
a frame's CSP (its length, up to kilobytes with a long scope or subject, in each of seven
|
|
2636
|
+
directives); a wall between versions on one origin (an origin is the browser's unit: storage,
|
|
2637
|
+
windows and workers cross it).
|
|
2638
|
+
**Revisit when** content needs to load other versions' files (a diff view: through the host), or a
|
|
2639
|
+
browser keeps path matching across redirects.
|
|
2640
|
+
|
|
2641
|
+
## P083 · 2026-10-18 · A page with files in a frame carries its access in its files' path, sealed · Accepted
|
|
2642
|
+
|
|
2643
|
+
**Decision.** Amends P025 for served pages with files. The ticket's answer is the version's entry
|
|
2644
|
+
page, in the shell, `no-store`, with no cookie; its plan carries the address of its files,
|
|
2645
|
+
`/__porthole/f/<sealed>/`, and the shell puts it in the frame's history (`history.replaceState`)
|
|
2646
|
+
before anything loads, so the page's relative addresses resolve there and the spent ticket leaves
|
|
2647
|
+
the address. `<sealed>` is the session (the instance, the viewer, the end, the host's subject)
|
|
2648
|
+
sealed with AES-256-GCM (Web Crypto) under a key derived from the server's secret
|
|
2649
|
+
(`porthole/files`), bound to that use; it opens only on the instance's own origin, and the host's
|
|
2650
|
+
check runs on every file (P050). A reload loads the files' address itself.
|
|
2651
|
+
- **Its life is its own** (after the review): an address opens the page's files on its own for an
|
|
2652
|
+
hour at most (its `x`), never past the session's end (its `e`, `sessionSeconds`, up to 30 days).
|
|
2653
|
+
The shell renews it five minutes before then (`<address>__porthole/renew`, which answers only
|
|
2654
|
+
the page itself: same-origin, not a navigation) and moves the page to the new address in place
|
|
2655
|
+
(`history.replaceState`). Past `x` and before `e`, only the running page's own loads
|
|
2656
|
+
(`Sec-Fetch-Site: same-origin`, not a navigation) open: its modules keep the address they loaded
|
|
2657
|
+
from (`import.meta.url`), and their later imports must still load. An address opened on its own
|
|
2658
|
+
(a tab, a history entry, Firefox's "Open Frame in New Tab") ends within the hour.
|
|
2659
|
+
- **Nothing Porthole reports names it** (after the review): the shell says the page's files'
|
|
2660
|
+
address as `./` in every error report, blocked navigation and notice (a stack trace, "Couldn't
|
|
2661
|
+
load", a link to a file that isn't a page), and the host's bridge replaces any sealed address
|
|
2662
|
+
content sends itself (`withoutSealedAddresses`), so neither `contentError` (which a host may give
|
|
2663
|
+
the agent) nor `navigationBlocked` carries it.
|
|
2664
|
+
**Threat it re-opens.** P025 rejected "a token in the document's path (a credential in every URL
|
|
2665
|
+
the content can read and log)". The sealed path is such a credential: whoever has it loads that
|
|
2666
|
+
version's files as that viewer until it ends. Bounded:
|
|
2667
|
+
- it opens one version's files on one origin: not its document path, not `/__porthole/session`,
|
|
2668
|
+
not a url-mode app, not another version;
|
|
2669
|
+
- it is made in the browser's own request, never in the app's API answers or logs (as the
|
|
2670
|
+
ticket's URL is), and every answer sends `Referrer-Policy: no-referrer`;
|
|
2671
|
+
- content that would leak it could send the files' bytes by the same ways; and another page can't
|
|
2672
|
+
embed them with it (`Cross-Origin-Resource-Policy: same-origin`, P081);
|
|
2673
|
+
- the host's check still decides each request, and a revocation ends it (`test/files.test.ts`).
|
|
2674
|
+
**Why.** WebKit keeps no cookie in a cross-site frame (P025, measured): a page whose files needed
|
|
2675
|
+
the cookie would show its entry there and nothing it loads. In the path, every engine loads them.
|
|
2676
|
+
Sealed, not signed: content reads its own address, and a grant's viewer and subject are the host's
|
|
2677
|
+
(never shown to content). In the ticket's own answer rather than behind a redirect: P025's own
|
|
2678
|
+
reason (the document comes with its ticket's answer), one round trip fewer, and Playwright's WebKit
|
|
2679
|
+
can't fulfill a routed redirect ("Cannot fulfill with redirect status: 303", measured with
|
|
2680
|
+
`checkPage`'s driver).
|
|
2681
|
+
**Rejected.** The cookie for files (WebKit); a service worker that adds the access (P025's reasons;
|
|
2682
|
+
and P081 refuses them); a signed token (the viewer and subject readable); a store of sessions (the
|
|
2683
|
+
ticket store takes once, and a new store is a new table for every D1 host); a ticket per file; an
|
|
2684
|
+
hour with no grace for the page's own loads (a single-page app's lazy chunk an hour on would fail).
|
|
2685
|
+
**Residual.** `Sec-Fetch-Site` is a browser's word: someone outside a browser who holds an address
|
|
2686
|
+
(from a log) can claim it, and so load that version's files until the session ends, as before the
|
|
2687
|
+
review; revocation is the host's check (`authorize`).
|
|
2688
|
+
**Cost.** A frame's file addresses are new each session (each seal has a fresh IV), so the browser's
|
|
2689
|
+
cache serves a version's files within a session (its reloads and pages), not across sessions.
|
|
2690
|
+
**Tested** (after the review): `test/files.test.ts` (the address opens on its own for an hour, then
|
|
2691
|
+
only same-origin non-navigation loads until the session's end; renewal only from the page; the
|
|
2692
|
+
host's check and the session's end still hold; sealed addresses taken out of what the host is
|
|
2693
|
+
told); `leak/served/files.spec.ts` (no error report, content error or blocked navigation of a page
|
|
2694
|
+
that throws from a module, fails to load a script, rejects with its own address and is stopped from
|
|
2695
|
+
opening a file names `/__porthole/f/`: each says `./`; the shell renews its address under a clock
|
|
2696
|
+
moved 56 minutes on, and the page goes on loading its files), on Chromium, WebKit and Firefox.
|
|
2697
|
+
**Revisit when** WebKit keeps partitioned cookies in frames (then the cookie, stable addresses and
|
|
2698
|
+
the shared cache), or hosts need a version's files cached across sessions (a seal per day).
|
|
2699
|
+
|
|
2700
|
+
## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted
|
|
2701
|
+
|
|
2702
|
+
**Decision.** Amends P079 (no navigation to another document) and P031 (a navigated frame is
|
|
2703
|
+
started again) for served pages with files. The shell's plan names the version's files' address
|
|
2704
|
+
(`files.base`); its navigate guard lets a navigation go on when its destination is under it and
|
|
2705
|
+
names a page (no extension, `.html`, `.htm`, or a directory), and tells the host first: Porthole's
|
|
2706
|
+
own `porthole/navigating` (`NAVIGATING_METHOD`), which the shell adapter turns into its session's
|
|
2707
|
+
`navigating` event. The host takes the frame's next load as that page: no restart, no `navigated`;
|
|
2708
|
+
the new page's shell says hello again on the same transport. The host takes the notice only from
|
|
2709
|
+
a display whose pages may come with files (`servesFiles`: an artifact with domain isolation), for
|
|
2710
|
+
the next load only, within ten seconds (after the review: any display's content could send it,
|
|
2711
|
+
and the flag lasted, so a load much later skipped P031's restart). A link to such a page opens it in
|
|
2712
|
+
the frame, whatever its target; a link to another file of the set doesn't open, and is reported as
|
|
2713
|
+
a blocked navigation (P080). Every other navigation is stopped, as before.
|
|
2714
|
+
**Threat it re-opens.** A frame that navigates itself carries data out in its URL (P079's reason).
|
|
2715
|
+
Now it may, to its own version's pages, on its own origin: the host's own content server sees the
|
|
2716
|
+
address, as it sees a fetch there (P082). Not to another origin, not to another path of its origin,
|
|
2717
|
+
not to a file that isn't a page (which wouldn't come in the shell). The announcement is the
|
|
2718
|
+
content's word: it only spares a restart, which P031 says is not a wall.
|
|
2719
|
+
**Why.** A set's other pages (Claude's contract names "further HTML pages") are links between
|
|
2720
|
+
pages; a guard that stops them, or a host that starts the display again at its entry on each,
|
|
2721
|
+
breaks every multi-page artifact.
|
|
2722
|
+
**Measured.** Under `navigate-guard` (P079's control), the cases "a link to another page opens it
|
|
2723
|
+
in the frame" (no announcement, so the display starts again) and "a page opens nothing else" (a
|
|
2724
|
+
file that isn't a page, `/`, `/__porthole/d/…` reach the server) fail on Chromium, WebKit and
|
|
2725
|
+
Firefox.
|
|
2726
|
+
**Rejected.** The host opening the page (`openLink`, or a restart at the new address): the frame's
|
|
2727
|
+
history goes, and the sealed address would land in a tab. A new bridge for each page: the host's
|
|
2728
|
+
gates, rates and consent are the display's, across its pages.
|
|
2729
|
+
**Residual.** The host gives annotations (P053) to the display's first page only; live
|
|
2730
|
+
subscriptions a page left keep running until the display ends.
|
|
2731
|
+
**Tested** (after the review): `test/files.test.ts` (the notice spares a restart for a served
|
|
2732
|
+
artifact's display, not one sent eleven seconds before the load, and never for a widget's).
|
|
2733
|
+
**Revisit when** hosts annotate multi-page artifacts (give the marks to each page), or an engine
|
|
2734
|
+
Porthole supports lacks the Navigation API (then `frame-src` is the wall, and a set's pages restart
|
|
2735
|
+
the display).
|