@botiverse/porthole 0.6.0 → 0.8.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.
Files changed (208) hide show
  1. package/README.md +25 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/bridge/bounded-text.d.ts +34 -0
  4. package/dist/bridge/bounded-text.js +188 -0
  5. package/dist/bridge/bridge.d.ts +38 -5
  6. package/dist/bridge/bridge.js +469 -39
  7. package/dist/bridge/json-data.d.ts +28 -0
  8. package/dist/bridge/json-data.js +86 -0
  9. package/dist/bridge/navigation.d.ts +5 -0
  10. package/dist/bridge/navigation.js +7 -0
  11. package/dist/bridge/refusal.d.ts +5 -1
  12. package/dist/bridge/refusal.js +17 -0
  13. package/dist/bridge/types.d.ts +73 -5
  14. package/dist/check/check.d.ts +7 -0
  15. package/dist/check/check.js +1 -0
  16. package/dist/check/instrument.d.ts +3 -0
  17. package/dist/check/lint.js +4 -2
  18. package/dist/check/page-source.js +1 -1
  19. package/dist/check/page.js +16 -0
  20. package/dist/check/tools.js +2 -3
  21. package/dist/compile/compile.d.ts +6 -0
  22. package/dist/compile/compile.js +3 -1
  23. package/dist/compile/policy.d.ts +55 -0
  24. package/dist/compile/policy.js +157 -0
  25. package/dist/config/capabilities.d.ts +85 -7
  26. package/dist/config/capabilities.js +32 -2
  27. package/dist/config/schema.d.ts +35 -0
  28. package/dist/config/validate.d.ts +9 -3
  29. package/dist/config/validate.js +92 -8
  30. package/dist/config/warnings.d.ts +20 -0
  31. package/dist/config/warnings.js +25 -0
  32. package/dist/conformance/behavior.js +46 -1
  33. package/dist/conformance/cookies.d.ts +15 -0
  34. package/dist/conformance/cookies.js +80 -0
  35. package/dist/conformance/harness/page.d.ts +1 -0
  36. package/dist/conformance/harness/page.js +9 -2
  37. package/dist/conformance/harness-source.js +1 -1
  38. package/dist/conformance/host-kit.js +5 -1
  39. package/dist/conformance/index.d.ts +11 -0
  40. package/dist/conformance/index.js +2 -0
  41. package/dist/conformance/limits.js +38 -1
  42. package/dist/conformance/runtime.d.ts +58 -0
  43. package/dist/conformance/runtime.js +324 -0
  44. package/dist/conformance/served.d.ts +2 -0
  45. package/dist/conformance/served.js +737 -4
  46. package/dist/files/paths.js +4 -0
  47. package/dist/guide/gates.d.ts +9 -0
  48. package/dist/guide/gates.js +31 -0
  49. package/dist/guide/guide.d.ts +2 -0
  50. package/dist/guide/guide.js +35 -33
  51. package/dist/guide/limits.js +4 -4
  52. package/dist/guide/runtime.d.ts +13 -0
  53. package/dist/guide/runtime.js +210 -0
  54. package/dist/host/create-host.js +73 -37
  55. package/dist/host/locate.js +8 -0
  56. package/dist/host/locator.js +7 -0
  57. package/dist/host/pages-of-set.d.ts +43 -0
  58. package/dist/host/pages-of-set.js +196 -0
  59. package/dist/host/types.d.ts +26 -1
  60. package/dist/index.d.ts +11 -4
  61. package/dist/index.js +11 -2
  62. package/dist/isolation/types.d.ts +8 -0
  63. package/dist/mcp/adapter.js +11 -15
  64. package/dist/node/index.d.ts +36 -4
  65. package/dist/node/index.js +402 -101
  66. package/dist/presets/presets.d.ts +22 -8
  67. package/dist/presets/presets.js +40 -8
  68. package/dist/protocol/live-data.d.ts +6 -2
  69. package/dist/protocol/live-data.js +20 -1
  70. package/dist/protocol/mcp-apps.d.ts +13 -2
  71. package/dist/protocol/mcp-apps.js +10 -2
  72. package/dist/protocol/message-text.d.ts +8 -0
  73. package/dist/protocol/message-text.js +29 -0
  74. package/dist/protocol/runtime-calls.d.ts +28 -0
  75. package/dist/protocol/runtime-calls.js +116 -0
  76. package/dist/protocol/shell-adapter.js +64 -25
  77. package/dist/react/context-notice.d.ts +32 -0
  78. package/dist/react/context-notice.js +28 -0
  79. package/dist/react/dialog.js +91 -16
  80. package/dist/react/frame.d.ts +25 -1
  81. package/dist/react/frame.js +85 -2
  82. package/dist/react/index.d.ts +2 -1
  83. package/dist/react/index.js +2 -1
  84. package/dist/runtime/contract.d.ts +201 -0
  85. package/dist/runtime/contract.js +245 -0
  86. package/dist/runtime/db.d.ts +188 -0
  87. package/dist/runtime/db.js +502 -0
  88. package/dist/runtime/declaration.d.ts +100 -0
  89. package/dist/runtime/declaration.js +363 -0
  90. package/dist/runtime/levels.d.ts +33 -0
  91. package/dist/runtime/levels.js +41 -0
  92. package/dist/runtime/requests.d.ts +125 -0
  93. package/dist/runtime/requests.js +215 -0
  94. package/dist/runtime/segments.d.ts +8 -0
  95. package/dist/runtime/segments.js +14 -0
  96. package/dist/runtime/types.generated.d.ts +1 -0
  97. package/dist/runtime/types.generated.js +19 -0
  98. package/dist/server/files.d.ts +19 -1
  99. package/dist/server/files.js +115 -6
  100. package/dist/server/host.d.ts +24 -2
  101. package/dist/server/host.js +137 -2
  102. package/dist/server/index.d.ts +3 -2
  103. package/dist/server/index.js +2 -1
  104. package/dist/server/peer.d.ts +4 -0
  105. package/dist/server/peer.js +19 -0
  106. package/dist/server/proxy.d.ts +6 -0
  107. package/dist/server/proxy.js +12 -3
  108. package/dist/server/pseudonym.d.ts +9 -0
  109. package/dist/server/pseudonym.js +20 -0
  110. package/dist/server/server.d.ts +0 -5
  111. package/dist/server/server.js +318 -52
  112. package/dist/server/types.d.ts +74 -2
  113. package/dist/shell/document.d.ts +16 -0
  114. package/dist/shell/document.js +19 -2
  115. package/dist/shell/legacy.d.ts +21 -0
  116. package/dist/shell/legacy.js +63 -0
  117. package/dist/shell/plan.d.ts +17 -1
  118. package/dist/shell/plan.js +13 -2
  119. package/dist/shell/runtime.js +390 -56
  120. package/dist/shell/use.d.ts +15 -0
  121. package/dist/shell/use.js +235 -0
  122. package/docs/ADOPTING.md +205 -15
  123. package/docs/ARCHITECTURE.md +34 -5
  124. package/docs/DECISIONS.md +1867 -11
  125. package/docs/DESIGN.md +137 -17
  126. package/docs/THREAT_MODEL.md +616 -0
  127. package/package.json +16 -3
  128. package/src/bridge/bounded-text.ts +240 -0
  129. package/src/bridge/bridge.ts +601 -51
  130. package/src/bridge/json-data.ts +95 -0
  131. package/src/bridge/navigation.ts +10 -0
  132. package/src/bridge/refusal.ts +17 -0
  133. package/src/bridge/types.ts +76 -5
  134. package/src/check/check.ts +8 -0
  135. package/src/check/instrument.ts +3 -0
  136. package/src/check/lint.ts +4 -2
  137. package/src/check/page.ts +16 -0
  138. package/src/check/tools.ts +2 -3
  139. package/src/compile/compile.ts +9 -1
  140. package/src/compile/policy.ts +177 -0
  141. package/src/config/capabilities.ts +71 -5
  142. package/src/config/schema.ts +35 -0
  143. package/src/config/validate.ts +141 -8
  144. package/src/config/warnings.ts +42 -0
  145. package/src/conformance/behavior.ts +54 -1
  146. package/src/conformance/cookies.ts +93 -0
  147. package/src/conformance/harness/page.ts +11 -2
  148. package/src/conformance/host-kit.ts +10 -1
  149. package/src/conformance/index.ts +17 -0
  150. package/src/conformance/limits.ts +39 -1
  151. package/src/conformance/runtime.ts +594 -0
  152. package/src/conformance/served.ts +888 -4
  153. package/src/files/paths.ts +4 -0
  154. package/src/guide/gates.ts +37 -0
  155. package/src/guide/guide.ts +61 -55
  156. package/src/guide/limits.ts +4 -4
  157. package/src/guide/runtime.ts +253 -0
  158. package/src/host/create-host.ts +88 -36
  159. package/src/host/locate.ts +10 -0
  160. package/src/host/locator.ts +11 -0
  161. package/src/host/pages-of-set.ts +226 -0
  162. package/src/host/types.ts +33 -1
  163. package/src/index.ts +94 -0
  164. package/src/isolation/types.ts +8 -0
  165. package/src/mcp/adapter.ts +16 -20
  166. package/src/node/index.ts +507 -116
  167. package/src/presets/presets.ts +67 -17
  168. package/src/protocol/live-data.ts +31 -3
  169. package/src/protocol/mcp-apps.ts +11 -2
  170. package/src/protocol/message-text.ts +36 -0
  171. package/src/protocol/runtime-calls.ts +141 -0
  172. package/src/protocol/shell-adapter.ts +79 -26
  173. package/src/react/context-notice.tsx +95 -0
  174. package/src/react/dialog.tsx +108 -15
  175. package/src/react/frame.tsx +120 -0
  176. package/src/react/index.ts +8 -1
  177. package/src/runtime/contract.ts +339 -0
  178. package/src/runtime/db.ts +650 -0
  179. package/src/runtime/declaration.ts +516 -0
  180. package/src/runtime/levels.ts +69 -0
  181. package/src/runtime/requests.ts +355 -0
  182. package/src/runtime/segments.ts +17 -0
  183. package/src/runtime/types.generated.ts +19 -0
  184. package/src/server/files.ts +138 -7
  185. package/src/server/host.ts +170 -3
  186. package/src/server/index.ts +4 -0
  187. package/src/server/peer.ts +21 -0
  188. package/src/server/proxy.ts +13 -3
  189. package/src/server/pseudonym.ts +21 -0
  190. package/src/server/server.ts +370 -57
  191. package/src/server/types.ts +73 -2
  192. package/src/shell/document.ts +29 -4
  193. package/src/shell/legacy.ts +64 -0
  194. package/src/shell/plan.ts +37 -3
  195. package/src/shell/runtime.ts +390 -56
  196. package/src/shell/use.ts +235 -0
  197. package/types/runtime/v1/artifact.d.ts +50 -0
  198. package/types/runtime/v1/assets.d.ts +43 -0
  199. package/types/runtime/v1/chat.d.ts +13 -0
  200. package/types/runtime/v1/clipboard.d.ts +14 -0
  201. package/types/runtime/v1/comments.d.ts +24 -0
  202. package/types/runtime/v1/context.d.ts +27 -0
  203. package/types/runtime/v1/data.d.ts +29 -0
  204. package/types/runtime/v1/db.d.ts +110 -0
  205. package/types/runtime/v1/downloads.d.ts +22 -0
  206. package/types/runtime/v1/links.d.ts +13 -0
  207. package/types/runtime/v1/porthole.d.ts +44 -0
  208. package/types/runtime/v1/user.d.ts +19 -0
