@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.
Files changed (73) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.js +8 -5
  3. package/dist/bridge/navigation.d.ts +1 -6
  4. package/dist/bridge/navigation.js +11 -0
  5. package/dist/check/check.d.ts +12 -3
  6. package/dist/check/check.js +54 -8
  7. package/dist/check/files.d.ts +26 -0
  8. package/dist/check/files.js +307 -0
  9. package/dist/check/lint.js +27 -10
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/tools.d.ts +23 -0
  12. package/dist/check/tools.js +25 -0
  13. package/dist/compile/policy.d.ts +15 -0
  14. package/dist/compile/policy.js +32 -0
  15. package/dist/config/schema.d.ts +8 -0
  16. package/dist/config/validate.js +8 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/files/paths.d.ts +99 -0
  19. package/dist/files/paths.js +263 -0
  20. package/dist/files/types.d.ts +24 -0
  21. package/dist/files/types.js +83 -0
  22. package/dist/guide/guide.js +11 -1
  23. package/dist/host/create-host.js +21 -0
  24. package/dist/index.d.ts +6 -3
  25. package/dist/index.js +8 -3
  26. package/dist/protocol/adapter.d.ts +4 -0
  27. package/dist/protocol/mcp-apps.d.ts +6 -0
  28. package/dist/protocol/mcp-apps.js +6 -0
  29. package/dist/protocol/shell-adapter.js +5 -1
  30. package/dist/server/files.d.ts +44 -0
  31. package/dist/server/files.js +244 -0
  32. package/dist/server/host.d.ts +38 -1
  33. package/dist/server/host.js +37 -2
  34. package/dist/server/index.d.ts +4 -2
  35. package/dist/server/index.js +4 -1
  36. package/dist/server/keys.d.ts +8 -0
  37. package/dist/server/keys.js +34 -0
  38. package/dist/server/server.js +287 -22
  39. package/dist/server/types.d.ts +49 -5
  40. package/dist/shell/document.d.ts +19 -0
  41. package/dist/shell/document.js +30 -0
  42. package/dist/shell/runtime.d.ts +2 -1
  43. package/dist/shell/runtime.js +85 -4
  44. package/docs/ADOPTING.md +56 -4
  45. package/docs/ARCHITECTURE.md +13 -3
  46. package/docs/DECISIONS.md +304 -4
  47. package/docs/DESIGN.md +31 -3
  48. package/package.json +1 -1
  49. package/src/bridge/bridge.ts +8 -5
  50. package/src/bridge/navigation.ts +12 -0
  51. package/src/check/check.ts +92 -14
  52. package/src/check/files.ts +384 -0
  53. package/src/check/lint.ts +29 -10
  54. package/src/check/tools.ts +50 -0
  55. package/src/compile/policy.ts +38 -0
  56. package/src/config/schema.ts +8 -0
  57. package/src/config/validate.ts +8 -1
  58. package/src/files/paths.ts +323 -0
  59. package/src/files/types.ts +101 -0
  60. package/src/guide/guide.ts +20 -0
  61. package/src/host/create-host.ts +21 -0
  62. package/src/index.ts +32 -0
  63. package/src/protocol/adapter.ts +3 -1
  64. package/src/protocol/mcp-apps.ts +7 -0
  65. package/src/protocol/shell-adapter.ts +5 -0
  66. package/src/server/files.ts +312 -0
  67. package/src/server/host.ts +72 -3
  68. package/src/server/index.ts +19 -0
  69. package/src/server/keys.ts +53 -0
  70. package/src/server/server.ts +353 -24
  71. package/src/server/types.ts +56 -4
  72. package/src/shell/document.ts +53 -0
  73. package/src/shell/runtime.ts +85 -4
@@ -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(urlOf === null ? "" : String(applyOf(urlOf, destination, [])));
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: String(message).slice(0, 2000) } });
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
@@ -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. Two kinds of attacker matter:
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`). It runs
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).