@botiverse/porthole 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/README.md +9 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/annotate/types.d.ts +40 -4
  4. package/dist/annotate/types.js +6 -1
  5. package/dist/annotate/validate.d.ts +10 -0
  6. package/dist/annotate/validate.js +24 -1
  7. package/dist/bridge/bounded-text.d.ts +34 -0
  8. package/dist/bridge/bounded-text.js +188 -0
  9. package/dist/bridge/bridge.d.ts +25 -5
  10. package/dist/bridge/bridge.js +311 -73
  11. package/dist/bridge/json-data.d.ts +28 -0
  12. package/dist/bridge/json-data.js +86 -0
  13. package/dist/bridge/navigation.d.ts +5 -0
  14. package/dist/bridge/navigation.js +7 -0
  15. package/dist/bridge/refusal.js +1 -0
  16. package/dist/bridge/types.d.ts +32 -1
  17. package/dist/check/page-source.js +1 -1
  18. package/dist/check/page.js +2 -0
  19. package/dist/compile/compile.d.ts +6 -0
  20. package/dist/compile/compile.js +3 -1
  21. package/dist/compile/policy.d.ts +38 -2
  22. package/dist/compile/policy.js +122 -7
  23. package/dist/config/capabilities.d.ts +23 -4
  24. package/dist/config/capabilities.js +12 -2
  25. package/dist/config/schema.d.ts +11 -0
  26. package/dist/config/validate.d.ts +8 -2
  27. package/dist/config/validate.js +28 -6
  28. package/dist/config/warnings.d.ts +20 -0
  29. package/dist/config/warnings.js +25 -0
  30. package/dist/conformance/behavior.js +46 -1
  31. package/dist/conformance/cookies.d.ts +15 -0
  32. package/dist/conformance/cookies.js +80 -0
  33. package/dist/conformance/harness/page.d.ts +1 -0
  34. package/dist/conformance/harness/page.js +9 -2
  35. package/dist/conformance/harness-source.js +1 -1
  36. package/dist/conformance/host-kit.js +5 -1
  37. package/dist/conformance/index.d.ts +10 -0
  38. package/dist/conformance/limits.js +38 -1
  39. package/dist/conformance/runtime.js +10 -0
  40. package/dist/conformance/served.d.ts +2 -0
  41. package/dist/conformance/served.js +737 -4
  42. package/dist/files/paths.js +4 -0
  43. package/dist/guide/gates.d.ts +7 -1
  44. package/dist/guide/gates.js +12 -0
  45. package/dist/guide/guide.js +2 -2
  46. package/dist/guide/runtime.js +11 -3
  47. package/dist/host/create-host.js +81 -39
  48. package/dist/host/pages-of-set.d.ts +43 -0
  49. package/dist/host/pages-of-set.js +196 -0
  50. package/dist/host/types.d.ts +8 -1
  51. package/dist/index.d.ts +5 -4
  52. package/dist/index.js +3 -2
  53. package/dist/mcp/adapter.js +11 -15
  54. package/dist/node/index.d.ts +36 -4
  55. package/dist/node/index.js +402 -101
  56. package/dist/platform/types.d.ts +9 -0
  57. package/dist/platform/web.js +8 -0
  58. package/dist/presets/presets.d.ts +16 -8
  59. package/dist/presets/presets.js +39 -8
  60. package/dist/protocol/live-data.d.ts +6 -2
  61. package/dist/protocol/live-data.js +20 -1
  62. package/dist/protocol/mcp-apps.d.ts +13 -2
  63. package/dist/protocol/mcp-apps.js +10 -2
  64. package/dist/protocol/message-text.d.ts +8 -0
  65. package/dist/protocol/message-text.js +29 -0
  66. package/dist/protocol/runtime-calls.js +3 -0
  67. package/dist/protocol/shell-adapter.js +16 -22
  68. package/dist/react/context-notice.d.ts +32 -0
  69. package/dist/react/context-notice.js +28 -0
  70. package/dist/react/dialog.js +62 -18
  71. package/dist/react/frame.d.ts +18 -3
  72. package/dist/react/frame.js +79 -2
  73. package/dist/react/index.d.ts +2 -1
  74. package/dist/react/index.js +2 -1
  75. package/dist/runtime/contract.d.ts +9 -1
  76. package/dist/runtime/contract.js +31 -2
  77. package/dist/runtime/db.d.ts +41 -6
  78. package/dist/runtime/db.js +120 -16
  79. package/dist/runtime/declaration.d.ts +15 -1
  80. package/dist/runtime/declaration.js +184 -87
  81. package/dist/runtime/requests.js +27 -11
  82. package/dist/runtime/types.generated.js +1 -1
  83. package/dist/server/files.d.ts +5 -0
  84. package/dist/server/files.js +22 -7
  85. package/dist/server/host.d.ts +18 -1
  86. package/dist/server/host.js +132 -2
  87. package/dist/server/index.d.ts +1 -1
  88. package/dist/server/index.js +1 -1
  89. package/dist/server/peer.d.ts +4 -0
  90. package/dist/server/peer.js +19 -0
  91. package/dist/server/proxy.d.ts +6 -0
  92. package/dist/server/proxy.js +12 -3
  93. package/dist/server/server.js +113 -26
  94. package/dist/server/types.d.ts +6 -3
  95. package/dist/shell/annotate.d.ts +7 -2
  96. package/dist/shell/annotate.js +233 -15
  97. package/dist/shell/document.d.ts +8 -0
  98. package/dist/shell/document.js +3 -0
  99. package/dist/shell/runtime.js +361 -14
  100. package/docs/ADOPTING.md +119 -14
  101. package/docs/ARCHITECTURE.md +15 -4
  102. package/docs/DECISIONS.md +1610 -9
  103. package/docs/DESIGN.md +114 -30
  104. package/docs/THREAT_MODEL.md +652 -0
  105. package/package.json +14 -3
  106. package/src/annotate/types.ts +37 -5
  107. package/src/annotate/validate.ts +30 -1
  108. package/src/bridge/bounded-text.ts +240 -0
  109. package/src/bridge/bridge.ts +373 -84
  110. package/src/bridge/json-data.ts +95 -0
  111. package/src/bridge/navigation.ts +10 -0
  112. package/src/bridge/refusal.ts +1 -0
  113. package/src/bridge/types.ts +30 -1
  114. package/src/check/page.ts +2 -0
  115. package/src/compile/compile.ts +9 -1
  116. package/src/compile/policy.ts +130 -7
  117. package/src/config/capabilities.ts +22 -3
  118. package/src/config/schema.ts +11 -0
  119. package/src/config/validate.ts +43 -5
  120. package/src/config/warnings.ts +42 -0
  121. package/src/conformance/behavior.ts +54 -1
  122. package/src/conformance/cookies.ts +93 -0
  123. package/src/conformance/harness/page.ts +11 -2
  124. package/src/conformance/host-kit.ts +10 -1
  125. package/src/conformance/index.ts +10 -0
  126. package/src/conformance/limits.ts +39 -1
  127. package/src/conformance/runtime.ts +21 -0
  128. package/src/conformance/served.ts +888 -4
  129. package/src/files/paths.ts +4 -0
  130. package/src/guide/gates.ts +13 -1
  131. package/src/guide/guide.ts +3 -3
  132. package/src/guide/runtime.ts +12 -3
  133. package/src/host/create-host.ts +88 -38
  134. package/src/host/pages-of-set.ts +226 -0
  135. package/src/host/types.ts +15 -1
  136. package/src/index.ts +5 -0
  137. package/src/mcp/adapter.ts +16 -20
  138. package/src/node/index.ts +507 -116
  139. package/src/platform/types.ts +6 -0
  140. package/src/platform/web.ts +10 -0
  141. package/src/presets/presets.ts +60 -17
  142. package/src/protocol/live-data.ts +31 -3
  143. package/src/protocol/mcp-apps.ts +11 -2
  144. package/src/protocol/message-text.ts +36 -0
  145. package/src/protocol/runtime-calls.ts +3 -0
  146. package/src/protocol/shell-adapter.ts +27 -23
  147. package/src/react/context-notice.tsx +95 -0
  148. package/src/react/dialog.tsx +77 -17
  149. package/src/react/frame.tsx +107 -2
  150. package/src/react/index.ts +8 -1
  151. package/src/runtime/contract.ts +36 -2
  152. package/src/runtime/db.ts +140 -20
  153. package/src/runtime/declaration.ts +227 -89
  154. package/src/runtime/requests.ts +27 -11
  155. package/src/runtime/types.generated.ts +1 -1
  156. package/src/server/files.ts +29 -11
  157. package/src/server/host.ts +158 -3
  158. package/src/server/index.ts +1 -0
  159. package/src/server/peer.ts +21 -0
  160. package/src/server/proxy.ts +13 -3
  161. package/src/server/server.ts +139 -36
  162. package/src/server/types.ts +6 -3
  163. package/src/shell/annotate.ts +233 -15
  164. package/src/shell/document.ts +8 -0
  165. package/src/shell/runtime.ts +361 -14
  166. package/types/runtime/v1/context.d.ts +13 -2