@@ -32,6 +32,8 @@ export interface ShellDocumentOptions {
32
32
  * (`https://a-x.example-usercontent.com/v/3/`). The shell lets the frame navigate to the set's
33
33
  * other pages there, and to nothing else.
34
34
  */
35
+ /** `same-origin`: the document's loads tell its own origin its address (P091); else none. */
36
+ readonly referrer?: "same-origin";
35
37
  readonly files?: {
36
38
  readonly base: string;
37
39
  /**
@@ -45,10 +47,24 @@ export interface ShellDocumentOptions {
45
47
  * renews it before then, at `<base>__porthole/renew`, and moves the page there.
46
48
  */
47
49
  readonly expires?: number;
50
+ /**
51
+ * The artifact version the files are (P098): the shell names it in its notices, and the host
52
+ * takes a notice only for the version it mounted. Not secret; the content can read it.
53
+ */
54
+ readonly set?: {
55
+ readonly id: string;
56
+ readonly version: string;
57
+ };
48
58
  };
49
59
  }
50
60
  /**
51
61
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
52
62
  * A given `document` travels in the runtime's plan, as data.
53
63
  */
64
+ /**
65
+ * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
66
+ * globals (the legacy path, P085) for what the config declares, and the capability runtime where
67
+ * the config has one.
68
+ */
69
+ export declare function composedRuntime(plan: ShellPlan): string;
54
70
  export declare function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string;
