@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
package/src/index.ts CHANGED
@@ -7,6 +7,7 @@
7
7
  export {
8
8
  CAPABILITIES,
9
9
  CAPABILITY_NAMES,
10
+ MAX_CONTEXT_CHARS,
10
11
  MAX_COPY_CHARS,
11
12
  capabilitySpec,
12
13
  isCapabilityName,
@@ -41,6 +42,7 @@ export {
41
42
  originSourceProblem,
42
43
  validateConfig,
43
44
  } from "./config/validate.ts";
45
+ export { configWarnings, type ConfigWarning } from "./config/warnings.ts";
44
46
  export {
45
47
  URL_PERMISSIONS,
46
48
  URL_SANDBOX_EXTRAS,
@@ -50,11 +52,97 @@ export {
50
52
  export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
51
53
  export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
52
54
 
55
+ // The capability runtime (P085-P090): its contract, levels, a page's declaration, its services'
56
+ // shapes. Hosts implement the services; Porthole carries, checks and gates the calls.
57
+ export {
58
+ RUNTIME_CALL_METHOD,
59
+ RUNTIME_CAPABILITIES,
60
+ RUNTIME_CAPABILITY_NAMES,
61
+ RUNTIME_EVENT_METHOD,
62
+ RUNTIME_EXPERIMENTAL_KEY,
63
+ RUNTIME_GLOBAL,
64
+ RUNTIME_HOST_FUNCTIONS,
65
+ RUNTIME_UNWATCH_METHOD,
66
+ RUNTIME_VERSION,
67
+ RUNTIME_VERSIONS,
68
+ familyOf,
69
+ isRuntimeCapabilityName,
70
+ methodGates,
71
+ isRuntimeVersion,
72
+ methodLevel,
73
+ offeredCapabilities,
74
+ rosterOf,
75
+ type RuntimeCapability,
76
+ type RuntimeCapabilityName,
77
+ type RuntimeMethod,
78
+ type RuntimeVersion,
79
+ } from "./runtime/contract.ts";
80
+ export {
81
+ VIEWER_LEVELS,
82
+ atLeast,
83
+ isViewerLevel,
84
+ parseViewer,
85
+ type ViewerInfo,
86
+ type ViewerLevel,
87
+ } from "./runtime/levels.ts";
88
+ export {
89
+ checkDeclaration,
90
+ declarationProblems,
91
+ declareCapabilities,
92
+ declaredMatch,
93
+ intersectDeclarations,
94
+ tryIntersectDeclarations,
95
+ type CapabilityDeclaration,
96
+ type DeclarationProblem,
97
+ type DeclaredCapability,
98
+ type DeclaredData,
99
+ type DeclaredDb,
100
+ type PageDeclaration,
101
+ } from "./runtime/declaration.ts";
102
+ export {
103
+ DB_LIMITS,
104
+ DB_USERS_PREFIX,
105
+ dbAccess,
106
+ isDbSegment,
107
+ isPlainJson,
108
+ withMe,
109
+ dbRulesProblem,
110
+ parseDbRequest,
111
+ type DbData,
112
+ type DbRequest,
113
+ type DbResult,
114
+ type DbRules,
115
+ type DbSnapshot,
116
+ type DbValue,
117
+ type DbWhere,
118
+ type DbWrite,
119
+ } from "./runtime/db.ts";
120
+ export {
121
+ ASSET_ID,
122
+ ASSET_PATH,
123
+ MAX_PUBLISH_FILES,
124
+ assetNameProblem,
125
+ assetUrl,
126
+ isCodeAsset,
127
+ type ArtifactInfo,
128
+ type ArtifactRequest,
129
+ type AssetInfo,
130
+ type AssetRequest,
131
+ type CommentAnchor,
132
+ type CommentRequest,
133
+ type DownloadedFile,
134
+ type PublishedFile,
135
+ type PublishedVersion,
136
+ type UserInfo,
137
+ } from "./runtime/requests.ts";
138
+ export { RUNTIME_TYPES } from "./runtime/types.generated.ts";
139
+
53
140
  // Presets.
54
141
  export {
55
142
  LIBRARY_CDNS,
56
143
  presets,
57
144
  type PresetName,
145
+ type LiveCapabilityConfig,
58
146
  type LiveWidgetOptions,
59
147
  type PresetOptions,
60
148
  type UrlPresetOptions,
@@ -101,6 +189,10 @@ export {
101
189
  egressOrigins,
102
190
  embedderCsp,
103
191
  embedderFrameSourcesOf,
192
+ ASSET_CODE_DIRECTIVES,
193
+ ASSET_DIRECTIVES,
194
+ assetCodeRuns,
195
+ assetCspDirectives,
104
196
  FILE_SET_DIRECTIVES,
105
197
  fileSetCspDirectives,
106
198
  INERT_FILE_CSP,
@@ -178,7 +270,9 @@ export type {
178
270
  Proceed,
179
271
  HostFunctionBridge,
180
272
  Refusal,
273
+ Show,
181
274
  SubscriptionContext,
275
+ DbContext,
182
276
  } from "./bridge/types.ts";
183
277
  export { createHost } from "./host/create-host.ts";
184
278
  // The client half of the host kit, and the display registry (P072).
@@ -12,6 +12,7 @@
12
12
  * one host app.
13
13
  */
14
14
  import type { EgressConfig } from "../config/schema.ts";
15
+ import type { ViewerInfo } from "../runtime/levels.ts";
15
16
 
16
17
  /**
17
18
  * Which document a served frame loads. `preset` names the config it is served under (the server's
@@ -63,6 +64,11 @@ export interface FrameLocation {
63
64
  * one that loaded. A host's own gateway may send the same message without this.
64
65
  */
65
66
  readonly reports?: boolean;
67
+ /**
68
+ * Who is viewing, as the host's access decided at issue (P087: `Grant.level`, `Grant.user`):
69
+ * the display's bridge checks each runtime method's level against it.
70
+ */
71
+ readonly viewer?: ViewerInfo;
66
72
  }
67
73
 
68
74
  /** The message a served page sends its host about loading (own-prefixed, P040). */
@@ -88,4 +94,6 @@ export type FrameSource =
88
94
  readonly url: string;
89
95
  readonly origin: string;
90
96
  readonly reports?: boolean;
97
+ /** The issue's viewer (`FrameLocation.viewer`), for the display's bridge. */
98
+ readonly viewer?: ViewerInfo;
91
99
  };
@@ -12,6 +12,7 @@ import type { AdapterConnection, AdapterSession, ProtocolAdapter } from "../prot
12
12
  import {
13
13
  MCP_APPS_METHODS,
14
14
  MCP_APPS_PROTOCOL_VERSION,
15
+ MODEL_CONTEXT_OFFERED,
15
16
  type HostContext,
16
17
  } from "../protocol/mcp-apps.ts";
17
18
  import {
@@ -20,6 +21,7 @@ import {
20
21
  NAVIGATION_BLOCKED_METHOD,
21
22
  } from "../protocol/mcp-apps.ts";
22
23
  import { liveData } from "../protocol/live-data.ts";
24
+ import { messageText } from "../protocol/message-text.ts";
23
25
  import { reasonFor } from "../bridge/refusal.ts";
24
26
 
25
27
  /**
@@ -96,15 +98,6 @@ export function viewHostContext(
96
98
  return out;
97
99
  }
98
100
 
99
- /** The text of a `ui/message`'s content: its text blocks, in order (the spec's examples send one). */
100
- function messageText(content: unknown): string | null {
101
- const blocks = Array.isArray(content) ? content : [content];
102
- const texts = blocks.flatMap((block) =>
103
- isRecord(block) && block.type === "text" && typeof block.text === "string" ? [block.text] : [],
104
- );
105
- return texts.length === 0 ? null : texts.join("\n\n");
106
- }
107
-
108
101
  /** Whether the host page has a live user gesture (a gesture in a frame activates its ancestors). */
109
102
  function hostActivation(): boolean | undefined {
110
103
  const activation = (globalThis as { navigator?: { userActivation?: { isActive: boolean } } })
@@ -164,9 +157,7 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
164
157
  ? { serverResources: declared("subscribeData") ? { subscribe: true } : {} }
165
158
  : {}),
166
159
  ...(declared("sendPrompt") ? { message: { text: {} } } : {}),
167
- ...(declared("setModelContext")
168
- ? { updateModelContext: { text: {}, structuredContent: {} } }
169
- : {}),
160
+ ...(declared("setModelContext") ? { updateModelContext: MODEL_CONTEXT_OFFERED } : {}),
170
161
  sandbox: {
171
162
  csp: {
172
163
  ...(connectDomains.length > 0 ? { connectDomains } : {}),
@@ -248,7 +239,16 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
248
239
  answer(request.id, {});
249
240
  return;
250
241
  case MCP_APPS_METHODS.message: {
251
- const text = params.role === "user" ? messageText(params.content) : null;
242
+ // Its text blocks, in order (the spec's examples send one), read bounded (P095).
243
+ const content = params.content;
244
+ const text =
245
+ params.role === "user"
246
+ ? messageText(
247
+ Array.isArray(content) ? content : [content],
248
+ "\n\n",
249
+ session.compiled.config.limits.maxPromptChars,
250
+ )
251
+ : null;
252
252
  if (text === null) {
253
253
  invalid('needs role "user" and text content');
254
254
  return;
@@ -393,14 +393,10 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
393
393
  return;
394
394
  }
395
395
  case MCP_APPS_METHODS.log:
396
+ // What the view said, as it came (S05, P095): the bridge reads it only within
397
+ // reportError's declaration and rate, into bounded text, and nothing in it throws here.
396
398
  if (typeof params.level === "string" && ERROR_LEVELS.has(params.level)) {
397
- const data = params.data;
398
- void bridge.call("reportError", {
399
- message: (typeof data === "string" ? data : (JSON.stringify(data) ?? "")).slice(
400
- 0,
401
- 2_000,
402
- ),
403
- });
399
+ void bridge.call("reportError", { message: params.data });
404
400
  }
405
401
  return;
406
402
  case NAVIGATION_BLOCKED_METHOD: