@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,4 +1,14 @@
1
1
  import type { AnnotationReport } from "../annotate/types.ts";
2
+ import type { DbRequest, DbResult } from "../runtime/db.ts";
3
+ import type {
4
+ ArtifactInfo,
5
+ ArtifactRequest,
6
+ AssetInfo,
7
+ AssetRequest,
8
+ CommentRequest,
9
+ PublishedVersion,
10
+ UserInfo,
11
+ } from "../runtime/requests.ts";
2
12
 
3
13
  /**
4
14
  * The capability vocabulary (PRINCIPLE 4): every power content has beyond drawing is one of these
@@ -22,6 +32,12 @@ export const CAPABILITY_NAMES = [
22
32
  "resize",
23
33
  "copyText",
24
34
  "annotate",
35
+ // The capability runtime's own (P085, `config.runtime`): reached through `porthole.use`.
36
+ "user",
37
+ "comments",
38
+ "artifact",
39
+ "assets",
40
+ "db",
25
41
  ] as const;
26
42
 
27
43
  export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
@@ -39,18 +55,25 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
39
55
  * call of any of its consent-gated capabilities, whether this content may have them (a viewer
40
56
  * allowing a widget to read their data). A no refuses every such call for the display's life;
41
57
  * no `consent` function refuses them all (fail closed).
58
+ * - `show` (P100): the host's `show` function puts the call's whole effect in front of the person,
59
+ * outside the frame, before the handler has it; it asks nothing. No `show` function, or one that
60
+ * throws, means the call is refused (fail closed).
42
61
  */
43
62
  export type Gate =
44
63
  | "user-activation"
45
64
  | "confirm"
46
65
  | "consent"
66
+ | "show"
47
67
  | { readonly rateLimit: { readonly perMinute: number } };
48
68
 
