@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/src/shell/document.ts
CHANGED
|
@@ -31,6 +31,41 @@ export interface ShellDocumentOptions {
|
|
|
31
31
|
* every script the shell runs for the content. The frame can read it.
|
|
32
32
|
*/
|
|
33
33
|
readonly nonce?: string;
|
|
34
|
+
/**
|
|
35
|
+
* A page that comes with files (P081, P084): the absolute URL its version's files are under
|
|
36
|
+
* (`https://a-x.example-usercontent.com/v/3/`). The shell lets the frame navigate to the set's
|
|
37
|
+
* other pages there, and to nothing else.
|
|
38
|
+
*/
|
|
39
|
+
readonly files?: {
|
|
40
|
+
readonly base: string;
|
|
41
|
+
/**
|
|
42
|
+
* The page's own address under `base`, where the request's isn't it (a ticket's answer, P083):
|
|
43
|
+
* the shell puts it in the frame's history first, before anything loads, so the page's
|
|
44
|
+
* relative addresses are its files' and the spent ticket leaves the address.
|
|
45
|
+
*/
|
|
46
|
+
readonly address?: string;
|
|
47
|
+
/**
|
|
48
|
+
* When a sealed address stops opening the page's files on its own (epoch ms, P083): the shell
|
|
49
|
+
* renews it before then, at `<base>__porthole/renew`, and moves the page there.
|
|
50
|
+
*/
|
|
51
|
+
readonly expires?: number;
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** A file set's base: an absolute http(s) URL that ends in `/`, no query or fragment. */
|
|
56
|
+
function filesBaseOk(base: string): boolean {
|
|
57
|
+
try {
|
|
58
|
+
const url = new URL(base);
|
|
59
|
+
return (
|
|
60
|
+
(url.protocol === "https:" || url.protocol === "http:") &&
|
|
61
|
+
url.href === base &&
|
|
62
|
+
base.endsWith("/") &&
|
|
63
|
+
url.search === "" &&
|
|
64
|
+
url.hash === ""
|
|
65
|
+
);
|
|
66
|
+
} catch {
|
|
67
|
+
return false;
|
|
68
|
+
}
|
|
34
69
|
}
|
|
35
70
|
|
|
36
71
|
/** A CSP nonce: base64 or base64url characters, 8 to 256 of them. */
|
|
@@ -98,6 +133,15 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
|
|
|
98
133
|
if (options.nonce !== undefined && !NONCE.test(options.nonce)) {
|
|
99
134
|
throw new TypeError("shellDocument: a nonce is 8 to 256 base64 characters");
|
|
100
135
|
}
|
|
136
|
+
if (options.files !== undefined && !filesBaseOk(options.files.base)) {
|
|
137
|
+
throw new TypeError("shellDocument: files.base is an http(s) URL ending in /, with no query");
|
|
138
|
+
}
|
|
139
|
+
if (
|
|
140
|
+
options.files?.address !== undefined &&
|
|
141
|
+
(!options.files.address.startsWith(options.files.base) || /[?#]/u.test(options.files.address))
|
|
142
|
+
) {
|
|
143
|
+
throw new TypeError("shellDocument: files.address is under files.base, with no query");
|
|
144
|
+
}
|
|
101
145
|
const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
|
|
102
146
|
// The annotation runtime only where it is declared; spliced in before the plan, which may carry
|
|
103
147
|
// any text (a document) and must not be searched.
|
|
@@ -108,6 +152,15 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
|
|
|
108
152
|
...plan,
|
|
109
153
|
origins: options.origins,
|
|
110
154
|
...(options.document === undefined ? {} : { document: options.document }),
|
|
155
|
+
...(options.files === undefined
|
|
156
|
+
? {}
|
|
157
|
+
: {
|
|
158
|
+
files: {
|
|
159
|
+
base: options.files.base,
|
|
160
|
+
...(options.files.address === undefined ? {} : { address: options.files.address }),
|
|
161
|
+
...(options.files.expires === undefined ? {} : { expires: options.files.expires }),
|
|
162
|
+
},
|
|
163
|
+
}),
|
|
111
164
|
}),
|
|
112
165
|
);
|
|
113
166
|
const head = [
|
package/src/shell/runtime.ts
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
|
}
|