@botiverse/porthole 0.5.0 → 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 (90) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.d.ts +12 -4
  3. package/dist/bridge/bridge.js +62 -27
  4. package/dist/bridge/navigation.d.ts +6 -0
  5. package/dist/bridge/navigation.js +41 -0
  6. package/dist/bridge/refusal.d.ts +53 -0
  7. package/dist/bridge/refusal.js +121 -0
  8. package/dist/bridge/types.d.ts +7 -0
  9. package/dist/check/check.d.ts +12 -3
  10. package/dist/check/check.js +54 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/lint.js +27 -10
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/page.js +5 -0
  16. package/dist/check/tools.d.ts +23 -0
  17. package/dist/check/tools.js +25 -0
  18. package/dist/compile/policy.d.ts +15 -0
  19. package/dist/compile/policy.js +32 -0
  20. package/dist/config/capabilities.d.ts +5 -0
  21. package/dist/config/schema.d.ts +8 -0
  22. package/dist/config/validate.js +8 -1
  23. package/dist/conformance/harness-source.js +1 -1
  24. package/dist/files/paths.d.ts +99 -0
  25. package/dist/files/paths.js +263 -0
  26. package/dist/files/types.d.ts +24 -0
  27. package/dist/files/types.js +83 -0
  28. package/dist/guide/guide.js +25 -5
  29. package/dist/host/create-host.js +36 -4
  30. package/dist/host/types.d.ts +15 -2
  31. package/dist/index.d.ts +7 -3
  32. package/dist/index.js +10 -3
  33. package/dist/mcp/adapter.js +22 -7
  34. package/dist/protocol/adapter.d.ts +4 -0
  35. package/dist/protocol/mcp-apps.d.ts +12 -0
  36. package/dist/protocol/mcp-apps.js +12 -0
  37. package/dist/protocol/shell-adapter.js +18 -2
  38. package/dist/react/frame.d.ts +19 -4
  39. package/dist/react/frame.js +37 -9
  40. package/dist/server/files.d.ts +44 -0
  41. package/dist/server/files.js +244 -0
  42. package/dist/server/host.d.ts +38 -1
  43. package/dist/server/host.js +37 -2
  44. package/dist/server/index.d.ts +4 -2
  45. package/dist/server/index.js +4 -1
  46. package/dist/server/keys.d.ts +8 -0
  47. package/dist/server/keys.js +34 -0
  48. package/dist/server/server.js +287 -22
  49. package/dist/server/types.d.ts +49 -5
  50. package/dist/shell/document.d.ts +19 -0
  51. package/dist/shell/document.js +30 -0
  52. package/dist/shell/runtime.d.ts +2 -1
  53. package/dist/shell/runtime.js +117 -10
  54. package/docs/ADOPTING.md +95 -13
  55. package/docs/ARCHITECTURE.md +13 -3
  56. package/docs/DECISIONS.md +396 -4
  57. package/docs/DESIGN.md +43 -10
  58. package/package.json +1 -1
  59. package/src/bridge/bridge.ts +74 -23
  60. package/src/bridge/navigation.ts +46 -0
  61. package/src/bridge/refusal.ts +151 -0
  62. package/src/bridge/types.ts +12 -1
  63. package/src/check/check.ts +92 -14
  64. package/src/check/files.ts +384 -0
  65. package/src/check/lint.ts +29 -10
  66. package/src/check/page.ts +7 -0
  67. package/src/check/tools.ts +50 -0
  68. package/src/compile/policy.ts +38 -0
  69. package/src/config/capabilities.ts +5 -1
  70. package/src/config/schema.ts +8 -0
  71. package/src/config/validate.ts +8 -1
  72. package/src/files/paths.ts +323 -0
  73. package/src/files/types.ts +101 -0
  74. package/src/guide/guide.ts +38 -4
  75. package/src/host/create-host.ts +37 -4
  76. package/src/host/types.ts +13 -2
  77. package/src/index.ts +41 -0
  78. package/src/mcp/adapter.ts +26 -6
  79. package/src/protocol/adapter.ts +3 -1
  80. package/src/protocol/mcp-apps.ts +14 -0
  81. package/src/protocol/shell-adapter.ts +20 -2
  82. package/src/react/frame.tsx +53 -14
  83. package/src/server/files.ts +312 -0
  84. package/src/server/host.ts +72 -3
  85. package/src/server/index.ts +19 -0
  86. package/src/server/keys.ts +53 -0
  87. package/src/server/server.ts +353 -24
  88. package/src/server/types.ts +56 -4
  89. package/src/shell/document.ts +53 -0
  90. package/src/shell/runtime.ts +117 -10