package/docs/ADOPTING.md CHANGED
@@ -5,6 +5,9 @@ app that does everything below: `examples/app.mjs` is the app, runtime-agnostic;
5
5
  `examples/node/server.mjs` (`nodeServer`) and `examples/workers/` (`contentHostFor`) run it, as
6
6
  §4 and §5 recommend; `examples/mcp/server.mjs` gives the
7
7
  agent its tools. DESIGN.md says how it works and DECISIONS.md why (the P-numbers the code cites).
8
+ [THREAT_MODEL.md](THREAT_MODEL.md) says, for each use (chat widgets, live data, private and public
9
+ pages, MCP Apps, previews, several displays on one page), what Porthole guarantees, what you must
10
+ do, and what isn't covered: read your use's section before you show content that matters.
8
11
 
9
12
  ## 1. Choose how content is shown
10
13
 
@@ -53,7 +56,7 @@ data (fetch, WebSocket). Every preset starts closed, and a kind opens more only
53
56
  | **Closed** (the default) | nothing to write | Nothing from outside the frame: content runs on what it carries (inline code, `data:` and `blob:` URLs). | None. | Widgets that draw their own SVG and CSS; any host that hasn't decided yet. | `Network: none. Nothing loads from outside` (and `write everything inline`) | [P006](DECISIONS.md#p006--2026-10-11--egress-is-closed-by-default-including-channels-a-frame-csp-doesnt-cover--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082-p089) | probes `1.connect`, `2.resources`, `3.webrtc`, `4.*` (nested frames), `5.*` (navigating out), `8.*` (resource hints), `10.self`; served `served.domain.egress` |
