@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.
- package/README.md +25 -0
- package/dist/bridge/bridge.d.ts +12 -4
- package/dist/bridge/bridge.js +62 -27
- package/dist/bridge/navigation.d.ts +6 -0
- package/dist/bridge/navigation.js +41 -0
- package/dist/bridge/refusal.d.ts +53 -0
- package/dist/bridge/refusal.js +121 -0
- package/dist/bridge/types.d.ts +7 -0
- package/dist/check/check.d.ts +12 -3
- package/dist/check/check.js +54 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/lint.js +27 -10
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -0
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +25 -0
- package/dist/compile/policy.d.ts +15 -0
- package/dist/compile/policy.js +32 -0
- package/dist/config/capabilities.d.ts +5 -0
- package/dist/config/schema.d.ts +8 -0
- package/dist/config/validate.js +8 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -0
- package/dist/guide/guide.js +25 -5
- package/dist/host/create-host.js +36 -4
- package/dist/host/types.d.ts +15 -2
- package/dist/index.d.ts +7 -3
- package/dist/index.js +10 -3
- package/dist/mcp/adapter.js +22 -7
- package/dist/protocol/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +12 -0
- package/dist/protocol/mcp-apps.js +12 -0
- package/dist/protocol/shell-adapter.js +18 -2
- package/dist/react/frame.d.ts +19 -4
- package/dist/react/frame.js +37 -9
- package/dist/server/files.d.ts +44 -0
- package/dist/server/files.js +244 -0
- package/dist/server/host.d.ts +38 -1
- package/dist/server/host.js +37 -2
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +4 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -0
- package/dist/server/server.js +287 -22
- package/dist/server/types.d.ts +49 -5
- package/dist/shell/document.d.ts +19 -0
- package/dist/shell/document.js +30 -0
- package/dist/shell/runtime.d.ts +2 -1
- package/dist/shell/runtime.js +117 -10
- package/docs/ADOPTING.md +95 -13
- package/docs/ARCHITECTURE.md +13 -3
- package/docs/DECISIONS.md +396 -4
- package/docs/DESIGN.md +43 -10
- package/package.json +1 -1
- package/src/bridge/bridge.ts +74 -23
- package/src/bridge/navigation.ts +46 -0
- package/src/bridge/refusal.ts +151 -0
- package/src/bridge/types.ts +12 -1
- package/src/check/check.ts +92 -14
- package/src/check/files.ts +384 -0
- package/src/check/lint.ts +29 -10
- package/src/check/page.ts +7 -0
- package/src/check/tools.ts +50 -0
- package/src/compile/policy.ts +38 -0
- package/src/config/capabilities.ts +5 -1
- package/src/config/schema.ts +8 -0
- package/src/config/validate.ts +8 -1
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/guide.ts +38 -4
- package/src/host/create-host.ts +37 -4
- package/src/host/types.ts +13 -2
- package/src/index.ts +41 -0
- package/src/mcp/adapter.ts +26 -6
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +14 -0
- package/src/protocol/shell-adapter.ts +20 -2
- package/src/react/frame.tsx +53 -14
- package/src/server/files.ts +312 -0
- package/src/server/host.ts +72 -3
- package/src/server/index.ts +19 -0
- package/src/server/keys.ts +53 -0
- package/src/server/server.ts +353 -24
- package/src/server/types.ts +56 -4
- package/src/shell/document.ts +53 -0
- package/src/shell/runtime.ts +117 -10
package/dist/shell/runtime.js
CHANGED
|
@@ -20,7 +20,8 @@
|
|
|
20
20
|
* 6. cancels every navigation the frame starts to another document (P079), before it sends a
|
|
21
21
|
* request: a navigation carries data out in its URL, and the embedding page's `frame-src`,
|
|
22
22
|
* the wall for that, must let served frames reach their own content origins. (Opaque frames
|
|
23
|
-
* get no navigate events: there `frame-src` is the wall.)
|
|
23
|
+
* get no navigate events: there `frame-src` is the wall.) A page that comes with files may
|
|
24
|
+
* open its set's other pages, under its version's own address, and nothing else (P084).
|
|
24
25
|
* A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
|
|
25
26
|
* imported, and its scripts run in order, as a fragment's are.
|
|
26
27
|
*
|
|
@@ -35,6 +36,13 @@
|
|
|
35
36
|
export const SHELL_RUNTIME = String.raw `(() => {
|
|
36
37
|
"use strict";
|
|
37
38
|
const plan = __PLAN__;
|
|
39
|
+
// A page that came with files, answered at its ticket's address (P083): its own address first,
|
|
40
|
+
// before anything loads, so its relative addresses are its files' (and the ticket leaves).
|
|
41
|
+
if (plan.files && typeof plan.files.address === "string" && location.href !== plan.files.address) {
|
|
42
|
+
try {
|
|
43
|
+
history.replaceState(null, "", plan.files.address);
|
|
44
|
+
} catch (_) {}
|
|
45
|
+
}
|
|
38
46
|
// The embedding page's nonce, where it gave one (a srcdoc frame inherits its policy): every
|
|
39
47
|
// script the shell runs for the content carries it.
|
|
40
48
|
const nonce = document.currentScript && document.currentScript.nonce ? document.currentScript.nonce : "";
|
|
@@ -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
|
|
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
|
-
|
|
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:
|
|
520
|
+
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: ownAddresses(message).slice(0, 2000) } });
|
|
477
521
|
};
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
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
|
-
|
|
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
|
-
|
|
109
|
-
|
|
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
|
|
404
|
-
once people see it: listen for `contentError` and pass
|
|
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
|
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -84,7 +84,10 @@ Pure mechanism, no product policy, no host or vendor types.
|
|
|
84
84
|
comes from the theme variables, never from a component vocabulary (P015).
|
|
85
85
|
- **Serving.** For served modes, a request handler a host's backend mounts: it
|
|
86
86
|
serves documents on their own origins with their CSP in headers, and turns a
|
|
87
|
-
one-time ticket the host minted into a cookie of that origin only.
|
|
87
|
+
one-time ticket the host minted into a cookie of that origin only. A stored
|
|
88
|
+
version may be one page or a set of files: each file is looked up in the
|
|
89
|
+
version's manifest only, typed by Porthole's own table, and served under that
|
|
90
|
+
version's own address, so a page's relative addresses are its version's.
|
|
88
91
|
|
|
89
92
|
### Preset policy layer
|
|
90
93
|
|
|
@@ -179,6 +182,10 @@ transparent to the view and the host.
|
|
|
179
182
|
The content is served as a real document at a URL on a separate registrable
|
|
180
183
|
domain with its CSP in HTTP headers; the host embeds that URL in a frame whose
|
|
181
184
|
`frame-ancestors` names the host. No code injection, and the shell is optional.
|
|
185
|
+
A page may come with files of its own (stylesheets, scripts, data, images, other
|
|
186
|
+
pages): they are served beside it, under its version's own address, and its CSP
|
|
187
|
+
opens that path and nothing else of its origin; every page of the set gets the
|
|
188
|
+
shell.
|
|
182
189
|
Access is gated by a one-time ticket exchanged for a scoped cookie. Where the host
|
|
183
190
|
holds the page and needs no stable origin, the shell writes it into an opaque
|
|
184
191
|
frame instead.
|
|
@@ -208,7 +215,9 @@ only the declared content origins.
|
|
|
208
215
|
says so.
|
|
209
216
|
|
|
210
217
|
2. **Content ↔ the outside network.** Closed by default and opened only to the
|
|
211
|
-
origins the config's capabilities declare
|
|
218
|
+
origins the config's capabilities declare (and, for a served page with files,
|
|
219
|
+
its own version's path on its own origin: the host's own server, P082). Two
|
|
220
|
+
kinds of attacker matter:
|
|
212
221
|
- *Attacking the host* (steal credentials, read other data, escape the
|
|
213
222
|
sandbox): stopped by origin isolation — the content is a stranger to the
|
|
214
223
|
host origin.
|
|
@@ -259,7 +268,8 @@ only the declared content origins.
|
|
|
259
268
|
- **Served content.** A host plugs its own policy and infrastructure into `/server`:
|
|
260
269
|
who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
|
|
261
270
|
how origins are named (`content.name`, other servers' `reserved` namespaces),
|
|
262
|
-
and where apps and artifact versions come from (`upstream`, `artifacts
|
|
271
|
+
and where apps and artifact versions come from (`upstream`, `artifacts`: a page, or a
|
|
272
|
+
manifest of files and their bytes), and which address means which version (`entry.at`). It runs
|
|
263
273
|
on any runtime with web-standard `Request`/`Response` (Node, Workers).
|
|
264
274
|
|
|
265
275
|
## How a new protocol or platform plugs in
|