@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
@@ -22,6 +22,16 @@ const DECLINED = {
22
22
  subscribeData: () => {
23
23
  throw new Error("The host declined the subscription");
24
24
  },
25
+ comments: () => false,
26
+ artifact: () => {
27
+ throw new Error("The host declined the artifact call");
28
+ },
29
+ assets: () => {
30
+ throw new Error("The host declined the asset call");
31
+ },
32
+ db: () => {
33
+ throw new Error("The host declined the db call");
34
+ },
25
35
  };
26
36
  /**
27
37
  * The web platform, with no person on the page: no call comes from a click (P078). The driver's
@@ -116,6 +126,8 @@ const check = {
116
126
  confirm: () => Promise.resolve("declined"),
117
127
  // A viewer who doesn't allow a live widget their data (P079): its calls are refused.
118
128
  consent: () => false,
129
+ // Model context goes to a surface nobody reads here (P100): the check has no person.
130
+ show: () => { },
119
131
  // A served config's instance, issued by the check's own server on this page's origin.
120
132
  locator: {
121
133
  locate: async (instance) => (await (await fetch("/issue", { method: "POST", body: JSON.stringify({ instance }) })).json()),
@@ -125,6 +137,10 @@ const check = {
125
137
  title: "Check",
126
138
  scheme: spec.scheme,
127
139
  ...(spec.instance === undefined ? {} : { instance: spec.instance }),
140
+ // Under a runtime: the page's declaration (none by default), a viewer who only views.
141
+ ...(spec.config.runtime === undefined
142
+ ? {}
143
+ : { declaration: spec.declaration ?? null, viewer: { level: "view" } }),
128
144
  });
129
145
  const run = {
130
146
  display,
@@ -1,5 +1,4 @@
1
- import { BUILT_IN_TOPICS } from "../config/validate.js";
2
- import { generateGuide, generateToolDescription } from "../guide/guide.js";
1
+ import { builtInTopics, generateGuide, generateToolDescription } from "../guide/guide.js";
3
2
  import { fragmentOf, lintContent } from "./lint.js";
4
3
  import { lintFiles, whereOf } from "./files.js";
5
4
  const noun = (config) => config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
@@ -9,7 +8,7 @@ const showName = (config) => config.guide.toolName ?? `show_${noun(config)}`;
9
8
  const guideName = (config) => config.guide.guideToolName ?? `${noun(config)}_guide`;
10
9
  /** The topics the manual has: the built-in ones and the config's own. */
11
10
  export function guideTopics(config) {
12
- return [...BUILT_IN_TOPICS, ...Object.keys(config.guide.topics ?? {})];
11
+ return [...builtInTopics(config), ...Object.keys(config.guide.topics ?? {})];
13
12
  }
14
13
  /** The tool that shows content: `{ title, html }`. */