54
57
  | **Library CDNs** (`LIBRARY_CDNS`, plus script hosts of your own) | `egress: LIBRARY_CDNS`; more script hosts: `egress: { ...LIBRARY_CDNS, script: [...LIBRARY_CDNS.script, "https://cdn.example.com"] }` | Scripts, styles, fonts, images and data from cdnjs, jsDelivr, unpkg and esm.sh; Google Fonts; scripts only from three libraries' own CDNs (Tailwind's Play CDN, jQuery, Plotly). Nothing else. | Code you don't control runs in the frame (a compromised or look-alike package), still inside the sandbox and egress; and a path requested from a CDN is a narrow channel out, read by the CDN's operator. The manual tells agents to pin versions. | Ferry's widgets, Raft Artifacts' pages: agents load Chart.js, ECharts, d3, Mermaid, Tailwind, jQuery, Plotly. | `scripts, styles, fonts, images and data (fetch, WebSocket) from https://cdnjs.cloudflare.com` …, `scripts from https://cdn.tailwindcss.com, https://code.jquery.com, https://cdn.plot.ly` and `pin an exact version` | [P078](DECISIONS.md#p078--2026-10-13--library_cdns-adds-tailwinds-jquerys-and-plotlys-own-cdns-for-scripts-only--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082-p089), [P048](DECISIONS.md#p048--2026-10-11--artifact-pages-reach-library-cdns-only-by-the-hosts-config--accepted) | `leak/cdn.spec.ts` (a CDN library loads only when the config opens it, opaque and served; another origin never; the libraries' own CDNs serve scripts and nothing else); probes `1.connect`, `2.resources` (an allowed origin loads, no other does) |
55
58
  | **Passive from any https site** (`anyHttps`, on top of either) | `egress: { ...LIBRARY_CDNS, anyHttps: ["img"] }`; closed but for them: `egress: { anyHttps: ["img"] }` | The passive kinds you name (`img`, `media`, `font`) from any https site. Never scripts, styles, data, workers or frames, and never `http:`: a config naming another kind is refused. | Any site an image names learns that someone viewed the content, and from which address; content can send data out in an image URL to a server of its choosing (the channel P006 closes); whoever owns an image controls what it shows, inside the frame. | A host showing content that already exists, with hotlinked media: Raft's HTML attachment previews, reports whose `<img>` point at other sites (the case P059 was written for). | `images from any https site` (`fonts, images, audio and video from any https site` for all three) | [P059](DECISIONS.md#p059--2026-10-11--passive-content-may-load-from-any-https-site-by-the-hosts-explicit-choice--accepted), [P062](DECISIONS.md#p062--2026-10-11--serveddomainegress-holds-a-host-to-its-own-configs-egress--accepted) | `leak/cdn.spec.ts` (a hotlinked image loads; a script, a stylesheet and a fetch to the same site never reach it; without the flag, nothing does); served `served.domain.egress` (the image must reach an https canary; scripts, styles, fetches and frames never), `leak/served/any-https.spec.ts` |
56
- | **Porthole's libraries** (`egress.libraries`, served kinds only; on in `presets.liveWidget`) | `egress: { libraries: true }` with `isolation: "domain"` | Chart.js 4.5.1 and D3 7.9.0 as scripts, from the frame's own origin (`/__porthole/lib/…`, served by `/server` on every content origin). Nothing from outside. | None from outside: the requests reach your content server, which serves fixed, pinned files. | Live widgets, which read your data and must have no network of their own (P079). | `Libraries, served from this frame's own address` with a `<script>` line for each | [P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084) | `test/libraries.test.ts`; `leak/served/live.spec.ts` (they load and draw; an external script, a stylesheet, an image and every fetch reach no oracle) |
59
+ | **Porthole's libraries** (`egress.libraries`, served kinds only; on in `presets.liveWidget`) | `egress: { libraries: true }` with `isolation: "domain"` | Chart.js 4.5.1 and D3 7.9.0 as scripts, from the frame's own origin (`/__porthole/lib/…`, served by `/server` on every content origin). Nothing from outside. | None from outside: the requests reach your content server, which serves fixed, pinned files. | Live widgets, which read your data and must have no network of their own (P079). | `Libraries, served from this frame's own address` with a `<script>` line for each | [P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084-p094-p103) | `test/libraries.test.ts`; `leak/served/live.spec.ts` (they load and draw; an external script, a stylesheet, an image and every fetch reach no oracle) |
57
60
 
58
61
  How to decide: **start closed; add `LIBRARY_CDNS` if agents use libraries; add passive `anyHttps`
59
62
  only for existing content with hotlinks**, and only the kinds it hotlinks (usually `img`). An
@@ -89,9 +92,11 @@ export const displays = defineDisplays({
89
92
  ### Live widgets: content that reads your data
90
93
 
91
94
  A live widget shows your data, current, read as the person viewing it, with no network of its own
92
- ([P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084)).
95
+ ([P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084-p094-p103)).
93
96
  Its only way out is your host: `readData` (MCP `resources/read`) and `subscribeData` (MCP
94
- `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`).
97
+ `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`). No option opens
98
+ its network: `presets.liveWidget` refuses `egress`, and a capability's own `connect` or `resource`
99
+ origins (a `ConfigError` naming the option, P103); a display that needs an origin is another kind.
95
100
 
96
101
  ```js
97
102
  import { defineDisplays, Refused } from "@botiverse/porthole";
@@ -112,7 +117,8 @@ createHost(displays.configFor(instance, contentSource), {
112
117
  contents: [{ uri, mimeType: "application/json", text: JSON.stringify(await load(uri)) }],
113
118
  };
114
119
  },
115
- // Call changed() when it changes (the content reads it again), or changed(result) to send it.
120
+ // Call changed() when it changes (the content reads it again), or changed(result) to send it:
121
+ // the content's read of it then passes readData's gates, and counts against its rate (P094).
116
122
  subscribeData: ({ uri }, { changed, signal }) => {
117
123
  const stop = realtime.on(uri, () => changed());
118
124
  signal.addEventListener("abort", stop);
@@ -152,7 +158,9 @@ createHost(displays.configFor(instance, contentSource), {
152
158
  The manual tells the agent to draw the widget without the data, with that sentence. A handler's
153
159
  other errors are `failed` in Porthole's words: their messages stay yours.
154
160
  - **Rates stay gates**: 120 reads and 60 subscriptions a minute per display by default; change them
155
- with the capability's `gates` (keep `"consent"` in the list).
161
+ with the capability's `gates` (keep `"consent"` in the list). Every read counts, a read your
162
+ `changed(result)` answers too (P094): a widget that follows a resource changing faster than
163
+ twice a second needs a higher read rate.
156
164
  - **Your page's CSP**: send `displays.embedderCsp(source, …)` (`frame-src` of your content origins
157
165
  and the authorize route, nothing else). It keeps a frame from navigating to an outside site; the
158
166
  shell keeps a served frame from navigating to another content origin (P079), and tells you:
@@ -163,7 +171,8 @@ createHost(displays.configFor(instance, contentSource), {
163
171
  - **Keep live widgets off pages with frames that reach the network.** A frame can `postMessage` any
164
172
  frame on its page, and nothing in it can stop that: a url-mode app (a dev server's preview) or an
165
173
  `anyHttps` display beside a live widget could be handed what it read. Displays with closed egress
166
- or `LIBRARY_CDNS` are fine beside it.
174
+ or `LIBRARY_CDNS` are fine beside it. The rule for any page: its egress is the union of its
175
+ frames' ([THREAT_MODEL.md § S7](THREAT_MODEL.md#s7-several-displays-on-one-page)).
167
176
  - **Opaque live widgets** (no content domain) work, without libraries: the manual tells the agent
168
177
  to draw with SVG and CSS. An opaque frame's only wall against navigating itself away is your
169
178
  page's `frame-src` (the shell's guard gets no events in an opaque origin), so show them on pages
@@ -197,6 +206,46 @@ counts nor resets the count). The request names the display (`request.display`:
197
206
  `title`, and the `instance` you gave the frame, served or opaque), so the dialog can say what it
198
207
  is from your own records. It stays on your side: an opaque frame never gets the instance. `useRunAgain()` gives a "run again" button.
199
208
 
209
+ ### Context for the agent (`setModelContext`)
210
+
211
+ A widget or an MCP Apps view may tell the agent what the person is looking at
212
+ (`ui/update-model-context`, the App SDK's `app.updateModelContext`). That is the content's text,
213
+ in your model's next turn, so by default the person is shown every update first (the `show` gate,
214
+ [P100](DECISIONS.md#p100--2026-10-19--what-content-tells-the-model-the-person-is-shown-first-the-show-gate-on-by-default-for-setmodelcontext--accepted)): pass `show`. It gets the whole update (`request.args`: text blocks and
215
+ structured content, at most `MAX_CONTEXT_CHARS` together) and the display, before your handler,
216
+ and draws it outside the frame: the latest per display, since each replaces the last. Without
217
+ `show` every update is refused (fail closed). React: `PortholeProvider` draws `ContextNotice`
218
+ unless you pass your own `show`.
219
+
220
+ ```js
221
+ createHost(config, {
222
+ handlers: { setModelContext: (update, { displayId }) => modelContext.set(displayId, update) },
223
+ // Before the handler has it: the person sees what the agent will read.
224
+ show: ({ args, display }) => composer.contextChip(display.id, display.title, args),
225
+ });
226
+ ```
227
+
228
+ - **Give it to the model as the content's words** ("the view “Signups” says: …"), never as the
229
+ person's message or as instructions. The manual tells the agent the same.
230
+ - **Send it with the person's next message** (MCP Apps lets a host defer it), so they have seen it
231
+ before the model reads it. If your agent takes turns on its own, add `"confirm"` to the gates.
232
+ - **Opting out**: `setModelContext: { gates: [{ rateLimit: { perMinute: 30 } }], withoutShow: true }`
233
+ names the gates without `show`, and says so on purpose. Do it only where your handler itself puts
234
+ the text in front of the person (or the content is your own): otherwise the content writes into
235
+ your model's turns unseen. Gates named without `show` and without `withoutShow` (a 0.7 config
236
+ that set its own rate) earn the warning `model-context-unshown`, which you see only if you read
237
+ it: Porthole logs nothing, anywhere. Read `host.compiled.warnings` (or `compile(config).warnings`,
238
+ `configWarnings(config)`) at startup, or pass `validateConfig(config, { onWarning })`, and log
239
+ or fail on what you find; otherwise nothing tells you.
240
+ - **What can't be seen is refused**: an update with an invisible character (zero-width ones, bidi
241
+ controls, variation selectors, tag or private-use characters, controls other than new lines and
242
+ tabs), in its text or any string of its structured content, never reaches `show` or your
243
+ handler. Real emoji pass (☀️, 👨‍👩‍👧, 👩🏽‍💻, 1️⃣): a selector right after a pictograph or in a
244
+ keycap, a joiner between two pictographs. So do joiners that shape letters: U+200C or U+200D
245
+ between two letters or marks of Arabic, Syriac, N'Ko, Mongolian, the Indic scripts, Sinhala or
246
+ Myanmar (Persian's می‌خواهم). Subdivision flags (tag characters) don't. Your own `show` resolves only once that very update is visible: if a later update of
247
+ the display replaces it before it is drawn, reject, and it doesn't go.
248
+
200
249
  ## 4. Served pages: the host kit
201
250
 
202
251
  ### Local development
@@ -268,9 +317,35 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
268
317
  yourself as soon as you make it is fine too.
269
318
  - **`nodeHost(content, { request })`** is for an app that keeps its own `node:http` server (or a
270
319
  framework that owns one): put its `request` and `upgrade` listeners on your server, call
271
- `content.start()` once it listens and `content.close()` when it stops.
320
+ `content.start()` once it listens and `content.close()` when it stops. A fetch-style app's
321
+ listener there is `nodeListener(app, { scheme })`, not `toRequest` and `sendResponse` by hand:
322
+ `toRequest` throws for a request fetch can't take (`TRACE`, a Host that is no URL), and a throw
323
+ in a listener ends a Node process. `nodeListener`, `nodeHost` and `nodeServer` answer those 405
324
+ and 400, and a handler or listener that fails 500 (P092). Pass `onError: (error, request) =>
325
+ log.error(…)` to any of them to hear your own failures (by default a process warning).
326
+ - **Rate limit:** `rateLimit: { perMinute }` keys an anonymous viewer by the address the server
327
+ saw (the socket's peer on Node, `CF-Connecting-IP` on Workers), never by `X-Forwarded-For` a
328
+ client can write (P092). **Behind a proxy** (a TLS edge, a load balancer, a CDN), that address
329
+ is the proxy's: say how many proxies append to `X-Forwarded-For` (`trustedProxies: 1` for one
330
+ edge, `2` for a CDN in front of a balancer), or key it yourself (`key: (request, viewer) =>
331
+ …`). Without either, anonymous requests through the proxy share one allowance. An IPv6
332
+ address counts by its /64 (one client's network). Three cases to know:
333
+ - **No peer address:** the Node adapter leaves the socket's peer on the request it makes. Where
334
+ it is missing (Hono's own Node adapter, an app that rebuilds the request with
335
+ `new Request(req)`, Deno or Bun), every anonymous request shares one allowance: set
336
+ `rateLimit.key`.
337
+ - **`trustedProxies` only where the app can't be reached except through those proxies:** a
338
+ client that reaches it directly writes the very `X-Forwarded-For` entry that is counted.
339
+ - **Uploads after the answer:** once an answer is out, a request body no one read is dropped
340
+ for at most 1 MiB and 5 s, then the connection closes (P092). An app that answers early and
341
+ keeps reading the upload (a handler that returns its Response before it has read the
342
+ request's body) is cut off there.
272
343
  - **Health:** `health: { probe: nodeProbe(), onServedChange: (served) => … }` checks the content
273
344
  domain over the real network and falls back to opaque frames while it doesn't answer.
345
+ - **Behind an edge that rewrites headers** (a CDN, a proxy), pass Porthole's
346
+ `Content-Security-Policy` on as it is: a served page opened on a tab of its own (a link, a new
347
+ tab) has no frame, and the header's `sandbox allow-scripts allow-same-origin` is its sandbox
348
+ there (P099). The conformance runner's `served.domain.tab-*` cases fail if it is lost.
274
349
 
275
350
  ### Pages made of many files
276
351
 
@@ -327,7 +402,9 @@ entry: {
327
402
 
328
403
  0.7 (P085–P090). A page reaches your services through one global, `porthole.use(name)`, for what
329
404
  it declared when it was published and what its viewer's level allows. Porthole carries, checks
330
- and gates the calls; you keep the services.
405
+ and gates the calls; you keep the services. It is an optional layer over the display: what it adds
406
+ to your side (your API's checks, versions, revocation, each person's data) is in
407
+ [THREAT_MODEL.md § The display layer and the app runtime](THREAT_MODEL.md#7-the-display-layer-and-the-app-runtime).
331
408
 
332
409
  ```js
333
410
  import { declareCapabilities, presets } from "@botiverse/porthole";
@@ -355,9 +432,12 @@ handlers: {
355
432
  comments: ({ anchor }) => composer.open(anchor), // true if it opened
356
433
  },
357
434
  // 5. The mount: what this version declared, within what the artifact declares now; null for a
358
- // page published before 0.7 (required under a runtime).
359
- <PortholeView display="page" instance={instance}
360
- declaration={version.declaration ? intersectDeclarations(version.declaration, artifact.declaration) : null} />
435
+ // page published before 0.7 (required under a runtime). Before rendering: a stored
436
+ // declaration that isn't one's shape is a problem to show, never a mount with null (0.6's
437
+ // surface) or with either declaration alone (P093).
438
+ const shown = version.declaration ? tryIntersectDeclarations(version.declaration, artifact.declaration) : null;
439
+ if (shown && !shown.ok) return <VersionError problems={shown.problems} />; // "This version can't be shown"
440
+ <PortholeView display="page" instance={instance} declaration={shown ? shown.declaration : null} />
361
441
  ```
362
442
 
363
443
  - **Built-ins** (`clipboard`, `links`, `downloads`, `comments`) reach every page whose kind offers
@@ -378,7 +458,16 @@ handlers: {
378
458
  order against one state, and refuse a moved base or version with `new Refused("conflict")`;
379
459
  check and admit the merged version as any (`checkFileSet`, `admitFiles`).
380
460
  - **Per version**: store each version's declaration with it (`declareCapabilities` at its publish)
381
- and mount a version with `intersectDeclarations(version's, current)`.
461
+ and mount a version with `tryIntersectDeclarations(version's, current)` (`intersectDeclarations`
462
+ throws its problems as a `TypeError`); your API's rules for that version are the same
463
+ intersection's (whatever it allows, both declarations allow).
464
+ - **Rules hold in any case**: `dbAccess` holds `Votes/a` to its exact name's rule (else `*`'s)
465
+ and to the rule for `votes` too (any rule naming it in another ASCII case), so a store that
466
+ folds case is safe with it; paths reach your handler as the page wrote them (Porthole never
467
+ lowercases them), and a publish that names a collection twice in different cases is refused.
468
+ - **Objects without a prototype**: checked declarations (`checkDeclaration`, `declareCapabilities`,
469
+ the intersection) have none, so `.hasOwnProperty()` on one, or one in a template string,
470
+ throws: use `Object.hasOwn` and `JSON.stringify`.
382
471
  - **Who the page may know**: `Grant.user.id` is one path segment, never `me`; give
383
472
  `pseudonymFor(secret, artifact, person)` where pages shouldn't link a person across artifacts.
384
473
  - **Assets**: `createContentHost({ assets: (id, access) => myStore.asset(id, access) })` answers
@@ -389,6 +478,10 @@ handlers: {
389
478
  uploaded code may run) and give it back: other code-typed assets are served as downloads. Pages
390
479
  show assets with `assets.url(id)` (some engines' frames send no address a `/_blob/` load could
391
480
  carry). `{ get, bearer: true }` serves by id alone, an explicit opt-in for public artifacts.
481
+ A trusted script goes out as one only while the config still lets uploaded code run, checked at
482
+ each load (P103): in bearer mode, with no access to name the page's config, every artifact
483
+ config your server has must (one where anyone who interacts uploads, or with no `assets`, turns
484
+ them all into downloads).
392
485
  Refuse names that aren't assets (`assetNameProblem`).
393
486
  - **Run the conformance cases** against your handlers (no browser):
394
487
 
@@ -506,6 +599,17 @@ same parts: `upstreamHeaders.request(headers, { origin, target, websocket })` an
506
599
  detail, reason, hostOrigins })` (a page that tells the frame's host why it shows nothing, desktop
507
600
  schemes included), and `nodeHost`'s `appSocket` (a WebSocket, Porthole's cookies already removed).
508
601
 
602
+ What a url-mode app gets from another origin (P101): its cookie opens it for what its own origin
603
+ asks (`Origin` its own, or `Sec-Fetch-Site` `same-origin` or `none`) and for a navigation that
604
+ opens it (GET or HEAD: your frame, a link, the way back from sign-in); anything else another origin
605
+ sends (a sibling app's fetch, form post, script tag or image, an opaque origin's `null`) is a 403
606
+ that never reaches the app or your `authorize.check`. A WebSocket opens from the app's own origin
607
+ only: `access(request)`, which `nodeHost` asks before `appSocket` and a Worker asks on its own
608
+ upgrade path, is null for any other `Origin`. A client that sends neither header (curl with the
609
+ cookie) is no browser and goes on. An app whose sign-in posts back from another site (OpenID's
610
+ `form_post`) can't sign in through the preview; a tab's `Lax` cookie didn't go with that post
611
+ before either.
612
+
509
613
  ## 5. Cloudflare Workers
510
614
 
511
615
  ```js
