@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.
- package/README.md +3 -1
- package/dist/bridge/bridge.d.ts +16 -2
- package/dist/bridge/bridge.js +65 -12
- package/dist/bridge/types.d.ts +44 -6
- package/dist/check/lint.js +2 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -0
- package/dist/compile/policy.d.ts +5 -0
- package/dist/compile/policy.js +18 -1
- package/dist/config/capabilities.d.ts +25 -2
- package/dist/config/capabilities.js +13 -0
- package/dist/config/schema.d.ts +7 -0
- package/dist/config/validate.js +14 -3
- package/dist/conformance/harness/page.js +1 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.d.ts +1 -1
- package/dist/guide/guide.js +48 -8
- package/dist/host/create-host.js +5 -1
- package/dist/host/types.d.ts +12 -1
- package/dist/index.d.ts +4 -3
- package/dist/index.js +2 -1
- package/dist/libraries/files.generated.d.ts +1 -0
- package/dist/libraries/files.generated.js +8 -0
- package/dist/libraries/libraries.d.ts +36 -0
- package/dist/libraries/libraries.js +40 -0
- package/dist/mcp/adapter.js +31 -2
- package/dist/presets/presets.d.ts +15 -0
- package/dist/presets/presets.js +27 -2
- package/dist/protocol/live-data.d.ts +27 -0
- package/dist/protocol/live-data.js +98 -0
- package/dist/protocol/mcp-apps.d.ts +9 -0
- package/dist/protocol/mcp-apps.js +11 -0
- package/dist/protocol/shell-adapter.js +35 -2
- package/dist/react/dialog.js +2 -0
- package/dist/react/frame.d.ts +15 -1
- package/dist/react/frame.js +35 -1
- package/dist/server/libraries.d.ts +7 -0
- package/dist/server/libraries.js +27 -0
- package/dist/server/server.js +2 -1
- package/dist/shell/annotate.js +4 -1
- package/dist/shell/runtime.d.ts +5 -1
- package/dist/shell/runtime.js +165 -1
- package/docs/ADOPTING.md +57 -1
- package/docs/DECISIONS.md +129 -0
- package/docs/DESIGN.md +19 -6
- package/package.json +3 -1
- package/src/bridge/bridge.ts +85 -13
- package/src/bridge/types.ts +45 -3
- package/src/check/lint.ts +2 -1
- package/src/check/page.ts +5 -0
- package/src/compile/policy.ts +19 -1
- package/src/config/capabilities.ts +21 -0
- package/src/config/schema.ts +7 -0
- package/src/config/validate.ts +21 -3
- package/src/conformance/harness/page.ts +1 -0
- package/src/displays/displays.ts +1 -1
- package/src/guide/guide.ts +57 -7
- package/src/host/create-host.ts +5 -1
- package/src/host/types.ts +12 -1
- package/src/index.ts +13 -0
- package/src/libraries/files.generated.ts +8 -0
- package/src/libraries/libraries.ts +64 -0
- package/src/mcp/adapter.ts +40 -2
- package/src/presets/presets.ts +46 -3
- package/src/protocol/live-data.ts +138 -0
- package/src/protocol/mcp-apps.ts +12 -0
- package/src/protocol/shell-adapter.ts +35 -3
- package/src/react/dialog.tsx +2 -0
- package/src/react/frame.tsx +54 -0
- package/src/server/libraries.ts +28 -0
- package/src/server/server.ts +2 -1
- package/src/shell/annotate.ts +4 -1
- 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
|
+
}
|
package/dist/server/server.js
CHANGED
|
@@ -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
|
}
|
package/dist/shell/annotate.js
CHANGED
|
@@ -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
|
-
|
|
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");
|
package/dist/shell/runtime.d.ts
CHANGED
|
@@ -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
|
*
|
package/dist/shell/runtime.js
CHANGED
|
@@ -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 |
|
|
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
|
|
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.
|
|
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",
|