49
69
  export interface CapabilitySpec {
50
70
  /** The gates a declared capability gets when its config names none. */
51
71
  readonly defaultGates: readonly Gate[];
52
- /** `handler`: the host passes a function that performs it. `event`: the framework emits it. */
53
- readonly served: "handler" | "event";
72
+ /**
73
+ * `handler`: the host passes a function that performs it. `event`: the framework emits it.
74
+ * `viewer`: the framework answers it from the viewer the host gave the display (`user`).
75
+ */
76
+ readonly served: "handler" | "event" | "viewer";
54
77
  /** The global the shell defines for it (sugar over the protocol message), if any. */
55
78
  readonly global?: string;
56
79
  /**
@@ -66,6 +89,12 @@ const rate = (perMinute: number): Gate => ({ rateLimit: { perMinute } });
66
89
  /** The most text one `copyText` call carries. */
67
90
  export const MAX_COPY_CHARS = 20_000;
68
91
 
92
+ /**
93
+ * The most one `setModelContext` update carries (P100): its text blocks' characters and its
94
+ * structured content's JSON, together. What the person is shown is all of it.
95
+ */
96
+ export const MAX_CONTEXT_CHARS = 20_000;
97
+
69
98
  export const CAPABILITIES = {
70
99
  sendPrompt: {
71
100
  defaultGates: ["user-activation", "confirm"],
@@ -85,7 +114,8 @@ export const CAPABILITIES = {
85
114
  request: { method: "ui/download-file", sdk: "app.downloadFile" },
86
115
  },
87
116
  callTool: {
88
- defaultGates: ["confirm"],
117
+ // A rate as well (P103): it needs no gesture, and a host's `confirm` may say yes by itself.
118
+ defaultGates: ["confirm", rate(30)],
89
119
  served: "handler",
90
120
  request: { method: "tools/call", sdk: "app.callServerTool" },
91
121
  },
@@ -106,8 +136,12 @@ export const CAPABILITIES = {
106
136
  global: "subscribeData",
107
137
  request: { method: "resources/subscribe" },
108
138
  },
139
+ /**
140
+ * Text for the model's next turns (P100): the content's own words, which the person never typed.
141
+ * Shown to them first by default (`show`), so nothing reaches the model they couldn't see.
142
+ */
109
143
  setModelContext: {
110
- defaultGates: [rate(30)],
144
+ defaultGates: [rate(30), "show"],
111
145
  served: "handler",
112
146
  request: { method: "ui/update-model-context", sdk: "app.updateModelContext" },
113
147
  },
@@ -129,6 +163,20 @@ export const CAPABILITIES = {
129
163
  * (it shares the realm): UI hints for the host, never permissions.
130
164
  */
131
165
  annotate: { defaultGates: [rate(120)], served: "event" },
166
+ /** Who is viewing (P087): answered from the viewer the host gave the display. */
167
+ user: { defaultGates: [rate(60)], served: "viewer", request: { method: "porthole/call" } },
168
+ /** Opens the host's comment composer at the page's anchor (P090): write-only. */
169
+ comments: {
170
+ defaultGates: ["user-activation", rate(30)],
171
+ served: "handler",
172
+ request: { method: "porthole/call" },
173
+ },
174
+ /** This artifact's current version, and a new version of it, base-checked (P088). */
175
+ artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
176
+ /** The artifact's asset library, served at `/_blob/<id>` (P089). */
177
+ assets: { defaultGates: [rate(30)], served: "handler", request: { method: "porthole/call" } },
178
+ /** The artifact's shared document store (P088). */
179
+ db: { defaultGates: [rate(600)], served: "handler", request: { method: "porthole/call" } },
132
180
  } as const satisfies { readonly [N in CapabilityName]: CapabilitySpec };
133
181
 
134
182
  /** The arguments a call carries, once the adapter has validated them. */
@@ -143,8 +191,12 @@ export interface CapabilityArgs {
143
191
  };
144
192
  readonly readData: { readonly uri: string };
145
193
  readonly subscribeData: { readonly uri: string };
194
+ /**
195
+ * Text blocks only (the modality the host offers), each rebuilt as `{ type, text }`; structured
196
+ * content plain JSON (P100). At most `MAX_CONTEXT_CHARS` together.
197
+ */
146
198
  readonly setModelContext: {
147
- readonly content?: readonly unknown[];
199
+ readonly content?: readonly { readonly type: "text"; readonly text: string }[];
148
200
  readonly structuredContent?: Readonly<Record<string, unknown>>;
149
201
  };
150
202
  /**
@@ -156,6 +208,12 @@ export interface CapabilityArgs {
156
208
  readonly copyText: { readonly text: string };
157
209
  /** What the frame reported, once checked (`AnnotationReport`). */
158
210
  readonly annotate: AnnotationReport;
211
+ readonly user: Readonly<Record<string, never>>;
212
+ readonly comments: CommentRequest;
213
+ readonly artifact: ArtifactRequest;
214
+ readonly assets: AssetRequest;
215
+ /** Paths checked, `me` resolved, the viewer's own data only (P088). */
216
+ readonly db: DbRequest;
159
217
  }
160
218
 
161
219
  /** What a call resolves to. Protocol-shaped results (a tool's result) stay opaque to the core. */
@@ -176,6 +234,14 @@ export interface CapabilityResults {
176
234
  /** Whether the text was copied. */
177
235
  readonly copyText: boolean;
178
236
  readonly annotate: undefined;
237
+ readonly user: UserInfo;
238
+ /** Whether the composer opened. Never a thread: content doesn't read comments (P090). */
239
+ readonly comments: boolean;
240
+ /** `get`: the current version; `publish`: the new one. */
241
+ readonly artifact: ArtifactInfo | PublishedVersion;
242
+ /** `list`: the library; `upload`: the new asset; `delete`: whether it was removed. */
243
+ readonly assets: AssetInfo | readonly AssetInfo[] | boolean;
244
+ readonly db: DbResult;
179
245
  }
180
246
 
181
247
  /** The capabilities a host serves with a handler. */
@@ -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
  /**
@@ -38,12 +40,37 @@ export type ThemeValue = string | { readonly light: string; readonly dark: strin
38
40
  export interface CapabilityConfig {
39
41
  /** Every gate must pass. Omitted: the capability's default gates. `[]`: ungated. */
40
42
  readonly gates?: readonly Gate[];
43
+ /**
44
+ * Says that `gates` leaves out the default `show` on purpose (P100: `setModelContext`): the
45
+ * host's handler shows the person each update itself, or the content is its own. Without it,
46
+ * such gates earn a warning (`configWarnings`); with `show` in the gates, or no gates named, it
47
+ * is an error.
48
+ */
49
+ readonly withoutShow?: true;
41
50
  /** Extra `connect-src` origins this capability needs. */
42
51
  readonly connect?: readonly string[];
43
52
  /** Extra script/style/img/font/media origins this capability needs. */
44
53
  readonly resource?: readonly string[];
45
54
  /** Replaces the generated manual entry for this capability. */
46
55
  readonly guide?: string;
56
+ /**
57
+ * The least viewer level that may call each of the runtime methods it serves (P087), by method
58
+ * name (`db: { levels: { set: "admin" } }`, `sendPrompt: { levels: { send: "admin" } }`): over
59
+ * the contract's own, never below a method's floor (`RUNTIME_CAPABILITIES`). For
60
+ * `assets.upload`, `admin` or above also lets the page run what was uploaded as scripts and
61
+ * styles (P089); `interact` doesn't.
62
+ */
63
+ readonly levels?: Readonly<Record<string, ViewerLevel>>;
64
+ /**
65
+ * Gates of each runtime method it serves, by name, in place of the contract's own (after the
66
+ * review: `artifact.publish` and `assets.delete` need a click and a yes; `assets.upload` a yes
67
+ * where uploaded code may run). Every one applies on top of `gates`. `[]`: none of its own.
68
+ * A call that runs other methods runs under theirs too (P094): a db `batch` under each of its
69
+ * writes' (`set`, `update`, `delete`; one confirmation for the whole batch, a rate counting each
70
+ * write), a `watch` under `get`'s (a document) or `query`'s (a collection), checked when it
71
+ * starts: its updates are its answers, so a rate counts once per watch, not per update.
72
+ */
73
+ readonly methodGates?: Readonly<Record<string, readonly Gate[]>>;
47
74
  }
48
75
 
49
76
  /** The declared capabilities. Absent: not available, not wired, not in the CSP, not in the manual. */
@@ -223,6 +250,14 @@ export interface PortholeConfig {
223
250
  * declares no `reportError`). Absent: the manual says they are reported to the app.
224
251
  */
225
252
  readonly errors?: "agent" | "host" | "none";
253
+ /**
254
+ * The capability runtime (P085): content reaches capabilities through one global,
255
+ * `porthole.use(name)`, under this contract version, and the manual teaches it (with declaring
256
+ * them, `capabilities: { name: config }`, for pages that are published). Only with it may the
257
+ * config declare the runtime's own host functions (`user`, `comments`, `artifact`, `assets`,
258
+ * `db`). Absent: 0.6's frames, globals and manual, exactly.
259
+ */
260
+ readonly runtime?: RuntimeVersion;
226
261
  }