@@ -691,7 +795,8 @@ prints each reason at the end; so does `--reporter=json`.
691
795
  (`'unsafe-inline'`), so eval adds no capability, and libraries content uses compile with it
692
796
  (Vue's in-browser build, Alpine.js, Vega's expressions, WebAssembly). Egress, the sandbox and the
693
797
  origin are what isolate it (P071).
694
- - On `http` loopback the session cookies are `porthole-<key>`; on `https`, `__Host-porthole-<key>`.
798
+ - On `http` loopback the session cookies are `porthole-<key>`; on `https`, `__Host-porthole-<key>`,
799
+ and only that name is read (P101: a sibling label can set any other for the whole domain).
695
800
  A frame's are `Secure; SameSite=None; Partitioned` on loopback too: browsers keep `Secure`
696
801
  cookies on `localhost`.
697
802
  - A served frame is one iframe on the content's own origin (no frame inside it), first loaded at
@@ -708,7 +813,7 @@ prints each reason at the end; so does `--reporter=json`.
708
813
  | `@botiverse/porthole` (the runtime, 0.7) | `declareCapabilities`, `declarationProblems`, `checkDeclaration`, `dbAccess`, `atLeast`, `methodLevel`, `rosterOf`, `assetNameProblem`, `RUNTIME_CAPABILITIES`, `RUNTIME_TYPES`, `Refused` (`conflict`, `forbidden`, `too_large`); `types/runtime/v1/*.d.ts` |
