@botiverse/porthole 0.7.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.
- package/README.md +9 -2
- package/THIRD_PARTY_NOTICES.md +421 -0
- package/dist/bridge/bounded-text.d.ts +34 -0
- package/dist/bridge/bounded-text.js +188 -0
- package/dist/bridge/bridge.d.ts +25 -5
- package/dist/bridge/bridge.js +311 -73
- package/dist/bridge/json-data.d.ts +28 -0
- package/dist/bridge/json-data.js +86 -0
- package/dist/bridge/navigation.d.ts +5 -0
- package/dist/bridge/navigation.js +7 -0
- package/dist/bridge/refusal.js +1 -0
- package/dist/bridge/types.d.ts +32 -1
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +2 -0
- package/dist/compile/compile.d.ts +6 -0
- package/dist/compile/compile.js +3 -1
- package/dist/compile/policy.d.ts +38 -2
- package/dist/compile/policy.js +122 -7
- package/dist/config/capabilities.d.ts +23 -4
- package/dist/config/capabilities.js +12 -2
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/validate.d.ts +8 -2
- package/dist/config/validate.js +28 -6
- package/dist/config/warnings.d.ts +20 -0
- package/dist/config/warnings.js +25 -0
- package/dist/conformance/behavior.js +46 -1
- package/dist/conformance/cookies.d.ts +15 -0
- package/dist/conformance/cookies.js +80 -0
- package/dist/conformance/harness/page.d.ts +1 -0
- package/dist/conformance/harness/page.js +9 -2
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +5 -1
- package/dist/conformance/index.d.ts +10 -0
- package/dist/conformance/limits.js +38 -1
- package/dist/conformance/runtime.js +10 -0
- package/dist/conformance/served.d.ts +2 -0
- package/dist/conformance/served.js +737 -4
- package/dist/files/paths.js +4 -0
- package/dist/guide/gates.d.ts +7 -1
- package/dist/guide/gates.js +12 -0
- package/dist/guide/guide.js +2 -2
- package/dist/guide/runtime.js +11 -3
- package/dist/host/create-host.js +49 -37
- package/dist/host/pages-of-set.d.ts +43 -0
- package/dist/host/pages-of-set.js +196 -0
- package/dist/host/types.d.ts +8 -1
- package/dist/index.d.ts +5 -4
- package/dist/index.js +3 -2
- package/dist/mcp/adapter.js +11 -15
- package/dist/node/index.d.ts +36 -4
- package/dist/node/index.js +402 -101
- package/dist/presets/presets.d.ts +16 -8
- package/dist/presets/presets.js +39 -8
- package/dist/protocol/live-data.d.ts +6 -2
- package/dist/protocol/live-data.js +20 -1
- package/dist/protocol/mcp-apps.d.ts +13 -2
- package/dist/protocol/mcp-apps.js +10 -2
- package/dist/protocol/message-text.d.ts +8 -0
- package/dist/protocol/message-text.js +29 -0
- package/dist/protocol/runtime-calls.js +3 -0
- package/dist/protocol/shell-adapter.js +16 -22
- package/dist/react/context-notice.d.ts +32 -0
- package/dist/react/context-notice.js +28 -0
- package/dist/react/dialog.js +62 -18
- package/dist/react/frame.d.ts +12 -1
- package/dist/react/frame.js +79 -2
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +2 -1
- package/dist/runtime/contract.d.ts +9 -1
- package/dist/runtime/contract.js +31 -2
- package/dist/runtime/db.d.ts +41 -6
- package/dist/runtime/db.js +120 -16
- package/dist/runtime/declaration.d.ts +15 -1
- package/dist/runtime/declaration.js +184 -87
- package/dist/runtime/requests.js +27 -11
- package/dist/runtime/types.generated.js +1 -1
- package/dist/server/files.d.ts +5 -0
- package/dist/server/files.js +22 -7
- package/dist/server/host.d.ts +18 -1
- package/dist/server/host.js +132 -2
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +1 -1
- package/dist/server/peer.d.ts +4 -0
- package/dist/server/peer.js +19 -0
- package/dist/server/proxy.d.ts +6 -0
- package/dist/server/proxy.js +12 -3
- package/dist/server/server.js +113 -26
- package/dist/server/types.d.ts +6 -3
- package/dist/shell/document.d.ts +8 -0
- package/dist/shell/document.js +3 -0
- package/dist/shell/runtime.js +361 -14
- package/docs/ADOPTING.md +119 -14
- package/docs/ARCHITECTURE.md +13 -3
- package/docs/DECISIONS.md +1455 -8
- package/docs/DESIGN.md +79 -25
- package/docs/THREAT_MODEL.md +616 -0
- package/package.json +14 -3
- package/src/bridge/bounded-text.ts +240 -0
- package/src/bridge/bridge.ts +373 -84
- package/src/bridge/json-data.ts +95 -0
- package/src/bridge/navigation.ts +10 -0
- package/src/bridge/refusal.ts +1 -0
- package/src/bridge/types.ts +30 -1
- package/src/check/page.ts +2 -0
- package/src/compile/compile.ts +9 -1
- package/src/compile/policy.ts +130 -7
- package/src/config/capabilities.ts +22 -3
- package/src/config/schema.ts +11 -0
- package/src/config/validate.ts +43 -5
- package/src/config/warnings.ts +42 -0
- package/src/conformance/behavior.ts +54 -1
- package/src/conformance/cookies.ts +93 -0
- package/src/conformance/harness/page.ts +11 -2
- package/src/conformance/host-kit.ts +10 -1
- package/src/conformance/index.ts +10 -0
- package/src/conformance/limits.ts +39 -1
- package/src/conformance/runtime.ts +21 -0
- package/src/conformance/served.ts +888 -4
- package/src/files/paths.ts +4 -0
- package/src/guide/gates.ts +13 -1
- package/src/guide/guide.ts +3 -3
- package/src/guide/runtime.ts +12 -3
- package/src/host/create-host.ts +54 -36
- package/src/host/pages-of-set.ts +226 -0
- package/src/host/types.ts +15 -1
- package/src/index.ts +5 -0
- package/src/mcp/adapter.ts +16 -20
- package/src/node/index.ts +507 -116
- package/src/presets/presets.ts +60 -17
- package/src/protocol/live-data.ts +31 -3
- package/src/protocol/mcp-apps.ts +11 -2
- package/src/protocol/message-text.ts +36 -0
- package/src/protocol/runtime-calls.ts +3 -0
- package/src/protocol/shell-adapter.ts +27 -23
- package/src/react/context-notice.tsx +95 -0
- package/src/react/dialog.tsx +77 -17
- package/src/react/frame.tsx +101 -0
- package/src/react/index.ts +8 -1
- package/src/runtime/contract.ts +36 -2
- package/src/runtime/db.ts +140 -20
- package/src/runtime/declaration.ts +227 -89
- package/src/runtime/requests.ts +27 -11
- package/src/runtime/types.generated.ts +1 -1
- package/src/server/files.ts +29 -11
- package/src/server/host.ts +158 -3
- package/src/server/index.ts +1 -0
- package/src/server/peer.ts +21 -0
- package/src/server/proxy.ts +13 -3
- package/src/server/server.ts +139 -36
- package/src/server/types.ts +6 -3
- package/src/shell/document.ts +8 -0
- package/src/shell/runtime.ts +361 -14
- 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
|
-
|
|
360
|
-
|
|
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 `
|
|
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 |
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|