@botiverse/porthole 0.4.0 → 0.5.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 +3 -1
  2. package/dist/bridge/bridge.d.ts +16 -2
  3. package/dist/bridge/bridge.js +65 -12
  4. package/dist/bridge/types.d.ts +44 -6
  5. package/dist/check/lint.js +2 -2
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/check/page.js +5 -0
  8. package/dist/compile/policy.d.ts +5 -0
  9. package/dist/compile/policy.js +18 -1
  10. package/dist/config/capabilities.d.ts +25 -2
  11. package/dist/config/capabilities.js +13 -0
  12. package/dist/config/schema.d.ts +7 -0
  13. package/dist/config/validate.js +14 -3
  14. package/dist/conformance/harness/page.js +1 -0
  15. package/dist/conformance/harness-source.js +1 -1
  16. package/dist/displays/displays.d.ts +1 -1
  17. package/dist/guide/guide.js +48 -8
  18. package/dist/host/create-host.js +5 -1
  19. package/dist/host/types.d.ts +12 -1
  20. package/dist/index.d.ts +4 -3
  21. package/dist/index.js +2 -1
  22. package/dist/libraries/files.generated.d.ts +1 -0
  23. package/dist/libraries/files.generated.js +8 -0
  24. package/dist/libraries/libraries.d.ts +36 -0
  25. package/dist/libraries/libraries.js +40 -0
  26. package/dist/mcp/adapter.js +31 -2
  27. package/dist/presets/presets.d.ts +15 -0
  28. package/dist/presets/presets.js +27 -2
  29. package/dist/protocol/live-data.d.ts +27 -0
  30. package/dist/protocol/live-data.js +98 -0
  31. package/dist/protocol/mcp-apps.d.ts +9 -0
  32. package/dist/protocol/mcp-apps.js +11 -0
  33. package/dist/protocol/shell-adapter.js +35 -2
  34. package/dist/react/dialog.js +2 -0
  35. package/dist/react/frame.d.ts +15 -1
  36. package/dist/react/frame.js +35 -1
  37. package/dist/server/libraries.d.ts +7 -0
  38. package/dist/server/libraries.js +27 -0
  39. package/dist/server/server.js +2 -1
  40. package/dist/shell/annotate.js +4 -1
  41. package/dist/shell/runtime.d.ts +5 -1
  42. package/dist/shell/runtime.js +165 -1
  43. package/docs/ADOPTING.md +57 -1
  44. package/docs/DECISIONS.md +129 -0
  45. package/docs/DESIGN.md +19 -6
  46. package/package.json +3 -1
  47. package/src/bridge/bridge.ts +85 -13
  48. package/src/bridge/types.ts +45 -3
  49. package/src/check/lint.ts +2 -1
  50. package/src/check/page.ts +5 -0
  51. package/src/compile/policy.ts +19 -1
  52. package/src/config/capabilities.ts +21 -0
  53. package/src/config/schema.ts +7 -0
  54. package/src/config/validate.ts +21 -3
  55. package/src/conformance/harness/page.ts +1 -0
  56. package/src/displays/displays.ts +1 -1
  57. package/src/guide/guide.ts +57 -7
  58. package/src/host/create-host.ts +5 -1
  59. package/src/host/types.ts +12 -1
  60. package/src/index.ts +13 -0
  61. package/src/libraries/files.generated.ts +8 -0
  62. package/src/libraries/libraries.ts +64 -0
  63. package/src/mcp/adapter.ts +40 -2
  64. package/src/presets/presets.ts +46 -3
  65. package/src/protocol/live-data.ts +138 -0
  66. package/src/protocol/mcp-apps.ts +12 -0
  67. package/src/protocol/shell-adapter.ts +35 -3
  68. package/src/react/dialog.tsx +2 -0
  69. package/src/react/frame.tsx +54 -0
  70. package/src/server/libraries.ts +28 -0
  71. package/src/server/server.ts +2 -1
  72. package/src/shell/annotate.ts +4 -1
  73. package/src/shell/runtime.ts +165 -1
@@ -0,0 +1,27 @@
1
+ import { LIBRARY_FILES } from "../libraries/files.generated.js";
2
+ import { LIBRARY_PATH } from "../libraries/libraries.js";
3
+ /**
4
+ * Porthole's vendored libraries (P079), as every content origin serves them under `LIBRARY_PATH`:
5
+ * fixed files, the same for everyone, so no ticket or cookie is asked for and they may be cached
6
+ * for good (a path's bytes never change). Same-site only: content origins load them, no one else.
7
+ * Null for any other path (the reserved prefix's 404 answers it).
8
+ */
9
+ export function libraryFile(pathname, method) {
10
+ if (!pathname.startsWith(LIBRARY_PATH) || (method !== "GET" && method !== "HEAD")) {
11
+ return null;
12
+ }
13
+ const body = Object.hasOwn(LIBRARY_FILES, pathname) ? LIBRARY_FILES[pathname] : undefined;
14
+ if (body === undefined) {
15
+ return null;
16
+ }
17
+ return new Response(method === "HEAD" ? null : body, {
18
+ headers: {
19
+ "content-type": pathname.endsWith(".js")
20
+ ? "text/javascript; charset=utf-8"
21
+ : "text/plain; charset=utf-8",
22
+ "cache-control": "public, max-age=31536000, immutable",
23
+ "cross-origin-resource-policy": "same-site",
24
+ "x-content-type-options": "nosniff",
25
+ },
26
+ });
27
+ }
@@ -5,6 +5,7 @@ import { base32, createKeys, newTicket, ticketId } from "./keys.js";
5
5
  import { randomBytes } from "./crypto.js";
6
6
  import { isHostLabel, reservedLabels } from "./naming.js";
7
7
  import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
8
+ import { libraryFile } from "./libraries.js";
8
9
  import { memoryTicketStore } from "./tickets.js";