709
814
  | `@botiverse/porthole/react` | `PortholeProvider`, `PortholeFrame`, `PortholeView`, `usePortholeLink`, `cssVariableTheme`, `useRunAgain` |
710
815
  | `@botiverse/porthole/server` | `createContentHost` (`routes`, `forget`), `contentHostFor`, `prefixedName`, `memoryTicketStore`, `d1TicketStore`, `upstreamHeaders`, `statusPage`, `conformancePage`, the callbacks' types |
711
- | `@botiverse/porthole/node` | `nodeServer`, `nodeHost`, `nodeProbe`, `toRequest`, `sendResponse` |
816
+ | `@botiverse/porthole/node` | `nodeServer`, `nodeHost`, `nodeListener`, `nodeProbe`, `toRequest`, `sendResponse` |
712
817
  | `@botiverse/porthole/check` | `checkPage`, `playwrightDriver`, `cdpDriver` (`CHECK_ORIGIN`, `CHECK_CONTENT_DOMAIN`: the names a driver of your own answers); `/check/page`, the check page's script (`checkPage` has it already) |
713
818
  | `@botiverse/porthole/mcp` | the MCP Apps adapter (views, the sandbox proxy) |
714
819
  | `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage`, `defineRuntimeConformance` (no browser); `/conformance/reporter`, skip reasons |
