@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
@@ -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
@@ -10,7 +11,7 @@ export declare class ConfigError extends Error {
10
11
  constructor(path: string, message: string);
11
12
  }
12
13
  /** The built-in manual topics; a host's own topics may not reuse these names. */
13
- export declare const BUILT_IN_TOPICS: readonly ["widget", "chart", "interactive"];
14
+ export declare const BUILT_IN_TOPICS: readonly ["widget", "chart", "interactive", "capabilities"];
14
15
  /**
15
16
  * Whether `value` is a CSP host source Porthole accepts: a scheme, a host (optionally `*.` for
16
17
  * every subdomain) and an optional port, nothing else. Insecure schemes only for loopback names.
@@ -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,7 @@
1
- import { CAPABILITY_NAMES, isCapabilityName } from "./capabilities.js";
1
+ import { CAPABILITY_NAMES, capabilitySpec, isCapabilityName, } from "./capabilities.js";
2
+ import { configWarnings } from "./warnings.js";
3
+ import { RUNTIME_HOST_FUNCTIONS, RUNTIME_VERSIONS, familyOf, isRuntimeVersion, runtimeCapability, } from "../runtime/contract.js";
4
+ import { atLeast, isViewerLevel } from "../runtime/levels.js";
2
5
  import { PASSIVE_KINDS, URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./schema.js";
3
6
  /**
4
7
  * Checks a config before anything is derived from it. Every string that ends up in a CSP, an
@@ -15,7 +18,7 @@ export class ConfigError extends Error {
15
18
  }
16
19
  }
17
20
  /** The built-in manual topics; a host's own topics may not reuse these names. */
18
- export const BUILT_IN_TOPICS = ["widget", "chart", "interactive"];
21
+ export const BUILT_IN_TOPICS = ["widget", "chart", "interactive", "capabilities"];
19
22
  const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/u;
