@botiverse/porthole 0.7.0 → 0.9.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 (166) hide show
  1. package/README.md +9 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/annotate/types.d.ts +40 -4
  4. package/dist/annotate/types.js +6 -1
  5. package/dist/annotate/validate.d.ts +10 -0
  6. package/dist/annotate/validate.js +24 -1
  7. package/dist/bridge/bounded-text.d.ts +34 -0
  8. package/dist/bridge/bounded-text.js +188 -0
  9. package/dist/bridge/bridge.d.ts +25 -5
  10. package/dist/bridge/bridge.js +311 -73
  11. package/dist/bridge/json-data.d.ts +28 -0
  12. package/dist/bridge/json-data.js +86 -0
  13. package/dist/bridge/navigation.d.ts +5 -0
  14. package/dist/bridge/navigation.js +7 -0
  15. package/dist/bridge/refusal.js +1 -0
  16. package/dist/bridge/types.d.ts +32 -1
  17. package/dist/check/page-source.js +1 -1
  18. package/dist/check/page.js +2 -0
  19. package/dist/compile/compile.d.ts +6 -0
  20. package/dist/compile/compile.js +3 -1
  21. package/dist/compile/policy.d.ts +38 -2
  22. package/dist/compile/policy.js +122 -7
  23. package/dist/config/capabilities.d.ts +23 -4
  24. package/dist/config/capabilities.js +12 -2
  25. package/dist/config/schema.d.ts +11 -0
  26. package/dist/config/validate.d.ts +8 -2
  27. package/dist/config/validate.js +28 -6
  28. package/dist/config/warnings.d.ts +20 -0
  29. package/dist/config/warnings.js +25 -0
  30. package/dist/conformance/behavior.js +46 -1
  31. package/dist/conformance/cookies.d.ts +15 -0
  32. package/dist/conformance/cookies.js +80 -0
  33. package/dist/conformance/harness/page.d.ts +1 -0
  34. package/dist/conformance/harness/page.js +9 -2
  35. package/dist/conformance/harness-source.js +1 -1
  36. package/dist/conformance/host-kit.js +5 -1
  37. package/dist/conformance/index.d.ts +10 -0
  38. package/dist/conformance/limits.js +38 -1
  39. package/dist/conformance/runtime.js +10 -0
  40. package/dist/conformance/served.d.ts +2 -0
  41. package/dist/conformance/served.js +737 -4
  42. package/dist/files/paths.js +4 -0
  43. package/dist/guide/gates.d.ts +7 -1
  44. package/dist/guide/gates.js +12 -0
  45. package/dist/guide/guide.js +2 -2
  46. package/dist/guide/runtime.js +11 -3
  47. package/dist/host/create-host.js +81 -39
  48. package/dist/host/pages-of-set.d.ts +43 -0
  49. package/dist/host/pages-of-set.js +196 -0
  50. package/dist/host/types.d.ts +8 -1
  51. package/dist/index.d.ts +5 -4
  52. package/dist/index.js +3 -2
  53. package/dist/mcp/adapter.js +11 -15
  54. package/dist/node/index.d.ts +36 -4
  55. package/dist/node/index.js +402 -101
  56. package/dist/platform/types.d.ts +9 -0
  57. package/dist/platform/web.js +8 -0
  58. package/dist/presets/presets.d.ts +16 -8
  59. package/dist/presets/presets.js +39 -8
  60. package/dist/protocol/live-data.d.ts +6 -2
  61. package/dist/protocol/live-data.js +20 -1
  62. package/dist/protocol/mcp-apps.d.ts +13 -2
  63. package/dist/protocol/mcp-apps.js +10 -2
  64. package/dist/protocol/message-text.d.ts +8 -0
  65. package/dist/protocol/message-text.js +29 -0
  66. package/dist/protocol/runtime-calls.js +3 -0
  67. package/dist/protocol/shell-adapter.js +16 -22
  68. package/dist/react/context-notice.d.ts +32 -0
  69. package/dist/react/context-notice.js +28 -0
  70. package/dist/react/dialog.js +62 -18
  71. package/dist/react/frame.d.ts +18 -3
  72. package/dist/react/frame.js +79 -2
  73. package/dist/react/index.d.ts +2 -1
  74. package/dist/react/index.js +2 -1
  75. package/dist/runtime/contract.d.ts +9 -1
  76. package/dist/runtime/contract.js +31 -2
  77. package/dist/runtime/db.d.ts +41 -6
  78. package/dist/runtime/db.js +120 -16
  79. package/dist/runtime/declaration.d.ts +15 -1
  80. package/dist/runtime/declaration.js +184 -87
  81. package/dist/runtime/requests.js +27 -11
  82. package/dist/runtime/types.generated.js +1 -1
  83. package/dist/server/files.d.ts +5 -0
  84. package/dist/server/files.js +22 -7
  85. package/dist/server/host.d.ts +18 -1
  86. package/dist/server/host.js +132 -2
  87. package/dist/server/index.d.ts +1 -1
  88. package/dist/server/index.js +1 -1
  89. package/dist/server/peer.d.ts +4 -0
  90. package/dist/server/peer.js +19 -0
  91. package/dist/server/proxy.d.ts +6 -0
  92. package/dist/server/proxy.js +12 -3
  93. package/dist/server/server.js +113 -26
  94. package/dist/server/types.d.ts +6 -3
  95. package/dist/shell/annotate.d.ts +7 -2
  96. package/dist/shell/annotate.js +233 -15
  97. package/dist/shell/document.d.ts +8 -0
  98. package/dist/shell/document.js +3 -0
  99. package/dist/shell/runtime.js +361 -14
  100. package/docs/ADOPTING.md +119 -14
  101. package/docs/ARCHITECTURE.md +15 -4
  102. package/docs/DECISIONS.md +1610 -9
  103. package/docs/DESIGN.md +114 -30
  104. package/docs/THREAT_MODEL.md +652 -0
  105. package/package.json +14 -3
  106. package/src/annotate/types.ts +37 -5
  107. package/src/annotate/validate.ts +30 -1
  108. package/src/bridge/bounded-text.ts +240 -0
  109. package/src/bridge/bridge.ts +373 -84
  110. package/src/bridge/json-data.ts +95 -0
  111. package/src/bridge/navigation.ts +10 -0
  112. package/src/bridge/refusal.ts +1 -0
  113. package/src/bridge/types.ts +30 -1
  114. package/src/check/page.ts +2 -0
  115. package/src/compile/compile.ts +9 -1
  116. package/src/compile/policy.ts +130 -7
  117. package/src/config/capabilities.ts +22 -3
  118. package/src/config/schema.ts +11 -0
  119. package/src/config/validate.ts +43 -5
  120. package/src/config/warnings.ts +42 -0
  121. package/src/conformance/behavior.ts +54 -1
  122. package/src/conformance/cookies.ts +93 -0
  123. package/src/conformance/harness/page.ts +11 -2
  124. package/src/conformance/host-kit.ts +10 -1
  125. package/src/conformance/index.ts +10 -0
  126. package/src/conformance/limits.ts +39 -1
  127. package/src/conformance/runtime.ts +21 -0
  128. package/src/conformance/served.ts +888 -4
  129. package/src/files/paths.ts +4 -0
  130. package/src/guide/gates.ts +13 -1
  131. package/src/guide/guide.ts +3 -3
  132. package/src/guide/runtime.ts +12 -3
  133. package/src/host/create-host.ts +88 -38
  134. package/src/host/pages-of-set.ts +226 -0
  135. package/src/host/types.ts +15 -1
  136. package/src/index.ts +5 -0
  137. package/src/mcp/adapter.ts +16 -20
  138. package/src/node/index.ts +507 -116
  139. package/src/platform/types.ts +6 -0
  140. package/src/platform/web.ts +10 -0
  141. package/src/presets/presets.ts +60 -17
  142. package/src/protocol/live-data.ts +31 -3
  143. package/src/protocol/mcp-apps.ts +11 -2
  144. package/src/protocol/message-text.ts +36 -0
  145. package/src/protocol/runtime-calls.ts +3 -0
  146. package/src/protocol/shell-adapter.ts +27 -23
  147. package/src/react/context-notice.tsx +95 -0
  148. package/src/react/dialog.tsx +77 -17
  149. package/src/react/frame.tsx +107 -2
  150. package/src/react/index.ts +8 -1
  151. package/src/runtime/contract.ts +36 -2
  152. package/src/runtime/db.ts +140 -20
  153. package/src/runtime/declaration.ts +227 -89
  154. package/src/runtime/requests.ts +27 -11
  155. package/src/runtime/types.generated.ts +1 -1
  156. package/src/server/files.ts +29 -11
  157. package/src/server/host.ts +158 -3
  158. package/src/server/index.ts +1 -0
  159. package/src/server/peer.ts +21 -0
  160. package/src/server/proxy.ts +13 -3
  161. package/src/server/server.ts +139 -36
  162. package/src/server/types.ts +6 -3
  163. package/src/shell/annotate.ts +233 -15
  164. package/src/shell/document.ts +8 -0
  165. package/src/shell/runtime.ts +361 -14
  166. package/types/runtime/v1/context.d.ts +13 -2