@@ -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,11 +14,13 @@ 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
 
19
- A page published as an artifact may be an app: under the **capability runtime** it reaches its
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
20
24
  host through one global, `porthole.use(name)`, for the capabilities it declared and its viewer's
21
25
  level allows. The runtime is how content reaches host functions, not new ones: each of its
22
26
  methods is served by a host function the config declares, and the bridge alone decides each call
@@ -213,6 +217,9 @@ only the declared content origins.
213
217
 
214
218
  ## Trust boundaries
215
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
+
216
223
  1. **Host ↔ content.** The hard boundary. The content runs on an origin that is
217
224
  never the host's, so same-origin policy denies it the host's DOM, storage,
218
225
  cookies and credentials. Everything it wants beyond drawing crosses the bridge
@@ -236,6 +243,9 @@ only the declared content origins.
236
243
  realm) reach the network outside a frame's own `connect-src`. These are
237
244
  closed by in-shell defenses and by the embedding page's own policy, each
238
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).
239
249
  - *An opaque frame is as closed as its page.* A `srcdoc` frame inherits the
240
250
  embedding page's whole policy as well as its own, so on a page with
241
251
  `default-src 'none'` and a tight `connect-src`/`img-src` its content is more
@@ -283,7 +293,8 @@ only the declared content origins.
283
293
  `/server` from the host's store at `/_blob/<id>` on the artifact's origin.
284
294
  - **Annotations** (`annotate`): the host drives a select mode and marks anchors in
285
295
  the shell; anchors are W3C Web Annotation selectors a host stores with its own
286
- comments (P053).
296
+ comments (P053). A mark may carry a count, drawn as a clickable marker whose click
297
+ the host hears and answers with its own UI outside the frame (P104).
287
298
  - **Served content.** A host plugs its own policy and infrastructure into `/server`:
288
299
  who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
289
300
  how origins are named (`content.name`, other servers' `reserved` namespaces),