20
23
  /**
21
24
  * Suffixes under which anyone can register or publish a name (a public suffix): a wildcard over
@@ -229,12 +232,15 @@ function positive(value, path, max = Number.MAX_SAFE_INTEGER) {
229
232
  }
230
233
  }
231
234
  function gate(value, path) {
232
- if (value === "user-activation" || value === "confirm" || value === "consent") {
235
+ if (value === "user-activation" ||
236
+ value === "confirm" ||
237
+ value === "consent" ||
238
+ value === "show") {
233
239
  return;
234
240
  }
235
241
  const limit = isObject(value) && isObject(value.rateLimit) ? value.rateLimit : null;
236
242
  if (limit === null || Object.keys(value).length !== 1) {
237
- fail(path, 'must be "user-activation", "confirm", "consent" or { rateLimit: { perMinute } }');
243
+ fail(path, 'must be "user-activation", "confirm", "consent", "show" or { rateLimit: { perMinute } }');
238
244
  return;
239
245
  }
240
246
  only(limit, ["perMinute"], `${path}.rateLimit`);
@@ -242,8 +248,11 @@ function gate(value, path) {
242
248
  }
243
249
  const MODES = ["inline", "artifact", "mcp-app", "url"];
244
250
  const ISOLATIONS = ["opaque", "domain", "external"];
245
- /** Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise. */
246
- 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 = {}) {
247
256
  const config = object(input, "config");
248
257
  only(config, [
249
258
  "mode",
@@ -260,6 +269,7 @@ export function validateConfig(input) {
260
269
  "permissions",
261
270
  "storage",
262
271
  "errors",
272
+ "runtime",
263
273
  ], "config");
264
274
  if (!MODES.includes(config.mode)) {
265
275
  fail("config.mode", `must be one of ${MODES.join(", ")}`);
@@ -277,13 +287,59 @@ export function validateConfig(input) {
277
287
  fail(path, `is not a capability (${CAPABILITY_NAMES.join(", ")})`);
278
288
  }
279
289
  const capability = object(value, path);
280
- only(capability, ["gates", "connect", "resource", "guide"], path);
290
+ only(capability, ["gates", "connect", "resource", "guide", "levels", "methodGates", "withoutShow"], path);
291
+ if (capability.methodGates !== undefined) {
292
+ const family = familyOf(name);
293
+ for (const [method, gates] of Object.entries(object(capability.methodGates, `${path}.methodGates`))) {
294
+ const methods = family === null ? undefined : runtimeCapability(family.name).methods;
295
+ if (methods === undefined ||
296
+ !Object.hasOwn(methods, method) ||
297
+ methods[method]?.serves !== name) {
298
+ fail(`${path}.methodGates.${method}`, `is not a runtime method ${name} serves`);
299
+ }
300
+ if (!Array.isArray(gates)) {
301
+ fail(`${path}.methodGates.${method}`, "must be an array of gates");
302
+ }
303
+ gates.forEach((each, index) => gate(each, `${path}.methodGates.${method}[${index}]`));
304
+ }
305
+ }
306
+ if (capability.levels !== undefined) {
307
+ const levels = object(capability.levels, `${path}.levels`);
308
+ const family = familyOf(name);
309
+ for (const [method, level] of Object.entries(levels)) {
310
+ const methods = family === null ? undefined : runtimeCapability(family.name).methods;
311
+ const spec = methods !== undefined && Object.hasOwn(methods, method) ? methods[method] : undefined;
312
+ if (family === null || spec === undefined || spec.serves !== name) {
313
+ fail(`${path}.levels.${method}`, family === null
314
+ ? `${name} serves no runtime method: it has no levels`
315
+ : `is not a method ${name} serves (${family.methods.join(", ")})`);
316
+ }
317
+ if (!isViewerLevel(level)) {
318
+ fail(`${path}.levels.${method}`, "must be view, interact, admin or owner");
319
+ }
320
+ if (spec !== undefined && !atLeast(level, spec.floor)) {
321
+ fail(`${path}.levels.${method}`, `can't be below ${spec.floor} (${family?.name}.${method}'s floor, P087)`);
322
+ }
323
+ }
324
+ }
281
325
  if (capability.gates !== undefined) {
282
326
  if (!Array.isArray(capability.gates)) {
283
327
  fail(`${path}.gates`, "must be an array");
284
328
  }
285
329
  capability.gates.forEach((each, index) => gate(each, `${path}.gates[${index}]`));
286
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
+ }
287
343
  sources(capability.connect, `${path}.connect`);
288
344
  sources(capability.resource, `${path}.resource`);
289
345
  if (capability.guide !== undefined && typeof capability.guide !== "string") {
@@ -293,6 +349,29 @@ export function validateConfig(input) {
293
349
  if (config.mode === "url" && Object.keys(capabilities).length > 0) {
294
350
  fail("config.capabilities", "url mode has no shell, so it can declare no capabilities");
295
351
  }
352
+ // The capability runtime (P085): its global and its own host functions.
353
+ if (config.runtime !== undefined) {
354
+ if (!isRuntimeVersion(config.runtime)) {
355
+ fail("config.runtime", `must be a runtime contract version: ${RUNTIME_VERSIONS.join(", ")}`);
356
+ }
357
+ if (config.mode !== "inline" && config.mode !== "artifact") {
358
+ fail("config.runtime", "the runtime is the shell's: inline widgets and artifact pages only");
359
+ }
360
+ }
361
+ for (const name of RUNTIME_HOST_FUNCTIONS) {
362
+ if (capabilities[name] === undefined) {
363
+ continue;
364
+ }
365
+ if (config.runtime === undefined) {
366
+ fail(`config.capabilities.${name}`, "is the capability runtime's: set config.runtime (content reaches it through porthole.use)");
367
+ }
368
+ if ((name === "artifact" || name === "assets") && config.mode !== "artifact") {
369
+ fail(`config.capabilities.${name}`, "is an artifact page's: artifact mode only");
370
+ }
371
+ }
372
+ if (capabilities.assets !== undefined && config.isolation !== "domain") {
373
+ fail("config.capabilities.assets", "assets are served from the page's own origin (/_blob/): domain isolation only");
374
+ }
296
375
  const egress = object(config.egress, "config.egress");
297
376
  const kinds = ["connect", "script", "style", "img", "font", "media"];
298
377
  only(egress, [...kinds, "anyHttps", "libraries"], "config.egress");
@@ -408,7 +487,9 @@ export function validateConfig(input) {
408
487
  for (const [name, text] of Object.entries(object(guide.topics, "config.guide.topics"))) {
409
488
  const path = `config.guide.topics.${name}`;
410
489
  if (!/^[a-z][a-z0-9-]{0,31}$/u.test(name) ||
411
- BUILT_IN_TOPICS.includes(name)) {
490
+ // `capabilities` is built in only under the runtime (P085): a 0.6 config's own stays.
491
+ (BUILT_IN_TOPICS.includes(name) &&
492
+ (name !== "capabilities" || config.runtime !== undefined))) {
412
493
  fail(path, "must be a new topic name (lowercase), not a built-in one");
413
494
  }
414
495
  if (typeof text !== "string" || text.trim() === "") {
@@ -486,5 +567,8 @@ export function validateConfig(input) {
486
567
  }
487
568
  });
488
569
  }
570
+ for (const warning of configWarnings(input)) {
571
+ options.onWarning?.(warning);
572
+ }
489
573
  return input;
490
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>;
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Whether this browser keeps a cookie a cross-site frame's own document was answered with
3
+ * (P025, P098): what a framed url-mode app needs, since its every request rides on the cookie its
4
+ * ticket's answer set. Measured, never assumed from the engine's name: Playwright's WebKit keeps
5
+ * none on Linux and keeps them on macOS (the audit of 2026-10-19), and an engine's policy changes
6
+ * between versions.
7
+ *
8
+ * The probe is the browser's own, outside the host under test: in a context of its own, a page on
9
+ * one site frames a page on another (both answered by the probe's routes, never the network,
10
+ * never the host's server), whose answer sets a cookie as Porthole's server sets a framed one
11
+ * (`Secure; SameSite=None; Partitioned`, over the display's own scheme); the frame then reads
12
+ * whether it was kept. Asked once per browser.
13
+ */
14
+ export function keepsFramedCookies(page, scheme) {
15
+ const browser = page.context().browser();
16
+ const key = `${scheme} ${browser === null ? "persistent" : browser.version()}`;
17
+ const known = cache(browser ?? page.context());
18
+ let answer = known.get(key);
19
+ if (answer === undefined) {
20
+ answer = probe(browser, page.context(), scheme);
21
+ known.set(key, answer);
22
+ }
23
+ return answer;
24
+ }
25
+ const answers = new WeakMap();
26
+ function cache(owner) {
27
+ let known = answers.get(owner);
28
+ if (known === undefined) {
29
+ known = new Map();
30
+ answers.set(owner, known);
31
+ }
32
+ return known;
33
+ }
34
+ /** Two sites the probe makes up: the embedding page's, and the frame's. */
35
+ function sites(scheme) {
36
+ // Over http, as a loopback host and its content origins are (a `*.localhost` frame on a
37
+ // `127.0.0.1` page, the leak suite's own shape); over https, two names that are each a site.
38
+ // Default ports: a browser refuses to navigate to some others (9 is on Fetch's bad-port list).
39
+ return scheme === "http:"
40
+ ? {
41
+ top: "http://127.0.0.1/__porthole-cookie-probe/",
42
+ framed: "http://porthole-cookie-probe.localhost/",
43
+ }
44
+ : {
45
+ top: "https://porthole-cookie-probe-top.test/",
46
+ framed: "https://porthole-cookie-probe-frame.test/",
47
+ };
48
+ }
49
+ async function probe(browser, context, scheme) {
50
+ const own = browser === null ? null : await browser.newContext();
51
+ const page = await (own ?? context).newPage();
52
+ try {
53
+ const { top, framed } = sites(scheme);
54
+ await page.route(`${framed}**`, (route) => route.fulfill({
55
+ status: 200,
56
+ headers: {
57
+ "content-type": "text/html; charset=utf-8",
58
+ "cache-control": "no-store",
59
+ "set-cookie": "porthole-cookie-probe=1; Path=/; Secure; SameSite=None; Partitioned",
60
+ },
61
+ body: "<!doctype html><title>probe</title>",
62
+ }));
63
+ await page.route(top, (route) => route.fulfill({
64
+ status: 200,
65
+ headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
66
+ body: `<!doctype html><title>probe</title><iframe src="${framed}frame"></iframe>`,
67
+ }));
68
+ await page.goto(top);
69
+ const frame = await (await page.locator("iframe").elementHandle())?.contentFrame();
70
+ if (frame === null || frame === undefined) {
71
+ throw new Error("keepsFramedCookies: the probe's frame didn't load");
72
+ }
73
+ await frame.waitForLoadState("load");
74
+ return await frame.evaluate(() => document.cookie.includes("porthole-cookie-probe=1"));
75
+ }
76
+ finally {
77
+ await page.close();
78
+ await own?.close();
79
+ }
80
+ }
@@ -21,6 +21,7 @@ declare const harness: {
21
21
  post(id: number, message: unknown): void;
22
22
  setContent(id: number, html: string, partial: boolean): void;
23
23
  calls: (id: number) => RecordedCall[];
24
+ shown: (id: number) => ConfirmRequest[];
24
25
  events: (id: number) => RecordedEvent[];
25
26
  errors: (id: number) => string[];
26
27
  pendingConfirmations: (id: number) => number;
@@ -78,6 +78,7 @@ const harness = {
78
78
  const container = box(id, spec.widthPx ?? 600, spec.heightPx);
79
79
  const calls = [];
80
80
  const confirmations = [];
81
+ const disclosed = [];
81
82
  const host = createHost(spec.config, {
82
83
  handlers: recorder(calls),
83
84
  ...(spec.confirms === false
@@ -85,6 +86,9 @@ const harness = {
85
86
  : {
86
87
  confirm: (request) => new Promise((resolve) => confirmations.push({ request, resolve })),
87
88
  }),
89
+ ...(spec.shows === false
90
+ ? {}
91
+ : { show: (request) => void disclosed.push(request) }),
88
92
  theme: (scheme) => spec.hostTheme?.[scheme] ?? {},
89
93
  hostInfo: { name: "porthole-conformance", version: "1" },
90
94
  ...(nonce === undefined ? {} : { nonce }),
@@ -95,18 +99,19 @@ const harness = {
95
99
  scheme: spec.scheme ?? "light",
96
100
  ...(spec.document === undefined ? {} : { document: spec.document }),
97
101
  });
98
- const shown = {
102
+ const display = {
99
103
  handle,
100
104
  calls,
101
105
  events: [],
102
106
  confirmations,
107
+ disclosed,
103
108
  received: [],
104
109
  origin: null,
105
110
  failure: null,
106
111
  frame: null,
107
112
  };
108
113
  const initialized = new Promise((resolve) => handle.on("initialized", () => resolve()));
109
- watch(id, shown);
114
+ watch(id, display);
110
115
  if (spec.document === undefined) {
111
116
  await Promise.race([initialized, pause(5_000)]);
112
117
  for (const partial of spec.partials ?? []) {
@@ -133,6 +138,7 @@ const harness = {
133
138
  calls,
134
139
  events: [],
135
140
  confirmations: [],
141
+ disclosed: [],
136
142
  received: [],
137
143
  origin: null,
138
144
  failure: null,
@@ -194,6 +200,7 @@ const harness = {
194
200
  displays.get(id)?.handle.setContent(html, { partial });
195
201
  },
196
202
  calls: (id) => displays.get(id)?.calls ?? [],
203
+ shown: (id) => displays.get(id)?.disclosed ?? [],
197
204
  events: (id) => displays.get(id)?.events ?? [],
198
205
  errors: (id) => (displays.get(id)?.events ?? []).flatMap((event) => event.type === "error" ? [event.detail.message] : []),
199
206
  pendingConfirmations: (id) => displays.get(id)?.confirmations.length ?? 0,