227
262
 
228
263
  export interface StorageConfig {
@@ -1,4 +1,20 @@
1
- import { CAPABILITY_NAMES, isCapabilityName, type Gate } from "./capabilities.ts";
1
+ import {
2
+ CAPABILITY_NAMES,
3
+ capabilitySpec,
4
+ isCapabilityName,
5
+ type CapabilityName,
6
+ type Gate,
7
+ } from "./capabilities.ts";
8
+ import { configWarnings, type ConfigWarning } from "./warnings.ts";
9
+ import {
10
+ RUNTIME_HOST_FUNCTIONS,
11
+ RUNTIME_VERSIONS,
12
+ familyOf,
13
+ isRuntimeVersion,
14
+ runtimeCapability,
15
+ type RuntimeMethod,
16
+ } from "../runtime/contract.ts";
17
+ import { atLeast, isViewerLevel } from "../runtime/levels.ts";
2
18
  import {
3
19
  PASSIVE_KINDS,
4
20
  URL_PERMISSIONS,
@@ -24,7 +40,7 @@ export class ConfigError extends Error {
24
40
  }
25
41
 
26
42
  /** The built-in manual topics; a host's own topics may not reuse these names. */
27
- export const BUILT_IN_TOPICS = ["widget", "chart", "interactive"] as const;
43
+ export const BUILT_IN_TOPICS = ["widget", "chart", "interactive", "capabilities"] as const;
28
44
 
29
45
  const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/u;
30
46
 
@@ -258,12 +274,20 @@ function positive(value: unknown, path: string, max = Number.MAX_SAFE_INTEGER):
258
274
  }
259
275
 
260
276
  function gate(value: unknown, path: string): asserts value is Gate {
261
- if (value === "user-activation" || value === "confirm" || value === "consent") {
277
+ if (
278
+ value === "user-activation" ||
279
+ value === "confirm" ||
280
+ value === "consent" ||
281
+ value === "show"
282
+ ) {
262
283
  return;
263
284
  }
264
285
  const limit = isObject(value) && isObject(value.rateLimit) ? value.rateLimit : null;
265
286
  if (limit === null || Object.keys(value as object).length !== 1) {
266
- fail(path, 'must be "user-activation", "confirm", "consent" or { rateLimit: { perMinute } }');
287
+ fail(
288
+ path,
289
+ 'must be "user-activation", "confirm", "consent", "show" or { rateLimit: { perMinute } }',
290
+ );
267
291
  return;
268
292
  }
269
293
  only(limit, ["perMinute"], `${path}.rateLimit`);
@@ -273,8 +297,14 @@ function gate(value: unknown, path: string): asserts value is Gate {
273
297
  const MODES = ["inline", "artifact", "mcp-app", "url"];
274
298
  const ISOLATIONS = ["opaque", "domain", "external"];
275
299
 
276
- /** Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise. */
277
- export function validateConfig(input: unknown): PortholeConfig {
300
+ /**
301
+ * Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise.
302
+ * `onWarning` hears each `ConfigWarning` a valid config earns (`configWarnings`).
303
+ */
304
+ export function validateConfig(
305
+ input: unknown,
306
+ options: { readonly onWarning?: (warning: ConfigWarning) => void } = {},
307
+ ): PortholeConfig {
278
308
  const config = object(input, "config");
279
309
  only(
280
310
  config,
@@ -293,6 +323,7 @@ export function validateConfig(input: unknown): PortholeConfig {
293
323
  "permissions",
294
324
  "storage",
295
325
  "errors",
326
+ "runtime",
296
327
  ],
297
328
  "config",
298
329
  );
@@ -314,7 +345,60 @@ export function validateConfig(input: unknown): PortholeConfig {
314
345
  fail(path, `is not a capability (${CAPABILITY_NAMES.join(", ")})`);
315
346
  }
316
347
  const capability = object(value, path);
317
- only(capability, ["gates", "connect", "resource", "guide"], path);
348
+ only(
349
+ capability,
350
+ ["gates", "connect", "resource", "guide", "levels", "methodGates", "withoutShow"],
351
+ path,
352
+ );
353
+ if (capability.methodGates !== undefined) {
354
+ const family = familyOf(name as CapabilityName);
355
+ for (const [method, gates] of Object.entries(
356
+ object(capability.methodGates, `${path}.methodGates`),
357
+ )) {
358
+ const methods: Readonly<Record<string, RuntimeMethod>> | undefined =
359
+ family === null ? undefined : runtimeCapability(family.name).methods;
360
+ if (
361
+ methods === undefined ||
362
+ !Object.hasOwn(methods, method) ||
363
+ methods[method]?.serves !== name
364
+ ) {
365
+ fail(`${path}.methodGates.${method}`, `is not a runtime method ${name} serves`);
366
+ }
367
+ if (!Array.isArray(gates)) {
368
+ fail(`${path}.methodGates.${method}`, "must be an array of gates");
369
+ }
370
+ (gates as unknown[]).forEach((each, index) =>
371
+ gate(each, `${path}.methodGates.${method}[${index}]`),
372
+ );
373
+ }
374
+ }
375
+ if (capability.levels !== undefined) {
376
+ const levels = object(capability.levels, `${path}.levels`);
377
+ const family = familyOf(name as CapabilityName);
378
+ for (const [method, level] of Object.entries(levels)) {
379
+ const methods: Readonly<Record<string, RuntimeMethod>> | undefined =
380
+ family === null ? undefined : runtimeCapability(family.name).methods;
381
+ const spec =
382
+ methods !== undefined && Object.hasOwn(methods, method) ? methods[method] : undefined;
383
+ if (family === null || spec === undefined || spec.serves !== name) {
384
+ fail(
385
+ `${path}.levels.${method}`,
386
+ family === null
387
+ ? `${name} serves no runtime method: it has no levels`
388
+ : `is not a method ${name} serves (${family.methods.join(", ")})`,
389
+ );
390
+ }
391
+ if (!isViewerLevel(level)) {
392
+ fail(`${path}.levels.${method}`, "must be view, interact, admin or owner");
393
+ }
394
+ if (spec !== undefined && !atLeast(level as never, spec.floor)) {
395
+ fail(
396
+ `${path}.levels.${method}`,
397
+ `can't be below ${spec.floor} (${family?.name}.${method}'s floor, P087)`,
398
+ );
399
+ }
400
+ }
401
+ }
318
402
  if (capability.gates !== undefined) {
319
403
  if (!Array.isArray(capability.gates)) {
320
404
  fail(`${path}.gates`, "must be an array");
@@ -323,6 +407,21 @@ export function validateConfig(input: unknown): PortholeConfig {
323
407
  gate(each, `${path}.gates[${index}]`),
324
408
  );
325
409
  }
410
+ // Leaving the default `show` out on purpose (P100): only where there is one, left out.
411
+ if (capability.withoutShow !== undefined) {
412
+ if (capability.withoutShow !== true) {
413
+ fail(`${path}.withoutShow`, "must be true: it says the gates leave show out on purpose");
414
+ }
415
+ if (!capabilitySpec(name as CapabilityName).defaultGates.includes("show")) {
416
+ fail(`${path}.withoutShow`, `${name} has no show gate to leave out`);
417
+ }
418
+ if (!Array.isArray(capability.gates) || (capability.gates as unknown[]).includes("show")) {
419
+ fail(
420
+ `${path}.withoutShow`,
421
+ "says show is left out, so the gates must be named, without it",
422
+ );
423
+ }
424
+ }
326
425
  sources(capability.connect, `${path}.connect`);
327
426
  sources(capability.resource, `${path}.resource`);
328
427
  if (capability.guide !== undefined && typeof capability.guide !== "string") {
@@ -332,6 +431,35 @@ export function validateConfig(input: unknown): PortholeConfig {
332
431
  if (config.mode === "url" && Object.keys(capabilities).length > 0) {
333
432
  fail("config.capabilities", "url mode has no shell, so it can declare no capabilities");
334
433
  }
434
+ // The capability runtime (P085): its global and its own host functions.
435
+ if (config.runtime !== undefined) {
436
+ if (!isRuntimeVersion(config.runtime)) {
437
+ fail("config.runtime", `must be a runtime contract version: ${RUNTIME_VERSIONS.join(", ")}`);
438
+ }
439
+ if (config.mode !== "inline" && config.mode !== "artifact") {
440
+ fail("config.runtime", "the runtime is the shell's: inline widgets and artifact pages only");
441
+ }
442
+ }
443
+ for (const name of RUNTIME_HOST_FUNCTIONS) {
444
+ if (capabilities[name] === undefined) {
445
+ continue;
446
+ }
447
+ if (config.runtime === undefined) {
448
+ fail(
449
+ `config.capabilities.${name}`,
450
+ "is the capability runtime's: set config.runtime (content reaches it through porthole.use)",
451
+ );
452
+ }
453
+ if ((name === "artifact" || name === "assets") && config.mode !== "artifact") {
454
+ fail(`config.capabilities.${name}`, "is an artifact page's: artifact mode only");
455
+ }
456
+ }
457
+ if (capabilities.assets !== undefined && config.isolation !== "domain") {
458
+ fail(
459
+ "config.capabilities.assets",
460
+ "assets are served from the page's own origin (/_blob/): domain isolation only",
461
+ );
462
+ }
335
463
 
336
464
  const egress = object(config.egress, "config.egress");
337
465
  const kinds = ["connect", "script", "style", "img", "font", "media"];
@@ -477,7 +605,9 @@ export function validateConfig(input: unknown): PortholeConfig {
477
605
  const path = `config.guide.topics.${name}`;
478
606
  if (
479
607
  !/^[a-z][a-z0-9-]{0,31}$/u.test(name) ||
480
- (BUILT_IN_TOPICS as readonly string[]).includes(name)
608
+ // `capabilities` is built in only under the runtime (P085): a 0.6 config's own stays.
609
+ ((BUILT_IN_TOPICS as readonly string[]).includes(name) &&
610
+ (name !== "capabilities" || config.runtime !== undefined))
481
611
  ) {
482
612
  fail(path, "must be a new topic name (lowercase), not a built-in one");
483
613
  }
@@ -585,5 +715,8 @@ export function validateConfig(input: unknown): PortholeConfig {
585
715
  });
586
716
  }
587
717
 
718
+ for (const warning of configWarnings(input as PortholeConfig)) {
719
+ options.onWarning?.(warning);
720
+ }
588
721
  return input as PortholeConfig;
589
722
  }
@@ -0,0 +1,42 @@
1
+ import { capabilitySpec, isCapabilityName } from "./capabilities.ts";
2
+ import type { PortholeConfig } from "./schema.ts";
3
+
4
+ /**
5
+ * What a valid config says that its host likely didn't mean (the review of P100): never an error,
6
+ * since the config is the host's to write. Porthole logs nothing itself (no console in library
7
+ * code): `validateConfig(config, { onWarning })` hands each one over, and `compile(config).warnings`
8
+ * (`host.compiled.warnings`) holds them, for a host to log at startup or fail its tests on.
9
+ */
10
+ export interface ConfigWarning {
11
+ /** `model-context-unshown`: a capability whose defaults have `show` lost it to named gates. */
12
+ readonly code: "model-context-unshown";
13
+ readonly path: string;
14
+ readonly message: string;
15
+ }
16
+
17
+ /**
18
+ * Each warning `config` earns. Since 0.8 (P100), `setModelContext`'s defaults have `show`; a
19
+ * config that names its gates (one written for 0.7 did, to change the rate) and leaves `show` out
20
+ * sends content's text to the model unseen, so it is said, unless `withoutShow: true` says the
21
+ * host meant it (its handler shows the person each update, or the content is its own).
22
+ */
23
+ export function configWarnings(config: PortholeConfig): readonly ConfigWarning[] {
24
+ const warnings: ConfigWarning[] = [];
25
+ for (const [name, capability] of Object.entries(config.capabilities)) {
26
+ if (
27
+ !isCapabilityName(name) ||
28
+ capability?.gates === undefined ||
29
+ !capabilitySpec(name).defaultGates.includes("show") ||
30
+ capability.gates.includes("show") ||
31
+ capability.withoutShow === true
32
+ ) {
33
+ continue;
34
+ }
35
+ warnings.push({
36
+ code: "model-context-unshown",
37
+ path: `config.capabilities.${name}.gates`,
38
+ 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.`,
39
+ });
40
+ }
41
+ return warnings;
42
+ }
@@ -2,7 +2,7 @@ import { expect, type Frame } from "@playwright/test";
2
2
  import { presets } from "../presets/presets.ts";
3
3
  import { resolveTheme } from "../theme/variables.ts";
4
4
  import type { LaunchedDisplay } from "./index.ts";
5
- import { inline, type Probe, type ProbeContext } from "./kit.ts";
5
+ import { inline, js, type Probe, type ProbeContext } from "./kit.ts";
6
6
  import { settle } from "./oracles.ts";
7
7
 
8
8
  /**
@@ -73,6 +73,21 @@ async function bodyData(display: LaunchedDisplay, name: string, timeout = 5_000)
73
73
  return (await frame.locator("body").getAttribute(`data-${name}`)) ?? "";
74
74
  }
75
75
 
76
+ /** A model context update (P100): what the view says the person is looking at. */
77
+ const CONTEXT_UPDATE = {
78
+ content: [{ type: "text", text: "The person is looking at March's signups." }],
79
+ structuredContent: { month: "March", signups: 412 },
80
+ };
81
+
82
+ /** Content that sends it as the App SDK does (`ui/update-model-context`), and keeps the answer. */
83
+ const CONTEXT_CONTENT = `<p>signups</p>
84
+ <script>
85
+ addEventListener("message", (event) => {
86
+ if (event.data && event.data.id === "ctx-1") document.body.dataset.answer = JSON.stringify(event.data.error ? event.data.error.data : event.data.result);
87
+ });
88
+ parent.postMessage({ jsonrpc: "2.0", id: "ctx-1", method: "ui/update-model-context", params: ${js(CONTEXT_UPDATE)} }, "*");
89
+ </script>`;
90
+
76
91
  const PROMPT_CONTENT = `<button id="ask">Explain March</button>
77
92
  <script>
78
93
  document.getElementById("ask").addEventListener("click", () => {
@@ -501,4 +516,42 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
501
516
  expect(await display.calls()).toEqual([]);
502
517
  },
503
518
  },
519
+ {
520
+ id: "12.model-context",
521
+ item: 12,
522
+ title:
523
+ "what content tells the model, the person is shown first, whole; a host that can't show it gets none (S5, P100)",
524
+ async run(context) {
525
+ const config = inline({ capabilities: { setModelContext: {} } });
526
+ const display = await context.launch({ config, content: CONTEXT_CONTENT });
527
+ const said = display.shown?.bind(display);
528
+ if (said === undefined) {
529
+ return context.inapplicable(
530
+ "this host's harness doesn't say what it shows the person (LaunchedDisplay.shown)",
531
+ );
532
+ }
533
+ expect(await bodyData(display, "answer")).toBe("{}");
534
+ const shown = await said();
535
+ expect(shown, "the update reached the model unseen").toHaveLength(1);
536
+ expect(shown[0]).toMatchObject({
537
+ capability: "setModelContext",
538
+ args: CONTEXT_UPDATE,
539
+ display: { title: "Probe" },
540
+ });
541
+ expect(await display.calls()).toEqual([
542
+ { capability: "setModelContext", args: CONTEXT_UPDATE },
543
+ ]);
544
+
545
+ const unseen = await context.launch({ config, shows: false, content: CONTEXT_CONTENT });
546
+ const answer = JSON.parse(await bodyData(unseen, "answer")) as { code?: string };
547
+ if (answer.code === undefined && ((await unseen.shown?.()) ?? []).length > 0) {
548
+ return context.inapplicable(
549
+ "this host always has a show function (a default surface), so a display without one can't be shown; it showed the person instead",
550
+ );
551
+ }
552
+ expect(answer.code, "an update nobody could see was taken").toBe("not_allowed");
553
+ expect(await refusals(unseen)).toContain("setModelContext:no-show");
554
+ expect(await unseen.calls()).toEqual([]);
555
+ },
556
+ },
504
557
  ];
@@ -0,0 +1,93 @@
1
+ import type { Browser, BrowserContext, Page } from "@playwright/test";
2
+
3
+ /**
4
+ * Whether this browser keeps a cookie a cross-site frame's own document was answered with
5
+ * (P025, P098): what a framed url-mode app needs, since its every request rides on the cookie its
6
+ * ticket's answer set. Measured, never assumed from the engine's name: Playwright's WebKit keeps
7
+ * none on Linux and keeps them on macOS (the audit of 2026-10-19), and an engine's policy changes
8
+ * between versions.
9
+ *
10
+ * The probe is the browser's own, outside the host under test: in a context of its own, a page on
11
+ * one site frames a page on another (both answered by the probe's routes, never the network,
12
+ * never the host's server), whose answer sets a cookie as Porthole's server sets a framed one
13
+ * (`Secure; SameSite=None; Partitioned`, over the display's own scheme); the frame then reads
14
+ * whether it was kept. Asked once per browser.
15
+ */
16
+ export function keepsFramedCookies(page: Page, scheme: "http:" | "https:"): Promise<boolean> {
17
+ const browser = page.context().browser();
18
+ const key = `${scheme} ${browser === null ? "persistent" : browser.version()}`;
19
+ const known = cache(browser ?? page.context());
20
+ let answer = known.get(key);
21
+ if (answer === undefined) {
22
+ answer = probe(browser, page.context(), scheme);
23
+ known.set(key, answer);
24
+ }
25
+ return answer;
26
+ }
27
+
28
+ const answers = new WeakMap<Browser | BrowserContext, Map<string, Promise<boolean>>>();
29
+
30
+ function cache(owner: Browser | BrowserContext): Map<string, Promise<boolean>> {
31
+ let known = answers.get(owner);
32
+ if (known === undefined) {
33
+ known = new Map();
34
+ answers.set(owner, known);
35
+ }
36
+ return known;
37
+ }
38
+
39
+ /** Two sites the probe makes up: the embedding page's, and the frame's. */
40
+ function sites(scheme: "http:" | "https:"): { top: string; framed: string } {
41
+ // Over http, as a loopback host and its content origins are (a `*.localhost` frame on a
42
+ // `127.0.0.1` page, the leak suite's own shape); over https, two names that are each a site.
43
+ // Default ports: a browser refuses to navigate to some others (9 is on Fetch's bad-port list).
44
+ return scheme === "http:"
45
+ ? {
46
+ top: "http://127.0.0.1/__porthole-cookie-probe/",
47
+ framed: "http://porthole-cookie-probe.localhost/",
48
+ }
49
+ : {
50
+ top: "https://porthole-cookie-probe-top.test/",
51
+ framed: "https://porthole-cookie-probe-frame.test/",
52
+ };
53
+ }
54
+
55
+ async function probe(
56
+ browser: Browser | null,
57
+ context: BrowserContext,
58
+ scheme: "http:" | "https:",
59
+ ): Promise<boolean> {
60
+ const own = browser === null ? null : await browser.newContext();
61
+ const page = await (own ?? context).newPage();
62
+ try {
63
+ const { top, framed } = sites(scheme);
64
+ await page.route(`${framed}**`, (route) =>
65
+ route.fulfill({
66
+ status: 200,
67
+ headers: {
68
+ "content-type": "text/html; charset=utf-8",
69
+ "cache-control": "no-store",
70
+ "set-cookie": "porthole-cookie-probe=1; Path=/; Secure; SameSite=None; Partitioned",
71
+ },
72
+ body: "<!doctype html><title>probe</title>",
73
+ }),
74
+ );
75
+ await page.route(top, (route) =>
76
+ route.fulfill({
77
+ status: 200,
78
+ headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
79
+ body: `<!doctype html><title>probe</title><iframe src="${framed}frame"></iframe>`,
80
+ }),
81
+ );
82
+ await page.goto(top);
83
+ const frame = await (await page.locator("iframe").elementHandle())?.contentFrame();
84
+ if (frame === null || frame === undefined) {
85
+ throw new Error("keepsFramedCookies: the probe's frame didn't load");
86
+ }
87
+ await frame.waitForLoadState("load");
88
+ return await frame.evaluate(() => document.cookie.includes("porthole-cookie-probe=1"));
89
+ } finally {
90
+ await page.close();
91
+ await own?.close();
92
+ }
93
+ }