@@ -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 : "";
@@ -85,7 +93,34 @@ export const SHELL_RUNTIME = String.raw `(() => {
85
93
  // own getters, kept now, so content can neither stop it nor lie to it. Same-document ones (an
86
94
  // anchor) go on, and so do reloads: the same address, on the frame's own origin (or none, in a
87
95
  // srcdoc frame), which history can change only within that origin. The host's own (a new
88
- // frame) are none of this document's.
96
+ // frame) are none of this document's. Each one stopped is told to the host (P080), as an error
97
+ // report: below, once the shell can speak.
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
+ };
89
124
  const navigationApi = window.navigation;
90
125
  const getterOf = (proto, name) => {
91
126
  const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
@@ -94,13 +129,22 @@ export const SHELL_RUNTIME = String.raw `(() => {
94
129
  const navigateProto = typeof NavigateEvent === "function" ? NavigateEvent.prototype : null;
95
130
  const destinationOf = getterOf(navigateProto, "destination");
96
131
  const navigationTypeOf = getterOf(navigateProto, "navigationType");
97
- const sameDocumentOf = getterOf(typeof NavigationDestination === "function" ? NavigationDestination.prototype : null, "sameDocument");
132
+ const destinationProto = typeof NavigationDestination === "function" ? NavigationDestination.prototype : null;
133
+ const sameDocumentOf = getterOf(destinationProto, "sameDocument");
134
+ const urlOf = getterOf(destinationProto, "url");
98
135
  const preventNavigation = Event.prototype.preventDefault;
99
136
  const applyOf = Reflect.apply;
100
137
  if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
101
138
  navigationApi.addEventListener("navigate", (event) => {
102
- if (!applyOf(sameDocumentOf, applyOf(destinationOf, event, []), []) && applyOf(navigationTypeOf, event, []) !== "reload") {
139
+ const destination = applyOf(destinationOf, event, []);
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
+ }
103
146
  applyOf(preventNavigation, event, []);
147
+ navigationBlocked(url);
104
148
  }
105
149
  }, true);
106
150
  }
