@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.
Files changed (77) hide show
  1. package/README.md +3 -1
  2. package/dist/bridge/bridge.d.ts +24 -2
  3. package/dist/bridge/bridge.js +102 -17
  4. package/dist/bridge/navigation.d.ts +11 -0
  5. package/dist/bridge/navigation.js +30 -0
  6. package/dist/bridge/refusal.d.ts +53 -0
  7. package/dist/bridge/refusal.js +121 -0
  8. package/dist/bridge/types.d.ts +51 -6
  9. package/dist/check/lint.js +2 -2
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/page.js +10 -0
  12. package/dist/compile/policy.d.ts +5 -0
  13. package/dist/compile/policy.js +18 -1
  14. package/dist/config/capabilities.d.ts +30 -2
  15. package/dist/config/capabilities.js +13 -0
  16. package/dist/config/schema.d.ts +7 -0
  17. package/dist/config/validate.js +14 -3
  18. package/dist/conformance/harness/page.js +1 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/displays/displays.d.ts +1 -1
  21. package/dist/guide/guide.js +58 -8
  22. package/dist/host/create-host.js +18 -3
  23. package/dist/host/types.d.ts +25 -1
  24. package/dist/index.d.ts +5 -3
  25. package/dist/index.js +4 -1
  26. package/dist/libraries/files.generated.d.ts +1 -0
  27. package/dist/libraries/files.generated.js +8 -0
  28. package/dist/libraries/libraries.d.ts +36 -0
  29. package/dist/libraries/libraries.js +40 -0
  30. package/dist/mcp/adapter.js +49 -5
  31. package/dist/presets/presets.d.ts +15 -0
  32. package/dist/presets/presets.js +27 -2
  33. package/dist/protocol/live-data.d.ts +27 -0
  34. package/dist/protocol/live-data.js +98 -0
  35. package/dist/protocol/mcp-apps.d.ts +15 -0
  36. package/dist/protocol/mcp-apps.js +17 -0
  37. package/dist/protocol/shell-adapter.js +49 -4
  38. package/dist/react/dialog.js +2 -0
  39. package/dist/react/frame.d.ts +30 -1
  40. package/dist/react/frame.js +63 -1
  41. package/dist/server/libraries.d.ts +7 -0
  42. package/dist/server/libraries.js +27 -0
  43. package/dist/server/server.js +2 -1
  44. package/dist/shell/runtime.d.ts +5 -1
  45. package/dist/shell/runtime.js +196 -6
  46. package/docs/ADOPTING.md +89 -3
  47. package/docs/DECISIONS.md +221 -0
  48. package/docs/DESIGN.md +28 -10
  49. package/package.json +3 -1
  50. package/src/bridge/bridge.ts +136 -16
  51. package/src/bridge/navigation.ts +34 -0
  52. package/src/bridge/refusal.ts +151 -0
  53. package/src/bridge/types.ts +57 -4
  54. package/src/check/lint.ts +2 -1
  55. package/src/check/page.ts +12 -0
  56. package/src/compile/policy.ts +19 -1
  57. package/src/config/capabilities.ts +26 -1
  58. package/src/config/schema.ts +7 -0
  59. package/src/config/validate.ts +21 -3
  60. package/src/conformance/harness/page.ts +1 -0
  61. package/src/displays/displays.ts +1 -1
  62. package/src/guide/guide.ts +71 -7
  63. package/src/host/create-host.ts +19 -3
  64. package/src/host/types.ts +23 -1
  65. package/src/index.ts +22 -0
  66. package/src/libraries/files.generated.ts +8 -0
  67. package/src/libraries/libraries.ts +64 -0
  68. package/src/mcp/adapter.ts +63 -5
  69. package/src/presets/presets.ts +46 -3
  70. package/src/protocol/live-data.ts +138 -0
  71. package/src/protocol/mcp-apps.ts +19 -0
  72. package/src/protocol/shell-adapter.ts +50 -5
  73. package/src/react/dialog.tsx +2 -0
  74. package/src/react/frame.tsx +93 -0
  75. package/src/server/libraries.ts +28 -0
  76. package/src/server/server.ts +2 -1
  77. package/src/shell/runtime.ts +196 -6
@@ -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
  });
@@ -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
@@ -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
- ["script-src", "'unsafe-inline'", "'unsafe-eval'", "blob:", ...origins("script")],
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",
@@ -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"];
@@ -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
  };