@@ -126,6 +126,8 @@ const check = {
126
126
  confirm: () => Promise.resolve("declined"),
127
127
  // A viewer who doesn't allow a live widget their data (P079): its calls are refused.
128
128
  consent: () => false,
129
+ // Model context goes to a surface nobody reads here (P100): the check has no person.
130
+ show: () => { },
129
131
  // A served config's instance, issued by the check's own server on this page's origin.
130
132
  locator: {
131
133
  locate: async (instance) => (await (await fetch("/issue", { method: "POST", body: JSON.stringify({ instance }) })).json()),
@@ -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(" "),
@@ -16,8 +16,9 @@ export declare function declaredCapabilities(config: PortholeConfig): Capability
16
16
  /** The gates a declared capability runs under: its own, else the vocabulary's defaults. */
17
17
  export declare function effectiveGates(config: PortholeConfig, name: CapabilityName): readonly Gate[];
18
18
  /**
19
- * The gates one call runs under: its host function's, and its runtime method's own (after the
20
- * review: `artifact.publish`, `assets.delete`, an upload whose code may run), every one applying.
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.
21
22
  */
22
23
  export declare function callGates(config: PortholeConfig, name: CapabilityName, args: unknown): readonly Gate[];
23
24
  /** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
@@ -73,6 +74,41 @@ export declare function serializeCsp(directives: readonly CspDirective[]): strin
73
74
  * isn't). External (url mode): what a running web app needs to work on its own origin.
74
75
  */
75
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;
76
112
  /**
77
113
  * The frame's `allow` attribute (Permissions Policy). No camera, microphone, geolocation,
78
114
  * fullscreen or other powerful feature is delegated to the frame, and the clipboard is denied by
@@ -1,6 +1,6 @@
1
1
  import { CAPABILITIES } from "../config/capabilities.js";
2
2
  import { LIBRARY_PATH } from "../libraries/libraries.js";
3
- import { assetCodeRuns, familyOf, methodGates, methodOf } from "../runtime/contract.js";
3
+ import { assetCodeRuns, familyOf, methodGates, methodsOfCall } from "../runtime/contract.js";
4
4
  import { ASSET_PATH } from "../runtime/requests.js";
5
5
  /** Whether `kind` loads from any https site (`EgressConfig.anyHttps`, P059): passive kinds only. */
6
6
  export function anyHttps(config, kind) {
@@ -15,15 +15,24 @@ export function effectiveGates(config, name) {
15
15
  return config.capabilities[name]?.gates ?? CAPABILITIES[name].defaultGates;
16
16
  }
17
17
  /**
18
- * The gates one call runs under: its host function's, and its runtime method's own (after the
19
- * review: `artifact.publish`, `assets.delete`, an upload whose code may run), every one applying.
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.
20
21
  */
21
22
  export function callGates(config, name, args) {
22
- const gates = effectiveGates(config, name);
23
+ const gates = [...effectiveGates(config, name)];
23
24
  const family = familyOf(name);
24
- const method = family === null ? null : methodOf(name, args);
25
- const own = family === null || method === null ? [] : methodGates(config, family.name, method);
26
- return own.length === 0 ? gates : [...gates, ...own.filter((gate) => !gates.includes(gate))];
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;
27
36
  }
28
37
  const unique = (values) => [...new Set(values)];
29
38
  /** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
@@ -170,6 +179,112 @@ export function sandboxTokens(config) {
170
179
  return ["allow-scripts", "allow-same-origin", "allow-forms", ...(config.sandbox ?? [])];
171
180
  }
172
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
+ }
173
288
  /**
174
289
  * The frame's `allow` attribute (Permissions Policy). No camera, microphone, geolocation,
175
290
  * fullscreen or other powerful feature is delegated to the frame, and the clipboard is denied by
@@ -25,8 +25,11 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
25
25
  * call of any of its consent-gated capabilities, whether this content may have them (a viewer
26
26
  * allowing a widget to read their data). A no refuses every such call for the display's life;
27
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).
28
31
  */
29
- export type Gate = "user-activation" | "confirm" | "consent" | {
32
+ export type Gate = "user-activation" | "confirm" | "consent" | "show" | {
30
33
  readonly rateLimit: {
31
34
  readonly perMinute: number;
32
35
  };
@@ -53,6 +56,11 @@ export interface CapabilitySpec {
53
56
  }
54
57
  /** The most text one `copyText` call carries. */
55
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;
56
64
  export declare const CAPABILITIES: {
57
65
  readonly sendPrompt: {
58
66
  readonly defaultGates: readonly ["user-activation", "confirm"];
@@ -81,7 +89,7 @@ export declare const CAPABILITIES: {
81
89
  };
82
90
  };
83
91
  readonly callTool: {
84
- readonly defaultGates: readonly ["confirm"];
92
+ readonly defaultGates: readonly ["confirm", Gate];
85
93
  readonly served: "handler";
86
94
  readonly request: {
87
95
  readonly method: "tools/call";
@@ -110,8 +118,12 @@ export declare const CAPABILITIES: {
110
118
  readonly method: "resources/subscribe";
111
119
  };
112
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
+ */
113
125
  readonly setModelContext: {
114
- readonly defaultGates: readonly [Gate];
126
+ readonly defaultGates: readonly [Gate, "show"];
115
127
  readonly served: "handler";
116
128
  readonly request: {
117
129
  readonly method: "ui/update-model-context";
@@ -210,8 +222,15 @@ export interface CapabilityArgs {
210
222
  readonly subscribeData: {
211
223
  readonly uri: string;
212
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
+ */
213
229
  readonly setModelContext: {
214
- readonly content?: readonly unknown[];
230
+ readonly content?: readonly {
231
+ readonly type: "text";
232
+ readonly text: string;
233
+ }[];
215
234
  readonly structuredContent?: Readonly<Record<string, unknown>>;
216
235
  };
217
236
  /**
@@ -29,6 +29,11 @@ export const CAPABILITY_NAMES = [
29
29
  const rate = (perMinute) => ({ rateLimit: { perMinute } });
30
30
  /** The most text one `copyText` call carries. */
31
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;
32
37
  export const CAPABILITIES = {
33
38
  sendPrompt: {
34
39
  defaultGates: ["user-activation", "confirm"],
@@ -48,7 +53,8 @@ export const CAPABILITIES = {
48
53
  request: { method: "ui/download-file", sdk: "app.downloadFile" },
49
54
  },
50
55
  callTool: {
51
- 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)],
52
58
  served: "handler",
53
59
  request: { method: "tools/call", sdk: "app.callServerTool" },
54
60
  },
@@ -69,8 +75,12 @@ export const CAPABILITIES = {
69
75
  global: "subscribeData",
70
76
  request: { method: "resources/subscribe" },
71
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
+ */
72
82
  setModelContext: {
73
- defaultGates: [rate(30)],
83
+ defaultGates: [rate(30), "show"],
74
84
  served: "handler",
75
85
  request: { method: "ui/update-model-context", sdk: "app.updateModelContext" },
76
86
  },
@@ -37,6 +37,13 @@ export type ThemeValue = string | {
37
37
  export interface CapabilityConfig {
38
38
  /** Every gate must pass. Omitted: the capability's default gates. `[]`: ungated. */
39
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;
40
47
  /** Extra `connect-src` origins this capability needs. */
41
48
  readonly connect?: readonly string[];
42
49
  /** Extra script/style/img/font/media origins this capability needs. */
@@ -55,6 +62,10 @@ export interface CapabilityConfig {
55
62
  * Gates of each runtime method it serves, by name, in place of the contract's own (after the
56
63
  * review: `artifact.publish` and `assets.delete` need a click and a yes; `assets.upload` a yes
57
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.
58
69
  */
59
70
  readonly methodGates?: Readonly<Record<string, readonly Gate[]>>;
60
71
  }
@@ -1,3 +1,4 @@
1
+ import { type ConfigWarning } from "./warnings.ts";
1
2
  import { type PortholeConfig } from "./schema.ts";
2
3
  /**
3
4
  * Checks a config before anything is derived from it. Every string that ends up in a CSP, an
@@ -18,5 +19,10 @@ export declare const BUILT_IN_TOPICS: readonly ["widget", "chart", "interactive"
18
19
  export declare function isOriginSource(value: unknown): value is string;
19
20
  /** Why `value` isn't an origin source Porthole accepts, in words to act on; null if it is. */
20
21
  export declare function originSourceProblem(value: unknown): string | null;
21
- /** Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise. */
22
- export declare function validateConfig(input: unknown): PortholeConfig;
22
+ /**
23
+ * Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise.
24
+ * `onWarning` hears each `ConfigWarning` a valid config earns (`configWarnings`).
25
+ */
26
+ export declare function validateConfig(input: unknown, options?: {
27
+ readonly onWarning?: (warning: ConfigWarning) => void;
28
+ }): PortholeConfig;
@@ -1,4 +1,5 @@
1
- import { CAPABILITY_NAMES, isCapabilityName, } from "./capabilities.js";
1
+ import { CAPABILITY_NAMES, capabilitySpec, isCapabilityName, } from "./capabilities.js";
2
+ import { configWarnings } from "./warnings.js";
2
3
  import { RUNTIME_HOST_FUNCTIONS, RUNTIME_VERSIONS, familyOf, isRuntimeVersion, runtimeCapability, } from "../runtime/contract.js";
3
4
  import { atLeast, isViewerLevel } from "../runtime/levels.js";
4
5
  import { PASSIVE_KINDS, URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./schema.js";
@@ -231,12 +232,15 @@ function positive(value, path, max = Number.MAX_SAFE_INTEGER) {
231
232
  }
232
233
  }
233
234
  function gate(value, path) {
234
- if (value === "user-activation" || value === "confirm" || value === "consent") {
235
+ if (value === "user-activation" ||
236
+ value === "confirm" ||
237
+ value === "consent" ||
238
+ value === "show") {
235
239
  return;
236
240
  }
237
241
  const limit = isObject(value) && isObject(value.rateLimit) ? value.rateLimit : null;
238
242
  if (limit === null || Object.keys(value).length !== 1) {
239
- fail(path, 'must be "user-activation", "confirm", "consent" or { rateLimit: { perMinute } }');
243
+ fail(path, 'must be "user-activation", "confirm", "consent", "show" or { rateLimit: { perMinute } }');
240
244
  return;
241
245
  }
242
246
  only(limit, ["perMinute"], `${path}.rateLimit`);
@@ -244,8 +248,11 @@ function gate(value, path) {
244
248
  }
245
249
  const MODES = ["inline", "artifact", "mcp-app", "url"];
246
250
  const ISOLATIONS = ["opaque", "domain", "external"];
247
- /** Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise. */
248
- export function validateConfig(input) {
251
+ /**
252
+ * Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise.
253
+ * `onWarning` hears each `ConfigWarning` a valid config earns (`configWarnings`).
254
+ */
255
+ export function validateConfig(input, options = {}) {
249
256
  const config = object(input, "config");
250
257
  only(config, [
251
258
  "mode",
@@ -280,7 +287,7 @@ export function validateConfig(input) {
280
287
  fail(path, `is not a capability (${CAPABILITY_NAMES.join(", ")})`);
281
288
  }
282
289
  const capability = object(value, path);
283
- only(capability, ["gates", "connect", "resource", "guide", "levels", "methodGates"], path);
290
+ only(capability, ["gates", "connect", "resource", "guide", "levels", "methodGates", "withoutShow"], path);
284
291
  if (capability.methodGates !== undefined) {
285
292
  const family = familyOf(name);
286
293
  for (const [method, gates] of Object.entries(object(capability.methodGates, `${path}.methodGates`))) {
@@ -321,6 +328,18 @@ export function validateConfig(input) {
321
328
  }
322
329
  capability.gates.forEach((each, index) => gate(each, `${path}.gates[${index}]`));
323
330
  }
331
+ // Leaving the default `show` out on purpose (P100): only where there is one, left out.
332
+ if (capability.withoutShow !== undefined) {
333
+ if (capability.withoutShow !== true) {
334
+ fail(`${path}.withoutShow`, "must be true: it says the gates leave show out on purpose");
335
+ }
336
+ if (!capabilitySpec(name).defaultGates.includes("show")) {
337
+ fail(`${path}.withoutShow`, `${name} has no show gate to leave out`);
338
+ }
339
+ if (!Array.isArray(capability.gates) || capability.gates.includes("show")) {
340
+ fail(`${path}.withoutShow`, "says show is left out, so the gates must be named, without it");
341
+ }
342
+ }
324
343
  sources(capability.connect, `${path}.connect`);
325
344
  sources(capability.resource, `${path}.resource`);
326
345
  if (capability.guide !== undefined && typeof capability.guide !== "string") {
@@ -548,5 +567,8 @@ export function validateConfig(input) {
548
567
  }
549
568
  });
550
569
  }
570
+ for (const warning of configWarnings(input)) {
571
+ options.onWarning?.(warning);
572
+ }
551
573
  return input;
552
574
  }
@@ -0,0 +1,20 @@
1
+ import type { PortholeConfig } from "./schema.ts";
2
+ /**
3
+ * What a valid config says that its host likely didn't mean (the review of P100): never an error,
4
+ * since the config is the host's to write. Porthole logs nothing itself (no console in library
5
+ * code): `validateConfig(config, { onWarning })` hands each one over, and `compile(config).warnings`
6
+ * (`host.compiled.warnings`) holds them, for a host to log at startup or fail its tests on.
7
+ */
8
+ export interface ConfigWarning {
9
+ /** `model-context-unshown`: a capability whose defaults have `show` lost it to named gates. */
10
+ readonly code: "model-context-unshown";
11
+ readonly path: string;
12
+ readonly message: string;
13
+ }
14
+ /**
15
+ * Each warning `config` earns. Since 0.8 (P100), `setModelContext`'s defaults have `show`; a
16
+ * config that names its gates (one written for 0.7 did, to change the rate) and leaves `show` out
17
+ * sends content's text to the model unseen, so it is said, unless `withoutShow: true` says the
18
+ * host meant it (its handler shows the person each update, or the content is its own).
19
+ */
20
+ export declare function configWarnings(config: PortholeConfig): readonly ConfigWarning[];
@@ -0,0 +1,25 @@
1
+ import { capabilitySpec, isCapabilityName } from "./capabilities.js";
2
+ /**
3
+ * Each warning `config` earns. Since 0.8 (P100), `setModelContext`'s defaults have `show`; a
4
+ * config that names its gates (one written for 0.7 did, to change the rate) and leaves `show` out
5
+ * sends content's text to the model unseen, so it is said, unless `withoutShow: true` says the
6
+ * host meant it (its handler shows the person each update, or the content is its own).
7
+ */
8
+ export function configWarnings(config) {
9
+ const warnings = [];
10
+ for (const [name, capability] of Object.entries(config.capabilities)) {
11
+ if (!isCapabilityName(name) ||
12
+ capability?.gates === undefined ||
13
+ !capabilitySpec(name).defaultGates.includes("show") ||
14
+ capability.gates.includes("show") ||
15
+ capability.withoutShow === true) {
16
+ continue;
17
+ }
18
+ warnings.push({
19
+ code: "model-context-unshown",
20
+ path: `config.capabilities.${name}.gates`,
21
+ message: `${name}'s gates leave out "show" (P100): what content tells the model reaches it without the person seeing it. Add "show" to the gates, or set withoutShow: true where your handler shows the person each update itself.`,
22
+ });
23
+ }
24
+ return warnings;
25
+ }
@@ -1,7 +1,7 @@
1
1
  import { expect } from "@playwright/test";
2
2
  import { presets } from "../presets/presets.js";
3
3
  import { resolveTheme } from "../theme/variables.js";
4
- import { inline } from "./kit.js";
4
+ import { inline, js } from "./kit.js";
5
5
  import { settle } from "./oracles.js";
6
6
  /**
7
7
  * The display's behavior in a real frame (item 11: streaming, sizing, theming, base styles) and
@@ -52,6 +52,19 @@ async function bodyData(display, name, timeout = 5_000) {
52
52
  .not.toBeNull();
53
53
  return (await frame.locator("body").getAttribute(`data-${name}`)) ?? "";
54
54
  }
55
+ /** A model context update (P100): what the view says the person is looking at. */
56
+ const CONTEXT_UPDATE = {
57
+ content: [{ type: "text", text: "The person is looking at March's signups." }],
58
+ structuredContent: { month: "March", signups: 412 },
59
+ };
60
+ /** Content that sends it as the App SDK does (`ui/update-model-context`), and keeps the answer. */
61
+ const CONTEXT_CONTENT = `<p>signups</p>
62
+ <script>
63
+ addEventListener("message", (event) => {
64
+ if (event.data && event.data.id === "ctx-1") document.body.dataset.answer = JSON.stringify(event.data.error ? event.data.error.data : event.data.result);
65
+ });
66
+ parent.postMessage({ jsonrpc: "2.0", id: "ctx-1", method: "ui/update-model-context", params: ${js(CONTEXT_UPDATE)} }, "*");
67
+ </script>`;
55
68
  const PROMPT_CONTENT = `<button id="ask">Explain March</button>
56
69
  <script>
57
70
  document.getElementById("ask").addEventListener("click", () => {
@@ -436,4 +449,36 @@ export const BEHAVIOR_PROBES = [
436
449
  expect(await display.calls()).toEqual([]);
437
450
  },
438
451
  },
452
+ {
453
+ id: "12.model-context",
454
+ item: 12,
455
+ title: "what content tells the model, the person is shown first, whole; a host that can't show it gets none (S5, P100)",
456
+ async run(context) {
457
+ const config = inline({ capabilities: { setModelContext: {} } });
458
+ const display = await context.launch({ config, content: CONTEXT_CONTENT });
459
+ const said = display.shown?.bind(display);
460
+ if (said === undefined) {
461
+ return context.inapplicable("this host's harness doesn't say what it shows the person (LaunchedDisplay.shown)");
462
+ }
463
+ expect(await bodyData(display, "answer")).toBe("{}");
464
+ const shown = await said();
465
+ expect(shown, "the update reached the model unseen").toHaveLength(1);
466
+ expect(shown[0]).toMatchObject({
467
+ capability: "setModelContext",
468
+ args: CONTEXT_UPDATE,
469
+ display: { title: "Probe" },
470
+ });
471
+ expect(await display.calls()).toEqual([
472
+ { capability: "setModelContext", args: CONTEXT_UPDATE },
473
+ ]);
474
+ const unseen = await context.launch({ config, shows: false, content: CONTEXT_CONTENT });
475
+ const answer = JSON.parse(await bodyData(unseen, "answer"));
476
+ if (answer.code === undefined && ((await unseen.shown?.()) ?? []).length > 0) {
477
+ return context.inapplicable("this host always has a show function (a default surface), so a display without one can't be shown; it showed the person instead");
478
+ }
479
+ expect(answer.code, "an update nobody could see was taken").toBe("not_allowed");
480
+ expect(await refusals(unseen)).toContain("setModelContext:no-show");
481
+ expect(await unseen.calls()).toEqual([]);
482
+ },
483
+ },
439
484
  ];
@@ -0,0 +1,15 @@
1
+ import type { Page } from "@playwright/test";
2
+ /**
3
+ * Whether this browser keeps a cookie a cross-site frame's own document was answered with
4
+ * (P025, P098): what a framed url-mode app needs, since its every request rides on the cookie its
5
+ * ticket's answer set. Measured, never assumed from the engine's name: Playwright's WebKit keeps
6
+ * none on Linux and keeps them on macOS (the audit of 2026-10-19), and an engine's policy changes
7
+ * between versions.
8
+ *
9
+ * The probe is the browser's own, outside the host under test: in a context of its own, a page on
10
+ * one site frames a page on another (both answered by the probe's routes, never the network,
11
+ * never the host's server), whose answer sets a cookie as Porthole's server sets a framed one
12
+ * (`Secure; SameSite=None; Partitioned`, over the display's own scheme); the frame then reads
13
+ * whether it was kept. Asked once per browser.
14
+ */
15
+ export declare function keepsFramedCookies(page: Page, scheme: "http:" | "https:"): Promise<boolean>;