@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
@@ -2,7 +2,9 @@
2
2
 
3
3
  This describes the layers, their contracts, the flows and trust boundaries, and
4
4
  the extension points. It is meant to stay stable while concrete APIs change; the
5
- phase-1 API lives in [DESIGN.md](DESIGN.md).
5
+ phase-1 API lives in [DESIGN.md](DESIGN.md). What the boundaries protect, from whom,
6
+ and what each use guarantees and leaves to the host is in
7
+ [THREAT_MODEL.md](THREAT_MODEL.md).
6
8
 
7
9
  ## The core abstraction
8
10
 
@@ -12,10 +14,19 @@ Porthole renders **agent-drawn HTML plus a declared set of host functions.**
12
14
  - A **host function (capability)** is any power beyond drawing: send a prompt to
13
15
  the agent, open a link, read or write state, call a tool, read data, report an
14
16
  error. Each is named in the config and carries three facts: its **gate** (needs
15
- a user gesture, needs a person's confirmation, is rate-limited), its **egress
17
+ a user gesture, needs a person's confirmation, is shown to the person first, is
18
+ rate-limited), its **egress
16
19
  needs** (origins it must reach), and its **guide entry** (how the manual
17
20
  describes it).
18
21
 
22
+ A page published as an artifact may be an app: under the **capability runtime**, an optional
23
+ layer over the display (THREAT_MODEL.md says what each guarantees), it reaches its
24
+ host through one global, `porthole.use(name)`, for the capabilities it declared and its viewer's
25
+ level allows. The runtime is how content reaches host functions, not new ones: each of its
26
+ methods is served by a host function the config declares, and the bridge alone decides each call
27
+ (the page's declaration, the viewer's level, the gates). The services behind them (a document
28
+ store, an asset library, versions, comments) are the host's.
29
+
19
30
  One capability list therefore drives three artifacts: the **bridge** (which
20
31
  functions the shell wires and the host handles), the **CSP** (what the sandbox
21
32
  may reach), and the **manual** (what the agent is told). This is why the config
@@ -206,6 +217,9 @@ only the declared content origins.
206
217
 
207
218
  ## Trust boundaries
208
219
 
220
+ The attackers each boundary faces, what is out of scope, and the composition rule for
221
+ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
222
+
209
223
  1. **Host ↔ content.** The hard boundary. The content runs on an origin that is
210
224
  never the host's, so same-origin policy denies it the host's DOM, storage,
211
225
  cookies and credentials. Everything it wants beyond drawing crosses the bridge
@@ -216,7 +230,8 @@ only the declared content origins.
216
230
 
217
231
  2. **Content ↔ the outside network.** Closed by default and opened only to the
218
232
  origins the config's capabilities declare (and, for a served page with files,
219
- its own version's path on its own origin: the host's own server, P082). Two
233
+ its own version's path on its own origin, and its artifact's asset library at `/_blob/`: the
234
+ host's own server, P082, P089). Two
220
235
  kinds of attacker matter:
221
236
  - *Attacking the host* (steal credentials, read other data, escape the
222
237
  sandbox): stopped by origin isolation — the content is a stranger to the
@@ -228,20 +243,30 @@ only the declared content origins.
228
243
  realm) reach the network outside a frame's own `connect-src`. These are
229
244
  closed by in-shell defenses and by the embedding page's own policy, each
230
245
  proven by a leak-suite probe (DESIGN.md lists them).
246
+ - *A served page outside its frame* (a public link, a new tab) has no frame's sandbox and no
247
+ embedding page: its own CSP header carries the frame's sandbox tokens, and the shell closes
248
+ `window.open` and stops it navigating away (P099).
231
249
  - *An opaque frame is as closed as its page.* A `srcdoc` frame inherits the
232
250
  embedding page's whole policy as well as its own, so on a page with
233
251
  `default-src 'none'` and a tight `connect-src`/`img-src` its content is more
234
252
  closed than its config says: an origin the config opens stays shut. On such
235
253
  a page prefer domain mode, whose frames inherit nothing (P058).
236
254
 
237
- 3. **Message boundary.** Every message crossing the frame is validated against a
255
+ 3. **Host's decision ↔ what a page may do.** Under the capability runtime a page reaches only the
256
+ built-ins and what it declared at publish (stored by the host, given to the mount), and each
257
+ method only for viewers at its level (`view < interact < admin < owner`), which the host's
258
+ access says. The bridge refuses before any handler; the host's own API checks again, since it
259
+ is its data's wall. A person's per-user data is reached by the host's id for them, never the
260
+ content's word.
261
+
262
+ 4. **Message boundary.** Every message crossing the frame is validated against a
238
263
  schema and checked for sender identity before use; the shell accepts messages
239
264
  only from its host, and the host only from its frame. What the frame says about
240
265
  itself (its size, its errors, an annotation's anchor and where it is) is the
241
266
  content's word even when the shell says it, since they share a realm: the host
242
267
  bounds it and uses it as a UI hint, never as a permission (P053).
243
268
 
244
- 4. **Host's decision ↔ content domain.** Authentication and authorization
269
+ 5. **Host's decision ↔ content domain.** Authentication and authorization
245
270
  *policy* are the host's; carrying the host's decision safely onto the content
246
271
  domain is Porthole's *mechanism*. The host decides who may open an instance
247
272
  before it calls `issue` (a viewer it knows, or a public link), and may decide
@@ -262,6 +287,10 @@ only the declared content origins.
262
287
  names are the default vocabulary.
263
288
  - **The person's clipboard** is the host's alone: content asks for a copy
264
289
  (`copyText`), the host performs it and shows what it copied (P051, P052).
290
+ - **The capability runtime** (`config.runtime`): a contract version's capabilities, each a
291
+ namespace of methods over host functions, with a versioned `.d.ts`; a host offers them through
292
+ its config and serves them through its handlers; an artifact's asset library is served by
293
+ `/server` from the host's store at `/_blob/<id>` on the artifact's origin.
265
294
  - **Annotations** (`annotate`): the host drives a select mode and marks anchors in
266
295
  the shell; anchors are W3C Web Annotation selectors a host stores with its own
267
296
  comments (P053).