@@ -1,6 +1,8 @@
1
1
  import { hostOriginProblem } from "../isolation/served.js";
2
2
  import { ANNOTATE_RUNTIME } from "./annotate.js";
3
+ import { LEGACY_GLOBALS_RUNTIME } from "./legacy.js";
3
4
  import { SHELL_RUNTIME } from "./runtime.js";
5
+ import { USE_RUNTIME } from "./use.js";
4
6
  /** A file set's base: an absolute http(s) URL that ends in `/`, no query or fragment. */
5
7
  function filesBaseOk(base) {
6
8
  try {
@@ -62,6 +64,16 @@ body {
62
64
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
63
65
  * A given `document` travels in the runtime's plan, as data.
64
66
  */
67
+ /**
68
+ * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
69
+ * globals (the legacy path, P085) for what the config declares, and the capability runtime where
70
+ * the config has one.
71
+ */
72
+ export function composedRuntime(plan) {
73
+ return SHELL_RUNTIME.replace("__ANNOTATE__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME)
74
+ .replace("__LEGACY__", () => LEGACY_GLOBALS_RUNTIME)
75
+ .replace("__RUNTIME__", () => (plan.runtime === undefined ? "" : USE_RUNTIME));
76
+ }
65
77
  export function shellDocument(plan, csp, options) {
66
78
  for (const origin of options.origins) {
67
79
  const problem = hostOriginProblem(origin);
@@ -82,7 +94,7 @@ export function shellDocument(plan, csp, options) {
82
94
  const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
83
95
  // The annotation runtime only where it is declared; spliced in before the plan, which may carry
84
96
  // any text (a document) and must not be searched.
85
- const runtime = SHELL_RUNTIME.replace("__ANNOTATE__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME).replace("__PLAN__", () => scriptJson({
97
+ const runtime = composedRuntime(plan).replace("__PLAN__", () => scriptJson({
86
98
  ...plan,
87
99
  origins: options.origins,
88
100
  ...(options.document === undefined ? {} : { document: options.document }),
@@ -93,6 +105,9 @@ export function shellDocument(plan, csp, options) {
93
105
  base: options.files.base,
94
106
  ...(options.files.address === undefined ? {} : { address: options.files.address }),
95
107
  ...(options.files.expires === undefined ? {} : { expires: options.files.expires }),
108
+ ...(options.files.set === undefined
109
+ ? {}
110
+ : { set: { id: options.files.set.id, version: options.files.set.version } }),
96
111
  },
97
112
  }),
98
113
  }));
@@ -101,7 +116,9 @@ export function shellDocument(plan, csp, options) {
101
116
  options.cspMeta === false
102
117
  ? null
103
118
  : `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}">`,
104
- '<meta name="referrer" content="no-referrer">',
119
+ // A framed page of files whose config serves assets says its sealed address to its own
120
+ // origin only, which its asset loads carry (P091); every other document says nothing.
121
+ `<meta name="referrer" content="${options.referrer === "same-origin" ? "same-origin" : "no-referrer"}">`,
105
122
  // Off for good: an engine may prefetch names it sees in links, outside the CSP.
106
123
  '<meta http-equiv="x-dns-prefetch-control" content="off">',
107
124
  ].filter((line) => line !== null);
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The legacy path (P085): the globals pages written for Porthole 0.5 and 0.6 call
3
+ * (`sendPrompt`, `copyText`, `openLink`, `readData`, `subscribeData`), spliced into the shell's
4
+ * runtime (`__LEGACY__`) for each capability the config declares, as before. A page written for the
5
+ * capability runtime reaches the same host functions through `porthole.use` instead; the bridge
6
+ * gates both paths alike, and holds a page that declared capabilities to its declaration on
7
+ * either (P086).
8
+ *
9
+ * Since 0.7.0. Remove when no host serves a page written before it (hosts migrate their stored
10
+ * pages' calls to `porthole.use`); until then the manual teaches these only where the config has
11
+ * no runtime.
12
+ */
13
+ export declare const LEGACY_GLOBALS_RUNTIME: string;
14
+ /** The globals the legacy path defines, by the capability that defines each. */
15
+ export declare const LEGACY_GLOBALS: {
16
+ readonly sendPrompt: "sendPrompt";
17
+ readonly copyText: "copyText";
18
+ readonly openLink: "openLink";
19
+ readonly readData: "readData";
20
+ readonly subscribeData: "subscribeData";
21
+ };
@@ -0,0 +1,63 @@
1
+ /**
2
+ * The legacy path (P085): the globals pages written for Porthole 0.5 and 0.6 call
3
+ * (`sendPrompt`, `copyText`, `openLink`, `readData`, `subscribeData`), spliced into the shell's
4
+ * runtime (`__LEGACY__`) for each capability the config declares, as before. A page written for the
5
+ * capability runtime reaches the same host functions through `porthole.use` instead; the bridge
6
+ * gates both paths alike, and holds a page that declared capabilities to its declaration on
7
+ * either (P086).
8
+ *
9
+ * Since 0.7.0. Remove when no host serves a page written before it (hosts migrate their stored
10
+ * pages' calls to `porthole.use`); until then the manual teaches these only where the config has
11
+ * no runtime.
12
+ */
13
+ export const LEGACY_GLOBALS_RUNTIME = String.raw `
14
+ if (declared("sendPrompt")) {
15
+ lock(window, "sendPrompt", (text) => {
16
+ if (!gestured("sendPrompt")) {
17
+ return refuse("sendPrompt needs a click: call it from a button's handler");
18
+ }
19
+ const words = String(text);
20
+ if (words.trim() === "" || words.length > plan.maxPromptChars) {
21
+ return refuse("sendPrompt takes 1 to " + plan.maxPromptChars + " characters");
22
+ }
23
+ return request("ui/message", { role: "user", content: [{ type: "text", text: words }] }).then(
24
+ (result) => !(result && result.isError),
25
+ );
26
+ });
27
+ }
28
+ if (declared("copyText")) {
29
+ lock(window, "copyText", (text) => {
30
+ if (!gestured("copyText")) {
31
+ return refuse("copyText needs a click: call it from a button's handler");
32
+ }
33
+ const words = String(text);
34
+ if (words === "" || words.length > plan.maxCopyChars) {
35
+ return refuse("copyText takes 1 to " + plan.maxCopyChars + " characters");
36
+ }
37
+ return request("porthole/copy-text", { text: words }).then((result) => !(result && result.isError));
38
+ });
39
+ }
40
+ if (declared("openLink")) {
41
+ lock(window, "openLink", (url) => {
42
+ if (!gestured("openLink")) {
43
+ return refuse("openLink needs a click: call it from a link's or button's handler");
44
+ }
45
+ return request("ui/open-link", { url: String(url) }).then((result) => !(result && result.isError));
46
+ });
47
+ }
48
+
49
+ if (declared("readData")) {
50
+ lock(window, "readData", readValue);
51
+ }
52
+ if (follow !== null) {
53
+ lock(window, "subscribeData", follow);
54
+ }
55
+ `;
56
+ /** The globals the legacy path defines, by the capability that defines each. */
57
+ export const LEGACY_GLOBALS = {
58
+ sendPrompt: "sendPrompt",
59
+ copyText: "copyText",
60
+ openLink: "openLink",
61
+ readData: "readData",
62
+ subscribeData: "subscribeData",
63
+ };
@@ -1,5 +1,6 @@
1
1
  import { type CapabilityName } from "../config/capabilities.ts";
2
2
  import type { PortholeConfig } from "../config/schema.ts";
3
+ import { type RuntimeVersion } from "../runtime/contract.ts";
3
4
  /**
4
5
  * What the shell wires, derived from the config: the JSON the shell's runtime is given. The
5
6
  * agreement test reads it against the CSP and the manual, so it lists everything the shell
@@ -20,8 +21,23 @@ export interface ShellPlan {
20
21
  readonly userActivation: boolean;
21
22
  };
22
23
  };
23
- /** The globals the shell defines on `window` (sugar over the protocol's requests). */
24
+ /**
25
+ * The globals the shell defines on `window` and the manual teaches: `porthole` where the config
26
+ * has the capability runtime (P085), else 0.6's (sugar over the protocol's requests).
27
+ */
24
28
  readonly globals: readonly string[];
29
+ /**
30
+ * 0.6's globals the shell still defines under the runtime, for pages written before it (the
31
+ * legacy path, `shell/legacy.ts`), which the manual no longer teaches. Empty without a runtime.
32
+ */
33
+ readonly legacyGlobals: readonly string[];
34
+ /** The capability runtime's contract version, where the config has one (`porthole.use`). */
35
+ readonly runtime?: RuntimeVersion;
36
+ /**
37
+ * The runtime methods whose own gates want a gesture (`capability.method`: `artifact.publish`,
38
+ * `assets.delete`): the shell refuses them without one, as it does a host function's.
39
+ */
40
+ readonly methodActivation?: readonly string[];
25
41
  /** The theme variables the shell applies; it drops any other name the host sends. */
26
42
  readonly themeVariables: readonly string[];
27
43
  /** The window event fired after a theme change. */
@@ -1,6 +1,7 @@
1
1
  import { MAX_COPY_CHARS, capabilitySpec } from "../config/capabilities.js";
2
2
  import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
3
3
  import { MCP_APPS_PROTOCOL_VERSION } from "../protocol/mcp-apps.js";
4
+ import { RUNTIME_GLOBAL, methodGates, offeredCapabilities, runtimeCapability, } from "../runtime/contract.js";
4
5
  export function shellPlan(config) {
5
6
  if (config.mode === "url") {
6
7
  return null;
@@ -13,17 +14,27 @@ export function shellPlan(config) {
13
14
  userActivation: effectiveGates(config, name).includes("user-activation"),
14
15
  };
15
16
  }
16
- const globals = protocol === "shell"
17
+ const legacy = protocol === "shell"
17
18
  ? declared.flatMap((name) => {
18
19
  const spec = capabilitySpec(name);
19
20
  return spec.global === undefined ? [] : [spec.global];
20
21
  })
21
22
  : [];
23
+ const runtime = protocol === "shell" ? config.runtime : undefined;
22
24
  return {
23
25
  protocol,
24
26
  content: config.mode === "artifact" ? "document" : "fragment",
25
27
  capabilities,
26
- globals,
28
+ globals: runtime === undefined ? legacy : [RUNTIME_GLOBAL],
29
+ legacyGlobals: runtime === undefined ? [] : legacy,
30
+ ...(runtime === undefined
31
+ ? {}
32
+ : {
33
+ runtime,
34
+ methodActivation: offeredCapabilities(config).flatMap((family) => Object.keys(runtimeCapability(family).methods)
35
+ .filter((method) => methodGates(config, family, method).includes("user-activation"))
36
+ .map((method) => `${family}.${method}`)),
37
+ }),
27
38
  themeVariables: Object.keys(config.theme.variables),
28
39
  themeEvent: config.theme.event,
29
40
  themeDocuments: config.theme.documents ?? "declared",