@@ -473,15 +517,62 @@ export const SHELL_RUNTIME = String.raw `(() => {
473
517
  return;
474
518
  }
475
519
  reported += 1;
476
- 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) } });
477
521
  };
478
- const send = (message) => {
479
- if (plan.protocol === "shell" && window.parent !== window) {
480
- // Nothing secret is ever said from here, so any parent may hear it; what it hears is the
481
- // content's word, which the host gates before it acts on it.
522
+ // Nothing secret is ever said from here, so any parent may hear it; what it hears is the
523
+ // content's word, which the host gates before it acts on it.
524
+ const post = (message) => {
525
+ if (window.parent !== window) {
482
526
  window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
483
527
  }
484
528
  };
529
+ const send = (message) => {
530
+ if (plan.protocol === "shell") {
531
+ post(message);
532
+ }
533
+ };
534
+ // A navigation the guard above stopped (P080): one of the run's error reports, told even where
535
+ // the content speaks for itself (an MCP Apps view), in Porthole's own notification.
536
+ navigationBlocked = (url) => {
537
+ if (!declared("reportError") || reported >= plan.maxErrorReports || url === "") {
538
+ return;
539
+ }
540
+ reported += 1;
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) } });
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
+ }
485
576
 
486
577
  // A parsed tree's scripts are held (each replaced by a numbered marker) and run later, in order,
487
578
  // as the page's parser would run them: each made again, live, in its marker's place, and each
@@ -903,6 +994,16 @@ export const SHELL_RUNTIME = String.raw `(() => {
903
994
  try {
904
995
  url = new URL(href, document.baseURI).href;
905
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
+ }
906
1007
  if (/^https?:/i.test(url) && typeof window.openLink === "function") {
907
1008
  window.openLink(url).catch(() => {});
908
1009
  }
@@ -1020,7 +1121,13 @@ export const SHELL_RUNTIME = String.raw `(() => {
1020
1121
  if (waiting !== undefined) {
1021
1122
  pending.delete(data.id);
1022
1123
  if (data.error) {
1023
- waiting.reject(new Error(String(data.error.message || "refused")));
1124
+ // A refusal says why (P080): its code, and a sentence to show the person.
1125
+ const why = data.error.data !== null && typeof data.error.data === "object" ? data.error.data : {};
1126
+ const error = new Error(String(typeof why.message === "string" && why.message !== "" ? why.message : data.error.message || "refused"));
1127
+ if (typeof why.code === "string") {
1128
+ error.code = why.code;
1129
+ }
1130
+ waiting.reject(error);
1024
1131
  } else {
1025
1132
  waiting.resolve(data.result);
1026
1133
  }
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,12 +89,12 @@ 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
 
96
96
  ```js
97
- import { defineDisplays } from "@botiverse/porthole";
97
+ import { defineDisplays, Refused } from "@botiverse/porthole";
98
98
 
99
99
  export const displays = defineDisplays({
100
100
  // No egress option exists for it; served, it loads Porthole's Chart.js and D3 from its origin.
@@ -104,10 +104,14 @@ export const displays = defineDisplays({
104
104
  createHost(displays.configFor(instance, contentSource), {
105
105
  locator,
106
106
  handlers: {
107
- // As the viewer: your own access rules, never the author's. Return MCP's read result.
108
- readData: async ({ uri }, { displayId }) => ({
109
- contents: [{ uri, mimeType: "application/json", text: JSON.stringify(await load(uri)) }],
110
- }),
107
+ // As the viewer: your own access rules, never the author's. Return MCP's read result; refuse
108
+ // what you don't serve with a Refused, whose code and sentence the widget shows (P080).
109
+ readData: async ({ uri }, { displayId }) => {
110
+ if (!servedUri(uri)) throw new Refused("not_allowed", "This widget can read issues only.");
111
+ return {
112
+ contents: [{ uri, mimeType: "application/json", text: JSON.stringify(await load(uri)) }],
113
+ };
114
+ },
111
115
  // Call changed() when it changes (the content reads it again), or changed(result) to send it.
112
116
  subscribeData: ({ uri }, { changed, signal }) => {
113
117
  const stop = realtime.on(uri, () => changed());
@@ -125,12 +129,37 @@ createHost(displays.configFor(instance, contentSource), {
125
129
  - **Your handlers decide what a URI may name.** Answer only the resources you mean widgets to read
126
130
  (a whitelist of URI shapes), with the viewer's rights. The content's URI is its word.
127
131
  - **Consent is your UI.** Without a `consent` function every data call is refused (fail closed).
128
- React: `PortholeProvider` and `PortholeFrame` take `consent` and `cached`.
132
+ React: `PortholeProvider` and `PortholeFrame` take `consent` and `cached`. A consent function
133
+ that throws a `Refused` gives that answer, kept like `false`; anything else it throws is no
134
+ answer yet (the next call asks again).
135
+ - **A page where data must not run** (beside a frame that reaches the network, below): pass a
136
+ `Refused` as `consent` and no data handlers. Every data call is refused with it, nothing is asked,
137
+ and the widget shows your sentence:
138
+
139
+ ```js
140
+ createHost(displays.configFor(instance, contentSource), {
141
+ locator,
142
+ consent: new Refused("not_allowed", "Live data shows on the dashboard."),
143
+ });
144
+ ```
145
+
146
+ Any other capability you declare still needs its handler.
147
+ - **Refusals tell the widget why** (P080). A refused call's JSON-RPC error carries
148
+ `data: { code, message }`; the shell's `readData` rejects (and `subscribeData`'s `onError` is
149
+ called) with an `Error` whose `code` and `message` are those. `code` is `consent_required` (no
150
+ answer yet), `denied` (the viewer said no), `rate_limited`, `not_allowed` (not here, or not this
151
+ URI) or `failed` (your handler threw); `message` is your `Refused`'s sentence, else Porthole's.
152
+ The manual tells the agent to draw the widget without the data, with that sentence. A handler's
153
+ other errors are `failed` in Porthole's words: their messages stay yours.
129
154
  - **Rates stay gates**: 120 reads and 60 subscriptions a minute per display by default; change them
130
155
  with the capability's `gates` (keep `"consent"` in the list).
131
156
  - **Your page's CSP**: send `displays.embedderCsp(source, …)` (`frame-src` of your content origins
132
157
  and the authorize route, nothing else). It keeps a frame from navigating to an outside site; the
133
- shell keeps a served frame from navigating to another content origin (P079).
158
+ shell keeps a served frame from navigating to another content origin (P079), and tells you:
159
+ `display.on("navigationBlocked", ({ url }) => …)` (React `onNavigationBlocked`) gets the address
160
+ whole, and `contentError` a sentence naming it without its query, for the agent (P080). Only
161
+ where the config declares `reportError`, and only served frames: an opaque frame's navigations
162
+ get no events (you hear `navigated` when one replaces its document).
134
163
  - **Keep live widgets off pages with frames that reach the network.** A frame can `postMessage` any
135
164
  frame on its page, and nothing in it can stop that: a url-mode app (a dev server's preview) or an
136
165
  `anyHttps` display beside a live widget could be handed what it read. Displays with closed egress
@@ -243,6 +272,58 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
243
272
  - **Health:** `health: { probe: nodeProbe(), onServedChange: (served) => … }` checks the content
244
273
  domain over the real network and falls back to opaque frames while it doesn't answer.
245
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
+
246
327
  ### The page
247
328
 
248
329
  ```js
@@ -400,8 +481,9 @@ in the config also has the manual name them). The descriptions are the manual's
400
481
  warnings with the result. `refuseOn: "never"` only warns.
401
482
  - **`guideChanges(from, to)`** is the notice for the agent when a kind flips between served and
402
483
  opaque (null when its manual reads the same).
403
- - **`errors: "agent"`** sends what content throws (and what the sandbox blocks) back to the agent
404
- once people see it: listen for `contentError` and pass it on.
484
+ - **`errors: "agent"`** sends what content throws (and what the sandbox blocks, and a navigation
485
+ the shell stopped, P080) back to the agent once people see it: listen for `contentError` and pass
486
+ it on.
405
487
 
406
488
  ### Checking a page before people see it
407
489
 
@@ -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