@botiverse/porthole 0.4.1 → 0.5.1
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 +24 -2
- package/dist/bridge/bridge.js +102 -17
- package/dist/bridge/navigation.d.ts +11 -0
- package/dist/bridge/navigation.js +30 -0
- package/dist/bridge/refusal.d.ts +53 -0
- package/dist/bridge/refusal.js +121 -0
- package/dist/bridge/types.d.ts +51 -6
- package/dist/check/lint.js +2 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +10 -0
- package/dist/compile/policy.d.ts +5 -0
- package/dist/compile/policy.js +18 -1
- package/dist/config/capabilities.d.ts +30 -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 +58 -8
- package/dist/host/create-host.js +18 -3
- package/dist/host/types.d.ts +25 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.js +4 -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 +49 -5
- 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 +15 -0
- package/dist/protocol/mcp-apps.js +17 -0
- package/dist/protocol/shell-adapter.js +49 -4
- package/dist/react/dialog.js +2 -0
- package/dist/react/frame.d.ts +30 -1
- package/dist/react/frame.js +63 -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/runtime.d.ts +5 -1
- package/dist/shell/runtime.js +196 -6
- package/docs/ADOPTING.md +89 -3
- package/docs/DECISIONS.md +221 -0
- package/docs/DESIGN.md +28 -10
- package/package.json +3 -1
- package/src/bridge/bridge.ts +136 -16
- package/src/bridge/navigation.ts +34 -0
- package/src/bridge/refusal.ts +151 -0
- package/src/bridge/types.ts +57 -4
- package/src/check/lint.ts +2 -1
- package/src/check/page.ts +12 -0
- package/src/compile/policy.ts +19 -1
- package/src/config/capabilities.ts +26 -1
- 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 +71 -7
- package/src/host/create-host.ts +19 -3
- package/src/host/types.ts +23 -1
- package/src/index.ts +22 -0
- package/src/libraries/files.generated.ts +8 -0
- package/src/libraries/libraries.ts +64 -0
- package/src/mcp/adapter.ts +63 -5
- package/src/presets/presets.ts +46 -3
- package/src/protocol/live-data.ts +138 -0
- package/src/protocol/mcp-apps.ts +19 -0
- package/src/protocol/shell-adapter.ts +50 -5
- package/src/react/dialog.tsx +2 -0
- package/src/react/frame.tsx +93 -0
- package/src/server/libraries.ts +28 -0
- package/src/server/server.ts +2 -1
- package/src/shell/runtime.ts +196 -6
package/dist/check/page.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { capabilitySpec, isCapabilityName, } from "../config/capabilities.js";
|
|
2
|
+
import { addressWithoutQuery } from "../bridge/navigation.js";
|
|
2
3
|
import { createHost } from "../host/create-host.js";
|
|
3
4
|
import { webPlatform } from "../platform/web.js";
|
|
4
5
|
import { contentLine, instrumented, } from "./instrument.js";
|
|
@@ -18,6 +19,9 @@ const DECLINED = {
|
|
|
18
19
|
readData: () => {
|
|
19
20
|
throw new Error("The host declined the read");
|
|
20
21
|
},
|
|
22
|
+
subscribeData: () => {
|
|
23
|
+
throw new Error("The host declined the subscription");
|
|
24
|
+
},
|
|
21
25
|
};
|
|
22
26
|
/**
|
|
23
27
|
* The web platform, with no person on the page: no call comes from a click (P078). The driver's
|
|
@@ -110,6 +114,8 @@ const check = {
|
|
|
110
114
|
handlers: declining(Object.keys(spec.config.capabilities), calls),
|
|
111
115
|
platform: NOBODY,
|
|
112
116
|
confirm: () => Promise.resolve("declined"),
|
|
117
|
+
// A viewer who doesn't allow a live widget their data (P079): its calls are refused.
|
|
118
|
+
consent: () => false,
|
|
113
119
|
// A served config's instance, issued by the check's own server on this page's origin.
|
|
114
120
|
locator: {
|
|
115
121
|
locate: async (instance) => (await (await fetch("/issue", { method: "POST", body: JSON.stringify({ instance }) })).json()),
|
|
@@ -145,6 +151,10 @@ const check = {
|
|
|
145
151
|
calls.push({ capability, outcome: refusal });
|
|
146
152
|
}
|
|
147
153
|
});
|
|
154
|
+
// A navigation the shell stopped (P080): the content tried to leave its page.
|
|
155
|
+
display.on("navigationBlocked", ({ url }) => {
|
|
156
|
+
run.data.errors.push(`It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page`);
|
|
157
|
+
});
|
|
148
158
|
display.on("outcome", (outcome) => {
|
|
149
159
|
run.data.outcome = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
|
|
150
160
|
});
|
package/dist/compile/policy.d.ts
CHANGED
|
@@ -18,6 +18,11 @@ export declare function effectiveGates(config: PortholeConfig, name: CapabilityN
|
|
|
18
18
|
export declare function egressOrigins(config: PortholeConfig, kind: EgressKind): string[];
|
|
19
19
|
/** Every origin content may reach, of any kind. */
|
|
20
20
|
export declare function allEgressOrigins(config: PortholeConfig): string[];
|
|
21
|
+
/**
|
|
22
|
+
* Where Porthole's vendored libraries load from (`egress.libraries`, P079): their path on the
|
|
23
|
+
* content origins, so the frame's own, path-limited (nothing else served there runs as a script).
|
|
24
|
+
*/
|
|
25
|
+
export declare function librarySources(config: PortholeConfig): string[];
|
|
21
26
|
/**
|
|
22
27
|
* The frame's CSP directives. Closed by default: `default-src 'none'`, and each kind opened only
|
|
23
28
|
* to the config's origins. Inline code runs (agent content is inline), so the walls are origin
|
package/dist/compile/policy.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { CAPABILITIES } from "../config/capabilities.js";
|
|
2
|
+
import { LIBRARY_PATH } from "../libraries/libraries.js";
|
|
2
3
|
/** Whether `kind` loads from any https site (`EgressConfig.anyHttps`, P059): passive kinds only. */
|
|
3
4
|
export function anyHttps(config, kind) {
|
|
4
5
|
return (config.egress.anyHttps ?? []).some((each) => each === kind);
|
|
@@ -25,6 +26,15 @@ export function allEgressOrigins(config) {
|
|
|
25
26
|
const kinds = ["connect", "script", "style", "img", "font", "media"];
|
|
26
27
|
return unique(kinds.flatMap((kind) => egressOrigins(config, kind)));
|
|
27
28
|
}
|
|
29
|
+
/**
|
|
30
|
+
* Where Porthole's vendored libraries load from (`egress.libraries`, P079): their path on the
|
|
31
|
+
* content origins, so the frame's own, path-limited (nothing else served there runs as a script).
|
|
32
|
+
*/
|
|
33
|
+
export function librarySources(config) {
|
|
34
|
+
return config.egress.libraries === true && config.isolation === "domain"
|
|
35
|
+
? config.contentOrigins.map((origin) => `${origin}${LIBRARY_PATH}`)
|
|
36
|
+
: [];
|
|
37
|
+
}
|
|
28
38
|
const list = (sources) => sources.length === 0 ? ["'none'"] : [...sources];
|
|
29
39
|
/**
|
|
30
40
|
* The frame's CSP directives. Closed by default: `default-src 'none'`, and each kind opened only
|
|
@@ -42,7 +52,14 @@ export function frameCspDirectives(config) {
|
|
|
42
52
|
const https = (kind) => (anyHttps(config, kind) ? ["https:"] : []);
|
|
43
53
|
return [
|
|
44
54
|
["default-src", "'none'"],
|
|
45
|
-
[
|
|
55
|
+
[
|
|
56
|
+
"script-src",
|
|
57
|
+
"'unsafe-inline'",
|
|
58
|
+
"'unsafe-eval'",
|
|
59
|
+
"blob:",
|
|
60
|
+
...origins("script"),
|
|
61
|
+
...librarySources(config),
|
|
62
|
+
],
|
|
46
63
|
["style-src", "'unsafe-inline'", ...origins("style")],
|
|
47
64
|
["font-src", "data:", ...https("font"), ...origins("font")],
|
|
48
65
|
["img-src", "data:", "blob:", ...https("img"), ...origins("img")],
|
|
@@ -8,7 +8,7 @@ import type { AnnotationReport } from "../annotate/types.ts";
|
|
|
8
8
|
* are on by default), and is served either by a handler the host passes or as an event the
|
|
9
9
|
* framework emits.
|
|
10
10
|
*/
|
|
11
|
-
export declare const CAPABILITY_NAMES: readonly ["sendPrompt", "openLink", "downloadFile", "callTool", "readData", "setModelContext", "reportError", "resize", "copyText", "annotate"];
|
|
11
|
+
export declare const CAPABILITY_NAMES: readonly ["sendPrompt", "openLink", "downloadFile", "callTool", "readData", "subscribeData", "setModelContext", "reportError", "resize", "copyText", "annotate"];
|
|
12
12
|
export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
13
13
|
/**
|
|
14
14
|
* What must hold before a call reaches the host's handler. A capability's gates all apply.
|
|
@@ -19,8 +19,12 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
|
19
19
|
* - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
|
|
20
20
|
* goes only if they accept. No `confirm` function means the call is refused (fail closed).
|
|
21
21
|
* - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
|
|
22
|
+
* - `consent` (P079): the host's `consent` function is asked once per display, before the first
|
|
23
|
+
* call of any of its consent-gated capabilities, whether this content may have them (a viewer
|
|
24
|
+
* allowing a widget to read their data). A no refuses every such call for the display's life;
|
|
25
|
+
* no `consent` function refuses them all (fail closed).
|
|
22
26
|
*/
|
|
23
|
-
export type Gate = "user-activation" | "confirm" | {
|
|
27
|
+
export type Gate = "user-activation" | "confirm" | "consent" | {
|
|
24
28
|
readonly rateLimit: {
|
|
25
29
|
readonly perMinute: number;
|
|
26
30
|
};
|
|
@@ -82,11 +86,25 @@ export declare const CAPABILITIES: {
|
|
|
82
86
|
readonly readData: {
|
|
83
87
|
readonly defaultGates: readonly [Gate];
|
|
84
88
|
readonly served: "handler";
|
|
89
|
+
readonly global: "readData";
|
|
85
90
|
readonly request: {
|
|
86
91
|
readonly method: "resources/read";
|
|
87
92
|
readonly sdk: "app.readServerResource";
|
|
88
93
|
};
|
|
89
94
|
};
|
|
95
|
+
/**
|
|
96
|
+
* Live data (P079): content subscribes to a resource and the host tells it when it changed
|
|
97
|
+
* (MCP `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`);
|
|
98
|
+
* it then reads it again (`readData`, which it needs). The App SDK has no method for it.
|
|
99
|
+
*/
|
|
100
|
+
readonly subscribeData: {
|
|
101
|
+
readonly defaultGates: readonly [Gate];
|
|
102
|
+
readonly served: "handler";
|
|
103
|
+
readonly global: "subscribeData";
|
|
104
|
+
readonly request: {
|
|
105
|
+
readonly method: "resources/subscribe";
|
|
106
|
+
};
|
|
107
|
+
};
|
|
90
108
|
readonly setModelContext: {
|
|
91
109
|
readonly defaultGates: readonly [Gate];
|
|
92
110
|
readonly served: "handler";
|
|
@@ -144,12 +162,20 @@ export interface CapabilityArgs {
|
|
|
144
162
|
readonly readData: {
|
|
145
163
|
readonly uri: string;
|
|
146
164
|
};
|
|
165
|
+
readonly subscribeData: {
|
|
166
|
+
readonly uri: string;
|
|
167
|
+
};
|
|
147
168
|
readonly setModelContext: {
|
|
148
169
|
readonly content?: readonly unknown[];
|
|
149
170
|
readonly structuredContent?: Readonly<Record<string, unknown>>;
|
|
150
171
|
};
|
|
172
|
+
/**
|
|
173
|
+
* `navigationBlocked`: the address a navigation of the frame went to when the shell cancelled it
|
|
174
|
+
* (P080), the content's word; `message` is then Porthole's, which names it without its query.
|
|
175
|
+
*/
|
|
151
176
|
readonly reportError: {
|
|
152
177
|
readonly message: string;
|
|
178
|
+
readonly navigationBlocked?: string;
|
|
153
179
|
};
|
|
154
180
|
readonly resize: {
|
|
155
181
|
readonly height: number;
|
|
@@ -170,7 +196,9 @@ export interface CapabilityResults {
|
|
|
170
196
|
/** Whether the download started. */
|
|
171
197
|
readonly downloadFile: boolean;
|
|
172
198
|
readonly callTool: unknown;
|
|
199
|
+
/** An MCP `resources/read` result (`{ contents }`), as the host answers it. */
|
|
173
200
|
readonly readData: unknown;
|
|
201
|
+
readonly subscribeData: undefined;
|
|
174
202
|
readonly setModelContext: undefined;
|
|
175
203
|
readonly reportError: undefined;
|
|
176
204
|
readonly resize: undefined;
|
|
@@ -13,6 +13,7 @@ export const CAPABILITY_NAMES = [
|
|
|
13
13
|
"downloadFile",
|
|
14
14
|
"callTool",
|
|
15
15
|
"readData",
|
|
16
|
+
"subscribeData",
|
|
16
17
|
"setModelContext",
|
|
17
18
|
"reportError",
|
|
18
19
|
"resize",
|
|
@@ -48,8 +49,20 @@ export const CAPABILITIES = {
|
|
|
48
49
|
readData: {
|
|
49
50
|
defaultGates: [rate(120)],
|
|
50
51
|
served: "handler",
|
|
52
|
+
global: "readData",
|
|
51
53
|
request: { method: "resources/read", sdk: "app.readServerResource" },
|
|
52
54
|
},
|
|
55
|
+
/**
|
|
56
|
+
* Live data (P079): content subscribes to a resource and the host tells it when it changed
|
|
57
|
+
* (MCP `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`);
|
|
58
|
+
* it then reads it again (`readData`, which it needs). The App SDK has no method for it.
|
|
59
|
+
*/
|
|
60
|
+
subscribeData: {
|
|
61
|
+
defaultGates: [rate(60)],
|
|
62
|
+
served: "handler",
|
|
63
|
+
global: "subscribeData",
|
|
64
|
+
request: { method: "resources/subscribe" },
|
|
65
|
+
},
|
|
53
66
|
setModelContext: {
|
|
54
67
|
defaultGates: [rate(30)],
|
|
55
68
|
served: "handler",
|
package/dist/config/schema.d.ts
CHANGED
|
@@ -64,6 +64,13 @@ export interface EgressConfig {
|
|
|
64
64
|
* address and a visit signal reach any site, and data can leave in the URL.
|
|
65
65
|
*/
|
|
66
66
|
readonly anyHttps?: readonly PassiveKind[];
|
|
67
|
+
/**
|
|
68
|
+
* Porthole's own copies of a few libraries (`VENDORED_LIBRARIES`: Chart.js, D3), served from the
|
|
69
|
+
* frame's own origin under `/__porthole/lib/` (P079): domain isolation only. They open no
|
|
70
|
+
* channel out: the requests reach the content server, which serves fixed files, so a display
|
|
71
|
+
* with no network of its own (`presets.liveWidget`) still draws charts.
|
|
72
|
+
*/
|
|
73
|
+
readonly libraries?: boolean;
|
|
67
74
|
}
|
|
68
75
|
/** What `EgressConfig.anyHttps` may open: content that runs nothing (P059). */
|
|
69
76
|
export declare const PASSIVE_KINDS: readonly ["img", "media", "font"];
|
package/dist/config/validate.js
CHANGED
|
@@ -229,12 +229,12 @@ function positive(value, path, max = Number.MAX_SAFE_INTEGER) {
|
|
|
229
229
|
}
|
|
230
230
|
}
|
|
231
231
|
function gate(value, path) {
|
|
232
|
-
if (value === "user-activation" || value === "confirm") {
|
|
232
|
+
if (value === "user-activation" || value === "confirm" || value === "consent") {
|
|
233
233
|
return;
|
|
234
234
|
}
|
|
235
235
|
const limit = isObject(value) && isObject(value.rateLimit) ? value.rateLimit : null;
|
|
236
236
|
if (limit === null || Object.keys(value).length !== 1) {
|
|
237
|
-
fail(path, 'must be "user-activation", "confirm" or { rateLimit: { perMinute } }');
|
|
237
|
+
fail(path, 'must be "user-activation", "confirm", "consent" or { rateLimit: { perMinute } }');
|
|
238
238
|
return;
|
|
239
239
|
}
|
|
240
240
|
only(limit, ["perMinute"], `${path}.rateLimit`);
|
|
@@ -295,7 +295,7 @@ export function validateConfig(input) {
|
|
|
295
295
|
}
|
|
296
296
|
const egress = object(config.egress, "config.egress");
|
|
297
297
|
const kinds = ["connect", "script", "style", "img", "font", "media"];
|
|
298
|
-
only(egress, [...kinds, "anyHttps"], "config.egress");
|
|
298
|
+
only(egress, [...kinds, "anyHttps", "libraries"], "config.egress");
|
|
299
299
|
for (const kind of kinds) {
|
|
300
300
|
sources(egress[kind], `config.egress.${kind}`);
|
|
301
301
|
}
|
|
@@ -312,6 +312,17 @@ export function validateConfig(input) {
|
|
|
312
312
|
fail("config.egress.anyHttps", "url mode has no egress control");
|
|
313
313
|
}
|
|
314
314
|
}
|
|
315
|
+
if (egress.libraries !== undefined) {
|
|
316
|
+
if (typeof egress.libraries !== "boolean") {
|
|
317
|
+
fail("config.egress.libraries", "must be true or false");
|
|
318
|
+
}
|
|
319
|
+
if (egress.libraries && config.isolation !== "domain") {
|
|
320
|
+
fail("config.egress.libraries", "Porthole's libraries are served from the frame's own origin: domain isolation only");
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
if (capabilities.subscribeData !== undefined && capabilities.readData === undefined) {
|
|
324
|
+
fail("config.capabilities.subscribeData", "needs readData: content reads a resource again when it is told it changed");
|
|
325
|
+
}
|
|
315
326
|
const theme = object(config.theme, "config.theme");
|
|
316
327
|
only(theme, ["variables", "event", "documents"], "config.theme");
|
|
317
328
|
if (theme.documents !== undefined &&
|
|
@@ -51,6 +51,7 @@ function recorder(calls) {
|
|
|
51
51
|
downloadFile: record("downloadFile", true),
|
|
52
52
|
callTool: record("callTool", { content: [] }),
|
|
53
53
|
readData: record("readData", { contents: [] }),
|
|
54
|
+
subscribeData: record("subscribeData", undefined),
|
|
54
55
|
setModelContext: record("setModelContext", undefined),
|
|
55
56
|
copyText: record("copyText", true),
|
|
56
57
|
};
|