15
14
  export function showTool(config, options = {}) {
@@ -1,4 +1,5 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
+ import type { ConfigWarning } from "../config/warnings.ts";
2
3
  import { type GuideTopic } from "../guide/guide.ts";
3
4
  import { type ShellDocumentOptions } from "../shell/document.ts";
4
5
  import { type ShellPlan } from "../shell/plan.ts";
@@ -10,6 +11,11 @@ import { type CspDirective } from "./policy.ts";
10
11
  */
11
12
  export interface CompiledConfig {
12
13
  readonly config: PortholeConfig;
14
+ /**
15
+ * What the config says that its host likely didn't mean (`configWarnings`): log them at startup.
16
+ * Empty for a config without any.
17
+ */
18
+ readonly warnings: readonly ConfigWarning[];
13
19
  /** The frame's CSP, directive by directive; empty in url mode (the app sends its own). */
14
20
  readonly cspDirectives: readonly CspDirective[];
15
21
  /** The frame's CSP: in the shell's `<meta>`, or a served document's header. */
@@ -5,12 +5,14 @@ import { shellPlan } from "../shell/plan.js";
5
5
  import { allowAttribute, embedderFrameSources, frameCspDirectives, sandboxTokens, serializeCsp, } from "./policy.js";
6
6
  /** Validates `config` and derives everything from it. Throws a `ConfigError` on a bad config. */
7
7
  export function compile(config) {
8
- validateConfig(config);
8
+ const warnings = [];
9
+ validateConfig(config, { onWarning: (warning) => warnings.push(warning) });
9
10
  const cspDirectives = frameCspDirectives(config);
10
11
  const csp = serializeCsp(cspDirectives);
11
12
  const shell = shellPlan(config);
12
13
  return {
13
14
  config,
15
+ warnings,
14
16
  cspDirectives,
15
17
  csp,
16
18
  sandbox: sandboxTokens(config).join(" "),
@@ -1,5 +1,6 @@
1
1
  import { type CapabilityName, type Gate } from "../config/capabilities.ts";
2
2
  import type { PortholeConfig } from "../config/schema.ts";
3
+ import { assetCodeRuns } from "../runtime/contract.ts";
3
4
  /**
4
5
  * The frame's policies, derived from the config: its CSP (in the shell's `<meta>` for opaque
5
6
  * frames, in headers for served ones), its `sandbox` and `allow` attributes, and the `frame-src`
@@ -14,6 +15,12 @@ export declare function anyHttps(config: PortholeConfig, kind: EgressKind): bool
14
15
  export declare function declaredCapabilities(config: PortholeConfig): CapabilityName[];
15
16
  /** The gates a declared capability runs under: its own, else the vocabulary's defaults. */
16
17
  export declare function effectiveGates(config: PortholeConfig, name: CapabilityName): readonly Gate[];
18
+ /**
19
+ * The gates one call runs under: its host function's, and the own gates of each runtime method it
20
+ * runs (after the review: `artifact.publish`, `assets.delete`, an upload whose code may run; P094:
21
+ * a db batch's writes' and a watch's read's too, `methodsOfCall`), every one applying.
22
+ */
23
+ export declare function callGates(config: PortholeConfig, name: CapabilityName, args: unknown): readonly Gate[];
17
24
  /** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
18
25
  export declare function egressOrigins(config: PortholeConfig, kind: EgressKind): string[];
19
26
  /** Every origin content may reach, of any kind. */
@@ -41,6 +48,19 @@ export declare const FILE_SET_DIRECTIVES: readonly ["script-src", "style-src", "
41
48
  * `'none'`. Opaque frames have no files, and keep P022's rule whole.
42
49
  */
43
50
  export declare function fileSetCspDirectives(directives: readonly CspDirective[], source: string): CspDirective[];
51
+ /**
52
+ * The directives a page opens its artifact's asset library to (P089), at `/_blob/` on its own
53
+ * origin: what loads without running, always; what runs (scripts, styles) only where uploads are
54
+ * the admins' alone, who publish the page's code anyway.
55
+ */
56
+ export declare const ASSET_DIRECTIVES: readonly ["img-src", "media-src", "font-src", "connect-src"];
57
+ export declare const ASSET_CODE_DIRECTIVES: readonly ["script-src", "style-src"];
58
+ export { assetCodeRuns };
59
+ /**
60
+ * A served page's CSP with its asset library opened (P089), on `origin` (the page's own, exact:
61
+ * never a sibling's): only where the config declares `assets`. Never `'self'`.
62
+ */
63
+ export declare function assetCspDirectives(config: PortholeConfig, directives: readonly CspDirective[], origin: string): CspDirective[];
44
64
  /**
45
65
  * The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
46
66
  * and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
@@ -54,6 +74,41 @@ export declare function serializeCsp(directives: readonly CspDirective[]): strin
54
74
  * isn't). External (url mode): what a running web app needs to work on its own origin.
55
75
  */
56
76
  export declare function sandboxTokens(config: PortholeConfig): string[];
77
+ /**
78
+ * The `sandbox` a served document's CSP header carries (P099): the frame's own tokens, so a page
79
+ * opened on a tab of its own (a public link, a new tab, a bookmark, a frame's address opened
80
+ * outside it) holds no power it lacks in its frame: scripts on its own origin, and no popups,
81
+ * forms, downloads, modals, or navigation of another window (its opener's included). In a frame
82
+ * it repeats the frame's attribute, so it changes nothing there; it is sent on every served page,
83
+ * not only on a `Sec-Fetch-Dest: document` request, so a client that sends no fetch metadata is
84
+ * sandboxed too and one address needs no `Vary`. Domain isolation only: url mode serves the app's
85
+ * own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
86
+ */
87
+ export declare function servedSandboxDirective(config: PortholeConfig): CspDirective | null;
88
+ /** A served page's CSP header: the page's directives, then its sandbox (P099). */
89
+ export declare function servedDocumentCsp(config: PortholeConfig, directives: readonly CspDirective[]): string;
90
+ /**
91
+ * The features a cross-origin frame never has unless its `allow` names them (each one's default
92
+ * allowlist is `'self'`), and a served page denies itself (P099): devices, location, full screen,
93
+ * the clipboard, payments, credentials, sharing, the built-in AI models, WebMCP's `tools`, the
94
+ * local network, autofill. Every such feature Chromium lists for web pages
95
+ * (`test/reference/permissions-policy-features.json`), but client hints, `cross-origin-isolated`
96
+ * and Chromium's sample (`test/permissions-policy.test.ts` says why). Features whose default is
97
+ * `*` (a video's picture-in-picture, gamepads) are left out: a frame has them, so denying them on
98
+ * a tab would change the frame too. An engine that doesn't know a name ignores it.
99
+ */
100
+ export declare const FRAME_DENIED_FEATURES: readonly ["accelerometer", "ambient-light-sensor", "autofill", "autoplay", "bluetooth", "camera", "captured-surface-control", "clipboard-read", "clipboard-write", "compute-pressure", "deferred-fetch", "device-attributes", "digital-credentials-create", "digital-credentials-get", "display-capture", "encrypted-media", "fullscreen", "geolocation", "gyroscope", "haptics", "hid", "identity-credentials-get", "idle-detection", "keyboard-map", "language-detector", "language-model", "local-fonts", "local-network", "local-network-access", "loopback-network", "magnetometer", "manual-text", "microphone", "midi", "on-device-speech-recognition", "otp-credentials", "payment", "publickey-credentials-create", "publickey-credentials-get", "publickey-credentials-remote-client-data-json", "rewriter", "screen-wake-lock", "serial", "speaker-selection", "summarizer", "tools", "translator", "unbounded-element", "usb", "web-app-installation", "web-share", "webnn", "window-management", "writer", "xr-spatial-tracking"];
101
+ /** The features a frame's `allow` attribute grants (`allowAttribute`): none but url mode's. */
102
+ export declare function delegatedFeatures(config: PortholeConfig): string[];
103
+ /**
104
+ * The `Permissions-Policy` header of a served page (P099): every feature of
105
+ * `FRAME_DENIED_FEATURES` its frame's `allow` doesn't grant, denied (`camera=()`), so a page on
106
+ * a tab of its own (no `allow` there) can't ask for the camera, the microphone, location or full
107
+ * screen under the content origin's name. In a frame it changes nothing: the frame's `allow`
108
+ * grants none of them, and a frame's features are the intersection of the two. Domain isolation
109
+ * only, as `servedSandboxDirective`.
110
+ */
111
+ export declare function servedPermissionsPolicy(config: PortholeConfig): string | null;
57
112
  /**
58
113
  * The frame's `allow` attribute (Permissions Policy). No camera, microphone, geolocation,
59
114
  * fullscreen or other powerful feature is delegated to the frame, and the clipboard is denied by
@@ -1,5 +1,7 @@
1
1
  import { CAPABILITIES } from "../config/capabilities.js";
2
2
  import { LIBRARY_PATH } from "../libraries/libraries.js";
3
+ import { assetCodeRuns, familyOf, methodGates, methodsOfCall } from "../runtime/contract.js";
4
+ import { ASSET_PATH } from "../runtime/requests.js";
3
5
  /** Whether `kind` loads from any https site (`EgressConfig.anyHttps`, P059): passive kinds only. */
4
6
  export function anyHttps(config, kind) {
5
7
  return (config.egress.anyHttps ?? []).some((each) => each === kind);
@@ -12,6 +14,26 @@ export function declaredCapabilities(config) {
12
14
  export function effectiveGates(config, name) {
13
15
  return config.capabilities[name]?.gates ?? CAPABILITIES[name].defaultGates;
14
16
  }
17
+ /**
18
+ * The gates one call runs under: its host function's, and the own gates of each runtime method it
19
+ * runs (after the review: `artifact.publish`, `assets.delete`, an upload whose code may run; P094:
20
+ * a db batch's writes' and a watch's read's too, `methodsOfCall`), every one applying.
21
+ */
22
+ export function callGates(config, name, args) {
23
+ const gates = [...effectiveGates(config, name)];
24
+ const family = familyOf(name);
25
+ if (family === null) {
26
+ return gates;
27
+ }
28
+ for (const method of new Set(methodsOfCall(name, args))) {
29
+ for (const gate of methodGates(config, family.name, method)) {
30
+ if (!gates.includes(gate)) {
31
+ gates.push(gate);
32
+ }
33
+ }
34
+ }
35
+ return gates;
36
+ }
15
37
  const unique = (values) => [...new Set(values)];
16
38
  /** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
17
39
  export function egressOrigins(config, kind) {
@@ -103,6 +125,35 @@ export function fileSetCspDirectives(directives, source) {
103
125
  return [name, ...kept, source];
104
126
  });
105
127
  }
128
+ /**
129
+ * The directives a page opens its artifact's asset library to (P089), at `/_blob/` on its own
130
+ * origin: what loads without running, always; what runs (scripts, styles) only where uploads are
131
+ * the admins' alone, who publish the page's code anyway.
132
+ */
133
+ export const ASSET_DIRECTIVES = ["img-src", "media-src", "font-src", "connect-src"];
134
+ export const ASSET_CODE_DIRECTIVES = ["script-src", "style-src"];
135
+ export { assetCodeRuns };
136
+ /**
137
+ * A served page's CSP with its asset library opened (P089), on `origin` (the page's own, exact:
138
+ * never a sibling's): only where the config declares `assets`. Never `'self'`.
139
+ */
140
+ export function assetCspDirectives(config, directives, origin) {
141
+ if (config.capabilities.assets === undefined || config.isolation !== "domain") {
142
+ return [...directives];
143
+ }
144
+ const source = `${origin}${ASSET_PATH}`;
145
+ const opened = new Set([
146
+ ...ASSET_DIRECTIVES,
147
+ ...(assetCodeRuns(config) ? ASSET_CODE_DIRECTIVES : []),
148
+ ]);
149
+ return directives.map(([name, ...sources]) => {
150
+ if (!opened.has(name)) {
151
+ return [name, ...sources];
152
+ }
153
+ const kept = sources.filter((each) => each !== "'none'");
154
+ return [name, ...kept, source];
155
+ });
156
+ }
106
157
  /**
107
158
  * The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
108
159
  * and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
@@ -128,6 +179,112 @@ export function sandboxTokens(config) {
128
179
  return ["allow-scripts", "allow-same-origin", "allow-forms", ...(config.sandbox ?? [])];
129
180
  }
130
181
  }
182
+ /**
183
+ * The `sandbox` a served document's CSP header carries (P099): the frame's own tokens, so a page
184
+ * opened on a tab of its own (a public link, a new tab, a bookmark, a frame's address opened
185
+ * outside it) holds no power it lacks in its frame: scripts on its own origin, and no popups,
186
+ * forms, downloads, modals, or navigation of another window (its opener's included). In a frame
187
+ * it repeats the frame's attribute, so it changes nothing there; it is sent on every served page,
188
+ * not only on a `Sec-Fetch-Dest: document` request, so a client that sends no fetch metadata is
189
+ * sandboxed too and one address needs no `Vary`. Domain isolation only: url mode serves the app's
190
+ * own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
191
+ */
192
+ export function servedSandboxDirective(config) {
193
+ return config.isolation === "domain" ? ["sandbox", ...sandboxTokens(config)] : null;
194
+ }
195
+ /** A served page's CSP header: the page's directives, then its sandbox (P099). */
196
+ export function servedDocumentCsp(config, directives) {
197
+ const sandbox = servedSandboxDirective(config);
198
+ return serializeCsp(sandbox === null ? directives : [...directives, sandbox]);
199
+ }
200
+ /**
201
+ * The features a cross-origin frame never has unless its `allow` names them (each one's default
202
+ * allowlist is `'self'`), and a served page denies itself (P099): devices, location, full screen,
203
+ * the clipboard, payments, credentials, sharing, the built-in AI models, WebMCP's `tools`, the
204
+ * local network, autofill. Every such feature Chromium lists for web pages
205
+ * (`test/reference/permissions-policy-features.json`), but client hints, `cross-origin-isolated`
206
+ * and Chromium's sample (`test/permissions-policy.test.ts` says why). Features whose default is
207
+ * `*` (a video's picture-in-picture, gamepads) are left out: a frame has them, so denying them on
208
+ * a tab would change the frame too. An engine that doesn't know a name ignores it.
209
+ */
210
+ export const FRAME_DENIED_FEATURES = [
211
+ "accelerometer",
212
+ "ambient-light-sensor",
213
+ "autofill",
214
+ "autoplay",
215
+ "bluetooth",
216
+ "camera",
217
+ "captured-surface-control",
218
+ "clipboard-read",
219
+ "clipboard-write",
220
+ "compute-pressure",
221
+ "deferred-fetch",
222
+ "device-attributes",
223
+ "digital-credentials-create",
224
+ "digital-credentials-get",
225
+ "display-capture",
226
+ "encrypted-media",
227
+ "fullscreen",
228
+ "geolocation",
229
+ "gyroscope",
230
+ "haptics",
231
+ "hid",
232
+ "identity-credentials-get",
233
+ "idle-detection",
234
+ "keyboard-map",
235
+ "language-detector",
236
+ "language-model",
237
+ "local-fonts",
238
+ "local-network",
239
+ "local-network-access",
240
+ "loopback-network",
241
+ "magnetometer",
242
+ "manual-text",
243
+ "microphone",
244
+ "midi",
245
+ "on-device-speech-recognition",
246
+ "otp-credentials",
247
+ "payment",
248
+ "publickey-credentials-create",
249
+ "publickey-credentials-get",
250
+ "publickey-credentials-remote-client-data-json",
251
+ "rewriter",
252
+ "screen-wake-lock",
253
+ "serial",
254
+ "speaker-selection",
255
+ "summarizer",
256
+ "tools",
257
+ "translator",
258
+ "unbounded-element",
259
+ "usb",
260
+ "web-app-installation",
261
+ "web-share",
262
+ "webnn",
263
+ "window-management",
264
+ "writer",
265
+ "xr-spatial-tracking",
266
+ ];
267
+ /** The features a frame's `allow` attribute grants (`allowAttribute`): none but url mode's. */
268
+ export function delegatedFeatures(config) {
269
+ return config.mode === "url" ? [...(config.permissions ?? [])] : [];
270
+ }
271
+ /**
272
+ * The `Permissions-Policy` header of a served page (P099): every feature of
273
+ * `FRAME_DENIED_FEATURES` its frame's `allow` doesn't grant, denied (`camera=()`), so a page on
274
+ * a tab of its own (no `allow` there) can't ask for the camera, the microphone, location or full
275
+ * screen under the content origin's name. In a frame it changes nothing: the frame's `allow`
276
+ * grants none of them, and a frame's features are the intersection of the two. Domain isolation
277
+ * only, as `servedSandboxDirective`.
278
+ */
279
+ export function servedPermissionsPolicy(config) {
280
+ if (config.isolation !== "domain") {
281
+ return null;
282
+ }
283
+ const granted = new Set(delegatedFeatures(config));
284
+ return FRAME_DENIED_FEATURES.filter((feature) => !granted.has(feature))
285
+ .map((feature) => `${feature}=()`)
286
+ .join(", ");
287
+ }
131
288
  /**
132
289
  * The frame's `allow` attribute (Permissions Policy). No camera, microphone, geolocation,
133
290
  * fullscreen or other powerful feature is delegated to the frame, and the clipboard is denied by
@@ -1,4 +1,6 @@
1
1
  import type { AnnotationReport } from "../annotate/types.ts";
2
+ import type { DbRequest, DbResult } from "../runtime/db.ts";
3
+ import type { ArtifactInfo, ArtifactRequest, AssetInfo, AssetRequest, CommentRequest, PublishedVersion, UserInfo } from "../runtime/requests.ts";
2
4
  /**
3
5
  * The capability vocabulary (PRINCIPLE 4): every power content has beyond drawing is one of these
4
6
  * host functions, named in the config. A capability the config doesn't declare is not wired into
@@ -8,7 +10,7 @@ import type { AnnotationReport } from "../annotate/types.ts";
8
10
  * are on by default), and is served either by a handler the host passes or as an event the
9
11
  * framework emits.
10
12
  */
11
- export declare const CAPABILITY_NAMES: readonly ["sendPrompt", "openLink", "downloadFile", "callTool", "readData", "subscribeData", "setModelContext", "reportError", "resize", "copyText", "annotate"];
13
+ export declare const CAPABILITY_NAMES: readonly ["sendPrompt", "openLink", "downloadFile", "callTool", "readData", "subscribeData", "setModelContext", "reportError", "resize", "copyText", "annotate", "user", "comments", "artifact", "assets", "db"];
12
14
  export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
13
15
  /**
14
16
  * What must hold before a call reaches the host's handler. A capability's gates all apply.
@@ -23,8 +25,11 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
23
25
  * call of any of its consent-gated capabilities, whether this content may have them (a viewer
24
26
  * allowing a widget to read their data). A no refuses every such call for the display's life;
25
27
  * no `consent` function refuses them all (fail closed).
28
+ * - `show` (P100): the host's `show` function puts the call's whole effect in front of the person,
29
+ * outside the frame, before the handler has it; it asks nothing. No `show` function, or one that
30
+ * throws, means the call is refused (fail closed).
26
31
  */
27
- export type Gate = "user-activation" | "confirm" | "consent" | {
32
+ export type Gate = "user-activation" | "confirm" | "consent" | "show" | {
28
33
  readonly rateLimit: {
29
34
  readonly perMinute: number;
30
35
  };
@@ -32,8 +37,11 @@ export type Gate = "user-activation" | "confirm" | "consent" | {
32
37
  export interface CapabilitySpec {
33
38
  /** The gates a declared capability gets when its config names none. */
34
39
  readonly defaultGates: readonly Gate[];
35
- /** `handler`: the host passes a function that performs it. `event`: the framework emits it. */
36
- readonly served: "handler" | "event";
40
+ /**
41
+ * `handler`: the host passes a function that performs it. `event`: the framework emits it.
42
+ * `viewer`: the framework answers it from the viewer the host gave the display (`user`).
43
+ */
44
+ readonly served: "handler" | "event" | "viewer";
37
45
  /** The global the shell defines for it (sugar over the protocol message), if any. */
38
46
  readonly global?: string;
39
47
  /**
@@ -48,6 +56,11 @@ export interface CapabilitySpec {
48
56
  }
49
57
  /** The most text one `copyText` call carries. */
50
58
  export declare const MAX_COPY_CHARS = 20000;
59
+ /**
60
+ * The most one `setModelContext` update carries (P100): its text blocks' characters and its
61
+ * structured content's JSON, together. What the person is shown is all of it.
62
+ */
63
+ export declare const MAX_CONTEXT_CHARS = 20000;
51
64
  export declare const CAPABILITIES: {
52
65
  readonly sendPrompt: {
53
66
  readonly defaultGates: readonly ["user-activation", "confirm"];
@@ -76,7 +89,7 @@ export declare const CAPABILITIES: {
76
89
  };
77
90
  };
78
91
  readonly callTool: {
79
- readonly defaultGates: readonly ["confirm"];
92
+ readonly defaultGates: readonly ["confirm", Gate];
80
93
  readonly served: "handler";
81
94
  readonly request: {
82
95
  readonly method: "tools/call";
@@ -105,8 +118,12 @@ export declare const CAPABILITIES: {
105
118
  readonly method: "resources/subscribe";
106
119
  };
107
120
  };
121
+ /**
122
+ * Text for the model's next turns (P100): the content's own words, which the person never typed.
123
+ * Shown to them first by default (`show`), so nothing reaches the model they couldn't see.
124
+ */
108
125
  readonly setModelContext: {
109
- readonly defaultGates: readonly [Gate];
126
+ readonly defaultGates: readonly [Gate, "show"];
110
127
  readonly served: "handler";
111
128
  readonly request: {
112
129
  readonly method: "ui/update-model-context";
@@ -142,6 +159,46 @@ export declare const CAPABILITIES: {
142
159
  readonly defaultGates: readonly [Gate];
143
160
  readonly served: "event";
144
161
  };
162
+ /** Who is viewing (P087): answered from the viewer the host gave the display. */
163
+ readonly user: {
164
+ readonly defaultGates: readonly [Gate];
165
+ readonly served: "viewer";
166
+ readonly request: {
167
+ readonly method: "porthole/call";
168
+ };
169
+ };
170
+ /** Opens the host's comment composer at the page's anchor (P090): write-only. */
171
+ readonly comments: {
172
+ readonly defaultGates: readonly ["user-activation", Gate];
173
+ readonly served: "handler";
174
+ readonly request: {
175
+ readonly method: "porthole/call";
176
+ };
177
+ };
178
+ /** This artifact's current version, and a new version of it, base-checked (P088). */
179
+ readonly artifact: {
180
+ readonly defaultGates: readonly [Gate];
181
+ readonly served: "handler";
182
+ readonly request: {
183
+ readonly method: "porthole/call";
184
+ };
185
+ };
186
+ /** The artifact's asset library, served at `/_blob/<id>` (P089). */
187
+ readonly assets: {
188
+ readonly defaultGates: readonly [Gate];
189
+ readonly served: "handler";
190
+ readonly request: {
191
+ readonly method: "porthole/call";
192
+ };
193
+ };
194
+ /** The artifact's shared document store (P088). */
195
+ readonly db: {
196
+ readonly defaultGates: readonly [Gate];
197
+ readonly served: "handler";
198
+ readonly request: {
199
+ readonly method: "porthole/call";
200
+ };
201
+ };
145
202
  };
146
203
  /** The arguments a call carries, once the adapter has validated them. */
147
204
  export interface CapabilityArgs {
@@ -165,8 +222,15 @@ export interface CapabilityArgs {
165
222
  readonly subscribeData: {
166
223
  readonly uri: string;
167
224
  };
225
+ /**
226
+ * Text blocks only (the modality the host offers), each rebuilt as `{ type, text }`; structured
227
+ * content plain JSON (P100). At most `MAX_CONTEXT_CHARS` together.
228
+ */
168
229
  readonly setModelContext: {
169
- readonly content?: readonly unknown[];
230
+ readonly content?: readonly {
231
+ readonly type: "text";
232
+ readonly text: string;
233
+ }[];
170
234
  readonly structuredContent?: Readonly<Record<string, unknown>>;
171
235
  };
172
236
  /**
@@ -186,6 +250,12 @@ export interface CapabilityArgs {
186
250
  };
187
251
  /** What the frame reported, once checked (`AnnotationReport`). */
188
252
  readonly annotate: AnnotationReport;
253
+ readonly user: Readonly<Record<string, never>>;
254
+ readonly comments: CommentRequest;
255
+ readonly artifact: ArtifactRequest;
256
+ readonly assets: AssetRequest;
257
+ /** Paths checked, `me` resolved, the viewer's own data only (P088). */
258
+ readonly db: DbRequest;
189
259
  }
190
260
  /** What a call resolves to. Protocol-shaped results (a tool's result) stay opaque to the core. */
191
261
  export interface CapabilityResults {
@@ -205,6 +275,14 @@ export interface CapabilityResults {
205
275
  /** Whether the text was copied. */
206
276
  readonly copyText: boolean;
207
277
  readonly annotate: undefined;
278
+ readonly user: UserInfo;
279
+ /** Whether the composer opened. Never a thread: content doesn't read comments (P090). */
280
+ readonly comments: boolean;
281
+ /** `get`: the current version; `publish`: the new one. */
282
+ readonly artifact: ArtifactInfo | PublishedVersion;
283
+ /** `list`: the library; `upload`: the new asset; `delete`: whether it was removed. */
284
+ readonly assets: AssetInfo | readonly AssetInfo[] | boolean;
285
+ readonly db: DbResult;
208
286
  }
209
287
  /** The capabilities a host serves with a handler. */
210
288
  export type HandledCapability = {
@@ -19,10 +19,21 @@ export const CAPABILITY_NAMES = [
19
19
  "resize",
20
20
  "copyText",
21
21
  "annotate",
22
+ // The capability runtime's own (P085, `config.runtime`): reached through `porthole.use`.
23
+ "user",
24
+ "comments",
25
+ "artifact",
26
+ "assets",
27
+ "db",
22
28
  ];
23
29
  const rate = (perMinute) => ({ rateLimit: { perMinute } });
24
30
  /** The most text one `copyText` call carries. */
25
31
  export const MAX_COPY_CHARS = 20_000;
32
+ /**
33
+ * The most one `setModelContext` update carries (P100): its text blocks' characters and its
34
+ * structured content's JSON, together. What the person is shown is all of it.
35
+ */
36
+ export const MAX_CONTEXT_CHARS = 20_000;
26
37
  export const CAPABILITIES = {
27
38
  sendPrompt: {
28
39
  defaultGates: ["user-activation", "confirm"],
@@ -42,7 +53,8 @@ export const CAPABILITIES = {
42
53
  request: { method: "ui/download-file", sdk: "app.downloadFile" },
43
54
  },
44
55
  callTool: {
45
- defaultGates: ["confirm"],
56
+ // A rate as well (P103): it needs no gesture, and a host's `confirm` may say yes by itself.
57
+ defaultGates: ["confirm", rate(30)],
46
58
  served: "handler",
47
59
  request: { method: "tools/call", sdk: "app.callServerTool" },
48
60
  },
@@ -63,8 +75,12 @@ export const CAPABILITIES = {
63
75
  global: "subscribeData",
64
76
  request: { method: "resources/subscribe" },
65
77
  },
78
+ /**
79
+ * Text for the model's next turns (P100): the content's own words, which the person never typed.
80
+ * Shown to them first by default (`show`), so nothing reaches the model they couldn't see.
81
+ */
66
82
  setModelContext: {
67
- defaultGates: [rate(30)],
83
+ defaultGates: [rate(30), "show"],
68
84
  served: "handler",
69
85
  request: { method: "ui/update-model-context", sdk: "app.updateModelContext" },
70
86
  },
@@ -86,6 +102,20 @@ export const CAPABILITIES = {
86
102
  * (it shares the realm): UI hints for the host, never permissions.
87
103
  */
88
104
  annotate: { defaultGates: [rate(120)], served: "event" },
105
+ /** Who is viewing (P087): answered from the viewer the host gave the display. */
106
+ user: { defaultGates: [rate(60)], served: "viewer", request: { method: "porthole/call" } },
107
+ /** Opens the host's comment composer at the page's anchor (P090): write-only. */
108
+ comments: {
109
+ defaultGates: ["user-activation", rate(30)],
110
+ served: "handler",
111
+ request: { method: "porthole/call" },
112
+ },
113
+ /** This artifact's current version, and a new version of it, base-checked (P088). */
114
+ artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
115
+ /** The artifact's asset library, served at `/_blob/<id>` (P089). */
116
+ assets: { defaultGates: [rate(30)], served: "handler", request: { method: "porthole/call" } },
117
+ /** The artifact's shared document store (P088). */
118
+ db: { defaultGates: [rate(600)], served: "handler", request: { method: "porthole/call" } },
89
119
  };
90
120
  /** A capability's spec, as the general shape (the table above keeps literal types). */
91
121
  export function capabilitySpec(name) {
@@ -1,3 +1,5 @@
1
+ import type { RuntimeVersion } from "../runtime/contract.ts";
2
+ import type { ViewerLevel } from "../runtime/levels.ts";
1
3
  import type { CapabilityName, Gate } from "./capabilities.ts";
2
4
  /**
3
5
  * One config per kind of display (PRINCIPLE 3). The compiler derives the frame's CSP, its sandbox
@@ -35,12 +37,37 @@ export type ThemeValue = string | {
35
37
  export interface CapabilityConfig {
36
38
  /** Every gate must pass. Omitted: the capability's default gates. `[]`: ungated. */
37
39
  readonly gates?: readonly Gate[];
40
+ /**
41
+ * Says that `gates` leaves out the default `show` on purpose (P100: `setModelContext`): the
42
+ * host's handler shows the person each update itself, or the content is its own. Without it,
43
+ * such gates earn a warning (`configWarnings`); with `show` in the gates, or no gates named, it
44
+ * is an error.
45
+ */
46
+ readonly withoutShow?: true;
38
47
  /** Extra `connect-src` origins this capability needs. */
39
48
  readonly connect?: readonly string[];
40
49
  /** Extra script/style/img/font/media origins this capability needs. */
41
50
  readonly resource?: readonly string[];
42
51
  /** Replaces the generated manual entry for this capability. */
43
52
  readonly guide?: string;
53
+ /**
54
+ * The least viewer level that may call each of the runtime methods it serves (P087), by method
55
+ * name (`db: { levels: { set: "admin" } }`, `sendPrompt: { levels: { send: "admin" } }`): over
56
+ * the contract's own, never below a method's floor (`RUNTIME_CAPABILITIES`). For
57
+ * `assets.upload`, `admin` or above also lets the page run what was uploaded as scripts and
58
+ * styles (P089); `interact` doesn't.
59
+ */
60
+ readonly levels?: Readonly<Record<string, ViewerLevel>>;
61
+ /**
62
+ * Gates of each runtime method it serves, by name, in place of the contract's own (after the
63
+ * review: `artifact.publish` and `assets.delete` need a click and a yes; `assets.upload` a yes
64
+ * where uploaded code may run). Every one applies on top of `gates`. `[]`: none of its own.
65
+ * A call that runs other methods runs under theirs too (P094): a db `batch` under each of its
66
+ * writes' (`set`, `update`, `delete`; one confirmation for the whole batch, a rate counting each
67
+ * write), a `watch` under `get`'s (a document) or `query`'s (a collection), checked when it
68
+ * starts: its updates are its answers, so a rate counts once per watch, not per update.
69
+ */
70
+ readonly methodGates?: Readonly<Record<string, readonly Gate[]>>;
44
71
  }
45
72
  /** The declared capabilities. Absent: not available, not wired, not in the CSP, not in the manual. */
46
73
  export type CapabilityMap = {
@@ -203,6 +230,14 @@ export interface PortholeConfig {
203
230
  * declares no `reportError`). Absent: the manual says they are reported to the app.
204
231
  */
205
232
  readonly errors?: "agent" | "host" | "none";
233
+ /**
234
+ * The capability runtime (P085): content reaches capabilities through one global,
235
+ * `porthole.use(name)`, under this contract version, and the manual teaches it (with declaring
236
+ * them, `capabilities: { name: config }`, for pages that are published). Only with it may the
237
+ * config declare the runtime's own host functions (`user`, `comments`, `artifact`, `assets`,
238
+ * `db`). Absent: 0.6's frames, globals and manual, exactly.
239
+ */
240
+ readonly runtime?: RuntimeVersion;
206
241
  }
207
242
  export interface StorageConfig {
208
243
  /**