9
10
  /**
10
11
  * Paths on a content origin. Porthole's own live under `/__porthole/`; on a url-mode app's origin
@@ -938,7 +939,7 @@ export function createServer(options) {
938
939
  if (url.pathname === ENTRY_PATH && authorizeUrl !== null) {
939
940
  return await redeem(request, url, label);
940
941
  }
941
- const script = pageScript(url.pathname);
942
+ const script = pageScript(url.pathname) ?? libraryFile(url.pathname, method);
942
943
  if (script !== null) {
943
944
  return script;
944
945
  }
@@ -340,7 +340,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
340
340
  // The shell's own layer, over the content: marks, the outline of what would be picked.
341
341
  let layer = null;
342
342
  let shadow = null;
343
- const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.3);box-shadow:inset 0 -2px 0 rgba(202,138,4,.8)}.mark.element{background:rgba(250,204,21,.12);box-shadow:none;outline:2px solid rgba(202,138,4,.85);outline-offset:1px}.mark.active{background:rgba(250,204,21,.5)}.mark.element.active{background:rgba(250,204,21,.22);outline-width:3px}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{background:rgba(250,204,21,.9)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
343
+ // Marks lie over the content's text, so their fill is light (the text under them keeps its
344
+ // contrast, on a light page and a dark one alike) and an underline or outline says where
345
+ // they are; the active one and a flash add a ring around it, not more fill over its words.
346
+ const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
344
347
  const ensureLayer = () => {
345
348
  if (layer === null) {
346
349
  layer = createElement.call(document, "div");
@@ -16,7 +16,11 @@
16
16
  * shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`);
17
17
  * 5. keeps content off the clipboard: the async Clipboard API refuses, `execCommand` won't copy or
18
18
  * cut, and copy and cut events never reach content, so what a person copies is what they
19
- * selected (P051). Copy buttons go through the host (`copyText`, P052).
19
+ * selected (P051). Copy buttons go through the host (`copyText`, P052);
20
+ * 6. cancels every navigation the frame starts to another document (P079), before it sends a
21
+ * request: a navigation carries data out in its URL, and the embedding page's `frame-src`,
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.)
20
24
  * A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
21
25
  * imported, and its scripts run in order, as a fragment's are.
22
26
  *
@@ -16,7 +16,11 @@
16
16
  * shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`);
17
17
  * 5. keeps content off the clipboard: the async Clipboard API refuses, `execCommand` won't copy or
18
18
  * cut, and copy and cut events never reach content, so what a person copies is what they
19
- * selected (P051). Copy buttons go through the host (`copyText`, P052).
19
+ * selected (P051). Copy buttons go through the host (`copyText`, P052);
20
+ * 6. cancels every navigation the frame starts to another document (P079), before it sends a
21
+ * request: a navigation carries data out in its URL, and the embedding page's `frame-src`,
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.)
20
24
  * A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
21
25
  * imported, and its scripts run in order, as a fragment's are.
22
26
  *
@@ -72,6 +76,35 @@ export const SHELL_RUNTIME = String.raw `(() => {
72
76
  }
73
77
  }
74
78
 
79
+ // No navigation to another document (P079): a frame that navigates itself carries data out in
80
+ // the URL, and the embedding page's frame-src, the other wall, lets served frames reach every
81
+ // content origin. (An opaque frame gets no navigate events, as the spec says for opaque
82
+ // origins, measured: there frame-src is the wall, P033.) The navigate event comes before any request for every
83
+ // navigation this document starts (location, a link, window.open(…, "_self"), a refresh), and
84
+ // cancelling it stops it. Ours is the first listener, and reads the event through the platform's
85
+ // own getters, kept now, so content can neither stop it nor lie to it. Same-document ones (an
86
+ // anchor) go on, and so do reloads: the same address, on the frame's own origin (or none, in a
87
+ // srcdoc frame), which history can change only within that origin. The host's own (a new
88
+ // frame) are none of this document's.
89
+ const navigationApi = window.navigation;
90
+ const getterOf = (proto, name) => {
91
+ const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
92
+ return descriptor && typeof descriptor.get === "function" ? descriptor.get : null;
93
+ };
94
+ const navigateProto = typeof NavigateEvent === "function" ? NavigateEvent.prototype : null;
95
+ const destinationOf = getterOf(navigateProto, "destination");
96
+ const navigationTypeOf = getterOf(navigateProto, "navigationType");
97
+ const sameDocumentOf = getterOf(typeof NavigationDestination === "function" ? NavigationDestination.prototype : null, "sameDocument");
98
+ const preventNavigation = Event.prototype.preventDefault;
99
+ const applyOf = Reflect.apply;
100
+ if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
101
+ navigationApi.addEventListener("navigate", (event) => {
102
+ if (!applyOf(sameDocumentOf, applyOf(destinationOf, event, []), []) && applyOf(navigationTypeOf, event, []) !== "reload") {
103
+ applyOf(preventNavigation, event, []);
104
+ }
105
+ }, true);
106
+ }
107
+
75
108
  // No nested frames (each would be a fresh realm with WebRTC intact), no resource hints and no
76
109
  // refreshes (they reach the network outside the CSP's fetch directives). Removed as they are
77
110
  // added: a mutation observer's microtask runs before a child frame's document loads.
@@ -710,6 +743,132 @@ export const SHELL_RUNTIME = String.raw `(() => {
710
743
  });
711
744
  }
712
745
 
746
+ // Data (P079): readData reads a resource the host names, subscribeData follows one, through
747
+ // MCP's resources/* requests, which the host gates (the viewer's consent, a rate). A value is the
748
+ // first content's: JSON parsed when it says it is JSON, else its text.
749
+ let resourceUpdated = (_uri) => {};
750
+ const valueOf = (result) => {
751
+ const first = result && Array.isArray(result.contents) ? result.contents[0] : undefined;
752
+ if (first === null || typeof first !== "object") {
753
+ return undefined;
754
+ }
755
+ if (typeof first.text === "string") {
756
+ if (/(^|[/+])json(\s*;|$)/i.test(String(first.mimeType || ""))) {
757
+ try {
758
+ return JSON.parse(first.text);
759
+ } catch (_) {}
760
+ }
761
+ return first.text;
762
+ }
763
+ return typeof first.blob === "string" ? first.blob : undefined;
764
+ };
765
+ const staleOf = (result) => Boolean(result && result._meta && result._meta["porthole/stale"] === true);
766
+ const later = (error) => setTimeout(() => {
767
+ throw error;
768
+ });
769
+ if (declared("readData")) {
770
+ lock(window, "readData", (uri) => request("resources/read", { uri: String(uri) }).then(valueOf));
771
+ }
772
+ if (declared("subscribeData")) {
773
+ // One subscription per URI, however many follow it; a read at a time, one more if it changed
774
+ // meanwhile; a late follower gets the last value at once.
775
+ const followed = new Map();
776
+ const tell = (entry, result) => {
777
+ entry.last = result;
778
+ const value = valueOf(result);
779
+ const info = { stale: staleOf(result), uri: entry.uri };
780
+ for (const listener of Array.from(entry.listeners)) {
781
+ try {
782
+ listener.onData(value, info);
783
+ } catch (error) {
784
+ later(error);
785
+ }
786
+ }
787
+ };
788
+ const fail = (entry, error) => {
789
+ for (const listener of Array.from(entry.listeners)) {
790
+ if (typeof listener.onError === "function") {
791
+ try {
792
+ listener.onError(error);
793
+ } catch (thrown) {
794
+ later(thrown);
795
+ }
796
+ }
797
+ }
798
+ };
799
+ const refresh = (entry) => {
800
+ if (entry.reading) {
801
+ entry.again = true;
802
+ return;
803
+ }
804
+ entry.reading = true;
805
+ request("resources/read", { uri: entry.uri })
806
+ .then((result) => {
807
+ if (followed.get(entry.uri) === entry) {
808
+ tell(entry, result);
809
+ }
810
+ }, (error) => fail(entry, error))
811
+ .then(() => {
812
+ entry.reading = false;
813
+ if (entry.again && followed.get(entry.uri) === entry) {
814
+ entry.again = false;
815
+ refresh(entry);
816
+ }
817
+ });
818
+ };
819
+ resourceUpdated = (uri) => {
820
+ const entry = followed.get(uri);
821
+ if (entry !== undefined) {
822
+ refresh(entry);
823
+ }
824
+ };
825
+ lock(window, "subscribeData", (uri, onData, onError) => {
826
+ if (typeof onData !== "function") {
827
+ throw new TypeError("subscribeData(uri, onData, onError): onData must be a function");
828
+ }
829
+ const key = String(uri);
830
+ const listener = { onData, onError };
831
+ let entry = followed.get(key);
832
+ if (entry === undefined) {
833
+ const made = { uri: key, listeners: new Set(), reading: false, again: false, last: undefined };
834
+ entry = made;
835
+ followed.set(key, made);
836
+ request("resources/subscribe", { uri: key }).then(() => {
837
+ if (followed.get(key) === made) {
838
+ refresh(made);
839
+ }
840
+ }, (error) => {
841
+ if (followed.get(key) === made) {
842
+ followed.delete(key);
843
+ }
844
+ fail(made, error);
845
+ });
846
+ } else if (entry.last !== undefined) {
847
+ const known = entry;
848
+ Promise.resolve().then(() => {
849
+ if (known.listeners.has(listener)) {
850
+ try {
851
+ onData(valueOf(known.last), { stale: staleOf(known.last), uri: key });
852
+ } catch (error) {
853
+ later(error);
854
+ }
855
+ }
856
+ });
857
+ }
858
+ entry.listeners.add(listener);
859
+ const mine = entry;
860
+ return () => {
861
+ if (!mine.listeners.delete(listener) || mine.listeners.size > 0) {
862
+ return;
863
+ }
864
+ if (followed.get(key) === mine) {
865
+ followed.delete(key);
866
+ request("resources/unsubscribe", { uri: key }).catch(() => {});
867
+ }
868
+ };
869
+ });
870
+ }
871
+
713
872
  window.addEventListener("error", (event) => {
714
873
  const error = event.error;
715
874
  const where = event.lineno ? " (line " + event.lineno + ")" : "";
@@ -879,6 +1038,11 @@ export const SHELL_RUNTIME = String.raw `(() => {
879
1038
  case "ui/notifications/host-context-changed":
880
1039
  applyTheme(params);
881
1040
  break;
1041
+ case "notifications/resources/updated":
1042
+ if (typeof params.uri === "string") {
1043
+ resourceUpdated(params.uri);
1044
+ }
1045
+ break;
882
1046
  case "ui/resource-teardown":
883
1047
  case "ping":
884
1048
  if (data.id !== undefined) {
package/docs/ADOPTING.md CHANGED
@@ -46,13 +46,14 @@ height follows the content.
46
46
 
47
47
  Egress is what content may load and send out: scripts, styles, fonts, images, audio and video, and
48
48
  data (fetch, WebSocket). Every preset starts closed, and a kind opens more only through its
49
- `options.egress`. There are three levels:
49
+ `options.egress`. There are three levels, and Porthole's own libraries for served content:
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
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
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) |
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
57
 
57
58
  How to decide: **start closed; add `LIBRARY_CDNS` if agents use libraries; add passive `anyHttps`
58
59
  only for existing content with hotlinks**, and only the kinds it hotlinks (usually `img`). An
@@ -85,6 +86,61 @@ export const displays = defineDisplays({
85
86
  directive. The manual names exactly the origins the CSP allows (`test/agreement.test.ts`), and
86
87
  DESIGN.md § "Egress hardening, each with its test" is the long form.
87
88
 
89
+ ### Live widgets: content that reads your data
90
+
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)).
93
+ Its only way out is your host: `readData` (MCP `resources/read`) and `subscribeData` (MCP
94
+ `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`).
95
+
96
+ ```js
97
+ import { defineDisplays } from "@botiverse/porthole";
98
+
99
+ export const displays = defineDisplays({
100
+ // No egress option exists for it; served, it loads Porthole's Chart.js and D3 from its origin.
101
+ tile: { preset: "liveWidget", options: { capabilities: { openLink: {} } } },
102
+ });
103
+
104
+ createHost(displays.configFor(instance, contentSource), {
105
+ locator,
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
+ }),
111
+ // Call changed() when it changes (the content reads it again), or changed(result) to send it.
112
+ subscribeData: ({ uri }, { changed, signal }) => {
113
+ const stop = realtime.on(uri, () => changed());
114
+ signal.addEventListener("abort", stop);
115
+ },
116
+ },
117
+ // Asked once per display, before its first data call: may this widget read this viewer's data?
118
+ // Remember the answer per viewer and widget; a no refuses every data call (`denied`).
119
+ consent: async ({ display }) => allowedBefore(display) ?? (await askTheViewer(display)),
120
+ // Optional: your last copy, shown at once (stale), then the fresh read.
121
+ cached: ({ uri }) => lastCopy(uri),
122
+ });
123
+ ```
124
+
125
+ - **Your handlers decide what a URI may name.** Answer only the resources you mean widgets to read
126
+ (a whitelist of URI shapes), with the viewer's rights. The content's URI is its word.
127
+ - **Consent is your UI.** Without a `consent` function every data call is refused (fail closed).
128
+ React: `PortholeProvider` and `PortholeFrame` take `consent` and `cached`.
129
+ - **Rates stay gates**: 120 reads and 60 subscriptions a minute per display by default; change them
130
+ with the capability's `gates` (keep `"consent"` in the list).
131
+ - **Your page's CSP**: send `displays.embedderCsp(source, …)` (`frame-src` of your content origins
132
+ 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).
134
+ - **Keep live widgets off pages with frames that reach the network.** A frame can `postMessage` any
135
+ frame on its page, and nothing in it can stop that: a url-mode app (a dev server's preview) or an
136
+ `anyHttps` display beside a live widget could be handed what it read. Displays with closed egress
137
+ or `LIBRARY_CDNS` are fine beside it.
138
+ - **Opaque live widgets** (no content domain) work, without libraries: the manual tells the agent
139
+ to draw with SVG and CSS. An opaque frame's only wall against navigating itself away is your
140
+ page's `frame-src` (the shell's guard gets no events in an opaque origin), so show them on pages
141
+ that frame no content origins (`frame-src 'none'`), which is what `defineDisplays` gives a page
142
+ without a content domain.
143
+
88
144
  ## 3. Opaque displays: the page only
89
145
 
90
146
  ```js
package/docs/DECISIONS.md CHANGED
@@ -2212,3 +2212,132 @@ refused, and reported as a problem, on every engine (`leak/check.spec.ts`).
2212
2212
  **Revisit when** a host needs one of them for anything but scripts, or Raft's trace of blocked
2213
2213
  loads (its follow-up) proposes more hosts, such as mirrors reachable from mainland China.
2214
2214
 
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
2217
+
2218
+ **Decision.** Content that shows its host's data, current, read as the person viewing it (a
2219
+ dashboard tile, a kept widget) gets a preset of its own and the mechanisms it needs. 0.5.0.
2220
+ - **`presets.liveWidget(options)`**: an inline widget whose egress stays closed. Its options are
2221
+ a widget's less `egress` (a JavaScript caller passing one gets a `ConfigError`): no option opens
2222
+ its network. It declares `readData` and `subscribeData`, each gated `consent` and a rate (120 and
2223
+ 60 a minute). In domain isolation it sets `egress.libraries`. A host adds what any widget may
2224
+ have (a link, a copy button) or changes the data capabilities' gates, as for any capability.
2225
+ - **Porthole's libraries (`egress.libraries`)**: Chart.js 4.5.1 and D3 7.9.0
2226
+ (`VENDORED_LIBRARIES`), copied byte for byte from their npm packages (exact devDependencies, so
2227
+ the lockfile fixes the bytes) into a generated module (`scripts/vendor-libraries.ts`; P075: no
2228
+ file beside a module), with their licenses (MIT, ISC). `/server` serves them on every content
2229
+ origin at `/__porthole/lib/<name>@<version>/<file>` (the jsDelivr layout agents know), inside
2230
+ its reserved prefix: no ticket or cookie, `cache-control: immutable`, `nosniff`,
2231
+ `cross-origin-resource-policy: same-site`, GET and HEAD only, and nothing else under the path.
2232
+ A released path keeps its bytes; a new version is a new path beside it. The frame's CSP gets
2233
+ `script-src <content origin>/__porthole/lib/` per content origin: path-limited, so P022 holds
2234
+ (no `'self'`: nothing else served on the origin runs as a script). Domain isolation only; the
2235
+ manual gives a `<script>` line for each, and the chart topic says they are there.
2236
+ - **The `consent` gate**: the host's `consent(request)` (`HostOptions.consent`, React's
2237
+ `PortholeProvider`/`PortholeFrame` `consent`) is asked once per display before its first
2238
+ consent-gated call, the request being that call; Porthole keeps the answer for the display's life
2239
+ (`onceConsent`, across its frames); the host remembers it where it likes (per viewer, per widget).
2240
+ A no refuses every such call (`denied`) and no handler runs; no `consent` function refuses them
2241
+ (`no-consent`, fail closed); a consent function that throws is a no for that call and is asked
2242
+ again at the next. It comes after the rate and gesture gates and before `confirm`.
2243
+ - **`subscribeData`** speaks MCP's own subscriptions, which MCP Apps doesn't list: the view is the
2244
+ host's MCP client, as it is for `resources/read`. `resources/subscribe` and
2245
+ `resources/unsubscribe` with `{ uri }`, and the host's `notifications/resources/updated` with
2246
+ `{ uri }`, after which the view reads it again. The host offers it as MCP does,
2247
+ `hostCapabilities.serverResources: { subscribe: true }` (the official App SDK's schema keeps the
2248
+ field open, so its views still connect). The handler gets `changed(result?)` and an `AbortSignal`
2249
+ that ends with the subscription, the frame or the display; a `result` passed to `changed` answers
2250
+ the content's next read without the read handler. One subscription per URI per frame;
2251
+ unsubscribing is never gated.
2252
+ - **The host's cache (`HostOptions.cached`, `DataCache`)**: a read of a resource the content
2253
+ subscribes to is answered at once from it, after the gates, marked
2254
+ `_meta["porthole/stale"]: true` (`STALE_META`); the fresh read follows in the background, is kept
2255
+ for the content's next read, and is announced as an update. A read of an unsubscribed resource
2256
+ never gets the cache: no update would follow it.
2257
+ - **Shell globals**: `readData(uri)` (the first content's value: JSON parsed when its MIME type says
2258
+ JSON, else its text) and `subscribeData(uri, onData, onError)` (onData(value, { stale, uri }) now
2259
+ and at every change; a read at a time, one more if it changed meanwhile; one subscription per URI
2260
+ however many follow it; returns a stop function).
2261
+ - **No navigation to another document, in every shell**: the shell cancels each navigation the
2262
+ frame starts to another document (the Navigation API's `navigate` event, read through the
2263
+ platform's own getters kept at document start, its listener the first), before any request. It
2264
+ works where the frame has an origin of its own (served: domain isolation, MCP Apps proxies),
2265
+ which is where the page's `frame-src` must let frames in. An opaque frame gets no navigate
2266
+ events (the spec disables them for opaque origins; measured on Chromium: `navigation` is there,
2267
+ with no entries, and `location.href` goes on), so there `frame-src` stays the wall (P033).
2268
+ Same-document ones (an anchor) and reloads (the same address, on the frame's own origin) go on.
2269
+ Not only for live widgets: it is cheap and breaks nothing a shell's content did on purpose (links
2270
+ already open outside through `openLink`, P030; a page that reloads itself still does).
2271
+
2272
+ **Why.**
2273
+ - A widget that reads the viewer's data must have no way out but its host: Claude's dashboards
2274
+ take the same rule (no fetch, no external scripts; libraries from the host). The default egress
2275
+ is already closed (P022); what a live widget adds is that no option can open it, and libraries
2276
+ that don't need a CDN, whose request paths are a channel out (P048).
2277
+ - Two leaks Ferry measured in its own widget shell (2026-10-11): WebRTC gathering candidates (here
2278
+ since P006: `webrtc 'block'` and the shell's removal, probe `3.webrtc`, a child frame can't get the
2279
+ constructors: `4.*`), and a frame navigating itself away with data in the URL. Porthole's wall
2280
+ for the second is the embedding page's `frame-src` (P006, P033), but a page that frames served
2281
+ content must allow the content origins, so **a served frame could navigate itself to another
2282
+ content origin, with data in the URL** (measured on Chromium 153, WebKit 26.6 and Firefox 155:
2283
+ under the `navigate-guard` negative control, every one of `leak/served/live.spec.ts`' sibling
2284
+ navigations reaches the harness's server, the display restarting each time; with the guard, none
2285
+ does). On a host whose content origins include
2286
+ a url-mode app relayed to someone's machine (a dev server's preview), that is a way out. The
2287
+ guard closes it in the frame, where it starts.
2288
+ - Consent is the host's policy (PRINCIPLE 8), its gate is mechanism (PRINCIPLE 4): one answer per
2289
+ display, asked lazily, so a widget that never reads data never asks.
2290
+
2291
+ **Rejected.**
2292
+ - A config field (`network: "none"`) or a flag on `inlineWidget`: a preset is the knob-free path
2293
+ (PRINCIPLE 8), the CSP needs nothing new, and the guarantee is that no option opens egress.
2294
+ - `consent` among `readData`'s default gates: it would refuse every call of hosts that declare
2295
+ `readData` today (MCP Apps views proxying to a server). The live widget preset has it.
2296
+ - Libraries for opaque live widgets from the host app's own origin: a `srcdoc` frame inherits the
2297
+ embedding page's policy (nonce pages refuse them, P054), and it adds a second origin to name.
2298
+ Opaque live widgets get no libraries; the manual says so.
2299
+ - A third library. Plotly and ECharts are 1–3 MB; Mermaid draws diagrams, not data; a Markdown
2300
+ renderer would turn the host's data into HTML in a frame that holds the viewer's data (injection);
2301
+ a Chart.js date adapter is for time axes D3 already covers.
2302
+ - Data inside `notifications/resources/updated`: MCP's notification carries the URI only; the kept
2303
+ fresh result gives the same one round trip and keeps the wire standard.
2304
+ - Serving the libraries only to configs that set `egress.libraries`: the files are public, fixed
2305
+ and same-site only; a server that knows which config a request is for would need a ticket.
2306
+
2307
+ **Residual, documented (ADOPTING § Live widgets).**
2308
+ - A frame can `postMessage` any frame on its page (`top.frames[i]`), and nothing in it can stop
2309
+ that. A live widget on a page with frames that reach the network (a url-mode app, an `anyHttps`
2310
+ display) can hand them what it read. Hosts keep live widgets off such pages.
2311
+ - An opaque frame on a page that also frames content origins (one `frame-src` for every kind) can
2312
+ navigate itself to them: the guard has no events there. Show live widgets served, or keep opaque
2313
+ ones on pages whose `frame-src` is `'none'` (no content domain: `defineDisplays` gives every kind
2314
+ one or the other).
2315
+ - An engine without the Navigation API falls back to `frame-src`: an outside site stays shut, other
2316
+ content origins don't.
2317
+ - A clean address opened as a tab has no host, so no data.
2318
+ - Upstream: MCP Apps lists no resource subscriptions; to propose `serverResources.subscribe` and
2319
+ the three methods to the spec (ext-apps), with this entry as the evidence.
2320
+
2321
+ **Tested.** `test/live-data.test.ts` (the preset, its CSP, validation; consent: once, a no kept,
2322
+ fail closed, a throw asked again, invalid calls before consent, rates; MCP's subscribe, update,
2323
+ read again, a pushed result, unsubscribe, close, refusal, the cache stale then fresh, only after
2324
+ consent, only when subscribed); `test/libraries.test.ts` (the module is npm's bytes, pinned, with
2325
+ licenses; served without a ticket, immutable, nothing else under the path); `test/agreement.test.ts`
2326
+ (two live widget cases: the libraries taught exactly where the CSP loads them; consent's words
2327
+ exactly where the gate is); `leak/served/live.spec.ts` (a served live widget on a page with
2328
+ Porthole's embedder CSP: fetch, no-cors fetch, XHR, beacon, WebSocket, EventSource, an image, a CSS
2329
+ image, a stylesheet and an external script reach no oracle (no request, no connection); no RTC
2330
+ constructor, no peer, no STUN at a UDP oracle, no child frame; `location`, `replace`,
2331
+ `open(…, "_self")` and `navigation.navigate` to another content origin and to an outside site send
2332
+ no request (the document is kept, or the display started again); Chart.js and D3 load and draw; data read and followed, consent
2333
+ asked once; the cache first, stale, then fresh; a viewer's no refuses both), passing on
2334
+ Chromium, WebKit and Firefox. Negative control: `navigate-guard` (also applied to the served
2335
+ harness's documents) → the four navigation cases on all three engines (each sibling navigation
2336
+ reaches the harness's server). Measured on WebKit: `navigation.navigate()` to a site the page's
2337
+ `frame-src` blocks fires no navigate event (the block comes first), and WebKit then replaces the
2338
+ frame's document, so the display is started again (P031); nothing reaches the site, and the case
2339
+ accepts either outcome, as the opaque probes do. The opaque probes `5.*` keep failing under
2340
+ `embedder-csp` with the guard in place (measured, Chromium): their wall is the page's `frame-src`.
2341
+ **Revisit when** MCP Apps specifies subscriptions (follow it), an engine Porthole supports lacks the
2342
+ Navigation API, a host needs libraries in opaque frames, or agents' live widgets reach for a library
2343
+ the two don't cover.
package/docs/DESIGN.md CHANGED
@@ -51,7 +51,8 @@ compile/ compile.ts (config → CompiledConfig), policy.ts (CSP, sandbox, al
51
51
  shell/ runtime.ts (the in-frame script, a string), plan.ts (what it wires), document.ts
52
52
  guide/ guide.ts (manual + tool description), examples.ts
53
53
  theme/ variables.ts (the default vocabulary, resolveTheme)
54
- presets/ presets.ts (inlineWidget, artifact, mcpApp, url; LIBRARY_CDNS)
54
+ presets/ presets.ts (inlineWidget, liveWidget, artifact, mcpApp, url; LIBRARY_CDNS)
55
+ libraries/ libraries.ts (VENDORED_LIBRARIES), files.generated.ts (their bytes, P079)
55
56
  protocol/ adapter.ts (the adapter seam), mcp-apps.ts (method names, HostContext), jsonrpc.ts
56
57
  bridge/ types.ts (the host-function bridge)
57
58
  transport/ types.ts platform/ types.ts isolation/ types.ts
@@ -92,7 +93,7 @@ interface PortholeConfig {
92
93
  contentOrigins: string[]; // domain/external: where content is served from
93
94
  embedder: { frameSrc?: string[] }; // extra frames the embedding page shows
94
95
  }
95
- type Gate = "user-activation" | "confirm" | { rateLimit: { perMinute: number } };
96
+ type Gate = "user-activation" | "confirm" | "consent" | { rateLimit: { perMinute: number } };
96
97
  ```
97
98
 
98
99
  `mode` and `isolation` select the mechanism; everything else is policy. There is
@@ -106,7 +107,8 @@ no `components` field (P015).
106
107
  | `openLink` | user-activation, confirm | handler | `openLink(url)` | `ui/open-link` (`app.openLink`) |
107
108
  | `downloadFile` | user-activation, confirm | handler | — | `ui/download-file` (`app.downloadFile`) |
108
109
  | `callTool` | confirm | handler | — | `tools/call` (`app.callServerTool`) |
109
- | `readData` | 120/min | handler | — | `resources/read` (`app.readServerResource`) |
110
+ | `readData` | 120/min | handler | `readData(uri)` | `resources/read` (`app.readServerResource`) |
111
+ | `subscribeData` | 60/min (needs `readData`) | handler (`changed`, `signal`) | `subscribeData(uri, onData, onError)` | `resources/subscribe`, `resources/unsubscribe`; the host's `notifications/resources/updated` (MCP's own; none in MCP Apps, P079) |
110
112
  | `setModelContext` | 30/min | handler | — | `ui/update-model-context` (`app.updateModelContext`) |
111
113
  | `reportError` | 10/min | event | (automatic) | `notifications/message`, level `error` |
112
114
  | `resize` | none | event | (automatic) | `ui/notifications/size-changed` |
@@ -117,7 +119,11 @@ Every preset declares only `resize` and `reportError` (they report to the host a
117
119
  carry nothing out); the host declares the rest. Gates are explained in P021: all
118
120
  must pass; `confirm` calls the host's `confirm` function and fails closed without
119
121
  one; `user-activation` is checked by the shell (advisory: it shares the content's
120
- realm) and by the host where the engine passes the gesture up.
122
+ realm) and by the host where the engine passes the gesture up; `consent` asks the
123
+ host's `consent` function once per display, before its first consent-gated call,
124
+ and fails closed without one (P079). `presets.liveWidget` declares `readData` and
125
+ `subscribeData` with `consent` and its rate, and keeps egress closed (no option opens
126
+ it); served, it loads Porthole's libraries from its origin (`egress.libraries`).
121
127
 
122
128
  ## What the compiler derives
123
129
 
@@ -126,7 +132,8 @@ realm) and by the host where the engine passes the gesture up.
126
132
  - `csp` / `cspDirectives`: the frame's policy. `default-src 'none'`; scripts may be
127
133
  inline (agent content is inline), `'unsafe-eval'` (content is the agent's own script already,
128
134
  so eval adds no capability, and libraries content uses compile with it, WebAssembly too: P071),
129
- plus `blob:` and the script origins; each other
135
+ plus `blob:` and the script origins (and, with `egress.libraries`, Porthole's library path on
136
+ the content origins, `<origin>/__porthole/lib/`, P079); each other
130
137
  kind opens only to its origins; `connect-src 'none'` unless something is
131
138
  declared; `frame-src`, `object-src`, `base-uri`, `form-action` all `'none'`;
132
139
  `webrtc 'block'`. Never `'self'` (P022). Empty in url mode.
@@ -724,6 +731,10 @@ absent.
724
731
  - **Inline widget** (`presets.inlineWidget`). The host has the HTML (the agent
725
732
  wrote it) and the shell draws it in an opaque frame, streamed as it is written.
726
733
  The phase-1 workhorse.
734
+ - **Live widget** (`presets.liveWidget`, P079). An inline widget that shows the
735
+ host's data, current, as the viewer may see it: `readData` and `subscribeData`
736
+ behind the viewer's consent, no network of its own, and, served, Porthole's
737
+ Chart.js and D3 from its own origin.
727
738
  - **Artifact page** (`presets.artifact`). A whole document: written into an opaque
728
739
  frame by the shell where the host has it (the first host's "show an HTML file"),
729
740
  or served on its own origin (domain isolation), CSP in headers, versioned. It
@@ -786,7 +797,7 @@ closed like a strict host's (`leak/inherited-policy.spec.ts`).
786
797
  | 2 | images, CSS images, SVG `<image>`/`<use>`, media and posters, `input type=image`, stylesheets, `@import`, fonts, scripts, `import()`, workers, manifests, icons | CSP `img/media/font/style/script-src` = the allowlist only; `worker-src blob:` | `2.resources` (an allowed image as positive control) | — (the same CSP as item 1) |
787
798
  | 3 | WebRTC (ICE gathering reaches the network outside `connect-src`) | CSP `webrtc 'block'` **and** the shell removes every `RTC*`/`webkitRTC*` constructor, fixed in place, before content runs | `3.webrtc` (an unsandboxed peer connection as positive control: it sends STUN on both engines) | `webrtc` → `3.webrtc` (all three; Firefox's positive control needs `media.peerconnection.ice.loopback`, set in the suite's Firefox project, P035) |
788
799
  | 4 | a nested frame: a fresh realm where item 3's removal never happened | the shell drops frame-like elements (`iframe, frame, frameset, object, embed, portal, fencedframe`) synchronously wherever content connects a node (P030), and an observer removes any that arrive another way, in the document and every shadow root (`attachShadow` is wrapped so closed ones are reached too); documents are rendered inert and imported, never written; `document.open/write` throw; declarative shadow roots can't be built (P029); CSP `frame-src 'none'` | `4.light-dom`, `.sync-realm`, `.open-shadow`, `.closed-shadow`, `.shadow-nested`, `.declarative-shadow`, `.parse-html-unsafe`, `.domparser`, `.document-write`, `.plugins`, `.foreign-object`, `.template-clone`, `.static` (each: the child never runs, no STUN, no frame left) | `frame-guard,sync-guard` → light-dom, sync-realm, plugins, foreign-object, template-clone; `attach-shadow,sync-guard` → closed-shadow, shadow-nested; `declarative-shadow` → declarative-shadow; `parser-entry-points` → document-write (each on all three engines). Either guard alone is covered by the other. |
789
- | 5 | self-navigation out, with data in the URL (`location`, `replace`, `open(…, "_self")`, meta refresh, a link clicked past the shell, an SVG link), to the host's own origin, or to a `blob:`/`data:` document of its own (a fresh realm) | the **embedding page's** `frame-src` (`embedderCsp`: `'none'` for opaque content, P033; frames only, so the host's own workers are untouched, P038): a frame's own CSP cannot stop its own navigation; the shell sends link clicks out through `openLink` and drops refreshes (P030); a display whose frame navigates is started again, at most three times (P031) | `5.location`, `.replace`, `.open-self`, `.refresh`, `.anchor`, `.svg-link`, `.host-origin`, `.blob`, `.data` (no request reaches the canary or the host; a navigated document never runs: a witness origin hears nothing) | `embedder-csp` → location, replace, open-self, anchor, svg-link, blob, data, `6.remote-download` (all three; `.refresh` holds: the synchronous guard drops the refresh; Firefox also holds `.data` by itself, P035); `embedder-self` → `5.host-origin` |
800
+ | 5 | self-navigation out, with data in the URL (`location`, `replace`, `open(…, "_self")`, meta refresh, a link clicked past the shell, an SVG link), to the host's own origin, or to a `blob:`/`data:` document of its own (a fresh realm) | the **embedding page's** `frame-src` (`embedderCsp`: `'none'` for opaque content, P033; frames only, so the host's own workers are untouched, P038): a frame's own CSP cannot stop its own navigation; the shell sends link clicks out through `openLink` and drops refreshes (P030); a display whose frame navigates is started again, at most three times (P031). A served frame's page must let it reach the content origins, so there the shell cancels every navigation the frame starts to another document (the Navigation API's `navigate` event; reloads and same-document ones go on, P079); an opaque frame gets no navigate events | `5.location`, `.replace`, `.open-self`, `.refresh`, `.anchor`, `.svg-link`, `.host-origin`, `.blob`, `.data` (no request reaches the canary or the host; a navigated document never runs: a witness origin hears nothing); served: `leak/served/live.spec.ts` (`location`, `replace`, `open(…, "_self")`, `navigation.navigate` to another content origin and to an outside site: no request reaches either, the document stays) | `embedder-csp` → location, replace, open-self, anchor, svg-link, blob, data, `6.remote-download` (all three; `.refresh` holds: the synchronous guard drops the refresh; Firefox also holds `.data` by itself, P035; the navigation guard has no events in these opaque frames); `embedder-self` → `5.host-origin`; `navigate-guard` → the four served navigation cases (each reaches another content origin) |
790
801
  | 6 | forms, popups, downloads, top and parent navigation | `sandbox="allow-scripts"` only; CSP `form-action 'none'` | `6.submit`, `.request-submit`, `.blank-form`, `.open`, `.blank-link`, `.download`, `.remote-download`, `.top`, `.top-link`, `.parent` | `sandbox` → open, blank-link, top, top-link, parent (all three), download (Chromium; WebKit and Firefox started no download either way). Form submits still fail: `form-action` is a second wall |
791
802
  | 7 | `<base>` hijack, plugins | CSP `base-uri 'none'`, `object-src 'none'`; plugins removed as frames | `7.base-plugins` | `base-uri` → `7.base-plugins` (all three); `frame-guard,sync-guard` too (plugins left in place) |
792
803
  | 8 | resource hints and speculation rules | CSP for those an engine governs (`prefetch`, `preload`, `modulepreload`); for the rest the shell drops `dns-prefetch`, `preconnect`, `prefetch`, `prerender` links, speculation rules, refreshes and `x-dns-prefetch-control` metas synchronously, and refuses changes that would make a connected link one (P030); `x-dns-prefetch-control: off` | `8.preconnect`, `.dns-prefetch`, `.prefetch`, `.prerender`, `.preload`, `.modulepreload`, `.speculation-rules` (each in markup, inserted, and switched on by attribute change; no request, no connection) | `sync-guard` → `8.preconnect` (WebKit: it preconnects synchronously, outside CSP). Measured: Chromium and Firefox opened no preconnect even unsandboxed. `dns-prefetch` has no out-of-band oracle here (DNS isn't observed); the element is refused before it connects |
@@ -808,6 +819,7 @@ official App SDK connects under the inline, artifact and MCP Apps presets
808
819
  | 11 | theming | `setTheme(scheme)`: the host sends the resolved variables (the host's live values over the defaults, P028), the shell sets them in place, with `data-theme` and `color-scheme`, then fires the config's theme event once, only when the scheme or a value changed (never at mount, never for a host re-sending what the content has, P061); the frame element's `color-scheme` follows | `11.theme-flip` (no event at mount or for the same scheme; in place: content state kept, the event fired once per flip, back and forth), `11.theme-host-values` (live values for standard and own names; undeclared names dropped) | — |
809
820
  | 11 | base styles | plain CSS at zero specificity (`:where`): native buttons, inputs, selects and text areas take the theme's borders, radius, colors and focus ring, 44 px tall (the manual's touch size); the manual says so for inline widgets | `11.base-styles` (themed; content's own CSS overrides them) | — |
810
821
  | 12 | `sendPrompt` | the shell refuses a call without a gesture; the host refuses one without its page's user activation, then asks `confirm` with the whole text; declines count toward a mute | `12.prompt-gesture-confirm` (a call on load is refused; a click asks; a no sends nothing; a yes reaches the handler), `12.raw-message` (a raw `ui/message` around the shell, no click: refused by the host), `12.mute`, `12.no-confirm` | `confirm-gate` → prompt-gesture-confirm, link, mute, no-confirm; `shell-gesture` → prompt-gesture-confirm, mute; `host-gesture` → raw-message |
822
+ | 12 | live data (`readData`, `subscribeData`, P079) | MCP `resources/read`, `resources/subscribe`/`unsubscribe`, `notifications/resources/updated`; the `consent` gate asks the host once per display before the first data call (a no refuses them all; none refuses, fail closed), then the rate; a subscribed read may be answered from the host's cache, marked stale, the fresh one following as an update | `test/live-data.test.ts`; `leak/served/live.spec.ts` (read and followed, consent asked once; cached then fresh; a viewer's no refuses both, no handler runs) | — |
811
823
  | 12 | `openLink` | link clicks go out through `openLink`; the bridge takes http(s) only, without credentials in the URL; confirmed | `12.link` (a web link asks and opens; `javascript:` links and `openLink("javascript:…")` do nothing and are refused) | `link-scheme` → `12.link` |
812
824
 
813
825
  Measured: a click in the frame gives the host page user activation (it propagates to
@@ -822,6 +834,7 @@ for that to lapse and click with raw input.
822
834
  |------|-----------|-------|------------------|
823
835
  | The host's check (P050) | `authorize.check` after a ticket or cookie verifies, before anything is served; a deny is a 403 page saying `denied` and the host's code, and the display's `outcome` says so even after `loaded` | `leak/served/authorize.spec.ts`: a revoked subject's ticket (a page, an app); a framed app's next request and reload mid-session (Chromium, Firefox: WebKit keeps no framed cookie, P025); a framed page's next load; an app and a page in a tab | `authorize` → every case but WebKit's framed page (`session` either way) |
824
836
  | Url-mode delegation (P049) | `allow` from `permissions`, `""` by default | `leak/served/permissions.spec.ts`: full screen follows it on all three; clipboard writes on Chromium only (WebKit and Firefox let any frame write in a click) | `url-permissions` → the default case (all three) |
837
+ | Porthole's libraries (P079) | `egress.libraries` (domain isolation; on in `presets.liveWidget`): `script-src <content origin>/__porthole/lib/`; `/server` serves Chart.js 4.5.1 and D3 7.9.0, npm's bytes, on every content origin, without a ticket, immutable | `test/libraries.test.ts` (npm's bytes, pinned, licenses; headers; nothing else under the path); `leak/served/live.spec.ts` (both load and draw in a live widget whose every other load and fetch reaches no oracle) | — (rows 1–2) |
825
838
  | Library CDNs for artifacts (P048, P078) | `egress: LIBRARY_CDNS` in the host's artifact config; closed by default (P022); Tailwind's, jQuery's and Plotly's own CDNs for scripts only | `leak/cdn.spec.ts`: opaque and served, a CDN library loads only when opened; another origin never; a stylesheet, an image and a fetch never reach the libraries' own CDNs | — (the CSP of rows 1–2) |
826
839
  | Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
827
840
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "license": "Apache-2.0",
6
6
  "bin": {
@@ -62,6 +62,8 @@
62
62
  "@types/node": "26.6.3",
63
63
  "@types/react": "19.3.0",
64
64
  "@types/react-dom": "19.3.0",
65
+ "chart.js": "4.5.1",
66
+ "d3": "7.9.0",
65
67
  "esbuild": "0.28.2",
66
68
  "miniflare": "4.20260730.0",
67
69
  "react": "19.3.0",