@botiverse/porthole 0.15.3 → 0.16.1
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/CHANGELOG.md +70 -0
- package/dist/annotate/types.d.ts +15 -1
- package/dist/annotate/validate.js +19 -1
- package/dist/bridge/bridge.d.ts +1 -8
- package/dist/bridge/bridge.js +0 -7
- package/dist/bridge/types.d.ts +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +1 -1
- package/dist/compile/policy.d.ts +0 -7
- package/dist/compile/policy.js +1 -10
- package/dist/config/capabilities.d.ts +8 -14
- package/dist/config/capabilities.js +4 -5
- package/dist/config/schema.d.ts +2 -13
- package/dist/config/validate.js +0 -24
- package/dist/conformance/behavior.js +26 -37
- package/dist/conformance/clipboard.js +47 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +1 -3
- package/dist/guide/limits.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +1 -1
- package/dist/host/create-host.js +8 -52
- package/dist/host/door.d.ts +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +5 -12
- package/dist/host/outcome.js +8 -16
- package/dist/host/types.d.ts +6 -22
- package/dist/index.d.ts +2 -4
- package/dist/index.js +2 -4
- package/dist/isolation/served.d.ts +4 -14
- package/dist/isolation/served.js +7 -28
- package/dist/isolation/types.d.ts +2 -25
- package/dist/isolation/types.js +0 -23
- package/dist/platform/focus-field.d.ts +11 -0
- package/dist/platform/focus-field.js +18 -0
- package/dist/platform/types.d.ts +7 -23
- package/dist/platform/web.js +8 -106
- package/dist/presets/presets.d.ts +0 -2
- package/dist/presets/presets.js +0 -1
- package/dist/react/frame.d.ts +0 -8
- package/dist/react/frame.js +0 -4
- package/dist/runtime/contract.d.ts +2 -2
- package/dist/runtime/contract.js +2 -2
- package/dist/runtime/types.generated.js +6 -6
- package/dist/server/files.js +7 -23
- package/dist/server/host.d.ts +1 -1
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +4 -6
- package/dist/server/naming.js +1 -1
- package/dist/server/server.js +28 -166
- package/dist/server/types.d.ts +7 -7
- package/dist/shell/annotate.d.ts +3 -0
- package/dist/shell/annotate.js +15 -5
- package/dist/shell/plan.d.ts +0 -5
- package/dist/shell/plan.js +2 -4
- package/dist/shell/runtime.js +1 -268
- package/docs/ADOPTING.md +398 -1081
- package/docs/DECISIONS.md +172 -10
- package/docs/DESIGN.md +1114 -1388
- package/docs/PRINCIPLES.md +85 -1
- package/docs/THREAT_MODEL.md +658 -1127
- package/package.json +1 -1
- package/src/annotate/types.ts +12 -1
- package/src/annotate/validate.ts +23 -1
- package/src/bridge/bridge.ts +1 -17
- package/src/bridge/types.ts +1 -1
- package/src/check/page.ts +1 -1
- package/src/compile/policy.ts +1 -11
- package/src/config/capabilities.ts +8 -14
- package/src/config/schema.ts +2 -13
- package/src/config/validate.ts +0 -28
- package/src/conformance/behavior.ts +50 -52
- package/src/conformance/clipboard.ts +56 -1
- package/src/displays/displays.ts +1 -3
- package/src/guide/limits.ts +1 -1
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +8 -53
- package/src/host/door.ts +1 -1
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +8 -21
- package/src/host/types.ts +6 -20
- package/src/index.ts +2 -4
- package/src/isolation/served.ts +6 -34
- package/src/isolation/types.ts +2 -31
- package/src/platform/focus-field.ts +18 -0
- package/src/platform/types.ts +7 -22
- package/src/platform/web.ts +8 -129
- package/src/presets/presets.ts +0 -3
- package/src/react/frame.tsx +0 -10
- package/src/runtime/contract.ts +4 -4
- package/src/runtime/types.generated.ts +6 -6
- package/src/server/files.ts +4 -19
- package/src/server/host.ts +1 -1
- package/src/server/index.ts +4 -16
- package/src/server/naming.ts +1 -1
- package/src/server/server.ts +29 -189
- package/src/server/types.ts +7 -7
- package/src/shell/annotate.ts +15 -5
- package/src/shell/plan.ts +2 -9
- package/src/shell/runtime.ts +1 -268
- package/types/runtime/v1/artifact.d.ts +2 -3
- package/types/runtime/v1/assets.d.ts +1 -1
- package/types/runtime/v1/chat.d.ts +2 -2
- package/types/runtime/v1/comments.d.ts +1 -1
- package/types/runtime/v1/downloads.d.ts +2 -2
- package/types/runtime/v1/links.d.ts +2 -2
- package/dist/platform/focus-guard.d.ts +0 -288
- package/dist/platform/focus-guard.js +0 -838
- package/dist/server/nested.d.ts +0 -66
- package/dist/server/nested.js +0 -121
- package/dist/shell/frame.d.ts +0 -28
- package/dist/shell/frame.js +0 -407
- package/docs/ARCHITECTURE.md +0 -359
- package/docs/OBJECTIVES.md +0 -116
- package/src/platform/focus-guard.ts +0 -1114
- package/src/server/nested.ts +0 -157
- package/src/shell/frame.ts +0 -444
package/docs/DESIGN.md
CHANGED
|
@@ -1,81 +1,260 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
The stable shape is in [ARCHITECTURE.md](ARCHITECTURE.md) and the reasons in
|
|
4
|
-
[DECISIONS.md](DECISIONS.md). This is the concrete phase-1 plan. Web first:
|
|
5
|
-
a framework-agnostic TypeScript core plus a thin React binding.
|
|
6
|
-
|
|
7
|
-
Adopting Porthole? Start with [ADOPTING.md](ADOPTING.md) and the package's `examples/`. Paths
|
|
8
|
-
below like `leak/…` and `ops/…` are Porthole's own repository, not the package.
|
|
9
|
-
|
|
10
|
-
## Threat model
|
|
11
|
-
|
|
12
|
-
The whole of it, use by use (who attacks, what is out of scope, what each scenario
|
|
13
|
-
guarantees and leaves to the host), is [THREAT_MODEL.md](THREAT_MODEL.md). In short:
|
|
14
|
-
two classes of attacker, handled by different layers (ARCHITECTURE § Trust
|
|
15
|
-
boundaries):
|
|
16
|
-
|
|
17
|
-
1. **Attacking the host** — steal the host's credentials or data, act as the
|
|
18
|
-
person, or escape the sandbox. Countered by **origin isolation**: the content
|
|
19
|
-
runs on an origin that is never the host's, so same-origin policy denies it
|
|
20
|
-
the host's DOM, storage, cookies and credentials. This is the catastrophic
|
|
21
|
-
class; a regression here is the one bug that matters most.
|
|
22
|
-
2. **Leaking or deceiving** — exfiltrate what the content was already handed
|
|
23
|
-
(whatever the agent wrote into it, or data a capability returned), or draw a
|
|
24
|
-
convincing fake (a login form, an "approve" button) to fool the viewer.
|
|
25
|
-
Origin isolation does not help. Countered by **egress hardening** (close every
|
|
26
|
-
outbound channel to all but declared origins), **gating** (powers that affect
|
|
27
|
-
the person or the agent need a gesture or confirmation), and the host drawing
|
|
28
|
-
its own chrome/approvals outside the frame, never inside it.
|
|
29
|
-
|
|
30
|
-
The agent is itself a trust boundary: the HTML is agent-authored, so loading a
|
|
31
|
-
library from an allowed CDN is no more trusted than the agent's own code. The
|
|
32
|
-
manual's supply-chain rule (pin exact, aged versions) is advice to the agent, not
|
|
33
|
-
a wall; the walls are isolation and egress.
|
|
1
|
+
# Design
|
|
34
2
|
|
|
35
|
-
|
|
3
|
+
How Porthole works: the architecture, each mechanism, then every defense with the test that proves
|
|
4
|
+
it. What each use is protected from: [THREAT_MODEL.md](THREAT_MODEL.md). Why:
|
|
5
|
+
[DECISIONS.md](DECISIONS.md). Porthole is web first: a framework-agnostic TypeScript core plus a
|
|
6
|
+
thin React binding.
|
|
36
7
|
|
|
37
|
-
|
|
38
|
-
|
|
8
|
+
Adopting Porthole? Start with [ADOPTING.md](ADOPTING.md) and the package's `examples/`. Paths below
|
|
9
|
+
like `leak/…` and `ops/…` are in Porthole's own repository, not the package.
|
|
39
10
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
11
|
+
## Architecture
|
|
12
|
+
|
|
13
|
+
### The core abstraction
|
|
14
|
+
|
|
15
|
+
Porthole renders **agent-drawn HTML plus a declared set of host functions.** The HTML is untrusted:
|
|
16
|
+
on its own it can only draw. A **host function (capability)** is any power beyond drawing: send a
|
|
17
|
+
prompt to the agent, open a link, read or write state, call a tool, read data, report an error. The
|
|
18
|
+
config names each with its **gate** (a user gesture, a person's confirmation, shown to the person
|
|
19
|
+
first, a rate limit), its **egress needs** (origins it must reach) and its **guide entry** (how the
|
|
20
|
+
manual describes it).
|
|
47
21
|
|
|
48
|
-
|
|
22
|
+
One capability list drives three artifacts: the **bridge** (which functions the shell wires and the
|
|
23
|
+
host handles), the **CSP** (what the sandbox may reach) and the **manual** (what the agent is told).
|
|
24
|
+
So the config is the single source (PRINCIPLE 3), and "talk to the agent" is just one host function
|
|
25
|
+
(PRINCIPLE 4).
|
|
26
|
+
|
|
27
|
+
A page published as an artifact may be an app. Under the **capability runtime**, an optional layer
|
|
28
|
+
over the display, it reaches its host through one global, `porthole.use(name)`, for the capabilities
|
|
29
|
+
it declared and its viewer's level allows. Each runtime method is served by a host function the
|
|
30
|
+
config declares; the bridge alone decides each call (the page's declaration, the viewer's level, the
|
|
31
|
+
gates). The services behind them (a document store, an asset library, versions, comments) are the
|
|
32
|
+
host's.
|
|
33
|
+
|
|
34
|
+
### Layers
|
|
49
35
|
|
|
50
36
|
```
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
37
|
+
┌──────────────────────────────────────────────────────────┐
|
|
38
|
+
│ Host app (owns product policy, theme, callbacks) │
|
|
39
|
+
└───────────────┬──────────────────────────────────────────┘
|
|
40
|
+
│ picks a preset, passes theme + callbacks
|
|
41
|
+
┌─────────────────────────▼─────────────────────────────────────────┐
|
|
42
|
+
│ PRESET POLICY LAYER │
|
|
43
|
+
│ inline-widget · artifact · mcp-app · url │
|
|
44
|
+
│ each = a config: CSP+origins, capabilities+gates, theme, guide │
|
|
45
|
+
└─────────────────────────┬─────────────────────────────────────────┘
|
|
46
|
+
│ one config
|
|
47
|
+
┌─────────────────────────▼─────────────────────────────────────────┐
|
|
48
|
+
│ FRAMEWORK LAYER (mechanisms only, no policy) │
|
|
49
|
+
│ │
|
|
50
|
+
│ config compiler ── CSP + sandbox/allow attrs │
|
|
51
|
+
│ └── shell runtime (what to wire) │
|
|
52
|
+
│ └── guide + tool description │
|
|
53
|
+
│ │
|
|
54
|
+
│ isolation core · egress hardening · streaming render · auto-size │
|
|
55
|
+
│ theming · host-function bridge · guide gen · serving (/server) │
|
|
56
|
+
└───────┬───────────────────────────────────────┬────────────────────┘
|
|
57
|
+
│ host side │ in-frame side (shell)
|
|
58
|
+
┌───────▼─────────┐ ┌───────▼──────────────────┐
|
|
59
|
+
│ PROTOCOL ADAPTER│ ◄── transport ──► │ SHELL (runs first in │
|
|
60
|
+
│ (MCP Apps; …) │ (postMessage/ │ the isolated frame; │
|
|
61
|
+
│ │ native bridge) │ renders HTML, wires caps)│
|
|
62
|
+
└───────┬─────────┘ └───────────────────────────┘
|
|
63
|
+
│
|
|
64
|
+
┌───────▼───────────────────────────────────────────────────────────┐
|
|
65
|
+
│ PLATFORM HOST web (iframe) now · WKWebView / Android later │
|
|
66
|
+
└─────────────────────────────────────────────────────────────────── ┘
|
|
63
67
|
```
|
|
64
68
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
69
|
+
#### Framework layer (mechanisms)
|
|
70
|
+
|
|
71
|
+
Pure mechanism: no product policy, no host or vendor types.
|
|
72
|
+
|
|
73
|
+
- **Config compiler.** One config → the CSP, the iframe `sandbox` and `allow` attributes, the
|
|
74
|
+
shell's wiring, the guide and tool description. Pure and deterministic, so a test asserts the
|
|
75
|
+
outputs agree.
|
|
76
|
+
- **Isolation core.** Puts content on an origin that is never the host's, with nothing of the host's
|
|
77
|
+
reachable: an opaque-origin frame, or a served origin of its own (domain mode: a subdomain per
|
|
78
|
+
storage scope on a separate registrable domain; url mode: the app's own origin). Config picks the
|
|
79
|
+
mode; nothing else depends on which.
|
|
80
|
+
- **Egress hardening.** The closed-by-default network and navigation walls, plus in-shell defenses
|
|
81
|
+
for channels a CSP doesn't cover.
|
|
82
|
+
- **Shell runtime.** Runs first in the frame: applies the theme, inserts the HTML (streaming-aware),
|
|
83
|
+
reports size and errors, exposes the declared host functions.
|
|
84
|
+
- **Host-function bridge.** Carries capability calls to the host and results back over a transport,
|
|
85
|
+
validating and gating at the boundary.
|
|
86
|
+
- **Streaming render, auto-size, theming, guide generator**, each usable alone. Content is plain
|
|
87
|
+
HTML and SVG, styled by theme variables, never a component vocabulary (P015).
|
|
88
|
+
- **Serving** (`/server`). A request handler a host's backend mounts for served modes: documents on
|
|
89
|
+
their own origins, CSP in headers, entered by a one-time ticket the host minted that becomes a
|
|
90
|
+
cookie of that origin only. A stored version is one page or a set of files, each looked up in the
|
|
91
|
+
version's manifest only, typed by Porthole's own table, served under that version's own address.
|
|
92
|
+
|
|
93
|
+
#### Preset policy layer
|
|
94
|
+
|
|
95
|
+
A preset is a named config with safe defaults: CSP and origins, capabilities and gates, theme
|
|
96
|
+
vocabulary, manual. A host overrides only theme and callbacks. The presets (inline-widget, artifact,
|
|
97
|
+
mcp-app, url) are in § The modes.
|
|
98
|
+
|
|
99
|
+
#### Protocol adapters
|
|
100
|
+
|
|
101
|
+
A thin adapter maps capability and lifecycle events onto a wire protocol; **MCP Apps** is the first
|
|
102
|
+
and default. Only the adapter knows protocol method names and shapes (§ The MCP Apps adapters).
|
|
103
|
+
|
|
104
|
+
#### Platform hosts
|
|
105
|
+
|
|
106
|
+
The platform host owns the isolation primitive and the transport: `iframe` + `postMessage` on the
|
|
107
|
+
web now, `WKWebView` + a message handler on iOS later. The framework is written against a small
|
|
108
|
+
platform interface, so a new platform is an implementation, not a fork.
|
|
109
|
+
|
|
110
|
+
#### Conformance / leak suite
|
|
111
|
+
|
|
112
|
+
A standalone runner drives a platform host through an adapter and attempts every known egress and
|
|
113
|
+
escape channel, asserting none succeeds. Any host can run it on its own integration. It is our
|
|
114
|
+
regression gate and what we offer upstream (PRINCIPLE 5, 6).
|
|
115
|
+
|
|
116
|
+
### Contracts between layers
|
|
117
|
+
|
|
118
|
+
| Between | What passes |
|
|
119
|
+
| --- | --- |
|
|
120
|
+
| Host → preset | a preset name, theme tokens (resolved per color scheme), callbacks for each enabled host function; nothing else |
|
|
121
|
+
| Preset → framework | one config: capabilities with gates and egress needs, allowed origins, theme variable map, limits, layout, mode, isolation |
|
|
122
|
+
| Config → {CSP, shell, guide} | derived, never hand-written; a test asserts they agree |
|
|
123
|
+
| Framework ↔ shell | lifecycle and capability messages, validated both ways; unknown or malformed ones dropped |
|
|
124
|
+
| Framework ↔ adapter | capability/lifecycle events ↔ protocol messages, plus protocol-only ones (handshake, teardown) the framework doesn't model |
|
|
125
|
+
| Framework ↔ platform host | create an isolated surface, set its policy (CSP/sandbox/allow or native equivalent), send and receive messages, report size, tear down |
|
|
126
|
+
|
|
127
|
+
So *which protocol* (adapter), *which platform* (platform host) and *what policy* (preset/config)
|
|
128
|
+
vary independently. A new protocol is a new adapter plus a preset selecting it; the core and shell
|
|
129
|
+
mechanisms are untouched. A new platform is a new platform-host implementation; the shell runtime is
|
|
130
|
+
plain, dependency-free script that runs as-is in a new engine.
|
|
131
|
+
|
|
132
|
+
### Flows per mode
|
|
133
|
+
|
|
134
|
+
#### Inline widget
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
Host app Framework/Adapter Shell (opaque frame)
|
|
138
|
+
│ mount(config, cbs) │ │
|
|
139
|
+
│──────────────────────────►│ compile config → CSP, │
|
|
140
|
+
│ │ sandbox attrs, shell doc │
|
|
141
|
+
│ │ create opaque frame ───────►│ (shell runs first)
|
|
142
|
+
│ │◄──── initialize ─────────────│
|
|
143
|
+
│ │──── host context (theme, │
|
|
144
|
+
│ │ capabilities, size) ────►│
|
|
145
|
+
│ content (may stream) ───►│──── content (partial*) ─────►│ draw inert
|
|
146
|
+
│ │──── content (complete) ─────►│ run
|
|
147
|
+
│ │◄──── size / error ───────────│
|
|
148
|
+
│◄── onError / onResize ────│ │
|
|
149
|
+
│ │◄──── capability call ────────│ (e.g. sendPrompt)
|
|
150
|
+
│◄── gate (confirm?) ───────│ validate + gate │
|
|
151
|
+
│── result ────────────────►│──── result ─────────────────►│
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
`*` partial content is drawn inert (no scripts, handlers or navigation) until complete (§
|
|
155
|
+
Streaming).
|
|
156
|
+
|
|
157
|
+
#### MCP Apps view
|
|
158
|
+
|
|
159
|
+
Same shape, the adapter speaking MCP Apps. The view is an MCP Apps `App`; `initialize`/`initialized`
|
|
160
|
+
is the handshake; content arrives as tool input (tool-input-partial, then tool-input) and tool
|
|
161
|
+
result; capability calls (`ui/message`, `ui/open-link`, etc.) map to host functions. On the web a
|
|
162
|
+
second-origin sandbox proxy relays messages, isolating arbitrary MCP App HTML (which expects
|
|
163
|
+
`allow-same-origin`) from the host, transparently to both.
|
|
164
|
+
|
|
165
|
+
#### Artifact page
|
|
166
|
+
|
|
167
|
+
A real document at a URL on a separate registrable domain, CSP in HTTP headers, framed by the host;
|
|
168
|
+
its `frame-ancestors` names the host. No code injection; the shell is optional. A page's own files
|
|
169
|
+
(stylesheets, scripts, data, images, other pages) are served beside it under its version's address;
|
|
170
|
+
its CSP opens that path and nothing else of its origin, and every page of the set gets the shell.
|
|
171
|
+
Access: a one-time ticket exchanged for a scoped cookie. Where the host holds the page and needs no
|
|
172
|
+
stable origin, the shell writes it into an opaque frame instead.
|
|
173
|
+
|
|
174
|
+
#### URL frame
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
Host app Host backend (+ /server) App origin (served)
|
|
178
|
+
│ mount(url preset) │ │
|
|
179
|
+
│── locate ─────────►│ decide the viewer may see it, │
|
|
180
|
+
│◄── ticketed URL ───│ mint a one-time ticket │
|
|
181
|
+
│ frame src = URL ──────────────────────────────────────►│ ticket → cookie
|
|
182
|
+
│ │ (that origin only)
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
No shell and no protocol: the app is someone else's. The embedding page frames only the declared
|
|
186
|
+
content origins.
|
|
187
|
+
|
|
188
|
+
### Trust boundaries
|
|
189
|
+
|
|
190
|
+
Attackers, out of scope, and several displays on one page: [THREAT_MODEL.md](THREAT_MODEL.md) (§ 3,
|
|
191
|
+
§ 4).
|
|
192
|
+
|
|
193
|
+
1. **Host ↔ content.** The hard boundary. Content runs on an origin never the host's, so the
|
|
194
|
+
same-origin policy denies it the host's DOM, storage, cookies and credentials; it never holds a
|
|
195
|
+
host secret. Everything beyond drawing crosses the bridge as a validated, gated call. What
|
|
196
|
+
content says is its own word; the host confirms with a person where the gate says so.
|
|
197
|
+
2. **Content ↔ the network.** Closed by default; open only to the origins declared capabilities
|
|
198
|
+
need, plus, for a served page with files, its version's path on its own origin and its artifact's
|
|
199
|
+
asset library at `/_blob/` (the host's own server, P082, P089). Origin isolation stops attacks on
|
|
200
|
+
the host, the catastrophic class. Leaking and deceiving are stopped by egress hardening, gates,
|
|
201
|
+
and approvals drawn outside the frame (THREAT_MODEL.md § 4). Channels that bypass a frame's
|
|
202
|
+
`connect-src` (ICE gathering, self-navigation, a nested frame's fresh realm) are closed by
|
|
203
|
+
in-shell defenses and the embedding page's policy, each with a probe. A served page outside its
|
|
204
|
+
frame carries the sandbox in its CSP header (P099); an opaque frame also inherits its page's
|
|
205
|
+
policy (P058).
|
|
206
|
+
3. **Host's decision ↔ what a page may do.** Under the capability runtime a page reaches only the
|
|
207
|
+
built-ins and what it declared at publish (stored by the host, given to the mount), each method
|
|
208
|
+
only for viewers at its level (`view < interact < admin < owner`) as the host's access says. The
|
|
209
|
+
bridge refuses before any handler; the host's API checks again, as its data's wall. Per-user data
|
|
210
|
+
is reached by the host's id for the person, never the content's word.
|
|
211
|
+
4. **Message boundary.** Every message crossing the frame is schema-validated and its sender
|
|
212
|
+
checked: the shell takes messages only from its host, the host only from its frame. What the
|
|
213
|
+
frame says about itself (size, errors, an annotation's anchor and place, find's match count) is
|
|
214
|
+
the content's word even when the shell says it, since they share a realm: the host bounds it and
|
|
215
|
+
uses it as a UI hint, never a permission (P053, P131). What the host sends in (a mark, a find
|
|
216
|
+
query) the content can read.
|
|
217
|
+
5. **Host's decision ↔ content domain.** Authentication and authorization *policy* are the host's;
|
|
218
|
+
carrying its decision onto the content domain is Porthole's *mechanism*. The host decides who may
|
|
219
|
+
open an instance before it calls `issue` (a viewer, or a public link), and may decide again per
|
|
220
|
+
request (`ServerOptions.authorize`). Porthole carries the decision as a one-time ticket, then a
|
|
221
|
+
signed cookie of that origin and instance with the host's opaque `subject` inside, and never
|
|
222
|
+
interprets identity. A deny ends access from the next request on and tells the display why.
|
|
223
|
+
|
|
224
|
+
### Extension points
|
|
225
|
+
|
|
226
|
+
- **Capabilities.** A new host function joins the vocabulary with a gate, egress need and guide
|
|
227
|
+
entry, extending bridge, CSP and manual together.
|
|
228
|
+
- **Protocol extension points.** MCP Apps gaps go through the spec's own mechanisms (experimental
|
|
229
|
+
capabilities, own-prefixed methods), so the external contract stays standard (PRINCIPLE 2).
|
|
230
|
+
- **Theme variables.** The theme map is config; the MCP Apps variable names are the default
|
|
231
|
+
vocabulary.
|
|
232
|
+
- **Host-drawn features**, each in its section: the clipboard (content asks with `copyText`; the
|
|
233
|
+
host copies and shows what, P051, P052); the capability runtime (`config.runtime`: per contract
|
|
234
|
+
version, namespaces of methods over host functions with a versioned `.d.ts`); annotations
|
|
235
|
+
(`annotate`, P053: the host drives a select mode, stores W3C Web Annotation anchors with its
|
|
236
|
+
comments, and answers a marker's click with its own UI outside the frame); find in page (`find`:
|
|
237
|
+
the host's find bar, the shell's highlights).
|
|
238
|
+
- **Served content.** A host plugs into `/server`: who may see what (`authorize`), where tickets
|
|
239
|
+
live (`TicketStore`: memory, D1), how origins are named (`content.name`, other servers' `reserved`
|
|
240
|
+
namespaces), where apps and versions come from (`upstream`, `artifacts`: a page, or a manifest of
|
|
241
|
+
files and their bytes), which address means which version (`entry.at`). It runs on any runtime
|
|
242
|
+
with web-standard `Request`/`Response` (Node, Workers).
|
|
243
|
+
|
|
244
|
+
## Package layout
|
|
245
|
+
|
|
246
|
+
One package, `@botiverse/porthole` (`packages/porthole`), with subpath exports (P013), listed in the
|
|
247
|
+
package README's Subpaths; the source tree is in AGENTS.md § Layout. The core (`src/index.ts`) has
|
|
248
|
+
no DOM framework, no host and no MCP SDK. `/react` has the peer `react`, `/conformance` the peer
|
|
249
|
+
`@playwright/test`; `/mcp` depends on the core only. Node ≥ 24 runs the TypeScript by type
|
|
250
|
+
stripping. In the workspace the package exports its sources; `pnpm build` emits JS and declarations
|
|
251
|
+
to `dist/`, which a packed package exports (Node does not strip types under `node_modules`).
|
|
72
252
|
|
|
73
253
|
## Config schema
|
|
74
254
|
|
|
75
|
-
One config per kind of display (`src/config/schema.ts`)
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
that could break out of CSS). Presets return validated configs.
|
|
255
|
+
One config per kind of display (`src/config/schema.ts`). `validateConfig` refuses a bad one whole:
|
|
256
|
+
unknown fields, capabilities or gates; any origin not exactly `scheme://host[:port]` (so nothing can
|
|
257
|
+
inject a CSP directive); theme values that could break out of CSS. Presets return validated configs.
|
|
79
258
|
|
|
80
259
|
```ts
|
|
81
260
|
interface PortholeConfig {
|
|
@@ -99,16 +278,16 @@ interface PortholeConfig {
|
|
|
99
278
|
type Gate = "user-activation" | "confirm" | "consent" | "show" | { rateLimit: { perMinute: number } };
|
|
100
279
|
```
|
|
101
280
|
|
|
102
|
-
`mode` and `isolation` select the mechanism;
|
|
103
|
-
|
|
281
|
+
`mode` and `isolation` select the mechanism; the rest is policy. There is no `components` field
|
|
282
|
+
(P015).
|
|
104
283
|
|
|
105
284
|
### The capability vocabulary
|
|
106
285
|
|
|
107
286
|
| Capability | Default gates | Served by | Shell global | MCP Apps request (App SDK) |
|
|
108
287
|
| --- | --- | --- | --- | --- |
|
|
109
|
-
| `sendPrompt` |
|
|
110
|
-
| `openLink` |
|
|
111
|
-
| `downloadFile` |
|
|
288
|
+
| `sendPrompt` | confirm, 30/min (P149) | handler | `sendPrompt(text)` | `ui/message` (`app.sendMessage`) |
|
|
289
|
+
| `openLink` | confirm, 30/min (P149) | handler | `openLink(url)` | `ui/open-link` (`app.openLink`) |
|
|
290
|
+
| `downloadFile` | confirm, 30/min (P149) | handler | — | `ui/download-file` (`app.downloadFile`) |
|
|
112
291
|
| `callTool` | confirm, 30/min (P103) | handler | — | `tools/call` (`app.callServerTool`) |
|
|
113
292
|
| `readData` | 120/min | handler | `readData(uri)` | `resources/read` (`app.readServerResource`) |
|
|
114
293
|
| `subscribeData` | 60/min (needs `readData`) | handler (`changed`, `signal`) | `subscribeData(uri, onData, onError)` | `resources/subscribe`, `resources/unsubscribe`; the host's `notifications/resources/updated` (MCP's own; none in MCP Apps, P079) |
|
|
@@ -118,622 +297,463 @@ no `components` field (P015).
|
|
|
118
297
|
| `copyText` | user-activation, 30/min | handler | `copyText(text)` | `porthole/copy-text` (none in the standard) |
|
|
119
298
|
| `annotate` | 120/min (the frame's reports) | event | — | `porthole/annotate.*` (the host drives it, P053) |
|
|
120
299
|
| `user` (runtime) | 60/min | viewer (the host's `ViewerInfo`) | `porthole.use("user")` | `porthole/call` (P087) |
|
|
121
|
-
| `comments` (runtime) |
|
|
300
|
+
| `comments` (runtime) | 30/min (P149) | handler (answers a boolean) | `porthole.use("comments")` | `porthole/call` (P090) |
|
|
122
301
|
| `artifact` (runtime, artifact mode) | 10/min | handler (`op: get \| publish`) | `porthole.use("artifact")` | `porthole/call` (P088) |
|
|
123
302
|
| `assets` (runtime, served artifacts) | 30/min | handler (`op: list \| upload \| delete`) | `porthole.use("assets")` | `porthole/call`; `/server` serves `/_blob/<id>` (P089) |
|
|
124
303
|
| `db` (runtime) | 600/min | handler (`op: get \| query \| watch \| set \| update \| delete \| batch`) | `porthole.use("db")` | `porthole/call`, `porthole/event`, `porthole/unwatch` (P088) |
|
|
125
304
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
realm) and by the host where the engine passes
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
Porthole's libraries from its origin (`egress.libraries`).
|
|
305
|
+
Presets declare only `resize` and `reportError` (they report to the host and carry nothing out); the
|
|
306
|
+
host declares the rest. All gates must pass (P021):
|
|
307
|
+
- `confirm` calls the host's `confirm`; fails closed without one.
|
|
308
|
+
- `user-activation` (by default `copyText`'s alone, P149; a host may name it for any other) is
|
|
309
|
+
checked by the shell (advisory: same realm as the content) and by the host where the engine passes
|
|
310
|
+
the gesture up.
|
|
311
|
+
- `consent` asks the host's `consent` once per display, before the first consent-gated call; fails
|
|
312
|
+
closed without one (P079). A `Refused` given as `consent` refuses them all without asking, and
|
|
313
|
+
their capabilities need no handler (P080).
|
|
314
|
+
- `show` hands the host's `show` the call's whole effect before the handler, asking nothing; fails
|
|
315
|
+
closed without one or when it throws (P100). By default every model context update is shown, so
|
|
316
|
+
the person sees it outside the frame before the agent's next turn; the React binding's
|
|
317
|
+
`ContextNotice` is the default surface.
|
|
318
|
+
|
|
319
|
+
A refusal says why: `data: { code, message }` (`consent_required`, `denied`, `rate_limited`,
|
|
320
|
+
`not_allowed`, `failed`; a host's `Refused` words its own, P080).
|
|
143
321
|
|
|
144
322
|
## What the compiler derives
|
|
145
323
|
|
|
146
324
|
`compile(config)` (`src/compile/compile.ts`) validates the config and returns:
|
|
147
325
|
|
|
148
|
-
- `csp` / `cspDirectives`:
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
the declared capabilities, and each capability's manual entry states its gates
|
|
175
|
-
(confirm, click, rate); the manual names exactly the origins the CSP allows; each
|
|
176
|
-
CSP directive equals the egress plus the declared capabilities' needs; the manual
|
|
177
|
-
states the limits, layout and theme event; and changing the config (opening an
|
|
178
|
-
origin, dropping a capability or a variable, overriding an entry) changes all of
|
|
179
|
-
them together. The leak suite's `0.*` probes check the same wiring in real frames.
|
|
326
|
+
- `csp` / `cspDirectives`: `default-src 'none'`. Scripts: inline (agent content is inline),
|
|
327
|
+
`'unsafe-eval'` (the content is the agent's script already, so eval adds nothing; libraries
|
|
328
|
+
content uses compile with it, WebAssembly too: P071), `blob:`, the script origins, and with
|
|
329
|
+
`egress.libraries` Porthole's library path `<origin>/__porthole/lib/` on the content origins
|
|
330
|
+
(P079). Other kinds open only to their origins; `connect-src 'none'` unless declared; `frame-src`,
|
|
331
|
+
`object-src`, `base-uri`, `form-action` all `'none'`; `webrtc 'block'`. Never `'self'` (P022).
|
|
332
|
+
Empty in url mode.
|
|
333
|
+
- `sandbox`: `allow-scripts` (opaque); `allow-scripts allow-same-origin` (domain, P016);
|
|
334
|
+
`allow-scripts allow-same-origin allow-forms` (url, P020). `allow`: empty (nothing delegated).
|
|
335
|
+
- `embedderFrameSources` (and `embedderCsp(configs)` for a page showing several kinds): `frame-src
|
|
336
|
+
'self'` plus the content origins and the host's own frames, `child-src` the same; no
|
|
337
|
+
`default-src`.
|
|
338
|
+
- `shell` (the plan) and `shellDocument({ origins, title?, document?, cspMeta? })`: the frame's
|
|
339
|
+
document, CSP `<meta>` first, then base styles and the runtime with its plan. A given `document`
|
|
340
|
+
(an MCP Apps view, a served page) travels in the plan as data and is rendered as any document (§
|
|
341
|
+
The shell runtime), never handed to the page's parser.
|
|
342
|
+
- `guide(topics?)` and `toolDescription()`: the manual and the show tool's description.
|
|
343
|
+
|
|
344
|
+
**The agreement test** (`test/agreement.test.ts`) compiles every preset and variations, and asserts:
|
|
345
|
+
the shell injects exactly the config's theme variables and the manual teaches exactly them; the
|
|
346
|
+
manual names exactly the globals the shell defines, and the runtime defines each; the shell wires
|
|
347
|
+
exactly the declared capabilities, and each one's manual entry states its gates (confirm, click,
|
|
348
|
+
rate); the manual names exactly the origins the CSP allows; each CSP directive equals the egress
|
|
349
|
+
plus the declared capabilities' needs; the manual states the limits, layout and theme event; and a
|
|
350
|
+
config change (opening an origin, dropping a capability or variable, overriding an entry) changes
|
|
351
|
+
all of them together. The leak suite's `0.*` probes check the same wiring in real frames.
|
|
180
352
|
|
|
181
353
|
## Public interfaces
|
|
182
354
|
|
|
183
|
-
The seams other work builds against
|
|
184
|
-
functions not built yet throw `NotBuiltYet` naming their milestone.
|
|
185
|
-
|
|
186
|
-
| Seam | File | Built by | Used by |
|
|
187
|
-
| --- | --- | --- | --- |
|
|
188
|
-
| Config, presets, compiler, guide, theme | `src/config/`, `src/presets/`, `src/compile/`, `src/guide/`, `src/theme/` | core (M1, done) | everyone |
|
|
189
|
-
| Host API: `createHost`, `MountOptions`, `DisplayHandle`, `DisplayEvents` | `src/host/types.ts`, `src/host/create-host.ts` | core (M2, built: opaque, domain and url frames) | React binding, hosts |
|
|
190
|
-
| Isolation: `InstanceRef`, `ServedDocument`, `InstanceLocator`, `FrameLocation`, `FrameSource`; `checkFrameLocation` | `src/isolation/types.ts`, `src/isolation/served.ts` | core; served modes (the checks) | served modes, hosts |
|
|
191
|
-
| Platform host: `PlatformHost`, `Surface`, `SurfaceSpec`; `webPlatform` | `src/platform/` | core (web, M2, built) | native hosts later |
|
|
192
|
-
| Transport; `postMessageTransport` | `src/transport/` | core (M2, built) | adapters |
|
|
193
|
-
| Protocol adapter: `ProtocolAdapter`, `AdapterSession`, `AdapterConnection`, `ShellConnection`; `shellAdapter` | `src/protocol/adapter.ts`, `src/protocol/shell-adapter.ts` | core (shell adapter, M2, built) | MCP adapter |
|
|
194
|
-
| MCP Apps names: `MCP_APPS_METHODS`, `MCP_APPS_STYLE_VARIABLES`, `PORTHOLE_STYLES`, `HostContext`; JSON-RPC parsing | `src/protocol/mcp-apps.ts`, `src/protocol/jsonrpc.ts` | core | shell, both adapters |
|
|
195
|
-
| MCP Apps adapter: `mcpAppsAdapter`, `McpAppConnection`, `viewEgress`, `readViewResource`, `MCP_APPS_STYLE_VARIABLES`, `sandboxProxyDocument` | `src/mcp/` | MCP adapter (done) | hosts showing MCP Apps views |
|
|
196
|
-
| Host-function bridge: `HostFunctionBridge`, `CapabilityHandlers`, `Confirm`, `ConfirmRequest`, `Refusal`; `createBridge` | `src/bridge/` | core (M2–M3, built and proven) | adapters, hosts |
|
|
197
|
-
| React: `PortholeProvider`, `PortholeFrame`, `ConfirmDialog`, `admitFrame` | `src/react/` | core (M4, built) | first host |
|
|
198
|
-
| Conformance: `ConformanceHost`, `LaunchSpec`, `LaunchedDisplay`, `defineLeakSuite`, `PROBES`, the oracles; `defineServedSuite`, `ServedConformanceHost` | `src/conformance/` | core (M2, built); served modes (done) | any host |
|
|
199
|
-
| Server: `createServer`, `PortholeServer`, `TicketStore`, `ArtifactStore`, `ContentDomain`, `Grant`, `Access`, `Upstream`, `proxyTo`, `memoryTicketStore` | `src/server/` | served modes (done) | host backends |
|
|
200
|
-
| Files (P081): `checkFileSet`, `filePathProblem`, `fileLimits`, `requestFilePath`, `lookupFile`, `fileTypeOf`, `servesFiles`; `StoredFiles`, `FileAddress`, `versionedAddress`; `lintFiles`, `admitFiles` | `src/files/`, `src/server/files.ts`, `src/check/files.ts` | 0.6 (done) | host backends, publish tools |
|
|
355
|
+
The seams other work builds against, typed in these files.
|
|
201
356
|
|
|
202
|
-
|
|
357
|
+
| Seam | File | Used by |
|
|
358
|
+
| --- | --- | --- |
|
|
359
|
+
| Config, presets, compiler, guide, theme | `src/config/`, `src/presets/`, `src/compile/`, `src/guide/`, `src/theme/` | everyone |
|
|
360
|
+
| Host API: `createHost`, `MountOptions`, `DisplayHandle`, `DisplayEvents` | `src/host/types.ts`, `src/host/create-host.ts` | React binding, hosts |
|
|
361
|
+
| Isolation: `InstanceRef`, `ServedDocument`, `InstanceLocator`, `FrameLocation`, `FrameSource`; `checkFrameLocation` | `src/isolation/types.ts`, `src/isolation/served.ts` | served modes, hosts |
|
|
362
|
+
| Platform host: `PlatformHost`, `Surface`, `SurfaceSpec`; `webPlatform` | `src/platform/` | native hosts later |
|
|
363
|
+
| Transport; `postMessageTransport` | `src/transport/` | adapters |
|
|
364
|
+
| Protocol adapter: `ProtocolAdapter`, `AdapterSession`, `AdapterConnection`, `ShellConnection`; `shellAdapter` | `src/protocol/adapter.ts`, `src/protocol/shell-adapter.ts` | MCP adapter |
|
|
365
|
+
| MCP Apps names: `MCP_APPS_METHODS`, `MCP_APPS_STYLE_VARIABLES`, `PORTHOLE_STYLES`, `HostContext`; JSON-RPC parsing | `src/protocol/mcp-apps.ts`, `src/protocol/jsonrpc.ts` | shell, both adapters |
|
|
366
|
+
| MCP Apps adapter: `mcpAppsAdapter`, `McpAppConnection`, `viewEgress`, `readViewResource`, `MCP_APPS_STYLE_VARIABLES`, `sandboxProxyDocument` | `src/mcp/` | hosts showing MCP Apps views |
|
|
367
|
+
| Host-function bridge: `HostFunctionBridge`, `CapabilityHandlers`, `Confirm`, `ConfirmRequest`, `Refusal`; `createBridge` | `src/bridge/` | adapters, hosts |
|
|
368
|
+
| React: `PortholeProvider`, `PortholeFrame`, `ConfirmDialog`, `admitFrame` | `src/react/` | hosts |
|
|
369
|
+
| Conformance: `ConformanceHost`, `LaunchSpec`, `LaunchedDisplay`, `defineLeakSuite`, `PROBES`, the oracles; `defineServedSuite`, `ServedConformanceHost` | `src/conformance/` | any host |
|
|
370
|
+
| Server: `createServer`, `PortholeServer`, `TicketStore`, `ArtifactStore`, `ContentDomain`, `Grant`, `Access`, `Upstream`, `proxyTo`, `memoryTicketStore` | `src/server/` | host backends |
|
|
371
|
+
| Files (P081): `checkFileSet`, `filePathProblem`, `fileLimits`, `requestFilePath`, `lookupFile`, `fileTypeOf`, `servesFiles`; `StoredFiles`, `FileAddress`, `versionedAddress`; `lintFiles`, `admitFiles` | `src/files/`, `src/server/files.ts`, `src/check/files.ts` | host backends, publish tools |
|
|
203
372
|
|
|
204
|
-
|
|
205
|
-
import { createHost, presets, LIBRARY_CDNS } from "@botiverse/porthole";
|
|
206
|
-
|
|
207
|
-
const host = createHost(
|
|
208
|
-
presets.inlineWidget({
|
|
209
|
-
capabilities: { sendPrompt: {}, openLink: {} }, // default gates
|
|
210
|
-
egress: LIBRARY_CDNS, // opt in to library CDNs
|
|
211
|
-
guide: { toolName: "show_widget", guideToolName: "display_guide" },
|
|
212
|
-
}),
|
|
213
|
-
{
|
|
214
|
-
handlers: { sendPrompt: ({ text }, call) => send(text, call.displayId), openLink: ({ url }) => open(url) },
|
|
215
|
-
confirm: (request) => askThePerson(request), // or the React binding's default dialog
|
|
216
|
-
theme: (scheme) => readMyTokens(scheme), // live values for the config's names
|
|
217
|
-
},
|
|
218
|
-
);
|
|
219
|
-
|
|
220
|
-
const display = host.mount(container, { displayId, title, scheme: "light" });
|
|
221
|
-
display.setContent(code, { partial: true }); // while the agent writes it
|
|
222
|
-
display.setContent(code); // once, whole: now it runs
|
|
223
|
-
display.setTheme("dark");
|
|
224
|
-
display.on("resize", ({ height }) => {});
|
|
225
|
-
display.on("error", ({ message }) => {});
|
|
226
|
-
display.on("outcome", (outcome) => {}); // loaded | blocked (why) | timeout (P040)
|
|
227
|
-
display.refreshTheme(); // the host's values changed without a flip
|
|
228
|
-
display.destroy();
|
|
229
|
-
|
|
230
|
-
host.compiled.guide(["widget", "chart"]); // the manual, from the same config
|
|
231
|
-
host.compiled.toolDescription();
|
|
232
|
-
host.compiled.csp; // the exact CSP, for audit
|
|
233
|
-
embedderCsp([config]); // what the embedding page must send
|
|
234
|
-
```
|
|
373
|
+
### Host API
|
|
235
374
|
|
|
236
|
-
`
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
the
|
|
375
|
+
`createHost(config, options)` takes one config, the host's handlers, `confirm` and theme.
|
|
376
|
+
`host.mount(container, …)` gives a `DisplayHandle`: `setContent` (partial, then whole), `setTheme`,
|
|
377
|
+
`refreshTheme`, events `resize`, `error`, `outcome` (loaded, blocked and why, or timeout: P040),
|
|
378
|
+
`destroy`; the adapter adds its own operations (the MCP adapter, a tool result). `mount` throws if a
|
|
379
|
+
declared handler-served capability has no handler, so the manual never teaches a function nobody
|
|
380
|
+
serves. `host.compiled` holds the manual, the tool description and the exact CSP;
|
|
381
|
+
`embedderCsp([config])` is what the embedding page must send. Wiring: [ADOPTING.md](ADOPTING.md) §
|
|
382
|
+
"3. Opaque displays".
|
|
240
383
|
|
|
241
384
|
### Isolation modes and served content
|
|
242
385
|
|
|
243
|
-
|
|
244
|
-
the
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
- **Storage is keyed by origin.** An `InstanceRef` names its `scope` (the host's
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
`
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
content
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
(
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
DNS and a certificate for every level served, `*.f.<domain>` included) and the
|
|
344
|
-
host's own domain, to the same Worker, or the content domain to a Worker of its own.
|
|
345
|
-
- **Handler.** One server per isolate, made on first use from `env`:
|
|
346
|
-
|
|
347
|
-
```ts
|
|
348
|
-
const porthole = createServer({
|
|
349
|
-
content: { domain: "example-usercontent.com", scheme: "https", name: prefixedName("a-"), reserved: ["f", "www"] },
|
|
350
|
-
secret: new TextEncoder().encode(env.PORTHOLE_SECRET),
|
|
351
|
-
hostOrigins: ["https://app.example.com"],
|
|
352
|
-
configs: { artifact: presets.artifact({ isolation: "domain", contentOrigins: ["https://*.example-usercontent.com"] }) },
|
|
353
|
-
artifacts: { get: (id, version) => env.ARTIFACTS.get(`${id}/${version}`).then((o) => o && o.text()).then((html) => html && { html }) },
|
|
354
|
-
tickets: d1TicketStore(env.DB),
|
|
355
|
-
authorize: { check: ({ subject }) => stillShared(env, subject) }, // the host's policy
|
|
356
|
-
});
|
|
357
|
-
app.all("*", async (c, next) => (await porthole.handle(c.req.raw)) ?? next());
|
|
358
|
-
```
|
|
359
|
-
|
|
360
|
-
and from the host's own authenticated API, once it has decided the person may see
|
|
361
|
-
it, `porthole.issue({ scope: id, document: { kind: "artifact", id, version } },
|
|
362
|
-
{ viewer: userId, subject: shareId })` (a public share route: `{ anonymous: true,
|
|
363
|
-
subject: shareId }`) returns the `FrameLocation` the host page frames. Scopes named
|
|
364
|
-
by `prefixedName` must already be label-safe (lowercase letters, digits, inner
|
|
365
|
-
hyphens); other ids keep the keyed default.
|
|
366
|
-
|
|
367
|
-
A page whose `script-src` is nonce-based (no `'unsafe-inline'`) blocks an opaque
|
|
368
|
-
frame's shell: a `srcdoc` frame inherits the embedding page's whole policy (P054).
|
|
369
|
-
The host passes its nonce (`HostOptions.nonce`, `PortholeProvider`'s `nonce`); the
|
|
370
|
-
shell's script and style carry it, and the shell gives it to every script it runs
|
|
371
|
-
for the content. Inline event handlers in content (`onclick="…"`) stay blocked by
|
|
372
|
-
such a page's policy, as on the page itself; scripts and `addEventListener` work.
|
|
373
|
-
The whole leak suite runs again on a reference page with a nonce-only `script-src`
|
|
374
|
-
(`leak/strict-csp.spec.ts`), and passes on all three engines; its negative control
|
|
375
|
-
`nonce` (the shell without the nonce) fails it.
|
|
376
|
-
|
|
377
|
-
The served modes have their own conformance cases (`defineServedSuite`, run against
|
|
378
|
-
`leak/served/`'s reference serving, which starts its own servers per worker): content
|
|
379
|
-
runs on its own origin and can't reach the host's DOM, storage, cookies or URL,
|
|
380
|
-
navigate the host's page or open a window (domain and url mode, each also after a
|
|
381
|
-
click); storage persists within a scope and is never shared across scopes; a ticket
|
|
382
|
-
opens its content once; only the host origins may frame content; the CSP in headers
|
|
383
|
-
closes egress; each version of an artifact page shows as stored, hardened before it runs; an app shows nothing without its cookie, runs on a tab, and runs
|
|
384
|
-
framed where the engine keeps partitioned cookies; the sandbox proxy becomes a
|
|
385
|
-
hardened view, takes it only from its host, and opens only what the view declares.
|
|
386
|
-
`served.domain.egress` reads the policy that applied to the document (from the
|
|
387
|
-
violations its attempts raise) and holds the host to its config: scripts, styles,
|
|
388
|
-
fetches and frames never reach the canary, and no directive for them opens a scheme;
|
|
389
|
-
images and media are closed unless the config opened them to any https site
|
|
390
|
-
(`anyHttps`, P059), where an image then must reach an https canary, reported as
|
|
391
|
-
expected rather than as a leak (P062; `leak/served/any-https.spec.ts`).
|
|
392
|
-
A served shell draws nothing, and reports no height, until its host sends content,
|
|
393
|
-
so the suite gives `show` a line of content for each shell (`options.content`) and a
|
|
394
|
-
host that speaks to the shell sends it (P057). The shell cases also run against a
|
|
395
|
-
host on `createHost` whose frames take their content's height
|
|
386
|
+
An opaque frame is `srcdoc`: the host builds the shell document. A served frame (domain, external)
|
|
387
|
+
loads a URL: the host's `InstanceLocator` turns an `InstanceRef` into a `FrameLocation`, usually
|
|
388
|
+
through the host's backend, which authenticates the viewer, decides they may see it, and calls
|
|
389
|
+
`PortholeServer.issue`. It loads a `ServedDocument`: the shell (content then arrives over the
|
|
390
|
+
transport), a stored artifact version, the MCP Apps sandbox proxy, or an external app (url mode).
|
|
391
|
+
|
|
392
|
+
- **Storage is keyed by origin.** An `InstanceRef` names its `scope` (the host's choice: a display
|
|
393
|
+
id, an app id); `/server` maps it to `<label>.<content domain>`, the label keyed from the scope
|
|
394
|
+
with the server's secret. Same scope, same origin and storage; different scopes share nothing.
|
|
395
|
+
Browsers partition a framed origin's storage by top-level site, so it is stable within one host
|
|
396
|
+
app.
|
|
397
|
+
- **A served page carries its frame's sandbox** (P099; the row in § Served content). Every page
|
|
398
|
+
`/server` serves (a shell, an artifact page, a set's page, the sandbox proxy; not a url-mode app's
|
|
399
|
+
documents) sends `sandbox allow-scripts allow-same-origin`. In a frame that repeats the attribute;
|
|
400
|
+
on a tab of its own (a public link, a new tab, a frame's address opened outside it) it is the only
|
|
401
|
+
sandbox: no popups, forms, downloads, modals or navigation of another window. Its
|
|
402
|
+
`Permissions-Policy` denies camera, microphone, location, full screen and the rest of
|
|
403
|
+
`FRAME_DENIED_FEATURES`, changing nothing in a frame. On a tab the shell's locks cover engines
|
|
404
|
+
that don't read the header. An engine without the Navigation API has no wall against the page
|
|
405
|
+
navigating itself away on a tab (P099's accepted limit).
|
|
406
|
+
- **A version made of files** (P081–P084; rows in § Served content). The store answers a manifest
|
|
407
|
+
(`files`: path → `{ size, sha256, type? }`, an `entry`, `spa`) and `read(path)`; `{ html }` stays
|
|
408
|
+
one page. A request's path below the version's base is decoded once and looked up
|
|
409
|
+
(`requestFilePath`, `lookupFile`): `dir/` is its `index.html`, `name` is `name.html`, then the
|
|
410
|
+
nearest `404.html`, and a single-page app's navigations get the entry. An unknown type is a
|
|
411
|
+
download (`fileTypeOf`); a page's or script's CSP is the frame's plus the version's path (P082),
|
|
412
|
+
anything else `default-src 'none'; sandbox`; files carry `Cross-Origin-Resource-Policy:
|
|
413
|
+
same-origin`; files are immutable, pages revalidated. In a frame the address is
|
|
414
|
+
`/__porthole/f/<sealed access>/<path>` (the ticket's answer is the entry, whose shell moves there
|
|
415
|
+
first, P083). On a tab it is the version's clean address, `entry.at`'s `base` (`/v/3/`); an
|
|
416
|
+
address meaning the latest (`/`, `/style.css`) is redeemed there (P081). A page never mixes
|
|
417
|
+
versions; a set's pages open each other in the frame (P084).
|
|
418
|
+
- **Tickets.** `issue` mints one: one-time, short-lived, bound to an instance and a viewer, stored
|
|
419
|
+
as its hash, carried once in the frame's URL. The content origin takes it and answers with the
|
|
420
|
+
served document (at `/__porthole/d/<instance key>`) and a cookie of that origin and instance only
|
|
421
|
+
(`__Host-`, `Secure`, `HttpOnly`; `SameSite=None; Partitioned` in a frame, `Lax` on a tab) for
|
|
422
|
+
what follows, a reload. A url-mode app's ticket buys the cookie and redirects to the app's landing
|
|
423
|
+
path; every app request rides the cookie. WebKit keeps no cookie in a cross-site frame (measured),
|
|
424
|
+
so a framed url-mode app runs only where partitioned cookies are kept; elsewhere the host opens it
|
|
425
|
+
on a tab (P025).
|
|
426
|
+
- **Separation is checked.** The content domain is a registrable domain used for nothing else; a
|
|
427
|
+
mount refuses a located origin not in `contentOrigins` or same-site with the host.
|
|
428
|
+
- **Names** (P047). A label is keyed by default (24 base32 characters). A host may name its own
|
|
429
|
+
(`content.name`; `prefixedName("a-")` gives `a-<scope>`, one-to-one): one lowercase DNS label,
|
|
430
|
+
never an IDNA form or a `reserved` one. `reserved` labels are other servers' namespaces under the
|
|
431
|
+
domain (`f` for `<label>.f.<domain>`) or the host's own (`p-*`: every label starting `p-`; or a
|
|
432
|
+
function of the label, P056): they and anything under them return null, to the host's routes. Any
|
|
433
|
+
other deeper name gets this server's 404.
|
|
434
|
+
- **Requests** (P056). The label is the request URL's. A Host header naming another host, where
|
|
435
|
+
either is under the content domain, gets a 400 (a Node adapter builds the URL from an
|
|
436
|
+
absolute-form target; hosts and caches route by Host). A local Host (an IP literal, `localhost`),
|
|
437
|
+
as test runners send, isn't compared. Without an `upstream` only Porthole's own paths are served;
|
|
438
|
+
others are a plain 404. Every answer says `x-robots-tag: noindex`.
|
|
439
|
+
- **Who** (P046, P050). A grant names a `viewer`, or is `anonymous` (a public link: documents only,
|
|
440
|
+
never a url-mode app), and may carry the host's opaque `subject` (a share or session id), signed
|
|
441
|
+
into ticket and cookie. `authorize.check` runs after a ticket or cookie verifies, before anything
|
|
442
|
+
is served: document loads, url-mode entry, every app request, `/__porthole/session`, `access()`. A
|
|
443
|
+
deny is a 403 status page (`denied`, the host's code). Answers are reused only if the host sets
|
|
444
|
+
`ttlSeconds` (at most 300).
|
|
445
|
+
- **Runtimes** (P044, P045). `/server` uses no Node module (hashing in plain JavaScript,
|
|
446
|
+
`crypto.getRandomValues`), so it runs on Cloudflare Workers without `nodejs_compat`. Tickets there
|
|
447
|
+
live in D1 (`d1TicketStore`, taken by one `DELETE … RETURNING`), never KV (eventually consistent).
|
|
448
|
+
Sessions are signed cookies: no store. Steps: [ADOPTING.md](ADOPTING.md) § "5. Cloudflare
|
|
449
|
+
Workers"; `test/workers/` runs such a Worker in workerd with real D1. The routes need wildcard DNS
|
|
450
|
+
and a certificate for every level served (`*.f.<domain>` included). Scopes named by `prefixedName`
|
|
451
|
+
must already be label-safe (lowercase letters, digits, inner hyphens); other ids keep the keyed
|
|
452
|
+
default.
|
|
453
|
+
|
|
454
|
+
`/server`'s handler is fetch-style (`Request → Response | null`; null for requests not for the
|
|
455
|
+
content domain or in a reserved namespace), mounted in front of the backend's routes. Dev and tests
|
|
456
|
+
use `*.localhost` subdomains (browsers resolve them to loopback). In url mode, once the cookie
|
|
457
|
+
checks out, an app's requests go to the host's `upstream` (`proxyTo` relays by HTTP, telling the app
|
|
458
|
+
it is on its own origin and nothing of the proxy); WebSockets take the host's own upgrade path, let
|
|
459
|
+
in by `PortholeServer.access`. The MCP Apps sandbox proxy is served the same way, its CSP from the
|
|
460
|
+
config plus the view's declared egress, signed into the ticket; it becomes the view rather than
|
|
461
|
+
nesting it (P026).
|
|
462
|
+
|
|
463
|
+
**A strict host page** (P054). A nonce-based `script-src` (no `'unsafe-inline'`) blocks an opaque
|
|
464
|
+
frame's shell, since a `srcdoc` frame inherits the page's whole policy. The host passes its nonce
|
|
465
|
+
(`HostOptions.nonce`, `PortholeProvider`'s `nonce`); the shell's script and style carry it, and the
|
|
466
|
+
shell gives it to every script it runs for the content. Content's inline handlers (`onclick="…"`)
|
|
467
|
+
stay blocked, as on the page; scripts and `addEventListener` work. The whole leak suite runs again
|
|
468
|
+
on a reference page with a nonce-only `script-src` (`leak/strict-csp.spec.ts`) and passes on all
|
|
469
|
+
three engines; its negative control `nonce` (the shell without the nonce) fails it.
|
|
470
|
+
|
|
471
|
+
**Served conformance** (`defineServedSuite`, against `leak/served/`'s reference serving, which
|
|
472
|
+
starts its own servers per worker). Content runs on its own origin and can't reach the host's DOM,
|
|
473
|
+
storage, cookies or URL, navigate the host's page or open a window (domain and url mode, each also
|
|
474
|
+
after a click). Storage persists within a scope, never across. A ticket opens its content once. Only
|
|
475
|
+
host origins may frame content. The CSP in headers closes egress. Each artifact version shows as
|
|
476
|
+
stored, hardened before it runs. An app shows nothing without its cookie, runs on a tab, and runs
|
|
477
|
+
framed where partitioned cookies are kept. The sandbox proxy becomes a hardened view, takes it only
|
|
478
|
+
from its host, and opens only what the view declares. `served.domain.egress` reads the policy that
|
|
479
|
+
applied (from the violations its attempts raise) and holds the host to its config: scripts, styles,
|
|
480
|
+
fetches and frames never reach the canary, and no directive for them opens a scheme; images and
|
|
481
|
+
media stay closed unless opened to any https site (`anyHttps`, P059), where an image must then reach
|
|
482
|
+
an https canary, reported as expected, not a leak (P062; `leak/served/any-https.spec.ts`). A served
|
|
483
|
+
shell draws nothing and reports no height until content arrives, so the suite gives `show` a line of
|
|
484
|
+
content per shell (`options.content`) and a host that speaks to the shell sends it (P057). The shell
|
|
485
|
+
cases also run against a `createHost` host whose frames take their content's height
|
|
396
486
|
(`leak/served/core-host.spec.ts`), as a React host's do.
|
|
397
487
|
|
|
398
|
-
### The host kit
|
|
399
|
-
|
|
400
|
-
Two hosts each wrote the same ~2,000 lines around `/server`. The host kit makes that machinery
|
|
401
|
-
Porthole's, so an app writes its policy and its settings. The policy is four callbacks (five
|
|
402
|
-
with redirect entry):
|
|
403
|
-
- `instance`: the instance an issue request proposes, as the app means it;
|
|
404
|
-
- `access`: may this viewer see it, and with what grant;
|
|
405
|
-
- `authorize`: may this cookie still see it, on each request (P050);
|
|
406
|
-
- `source`: a stored version by id and version: one page (`{ html }`), or a set of files (P081);
|
|
407
|
-
- `entry.at`: the instance a clean address's path names (redirect entry), or, for a set of files,
|
|
408
|
-
the instance with its version's own address (`{ instance, base, file }`, P081).
|
|
488
|
+
### The host kit
|
|
409
489
|
|
|
410
|
-
|
|
411
|
-
|
|
490
|
+
The machinery around `/server` each app would otherwise write (P066, P068, P072). The app supplies
|
|
491
|
+
settings and callbacks: `instance` (the instance an issue request proposes, as the app means it),
|
|
492
|
+
`access` (may this viewer see it, with what grant), `authorize` (may this cookie still see it, per
|
|
493
|
+
request, P050), `source` (a stored version by id and version: one page `{ html }` or a set of files,
|
|
494
|
+
P081), and for redirect entry `entry.at` (the instance a clean address's path names; for a set of
|
|
495
|
+
files, with its version's address, `{ instance, base, file }`, P081). Wiring and options:
|
|
496
|
+
[ADOPTING.md](ADOPTING.md) § "The server" and `examples/app.mjs` (Node and Workers).
|
|
412
497
|
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
domain: env.CONTENT_DOMAIN, // "content.example.com" | "content.localhost:8790"; "" = off
|
|
416
|
-
appOrigins: [env.APP_ORIGIN], // frame-ancestors, and the clash guard
|
|
417
|
-
secret: env.PORTHOLE_SECRET, tickets: d1TicketStore(env.DB), // npx porthole secret
|
|
418
|
-
// Keyed by the preset a stored page names: an artifact's is "artifact" unless it says otherwise.
|
|
419
|
-
configs: (source) => ({ artifact: presets.artifact({ isolation: "domain", contentOrigins: [source] }) }),
|
|
420
|
-
name: prefixedName("a-"), reserved: ["p-*"], // only labels the app itself serves there
|
|
421
|
-
instance: (proposal, viewer) => mapToMyInstance(proposal), // a proposal: validate, derive the scope
|
|
422
|
-
access: async (instance, viewer) =>
|
|
423
|
-
viewer !== null && (await canSee(viewer, instance)) ? { viewer: viewer.id, subject: viewer.id } : null,
|
|
424
|
-
authorize: ({ subject }) => (revoked(subject) ? { allow: false, code: "revoked" } : { allow: true }),
|
|
425
|
-
source: (id, version) => store.page(id, version), // { html } | { files, read } | null
|
|
426
|
-
entry: {
|
|
427
|
-
authorizeUrl: `${env.APP_ORIGIN}/porthole/authorize`,
|
|
428
|
-
at: (scope, path) => pageAt(scope, path), // "/" → latest, "/v/3" → version 3
|
|
429
|
-
// Absolute: outside a browser, Response.redirect has no base URL.
|
|
430
|
-
signIn: (returnTo) => Response.redirect(`${env.APP_ORIGIN}/login?next=${encodeURIComponent(returnTo)}`, 303),
|
|
431
|
-
},
|
|
432
|
-
health: { probe: nodeProbe(), onChange: (view) => pushToClients(view) }, // optional: the opaque fallback
|
|
433
|
-
});
|
|
434
|
-
// Hono / Workers: content first, then the app's own routes.
|
|
435
|
-
app.use("*", async (c, next) => (await content.fetch(c.req.raw)) ?? next());
|
|
436
|
-
app.post("/api/frames", (c) => content.issue(viewerOf)(c.req.raw));
|
|
437
|
-
app.get("/porthole/authorize", (c) => content.authorize(viewerOf)(c.req.raw));
|
|
438
|
-
// The page: frame-src from content.frameSources; meta from content.meta(); "open in a new tab"
|
|
439
|
-
// and "copy link" from content.urlOf(scope, path).
|
|
440
|
-
```
|
|
441
|
-
|
|
442
|
-
**Server: `createContentHost(options)` (`@botiverse/porthole/server`, runtime-agnostic: Node,
|
|
443
|
-
Workers, Deno, Bun).** It gives:
|
|
444
|
-
- **`fetch(request)`, the routing middleware.** Every host under the content domain is
|
|
445
|
-
Porthole's, so the app never answers there. Reserved labels and the app's own hosts return
|
|
446
|
-
null, for the app's routes. `reserved` is only for labels the app itself serves on the content
|
|
447
|
-
domain (Ferry's `p-*` previews); a label nothing serves needs no entry. A label the naming
|
|
448
|
-
never makes, the bare domain, and a clean address `entry.at` says names nothing all get
|
|
449
|
-
Porthole's 404 there, never a trip to the app (P070). Settings that can't be served answer a
|
|
450
|
-
plain 503, never the app's. `owns(request)` says the same for a WebSocket upgrade.
|
|
451
|
-
- **`issue(viewerOf)`, the issue endpoint** (a fetch handler). The body is always `{ instance }`
|
|
452
|
-
(an `InstanceRef`, the wire shape). The app's `instance` callback treats it as a proposal: it
|
|
453
|
-
validates it, derives the scope from what it names (a session, a page), and refuses anything
|
|
454
|
-
else (404). App ids travel in the document's fields. **The client never chooses an origin**:
|
|
455
|
-
the scope the server maps to does. Then `access` (401 without a viewer, 403 refused), a ticket,
|
|
456
|
-
and `201 FrameLocation`. `503 not-served` while content isn't served; `409` when `/server`
|
|
457
|
-
refuses the instance; an optional per-viewer rate limit (429), an anonymous viewer keyed by an
|
|
458
|
-
address the host trusts (the socket's peer, `CF-Connecting-IP` on Workers, or behind
|
|
459
|
-
`trustedProxies` the `X-Forwarded-For` entry they appended; never what a client says, P092).
|
|
460
|
-
The body is read to at most
|
|
461
|
-
`ISSUE_BODY_BYTES` (64 KiB), counted as it arrives: past it the read stops and the answer is
|
|
462
|
-
`413 too-large`; a Content-Length over it is refused before the viewer is asked (P092).
|
|
463
|
-
- **`authorize(viewerOf)` and `urlOf(scope, path)`: redirect entry** (below).
|
|
464
|
-
- **`meta()`** `{ served, contentSource, health }` for the app's page; **`frameSources`** for
|
|
465
|
-
its CSP (`frame-src`), the authorize route's path included.
|
|
466
|
-
- **Domain helpers.** `contentDomain(input, { appOrigins })` parses (the scheme from loopback or
|
|
467
|
-
`*.localhost`, the port) and gives `originOf(label)`, `source`, `isContentHost(host)`,
|
|
468
|
-
`labelOf(host)`; `ContentDomainError` names the rule (`invalid`, `clash`, `same-site`).
|
|
469
|
-
- **Clashes.** Porthole never serves a content domain that holds an app origin or may share its
|
|
470
|
-
site. With the health gate (the opaque fallback) on, such settings are a lasting "unhealthy:
|
|
471
|
-
misconfigured, <reason>": logged once (`porthole.content.misconfigured`, with its `code`),
|
|
472
|
-
`meta().served` false, frames run opaque. Without it, `createContentHost` throws the typed
|
|
473
|
-
error at startup. Fail closed either way; there is no separate switch.
|
|
474
|
-
- **The health gate (optional).** Porthole answers a who-am-I on its health label
|
|
475
|
-
(`/__porthole/health`, a keyed id, so another deployment's answer doesn't count). The kit
|
|
476
|
-
probes it over the real network (DNS, the edge, TLS): every 60 s while unhealthy, every 10 min
|
|
477
|
-
while healthy, 10 s timeout. While unhealthy, `issue` answers `503 not-served` and the page's
|
|
478
|
-
`servedOrOpaque` picks opaque configs. `health.onChange(view)` is told each change of state
|
|
479
|
-
(P070), for an app that pushes "frames served" to its clients. On Workers the probe is optional (a host that doesn't
|
|
480
|
-
enable it serves from startup).
|
|
481
|
-
|
|
482
|
-
**Redirect entry (P068).** Every instance has a clean, stable address
|
|
483
|
-
(`https://a-<id>.content.example.com/v/3`) that opens directly: a new tab, a reload, a bookmark,
|
|
484
|
-
a link sent to someone with access.
|
|
485
|
-
1. A request on a clean address that names nothing gets Porthole's 404 on the content origin:
|
|
486
|
-
the naming never made its label, or `entry.at(scope, path)`, asked with no viewer, says
|
|
487
|
-
nothing (null or undefined) is there (P070).
|
|
488
|
-
A request on a clean address without a cookie for it gets a 302 to the app's authorize route
|
|
489
|
-
with a signed state (label, path, nonce, five minutes), and a cookie holding the nonce on the
|
|
490
|
-
content origin (partitioned in a frame, `Lax` on a tab, like the session cookie).
|
|
491
|
-
2. `authorize` asks `entry.at(scope, path)` and `access`. No viewer: the app's own sign-in
|
|
492
|
-
(`signIn(returnTo, request, entry)`), which comes back to the same route. No access: the app's
|
|
493
|
-
refusal (`refusal(status, request, entry)`; nothing returned: Porthole's page); never content.
|
|
494
|
-
**Redirect entry is for a tab alone (P125):** a clean address asked from a frame
|
|
495
|
-
(`Sec-Fetch-Dest: iframe`/`frame`), and the authorize route asked from one, answer Porthole's
|
|
496
|
-
"open this in a new tab" page (the status pages' policy, no script), never a trip to the app. Both hooks get the address decoded
|
|
497
|
-
(`EntryContext`: label, scope, path, clean URL, the instance, framed). `returnTo` (and
|
|
498
|
-
`entry.spa`'s `next`) is `authorizeUrl` with the request's query: the app as it is reached,
|
|
499
|
-
never the request's own URL, whose scheme and host behind a TLS edge or a dev proxy are
|
|
500
|
-
another's (P074).
|
|
501
|
-
3. Granted, a 302 back to `/__porthole/entry?code=…`: a one-time code (60 s), bound to the
|
|
502
|
-
label, the path and the nonce. The content origin redeems it only on that label and only with
|
|
503
|
-
the nonce's cookie, sets the session (bound to the path) and 303s to the clean address. The
|
|
504
|
-
code is in an address for that one hop (gone from history), every redirect sends
|
|
505
|
-
`no-referrer`, and Porthole never logs it.
|
|
506
|
-
4. A path whose session didn't come back is caught on the second bounce (`blocked: cookies`, the
|
|
507
|
-
loop guard): on a tab only, since a frame never enters (P125).
|
|
508
|
-
|
|
509
|
-
Frames use tickets (`issue` → `FrameLocation`, with its door): no extra round trip, and no
|
|
510
|
-
dependence on the app's own cookie reaching its authorize route inside a frame. To frame what a
|
|
511
|
-
clean address names, the host resolves it through `issue` first (`{ address }`, `client.resolve`,
|
|
512
|
-
`<PortholeView address>`, P125); a refusal there is the outcome, with no frame. (Why frames never
|
|
513
|
-
entered, measured before P125: Firefox and WebKit don't send a `Lax` app cookie on a frame
|
|
514
|
-
navigation that came through a cross-site redirect; Chromium does.) Use clean addresses for tabs, links, bookmarks and reloads: a host's "open in a new tab"
|
|
515
|
-
and "copy link" use `urlOf`, never a ticket. The first open of an instance per browser costs one
|
|
516
|
-
extra round trip through the app.
|
|
517
|
-
|
|
518
|
-
**Node: `@botiverse/porthole/node`.** `nodeHost(content, { request, upgrade, appSocket })`
|
|
519
|
-
returns a request listener and an upgrade listener for `http.createServer`: content hosts to
|
|
520
|
-
`content.fetch`, WebSockets on reserved labels to the app's upgrade, a url-mode app's socket to
|
|
521
|
-
`appSocket(access, …)` once its cookie checks out, any other socket on the content domain a 404.
|
|
522
|
-
`toRequest`/`sendResponse` convert (P070): the request carries a signal aborted when the client
|
|
523
|
-
goes away (`proxyTo` passes it on, so a proxied event stream ends with its page); the body is
|
|
524
|
-
written as the socket drains and cancelled when the client leaves; an error mid-body destroys
|
|
525
|
-
the response rather than end it looking whole. Nothing a request does throws out of the
|
|
526
|
-
listeners or ends the process (P092): a request fetch can't take is 405 (`CONNECT`, `TRACE`,
|
|
527
|
-
`TRACK`) or 400 (a Host or a target that is no URL); a handler or an app listener that throws or
|
|
528
|
-
rejects, or an answer Node can't write, is 500, and `onError` hears it (by default a process
|
|
529
|
-
warning); an upgrade's socket closes on its own errors. A HEAD gets the head, its body cancelled;
|
|
530
|
-
a client gone before the answer cancels it too. The request body is read only as it is pulled
|
|
531
|
-
(a reserved label's request reaches the app whole); once the answer is out, what no one read is
|
|
532
|
-
dropped (at most 1 MiB and 5 s) before the connection closes, so a client still sending reads
|
|
533
|
-
its answer. `nodeListener(app, { scheme, onError })` is a fetch-style app's listener with the
|
|
534
|
-
same guarantees (it is `nodeServer`'s `app`). `nodeProbe()` is the health probe (`*.localhost`
|
|
535
|
-
resolved to loopback, no redirects, 4 KB read). `/server` stays free of Node.
|
|
536
|
-
|
|
537
|
-
**Client** (core). `httpLocator(url, { headers, credentials, onNotServed })` POSTs
|
|
538
|
-
`{ instance }`, passes the abort signal, refuses redirects, and throws a `LocateError` with the
|
|
539
|
-
endpoint's status and code. `servedOrOpaque(meta, servedConfigs, opaqueConfigs)` gives
|
|
540
|
-
`{ served, configs }`, or null until meta is known, so a frame never starts opaque and then
|
|
541
|
-
restarts served. A redirect entry's pages on the app origin report the frame's status too
|
|
542
|
-
(`blocked: sign-in`), and the frame transport hears that from the host's own origin only for
|
|
543
|
-
frame status.
|
|
544
|
-
|
|
545
|
-
**Conformance runner (`@botiverse/porthole/conformance`).** `defineHostConformance(test,
|
|
546
|
-
{ name, open, issue, config, instances, entry?, nonce?, skip? })` registers the leak suite, the
|
|
547
|
-
served cases and the redirect entry cases against the app's real page:
|
|
548
|
-
- `open(page)` opens it as a person sees it (signed in, its real CSP);
|
|
549
|
-
- the harness is framework-free, on the core's `createHost` (no React: an app's own frame
|
|
550
|
-
components are its own e2e's; Porthole's React binding is Porthole's own tests'). It loads as a
|
|
551
|
-
script from the page's own origin (routed by the test), with the page's nonce, so a strict CSP
|
|
552
|
-
needs nothing added;
|
|
553
|
-
- served frames are located by the app's issue endpoint from the page, with its cookies;
|
|
554
|
-
- the canaries and a foreign origin are routed; cases for instances the app doesn't give
|
|
555
|
-
(versions, url mode, the MCP Apps proxy) are skipped with the reason.
|
|
556
|
-
|
|
557
|
-
The tests are located in the app's own spec file, at the `defineHostConformance` call, so
|
|
558
|
-
`playwright test <spec>` and `<spec>:<line>` select them (P070). `instances` and the entry
|
|
559
|
-
addresses may be async (an app publishes a test page on demand and returns its real instance,
|
|
560
|
-
which the issue endpoint then gets); `entry.unknown` lists addresses that name nothing, each of
|
|
561
|
-
which must be a 404 on the content domain. `hostConformance(options)` gives the hosts for an app
|
|
562
|
-
that registers the cases itself. Playwright's list and line reporters show a skipped case without
|
|
563
|
-
its reason; `@botiverse/porthole/conformance/reporter` prints each reason after the run (P074).
|
|
564
|
-
`contentSource` may be a function, asked per case (a port known only once the server runs), and
|
|
565
|
-
`conformanceProjects` merges an app's own `use` and per-engine `launchOptions` (a system
|
|
566
|
-
browser) with Porthole's (P074).
|
|
567
|
-
|
|
568
|
-
**Prod shape** (`ops/prod-shape/`, `ops/prod-shape/run.sh`). Docker compose: Caddy's internal
|
|
569
|
-
CA serving `app.test`, `*.content.test` (same-site siblings, as in production without a Public
|
|
570
|
-
Suffix List entry), `clash.test` and `evil.test`; wildcard DNS (CoreDNS); the kit reference app
|
|
571
|
-
behind the edge, its health probe over the real TLS; a misconfigured twin that must run opaque,
|
|
572
|
-
and a strict one that must not start; a Playwright image trusting the CA (Chromium's NSS store,
|
|
573
|
-
the system store for WebKit; Playwright's Firefox reads neither, so its project overrides
|
|
574
|
-
certificate errors). The suite (`packages/porthole/prod-shape`) runs the whole runner over https,
|
|
575
|
-
then the sibling cases: Porthole's cookies host-only and `__Host-`; a sibling label (an app's
|
|
576
|
-
preview) can't plant a cookie that opens content, or frame it; another site can't frame it; the
|
|
577
|
-
clash. CI (`.github/workflows/ci.yml`) runs the checks, the examples and the loopback suites on
|
|
578
|
-
Chromium on every push, and the loopback suites on each engine, the negative controls and the
|
|
579
|
-
prod-shape profile when started by hand, which a release requires on its commit (P146).
|
|
580
|
-
|
|
581
|
-
**Compatibility.** Every 0.1.x export stays as it was; the kit wraps `createServer`. The npm
|
|
582
|
-
package carries these docs (`docs/`), and `/server` exports the types an app's callbacks take
|
|
583
|
-
(`InstanceRef`, `FrameLocation`, `ServedDocument`, `PortholeConfig`, `EntryContext`). Nothing was
|
|
584
|
-
renamed, so there is no compat module. `FrameBlock` gains `sign-in`; `ContentDomain.name` takes
|
|
585
|
-
a `Naming` (any function still fits).
|
|
586
|
-
|
|
587
|
-
### The host kit 0.3: the client, the bootstrap, the relay (P072)
|
|
588
|
-
|
|
589
|
-
What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the walk-through):
|
|
590
|
-
- **`defineDisplays(kinds)`** (core): each kind's preset and options once; opaque and served
|
|
591
|
-
configs (memoized per content source), the kind an instance names, frame sources and the
|
|
498
|
+
- **`defineDisplays(kinds)`** (core): each kind's preset and options, once. It gives opaque and
|
|
499
|
+
served configs (memoized per content source), the kind an instance names, frame sources and the
|
|
592
500
|
`frame-src` directive without a server, and a served kind's config for the manual without a real
|
|
593
501
|
origin. `createContentHost({ displays })` and the conformance runner take it.
|
|
594
|
-
- **`
|
|
595
|
-
(`
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
`
|
|
600
|
-
`
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
`
|
|
623
|
-
|
|
624
|
-
- **
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
The
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
(
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
502
|
+
- **`createContentHost(options)`** (`@botiverse/porthole/server`; Node, Workers, Deno, Bun).
|
|
503
|
+
`fetch(request)` routes: every host under the content domain is Porthole's; reserved labels (only
|
|
504
|
+
those the app serves there, like Ferry's `p-*` previews) and the app's own hosts return null, to
|
|
505
|
+
the app's routes; a label the naming never makes, the bare domain, and a clean address `entry.at`
|
|
506
|
+
says names nothing get Porthole's 404, never the app (P070); unservable settings get a plain 503.
|
|
507
|
+
`owns(request)` says the same for a WebSocket upgrade. `routes(viewerOf)` is one mount under
|
|
508
|
+
`/porthole` (`prefix`): `POST frames` (`issue`, answering `link`, the clean address `entry.pathOf`
|
|
509
|
+
names, possibly a promise, P074), `GET authorize` (its URL the default `entry.authorizeUrl`), `GET
|
|
510
|
+
meta` (`ContentClientMeta`: served, content source, frame sources, health), `POST`/`DELETE
|
|
511
|
+
handoff`. Also: `authorize(viewerOf)` and `urlOf(scope, path)` (redirect entry), `meta()` (`{
|
|
512
|
+
served, contentSource, health }`), `frameSources` (for the app's `frame-src`, the authorize
|
|
513
|
+
route's path included). `contentHostFor(build)` gives one host per Workers `env`, failing closed
|
|
514
|
+
with a plain 503. A missing or short secret throws, naming `PORTHOLE_SECRET`.
|
|
515
|
+
- **The issue endpoint** (`issue(viewerOf)`). The body is always `{ instance }` (an `InstanceRef`),
|
|
516
|
+
a proposal: the `instance` callback validates it, derives the scope from what it names (a session,
|
|
517
|
+
a page), and refuses anything else (404); app ids travel in the document's fields. **The client
|
|
518
|
+
never chooses an origin.** Then `access` (401 without a viewer, 403 refused), a ticket, `201
|
|
519
|
+
FrameLocation`. `503 not-served` while content isn't served; `409` when `/server` refuses the
|
|
520
|
+
instance. An optional per-viewer rate limit (429) keys an anonymous viewer by an address the host
|
|
521
|
+
trusts (the socket's peer, `CF-Connecting-IP` on Workers, or behind `trustedProxies` the
|
|
522
|
+
`X-Forwarded-For` entry they appended; never a client's word, P092). The body is read to at most
|
|
523
|
+
`ISSUE_BODY_BYTES` (64 KiB), counted as it arrives (past it, `413 too-large`); a Content-Length
|
|
524
|
+
over it is refused before the viewer is asked (P092).
|
|
525
|
+
- **Domains and clashes.** `contentDomain(input, { appOrigins })` parses (scheme from loopback or
|
|
526
|
+
`*.localhost`, port) into `originOf(label)`, `source`, `isContentHost(host)`, `labelOf(host)`;
|
|
527
|
+
`ContentDomainError` names the rule (`invalid`, `clash`, `same-site`). Porthole never serves a
|
|
528
|
+
content domain that holds an app origin or may share its site. With the health gate on, that is a
|
|
529
|
+
lasting "unhealthy: misconfigured, <reason>": logged once (`porthole.content.misconfigured`, with
|
|
530
|
+
its `code`), `meta().served` false, frames opaque. Without it, `createContentHost` throws the
|
|
531
|
+
typed error at startup. Fail closed either way; no separate switch.
|
|
532
|
+
- **The health gate** (optional; the opaque fallback). Porthole answers a who-am-I on its health
|
|
533
|
+
label (`/__porthole/health`, a keyed id, so another deployment's answer doesn't count). The kit
|
|
534
|
+
probes it over the real network (DNS, edge, TLS): every 60 s while unhealthy, every 10 min while
|
|
535
|
+
healthy, 10 s timeout. While unhealthy, `issue` answers `503 not-served` and the page's
|
|
536
|
+
`servedOrOpaque` picks opaque configs. `health.onChange(view)` hears each state change (P070),
|
|
537
|
+
`health.onServedChange(served)` each flip. On Workers the probe is optional (without it, the host
|
|
538
|
+
serves from startup). `log` takes a `{ info, warn, error }` logger.
|
|
539
|
+
- **Handoff and relay.** The viewer handoff, for a page holding a token: `POST /porthole/handoff`
|
|
540
|
+
with the app's credential sets a 10-minute `HttpOnly` cookie scoped to the prefix, holding a
|
|
541
|
+
Porthole-signed key (viewer id, expiry) that the authorize route reads when `viewerOf` knows no
|
|
542
|
+
one; `entry.spa` signs a person in through the app's own route (ADOPTING.md § Sign-in). The
|
|
543
|
+
url-mode relay kit: `upstreamHeaders` (`proxyTo`'s header rewrite, for any transport, WebSockets
|
|
544
|
+
too), `statusPage` (the frame-status page, its script under its hash), `nodeHost`'s `appSocket`
|
|
545
|
+
without Porthole's cookies; `content.forget()` drops cached `authorize` answers.
|
|
546
|
+
|
|
547
|
+
**Redirect entry (P068).** Every instance has a clean, stable address
|
|
548
|
+
(`https://a-<id>.content.example.com/v/3`) for a new tab, a reload, a bookmark, a link sent to
|
|
549
|
+
someone with access.
|
|
550
|
+
1. One that names nothing gets Porthole's 404 on the content origin (the naming never made its
|
|
551
|
+
label, or `entry.at(scope, path)`, asked with no viewer, answers null or undefined, P070). One
|
|
552
|
+
without its cookie gets a 302 to the app's authorize route with a signed state (label, path,
|
|
553
|
+
nonce, five minutes) and a nonce cookie on the content origin (partitioned in a frame, `Lax` on a
|
|
554
|
+
tab, like the session cookie).
|
|
555
|
+
2. `authorize` asks `entry.at(scope, path)` and `access`. No viewer: the app's sign-in
|
|
556
|
+
(`signIn(returnTo, request, entry)`), which returns to this route. No access: the app's refusal
|
|
557
|
+
(`refusal(status, request, entry)`; nothing returned, Porthole's page); never content. Both get
|
|
558
|
+
the decoded address (`EntryContext`: label, scope, path, clean URL, instance, framed). `returnTo`
|
|
559
|
+
(and `entry.spa`'s `next`) is `authorizeUrl` plus the request's query, never the request's own
|
|
560
|
+
URL, whose scheme and host behind a TLS edge or dev proxy are another's (P074).
|
|
561
|
+
3. Granted: a 302 to `/__porthole/entry?code=…`, a one-time code (60 s) bound to label, path and
|
|
562
|
+
nonce. The content origin redeems it only on that label with the nonce's cookie, sets the session
|
|
563
|
+
(bound to the path) and 303s to the clean address. The code is in an address for one hop (gone
|
|
564
|
+
from history), every redirect sends `no-referrer`, and Porthole never logs it.
|
|
565
|
+
4. A session that didn't come back is caught on the second bounce (`blocked: cookies`, the loop
|
|
566
|
+
guard), on a tab only.
|
|
567
|
+
|
|
568
|
+
**Redirect entry is for a tab alone (P125).** A clean address or the authorize route asked from a
|
|
569
|
+
frame (`Sec-Fetch-Dest: iframe`/`frame`) answers Porthole's "open this in a new tab" page (the
|
|
570
|
+
status pages' policy, no script). Frames use tickets (`issue` → `FrameLocation`, with its door): no
|
|
571
|
+
extra round trip, and no reliance on the app's cookie reaching its authorize route in a frame
|
|
572
|
+
(Firefox and WebKit don't send a `Lax` app cookie on a frame navigation through a cross-site
|
|
573
|
+
redirect; Chromium does, measured). To frame what a clean address names, the host resolves it
|
|
574
|
+
through `issue` (`{ address }`, `client.resolve`, `<PortholeView address>`); a refusal there is the
|
|
575
|
+
outcome, with no frame. "Open in a new tab" and "copy link" use `urlOf`, never a ticket. The first
|
|
576
|
+
open of an instance per browser costs one extra round trip through the app.
|
|
577
|
+
|
|
578
|
+
**Node (`@botiverse/porthole/node`; `/server` stays free of Node).** `nodeServer({ content, app })`
|
|
579
|
+
is the whole server; `content` may be a function giving the host once made (P074), asked after the
|
|
580
|
+
`listen` callbacks and per request until it gives one; `start` is idempotent (P076).
|
|
581
|
+
`nodeHost(content, { request, upgrade, appSocket })` gives request and upgrade listeners for
|
|
582
|
+
`http.createServer`: content hosts → `content.fetch`; WebSockets on reserved labels → the app's
|
|
583
|
+
upgrade; a url-mode app's socket → `appSocket(access, …)` once its cookie checks out; other
|
|
584
|
+
content-domain sockets → 404. `nodeListener(app, { scheme, onError })` wraps a fetch-style app (it
|
|
585
|
+
is `nodeServer`'s `app`). `nodeProbe()` is the health probe (`*.localhost` to loopback, no
|
|
586
|
+
redirects, 4 KB read). Their guarantees:
|
|
587
|
+
- `toRequest`/`sendResponse` convert (P070). The request's signal aborts when the client leaves
|
|
588
|
+
(`proxyTo` passes it on, so a proxied event stream ends with its page). The body is written as the
|
|
589
|
+
socket drains and cancelled when the client leaves; an error mid-body destroys the response rather
|
|
590
|
+
than ending it looking whole.
|
|
591
|
+
- Nothing a request does throws out of the listeners or ends the process (P092): 405 for what fetch
|
|
592
|
+
can't take (`CONNECT`, `TRACE`, `TRACK`); 400 for a Host or target that is no URL; 500 for a
|
|
593
|
+
throwing or rejecting handler or listener, or an unwritable answer, which `onError` hears
|
|
594
|
+
(default: a process warning). An upgrade's socket closes on its own errors. A HEAD gets the head,
|
|
595
|
+
its body cancelled; a client gone before the answer cancels it.
|
|
596
|
+
- The request body is read only as pulled (a reserved label's request reaches the app whole). After
|
|
597
|
+
the answer, unread input is dropped (at most 1 MiB and 5 s) before the connection closes, so a
|
|
598
|
+
client still sending reads its answer.
|
|
599
|
+
|
|
600
|
+
**Client** (core). `httpLocator(url, { headers, credentials, onNotServed })` POSTs `{ instance }`,
|
|
601
|
+
passes the abort signal, refuses redirects, and throws a `LocateError` with the endpoint's status
|
|
602
|
+
and code. `servedOrOpaque(meta, servedConfigs, opaqueConfigs)` gives `{ served, configs }`, or null
|
|
603
|
+
until meta is known, so a frame never starts opaque then restarts served. `portholeClient({
|
|
604
|
+
displays, base, headers, credentials, handoff })` is the locator plus each kind's config from the
|
|
605
|
+
meta (null until known), links, `openInTab` (a tab opened in the click, then sent to the address),
|
|
606
|
+
the handoff, and `entryTarget` (the authorize route only; with `{ app: true }` also a path or
|
|
607
|
+
address on the app's origin, P074). `frameFallback(outcome)` words what to offer when a frame shows
|
|
608
|
+
nothing (`needs-tab`, `denied`, `expired`, `failed`, `timeout`). Redirect entry's pages on the app
|
|
609
|
+
origin report frame status too (`blocked: sign-in`), taken from the host's own origin only, for
|
|
610
|
+
frame status only.
|
|
611
|
+
|
|
612
|
+
**React** (the kit's part): `PortholeView` (a display by kind, served or opaque, with its fallback),
|
|
613
|
+
`usePortholeLink`, and the provider's shared props (ADOPTING.md § 3: `scheme`, `theme`, `nonce:
|
|
614
|
+
"auto"`, `handlers`, `openLink`, `notify`, `renderConfirm`, whose `redirect` doesn't count toward
|
|
615
|
+
muting, P074). The confirm request's `display` carries the instance the host gave the frame; an
|
|
616
|
+
opaque frame never gets it (P076, P077). A scheme flip or a new themeKey re-themes running frames in
|
|
617
|
+
place; no display-making effect depends on the context value those renew (#9, P074).
|
|
618
|
+
|
|
619
|
+
**Conformance runner (`@botiverse/porthole/conformance`).** `defineHostConformance(test, { name,
|
|
620
|
+
open, issue, config, instances, entry?, nonce?, skip? })` registers the leak suite, the served cases
|
|
621
|
+
and the redirect entry cases against the app's real page, which `open(page)` opens as a person sees
|
|
622
|
+
it (signed in, its real CSP). The harness is framework-free, on the core's `createHost` (an app's
|
|
623
|
+
frame components are its own e2e's; Porthole's React binding is Porthole's tests'), and loads as a
|
|
624
|
+
script from the page's origin (routed by the test) with the page's nonce, so a strict CSP needs
|
|
625
|
+
nothing added. The app's issue endpoint locates served frames from the page, with its cookies.
|
|
626
|
+
Canaries and a foreign origin are routed; cases for instances the app doesn't give (versions, url
|
|
627
|
+
mode, the MCP Apps proxy) are skipped with the reason. Tests are located at the
|
|
628
|
+
`defineHostConformance` call, so `playwright test <spec>` and `<spec>:<line>` select them (P070).
|
|
629
|
+
`entry.unknown`: addresses that name nothing, each a 404 on the content domain.
|
|
630
|
+
`hostConformance(options)` gives the hosts to an app that registers cases itself. Options, reporter,
|
|
631
|
+
`conformanceProjects`: [ADOPTING.md](ADOPTING.md) § "7. Conformance".
|
|
632
|
+
|
|
633
|
+
**Prod shape** (`ops/prod-shape/`, `ops/prod-shape/run.sh`). Docker compose: Caddy's internal CA
|
|
634
|
+
serving `app.test`, `*.content.test` (same-site siblings, as in production without a Public Suffix
|
|
635
|
+
List entry), `clash.test`, `evil.test`; wildcard DNS (CoreDNS); the kit reference app behind the
|
|
636
|
+
edge, its health probe over real TLS; a misconfigured twin that must run opaque and a strict one
|
|
637
|
+
that must not start; a Playwright image trusting the CA (Chromium's NSS store, the system store for
|
|
638
|
+
WebKit; Playwright's Firefox reads neither, so its project overrides certificate errors). The suite
|
|
639
|
+
(`packages/porthole/prod-shape`) runs the whole runner over https, then sibling cases: Porthole's
|
|
640
|
+
cookies are host-only and `__Host-`; a sibling label (an app's preview) can't plant a cookie that
|
|
641
|
+
opens content, or frame it; another site can't frame it; the clash. CI (`.github/workflows/ci.yml`)
|
|
642
|
+
runs the checks, examples and loopback suites on Chromium on every push; each engine's loopback
|
|
643
|
+
suites, the negative controls and prod shape run when started by hand, which a release requires on
|
|
644
|
+
its commit (P146).
|
|
645
|
+
|
|
646
|
+
**Types.** The kit wraps `createServer`, still public. The npm package carries these docs (`docs/`);
|
|
647
|
+
`/server` exports the types an app's callbacks take (`InstanceRef`, `FrameLocation`,
|
|
648
|
+
`ServedDocument`, `PortholeConfig`, `EntryContext`). `FrameBlock` includes `sign-in`;
|
|
649
|
+
`ContentDomain.name` takes a `Naming` (any function fits).
|
|
650
|
+
|
|
651
|
+
### The agent's side: lint, check, tools
|
|
652
|
+
|
|
653
|
+
Wiring: [ADOPTING.md](ADOPTING.md) § "6. The agent's side".
|
|
654
|
+
|
|
655
|
+
- **`lintContent(config, content)`** (core, pure): findings worded for the agent, with their line.
|
|
656
|
+
Errors only for what certainly fails or is cut: over the size, a document with no body where a
|
|
657
|
+
fragment goes, nested frames and plugins, `document.write`. Warnings for the rest: a document sent
|
|
658
|
+
as a widget (taken as its body, `fragmentOf`), the clipboard, dialogs, forms, hosts outside
|
|
659
|
+
egress, unpinned CDN libraries, `position: fixed` in a flow layout, new windows without
|
|
660
|
+
`openLink`, the page's own styles holding it to one screen (P106, P110: `src/check/scroll.ts`, a
|
|
661
|
+
cascade of html, body and the root's overflow, height and position; `lintFiles` reads the
|
|
662
|
+
version's linked stylesheets within its caps; advisory, so a throw says the page wasn't checked).
|
|
663
|
+
- **`admitContent(config, content, { refuseOn })`**, the show tool's gate: refuses errors by default
|
|
664
|
+
with what to change; otherwise shows the content (a widget's document taken as its body) and
|
|
665
|
+
returns warnings as a note.
|
|
666
|
+
- **Files** (P081). `lintFiles(config, files)` lints each page as `lintContent` does (findings name
|
|
667
|
+
their `path`), holds the set to `checkFileSet`'s rules and the config's limits, and looks each
|
|
668
|
+
relative reference up in the set (markup, CSS, module imports, workers, fetches). A page's
|
|
669
|
+
reference starting with `/` is an error (it names the address's root, not the version: a Vite
|
|
670
|
+
build without `base: "./"`); one not in the set, a warning. `admitFiles` is the publish tool's
|
|
671
|
+
gate. `checkPage({ config, files, driver })` serves the set and runs its entry (a served artifact
|
|
672
|
+
config, a driver that serves).
|
|
673
|
+
- **`checkPage({ config, content, driver })`** (`/check`) runs the content in the real sandbox per
|
|
674
|
+
width and scheme (default: the manual's phone and desktop widths, light and dark unless unthemed).
|
|
675
|
+
The check page (`src/check/page.ts`, shipped as `/check/page`, a module `checkPage` imports so a
|
|
676
|
+
bundle carries it, P075) is served by the driver at `https://porthole-check.invalid`; it mounts
|
|
677
|
+
the content with a small instrument first and hears errors, rejections, CSP blocks, failed loads,
|
|
678
|
+
the console and the document's width by `postMessage`; heights come from resize events. A served
|
|
679
|
+
config runs served (P074): the driver answers a reserved content domain
|
|
680
|
+
(`*.porthole-check-content.invalid`) with an in-process `createServer` (random secret, the check
|
|
681
|
+
page its only host origin), so the content gets its own origin per run, the served CSP in headers,
|
|
682
|
+
the shell, storage and cookies. An opaque config, an MCP Apps view (as a page with the view's
|
|
683
|
+
egress) and a driver without `serve` run opaque. Each inline script is named (`//#
|
|
684
|
+
sourceURL=porthole-script-<n>`) with its first line recorded, so an error's line is the content's
|
|
685
|
+
line, as lint numbers it. Host functions are answered as a host that declines (`confirm` says no;
|
|
686
|
+
handlers answer no; no call comes from a click, P078). Each call the host sees is reported
|
|
687
|
+
(`run.calls`): refused by a gate regardless of the person (no click, bad arguments, too often) is
|
|
688
|
+
a problem; declined or answered, a note. A global the shell refuses without a click (`sendPrompt`)
|
|
689
|
+
rejects in the content, so it shows as an error. The report's `text` names each problem once, with
|
|
690
|
+
where, at most 8. Drivers: `playwrightDriver(browser)` (`page.route`), `cdpDriver(open)` over any
|
|
691
|
+
CDP session (`Fetch` interception; Cloudflare Browser Rendering from a Worker).
|
|
692
|
+
- **Tools:** `showTool`, `guideTool`, `checkTool` give `{ name, description, inputSchema }` from the
|
|
693
|
+
config; `answerGuide` answers the guide tool; `guideChanges(from, to)` is the notice when a kind
|
|
694
|
+
flips between served and opaque. `examples/mcp/server.mjs` wires them over MCP.
|
|
695
|
+
- **The manual's examples pass the check:** `leak/check.spec.ts` runs every `GUIDE_EXAMPLES` entry
|
|
696
|
+
under each preset at the manual's widths, light and dark, on three engines ([PRINCIPLES.md §
|
|
697
|
+
Objectives](PRINCIPLES.md#objectives-and-success-criteria), criterion 5).
|
|
698
|
+
|
|
699
|
+
### The MCP Apps adapters
|
|
700
|
+
|
|
701
|
+
The core's adapter covers the MCP Apps subset its shell speaks (`ShellConnection`): `ui/initialize`
|
|
702
|
+
answered with the host context; `tool-input-partial` (0..n) then `tool-input` carrying `{ html }`;
|
|
703
|
+
`host-context-changed`; `size-changed`, `notifications/message` (errors), `ui/message` and
|
|
704
|
+
`ui/open-link` into the bridge; `ui/resource-teardown`. Content may also use the official App SDK:
|
|
705
|
+
the adapter answers a second `ui/initialize` from the same frame, and the shell numbers its requests
|
|
706
|
+
with strings (`porthole-shell-1`) so neither takes the other's answers. The shell asks
|
|
707
|
+
`ui/initialize` up to 40 times, 250 ms apart (the host may listen late). On a tab of its own it asks
|
|
708
|
+
nothing (no host can hear) and its runtime offers nothing. The document's root records the outcome
|
|
709
|
+
(`data-porthole-host`: `"answered"` or `"none"`) for a screenshot tool to wait on (P139).
|
|
710
|
+
|
|
711
|
+
`styles.variables` in the host context holds only MCP Apps' names (`MCP_APPS_STYLE_VARIABLES`): the
|
|
712
|
+
official SDK fails the whole handshake on any other. Porthole's own (the accent, the chart palette)
|
|
713
|
+
go in the own-prefixed `porthole/styles: { variables }`, which the shell applies and a view ignores
|
|
714
|
+
(P028). The `0.app-sdk-*` probes connect the official SDK from content under the inline, artifact
|
|
715
|
+
and MCP Apps presets.
|
|
716
|
+
|
|
717
|
+
The `/mcp` adapter (full MCP Apps views) implements `ProtocolAdapter` with its own connection
|
|
718
|
+
operations (`sendToolInputPartial`, `sendToolInput`, `sendToolResult`, `sendToolCancelled`). It
|
|
719
|
+
carries `ui/message`, `ui/open-link`, `tools/call`, `resources/read`, `ui/download-file` and
|
|
720
|
+
`ui/update-model-context` through the bridge, answers `ui/request-display-mode` with the current
|
|
721
|
+
mode, sends only standard style variables, and does the sandbox-proxy handshake when the frame is
|
|
722
|
+
the proxy (P027). `viewEgress` maps a view's `_meta.ui.csp` into the config's egress
|
|
723
|
+
(`readViewResource` reads the view and its egress from a `resources/read` result). Adapters validate
|
|
724
|
+
every message and never call a handler: `bridge.call` decides. The leak suite runs the official
|
|
725
|
+
ext-apps examples, as published, through it (`leak/mcp/`), opaque and behind the sandbox proxy.
|
|
726
|
+
|
|
727
|
+
**Not AppBridge** (P007). The SDK's host side, `AppBridge`, extends the MCP SDK's `Protocol` class
|
|
728
|
+
and pulls in the MCP client/core packages. Porthole reimplements the thin host-side subset that maps
|
|
729
|
+
to capabilities; no AppBridge-backed adapter is offered for now (P014). On the widget side nothing
|
|
730
|
+
is reimplemented: authors use the official `App` SDK. Upstream, once code and tests exist (P018), we
|
|
731
|
+
contribute what is general: the conformance/leak runner, the container-agnostic framing note (one
|
|
732
|
+
hardened frame instead of the mandated double-iframe, where equally secure), and the shadow-root /
|
|
733
|
+
document-rewrite frame-escape findings.
|
|
713
734
|
|
|
714
735
|
### The host-function bridge
|
|
715
736
|
|
|
716
|
-
`bridge.call(capability, args)` checks, in order: the display's run not stopped (a restart or
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
`declinesBeforeMute` declines a display stops asking (`muted`) until it runs again.
|
|
737
|
+
`bridge.call(capability, args)` checks, in order: the display's run not stopped (a restart or its
|
|
738
|
+
end closes its bridge, P095) → declared by the config → declared by the page, where it has a
|
|
739
|
+
declaration (P086) → before reading arguments: for the runtime's own host functions, a method by its
|
|
740
|
+
`op` and the viewer's level for it, then for every capability its host function's own rate (P091,
|
|
741
|
+
P095: a malformed call costs its rate) → arguments valid and within limits (`openLink` http(s) only,
|
|
742
|
+
no credentials in the URL; a prompt 1..`maxPromptChars` characters; a tool's arguments, model
|
|
743
|
+
context and a download's contents plain, bounded JSON, P095) → who may (P087: each method's level
|
|
744
|
+
for the viewer, the data a page named with or without a viewer (P094), db's rules) → muted, if
|
|
745
|
+
confirm-gated → each method's own rate (`methodGates`; P094: a batch's writes count each) → user
|
|
746
|
+
activation → the viewer's `consent` → `confirm` (at most 10 waiting a display, P095) → the host's
|
|
747
|
+
handler (or for a read, a result the host already gave for it (P094), or for a read allowed stale,
|
|
748
|
+
the host's cache). Each refusal is a `Refusal` and a `refused` display event; the frame gets an
|
|
749
|
+
error result. After `declinesBeforeMute` declines a display stops asking (`muted`) until it runs
|
|
750
|
+
again.
|
|
731
751
|
|
|
732
752
|
### React binding
|
|
733
753
|
|
|
734
|
-
`@botiverse/porthole/react` (`src/react/`, TSX
|
|
735
|
-
|
|
736
|
-
|
|
754
|
+
`@botiverse/porthole/react` (`src/react/`, TSX a host's bundler or `pnpm build` compiles; peer
|
|
755
|
+
`react` 19.2+ for `useEffectEvent`). Isolation is the core's; the binding is mounting and lifecycle
|
|
756
|
+
(P034).
|
|
737
757
|
|
|
738
758
|
```ts
|
|
739
759
|
<PortholeProvider confirm? hostInfo? locator? nonce? dialogClassName? toastClassName?> // once per page
|
|
@@ -755,193 +775,166 @@ binding is mounting and lifecycle (P034).
|
|
|
755
775
|
</PortholeProvider>
|
|
756
776
|
```
|
|
757
777
|
|
|
758
|
-
- **Provider** (per page):
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
host page
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
`
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
`
|
|
777
|
-
`
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
- **
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
`hostInfo` are compared by value, and the provider's `locator` and `confirm` are
|
|
798
|
-
read when used, so a host may build them inline. A new `config`, `document`,
|
|
799
|
-
`instance` or `generation` still makes a new display.
|
|
800
|
-
- **Fill** (P057): `fill` makes the frame fill its box (give the box, or its parent,
|
|
801
|
-
a height) and the content scroll inside it, instead of growing with it; a url-mode
|
|
802
|
-
app always fills. In the core, `MountOptions.fill`.
|
|
803
|
-
- **A strict page** (P054): `nonce` passes the page's CSP nonce to opaque frames, which
|
|
804
|
-
inherit the page's policy (`HostOptions.nonce` in the core).
|
|
805
|
-
|
|
806
|
-
Its tests run in real browsers (`leak/react.spec.ts`, against `leak/react/app.tsx`,
|
|
807
|
-
which the leak server bundles with esbuild because React ships CommonJS only).
|
|
778
|
+
- **Provider** (per page): a live-frame cap (`limits.maxLiveFrames`; frames off screen longest stop
|
|
779
|
+
first, show a placeholder at their last height with "Run again", and rerun when back); heights by
|
|
780
|
+
`displayId`, so a remounted frame starts at its last height; the default confirmation
|
|
781
|
+
(`ConfirmDialog`, P019: the call's whole effect and the display's title, Cancel focused, accept
|
|
782
|
+
ignoring presses for `ARM_DELAY_MS` after opening, Escape cancels; a modal in the host page,
|
|
783
|
+
outside every frame), which `confirm` replaces. Without a provider frames still run (one page-wide
|
|
784
|
+
registry) and calls needing a person are refused. It serves `copyText` for frames whose handlers
|
|
785
|
+
don't (P052): the host's page writes the clipboard and `CopyToast` shows what went on it, clipped
|
|
786
|
+
to four lines and `TOAST_CHARS`; a failed write says so and offers a Copy button, a click on the
|
|
787
|
+
host's own page.
|
|
788
|
+
- **Frame**: mounts near the screen (800 px) unless `eager`. Until its content reports a size it
|
|
789
|
+
holds its remembered height (at least `PLACEHOLDER_HEIGHT_PX`) behind its placeholder
|
|
790
|
+
(`data-porthole-state`: `waiting`, `running`, `stopped`; `data-porthole-ready` while loading),
|
|
791
|
+
then is as tall as its content within the config's limits. The shell reports no size before
|
|
792
|
+
drawing something, so an empty shell never overwrites a remembered height. Only a new `config`,
|
|
793
|
+
`document`, `instance` or `generation` makes a new display; `content`, `partial`, `scheme`,
|
|
794
|
+
handlers, even `displayId` and `title` go to the running one (a streamed display keeps its frame
|
|
795
|
+
when its id settles, and its confirmations name it as the host now does). `config`, `instance`,
|
|
796
|
+
`annotations` and the provider's `hostInfo` are compared by value, and the provider's `locator`
|
|
797
|
+
and `confirm` read when used, so a host may build them inline (P057). Navigation recovery is the
|
|
798
|
+
core's: restarted up to three times, `onNavigated` each time, then stopped with an error.
|
|
799
|
+
- **Annotations** follow props: `annotating` (what the person may point at now, or null),
|
|
800
|
+
`annotations` (the marks), `focusedAnnotation` (each new id is brought into view; `{ id, key }`
|
|
801
|
+
with a new key refocuses), `trackedAnnotation` (the mark followed, or null, P118),
|
|
802
|
+
`trackedSelection` (true: the selection followed in place and highlighted, P138). `onAnnotation`
|
|
803
|
+
gets the frame's reports, `tracked` and `selectionTracked` boxes too. A remounted frame gets them
|
|
804
|
+
all. The `ref` (`PortholeFrameHandle`) holds `clearSelection()`, `find`, `clearFind`,
|
|
805
|
+
`focusMark(id)`, each a no-op while no display runs.
|
|
806
|
+
- **Errors** (P055): `onContentError` gets the content's faults (what it threw, what the sandbox
|
|
807
|
+
blocked, a stopped navigation, that it kept navigating away): the agent's to hear.
|
|
808
|
+
`onNavigationBlocked` gets a stopped navigation's whole address (P080). `onHostError` gets the
|
|
809
|
+
host side's failures (`locate`, `mount`, `annotations`), never the agent's. `onError(message,
|
|
810
|
+
source)` gets both.
|
|
811
|
+
- **Fill** (P057): the frame fills its box (give it or its parent a height) and the content scrolls
|
|
812
|
+
inside instead of growing; a url-mode app always fills. Core: `MountOptions.fill`. **`nonce`**
|
|
813
|
+
(P054): see § Isolation modes and served content (`HostOptions.nonce` in the core).
|
|
814
|
+
|
|
815
|
+
Tests run in real browsers (`leak/react.spec.ts`, against `leak/react/app.tsx`, bundled by the leak
|
|
816
|
+
server with esbuild since React ships CommonJS only).
|
|
808
817
|
|
|
809
818
|
## Widget side (what the agent writes against)
|
|
810
819
|
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
`
|
|
815
|
-
|
|
816
|
-
for `localStorage` in an opaque frame, applies the theme variables, and fires the
|
|
817
|
-
config's theme event after a change. A capability that is not declared is simply
|
|
818
|
-
absent.
|
|
820
|
+
Content speaks **MCP Apps**: the official `@modelcontextprotocol/ext-apps` `App` SDK, or the raw
|
|
821
|
+
JSON-RPC over `postMessage` the spec documents. For convenience the shell defines `sendPrompt(text)`
|
|
822
|
+
and `openLink(url)` when declared (sugar over `ui/message` and `ui/open-link`), turns link clicks
|
|
823
|
+
into `openLink`, stands in for `localStorage` in an opaque frame, applies the theme variables, and
|
|
824
|
+
fires the config's theme event after a change. An undeclared capability is absent.
|
|
819
825
|
|
|
820
|
-
## The capability runtime
|
|
826
|
+
## The capability runtime
|
|
821
827
|
|
|
822
828
|
A config with `runtime: "1"` (inline widgets and artifact pages) gives its frames one global,
|
|
823
|
-
`porthole`, whose only member is `use(name)`:
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
- **Contract** (`RUNTIME_CAPABILITIES`, version 1; `types/runtime/v1/*.d.ts`): `clipboard`,
|
|
834
|
-
`links`, `downloads`, `comments` (built in), `user`, `chat`, `data`, `context`, `artifact`,
|
|
835
|
-
`assets`, `db` (declared). Each method is served by one of the config's host functions, gated as
|
|
836
|
-
the config says; the table in P085 maps them.
|
|
829
|
+
`porthole`, whose only member is `use(name)`: a frozen namespace, or null where the capability isn't
|
|
830
|
+
offered (the page draws without it). Errors carry a stable `code`. Offering it:
|
|
831
|
+
[ADOPTING.md](ADOPTING.md) § "The capability runtime". Guarantees: [THREAT_MODEL.md §
|
|
832
|
+
7](THREAT_MODEL.md#7-the-display-layer-and-the-app-runtime).
|
|
833
|
+
|
|
834
|
+
- **Contract** (`RUNTIME_CAPABILITIES`, version 1; `types/runtime/v1/*.d.ts`): `clipboard`, `links`,
|
|
835
|
+
`downloads`, `comments` (built in), `user`, `chat`, `data`, `context`, `artifact`, `assets`, `db`
|
|
836
|
+
(declared). Each method is served by one of the config's host functions, gated as configured;
|
|
837
|
+
P085's table maps them.
|
|
837
838
|
- **Declaration** (P086): `{ capabilities: { name: config }, runtime }`, stored by the host,
|
|
838
839
|
resolved at publish by `declareCapabilities` (omitted carries forward, `{}` clears, an object
|
|
839
|
-
replaces), checked against the config, given to `mount({ declaration })
|
|
840
|
-
undeclared capability on every path (`undeclared` →
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
allows exactly what both allow (each side's `db` rules read as `dbAccess` reads them, P093). A
|
|
858
|
-
display without a viewer gets nothing above view; a viewer that doesn't parse is an error.
|
|
840
|
+
replaces), checked against the config, given to `mount({ declaration })` (`null` for a page stored
|
|
841
|
+
without one). The bridge refuses an undeclared capability on every path (`undeclared` →
|
|
842
|
+
`not_allowed`). A page stored before runtime declarations takes the legacy path. An older version
|
|
843
|
+
mounts with `intersectDeclarations(version's, current)`: exactly what both allow (each side's `db`
|
|
844
|
+
rules read as `dbAccess` reads them, P093).
|
|
845
|
+
- **Levels** (P087): `view < interact < admin < owner`. Each method has a least level (config
|
|
846
|
+
`levels` at or above its floor; a page's declaration raises it). The host's access gives the
|
|
847
|
+
viewer's level (`Grant.level`, `Grant.user` → `FrameLocation.viewer`; or `mount({ viewer })`);
|
|
848
|
+
below it is `forbidden`, before any handler. Without a viewer the config's other host functions
|
|
849
|
+
run but the runtime's are refused, and nothing above view is given; a viewer that doesn't parse is
|
|
850
|
+
an error.
|
|
851
|
+
- **In the bridge** (§ The host-function bridge gives the order): arguments are checked for shape,
|
|
852
|
+
by bounded walks, and against limits (`too_large`); "who may" is the call's level (a batch's
|
|
853
|
+
writes', a watch's read's), `data`'s names (with or without a viewer, P094), `db`'s paths and
|
|
854
|
+
rules; the gates are the host function's plus each method's own (`artifact.publish` and
|
|
855
|
+
`assets.delete` a yes, an upload whose code may run a yes; a db batch its writes', confirmed once
|
|
856
|
+
whole, its rate counting each write; a watch its read's, P094). The handler gets context `viewer`,
|
|
857
|
+
`declared`, `instance`; `db` answers with `data/users/me` (P091).
|
|
859
858
|
- **Wire**: the roster in `ui/initialize`'s `hostCapabilities.experimental["porthole/runtime"]`;
|
|
860
|
-
`porthole/call { capability, method, args, watch? }` → `{ value }` or an error with
|
|
861
|
-
|
|
859
|
+
`porthole/call { capability, method, args, watch? }` → `{ value }` or an error with `data: { code,
|
|
860
|
+
message }`; `porthole/event { watch, data }`; `porthole/unwatch { watch }`.
|
|
862
861
|
`data.read`/`data.subscribe` use MCP's `resources/*`.
|
|
863
|
-
- **Services are the host's**: `db` (paths, versions, `ifVersion`, batches, watches,
|
|
864
|
-
private, the page's rules: `dbAccess`, which the host applies again), `artifact`
|
|
865
|
-
a base-checked patch), `assets` (an `AssetStore` `/server` serves at
|
|
866
|
-
(the host's composer; content hears a boolean).
|
|
867
|
-
handlers, and with `api` its own API past the
|
|
868
|
-
`context.viewer` or `context.declared`);
|
|
869
|
-
`pseudonymFor(secret, artifact, person)`
|
|
862
|
+
- **Services are the host's**: `db` (paths, versions, `ifVersion`, batches, watches,
|
|
863
|
+
`data/users/<id>` private, the page's rules: `dbAccess`, which the host applies again), `artifact`
|
|
864
|
+
(current version; a base-checked patch), `assets` (an `AssetStore` `/server` serves at
|
|
865
|
+
`/_blob/<id>`), `comments` (the host's composer; content hears a boolean).
|
|
866
|
+
`defineRuntimeConformance` checks an app's real handlers, and with `api` its own API past the
|
|
867
|
+
bridge with a forged context (never trust `context.viewer` or `context.declared`);
|
|
868
|
+
`leak/runtime/memory.ts` is the in-memory reference. `pseudonymFor(secret, artifact, person)`
|
|
869
|
+
gives a person an id per artifact.
|
|
870
870
|
- **Assets on the content origin** (P089, P091): for an access to the asset's artifact (a session
|
|
871
|
-
cookie, a framed set's sealed address as `Referer`, or `assets.url(id)`'s
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
offered capability's `.d.ts`. 0.6's globals stay defined (`shell/legacy.ts`) and untaught.
|
|
871
|
+
cookie, a framed set's sealed address as `Referer`, or `assets.url(id)`'s `<sealed
|
|
872
|
+
base>__porthole/blob/<id>`), then the host's check, then `AssetStore.get(id, access)`; revalidated
|
|
873
|
+
(`no-cache`, ETag); code-typed only where trusted and the config lets uploaded code run, asked at
|
|
874
|
+
each load (in bearer mode every artifact config must, P103); by id alone only in bearer mode.
|
|
875
|
+
- **The manual**: topic `interactive` lists `porthole.use`'s methods with levels and gates; topic
|
|
876
|
+
`capabilities` teaches declaring, levels, errors, where state goes, and each offered capability's
|
|
877
|
+
`.d.ts`. The legacy globals stay defined (`shell/legacy.ts`) and untaught.
|
|
879
878
|
|
|
880
879
|
## The modes
|
|
881
880
|
|
|
882
|
-
- **Inline widget** (`presets.inlineWidget`)
|
|
883
|
-
|
|
884
|
-
The
|
|
885
|
-
- **Live widget** (`presets.liveWidget`, P079)
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
- **Artifact page** (`presets.artifact`)
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
- **
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
blocked (and why: `cookies` on WebKit, `framing`, `session`, `upstream`, `denied`
|
|
909
|
-
with the host's code, `locate` when the host's own locator failed) or timeout, so
|
|
910
|
-
it can offer its own "Open in a new tab". A `denied` may follow `loaded`: the host
|
|
911
|
-
revoked access mid-session (P050).
|
|
881
|
+
- **Inline widget** (`presets.inlineWidget`): the agent's HTML, held by the host, drawn by the shell
|
|
882
|
+
in an opaque frame, streamed as written; the smallest capability set, for cards in a conversation.
|
|
883
|
+
The workhorse.
|
|
884
|
+
- **Live widget** (`presets.liveWidget`, P079): an inline widget showing the host's current data as
|
|
885
|
+
the viewer may see it. It declares `readData` and `subscribeData` with `consent` and its rate.
|
|
886
|
+
Egress stays closed: no option opens it; it refuses `egress` and a capability's own `connect` or
|
|
887
|
+
`resource` (P103). Served, it loads Porthole's Chart.js and D3 from its own origin
|
|
888
|
+
(`egress.libraries`).
|
|
889
|
+
- **Artifact page** (`presets.artifact`): a whole document, written into an opaque frame by the
|
|
890
|
+
shell where the host has it (an app's "show an HTML file"), or served on its own origin (domain
|
|
891
|
+
isolation), CSP in headers, versioned. It scrolls inside past a shorter height cap.
|
|
892
|
+
- **MCP Apps view** (`presets.mcpApp`): a `ui://` template plus tool input/result through the `/mcp`
|
|
893
|
+
adapter, hardened in an opaque frame (the shell's runtime first in the view's document) or behind
|
|
894
|
+
the sandbox proxy on a second origin.
|
|
895
|
+
- **Domain mode** (any of the above with `isolation: "domain"`): a stable origin per storage scope,
|
|
896
|
+
so `localStorage` persists (P016).
|
|
897
|
+
- **URL mode** (`presets.url`): a running app by URL (a dev server's preview): frame, isolation and
|
|
898
|
+
access auth; no shell, no capabilities, no egress control (P020). No handshake: its first load
|
|
899
|
+
makes it ready. It fills its container (it reports no size; give the frame a height), at least
|
|
900
|
+
`minHeightPx`. A host may add popups, modals and downloads to its sandbox, never top navigation
|
|
901
|
+
(P037), and delegate clipboard writes and full screen (`permissions`, P049; none by default).
|
|
902
|
+
Through `/server`, a framed app is entered through a page that checks the browser kept its cookie,
|
|
903
|
+
tells the host (P040), and goes on once loaded. The host's `outcome` says loaded, blocked
|
|
904
|
+
(`cookies` on WebKit, `framing`, `session`, `upstream`, `denied` with the host's code, `locate`
|
|
905
|
+
when the host's locator failed) or timeout, so it can offer "Open in a new tab". A `denied` after
|
|
906
|
+
`loaded` means the host revoked access mid-session (P050).
|
|
912
907
|
|
|
913
908
|
## Egress hardening, each with its test
|
|
914
909
|
|
|
915
|
-
Closed by default; opened only to origins the config declares.
|
|
916
|
-
(closed, library CDNs, passive media from any https site)
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
reach,
|
|
923
|
-
origin loads; an unsandboxed peer connection sends STUN; an unsandboxed
|
|
924
|
-
connects) or the probe says it has none. Each defense has a negative control
|
|
925
|
-
(`PORTHOLE_LEAK_WEAKEN`, P032) that takes it out, so its probes are seen to fail.
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
always has a confirm function (a default dialog). Tested against a reference page
|
|
944
|
-
closed like a strict host's (`leak/inherited-policy.spec.ts`).
|
|
910
|
+
Closed by default; opened only to origins the config declares. ADOPTING.md § "Choosing egress"
|
|
911
|
+
summarizes the levels (closed, library CDNs, passive media from any https site); this is the long
|
|
912
|
+
form.
|
|
913
|
+
|
|
914
|
+
The leak suite (`src/conformance/probes.ts`, `pnpm test:leak` against the reference host) attempts
|
|
915
|
+
each channel from inside the content, as an agent's code would, and asserts with an out-of-band
|
|
916
|
+
oracle that nothing left: an HTTP canary that also counts raw TCP connections, a UDP listener for
|
|
917
|
+
STUN, a witness origin a navigated document would reach, the page's responses. Each oracle has a
|
|
918
|
+
positive control (an allowed origin loads; an unsandboxed peer connection sends STUN; an unsandboxed
|
|
919
|
+
hint connects), or the probe says it has none. Each defense has a negative control
|
|
920
|
+
(`PORTHOLE_LEAK_WEAKEN`, P032) that takes it out, so its probes are seen to fail. Chromium 153,
|
|
921
|
+
WebKit 26.6 and Firefox 155 (Playwright 1.63) all gate (P017, P035).
|
|
922
|
+
|
|
923
|
+
Origins are exact, or `https://*.` a domain of the host's own. A wildcard over a public suffix
|
|
924
|
+
(`*.com`, `*.co.uk`, `*.github.io`) is refused, as is any scheme source, with one exception (P060):
|
|
925
|
+
`egress.anyHttps: ["img", "media", "font"]` lets passive content load from any https site (P059).
|
|
926
|
+
Those directives get `https:`; scripts, styles, data and frames never do, and the manual says so
|
|
927
|
+
(`leak/cdn.spec.ts`: a hotlinked image loads; a script, a stylesheet and a fetch to the same site
|
|
928
|
+
don't).
|
|
929
|
+
|
|
930
|
+
An opaque frame inherits the embedding page's whole policy (P058). On a page with `default-src
|
|
931
|
+
'none'` and a tight `connect-src`/`img-src`, an origin the config opens stays shut; there, prefer
|
|
932
|
+
domain mode, whose frames inherit nothing. On a page that closes images or fetches to its own
|
|
933
|
+
origin, the positive controls of `1.connect` and `2.resources` can't load, through no fault of the
|
|
934
|
+
host's isolation; the suite then reports the probe inapplicable on this host, with the reason (the
|
|
935
|
+
allowed origin was blocked by a policy not the frame's own), instead of failing it. `12.no-confirm`
|
|
936
|
+
likewise, on a host that always has a confirm function (a default dialog). Tested on a reference
|
|
937
|
+
page closed like a strict host's (`leak/inherited-policy.spec.ts`).
|
|
945
938
|
|
|
946
939
|
| # | Channel | Mechanism | Probes | Negative control → fails (Chromium / WebKit / Firefox) |
|
|
947
940
|
|---|---------|-----------|--------|------------------------------------------|
|
|
@@ -956,11 +949,10 @@ closed like a strict host's (`leak/inherited-policy.spec.ts`).
|
|
|
956
949
|
| 9 | the host's DOM, storage, cookies, credentials; another display | opaque origin (no `allow-same-origin`); nothing secret is sent into the frame; the shell takes messages only from its parent | `9.host`, `9.siblings` (a display can't navigate or drive another) | — (the sandbox is the platform's; measured: a new frame's realm is cross-origin even in the task that made it, both engines) |
|
|
957
950
|
| 10 | the embedding page's own origin | no `'self'` in any directive (P022) | `10.self` | `self` → none: measured, an opaque frame's `'self'` reaches nothing of the host on either engine. Kept out anyway (nothing legitimate needs it) |
|
|
958
951
|
|
|
959
|
-
Interop (`0.*`): the content runs in an opaque origin; the shell defines a global only
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
(`style-split` → all three, P028).
|
|
952
|
+
Interop (`0.*`): the content runs in an opaque origin; the shell defines a global only per declared
|
|
953
|
+
capability, fixed in place, and applies exactly the declared theme variables; streamed content is
|
|
954
|
+
drawn inert and runs once; content using the official App SDK connects under the inline, artifact
|
|
955
|
+
and MCP Apps presets (`style-split` → all three, P028).
|
|
964
956
|
|
|
965
957
|
### Behavior and gates, each with its test
|
|
966
958
|
|
|
@@ -970,24 +962,25 @@ official App SDK connects under the inline, artifact and MCP Apps presets
|
|
|
970
962
|
| 11 | auto-size | the shell reports its height (`size-changed`) as it changes; the host clamps it to `minHeightPx`..`maxHeightPx` and sizes the frame; past the cap the content scrolls inside | `11.size` (grows, shrinks, stops at the cap and scrolls, floors at the minimum; events carry the clamped height), `11.size-document` (a whole page's height; its own `load` fires; its title kept) | — |
|
|
971
963
|
| 11 | theming | `setTheme(scheme)`: the host sends the resolved variables (the host's live values over the defaults, P028), the shell sets them in place, with `data-theme` and `color-scheme`, then fires the config's theme event once, only when the scheme or a value changed (never at mount, never for a host re-sending what the content has, P061); the frame element's `color-scheme` follows | `11.theme-flip` (no event at mount or for the same scheme; in place: content state kept, the event fired once per flip, back and forth), `11.theme-host-values` (live values for standard and own names; undeclared names dropped) | — |
|
|
972
964
|
| 11 | base styles | plain CSS at zero specificity (`:where`): native buttons, inputs, selects and text areas take the theme's borders, radius, colors and focus ring, 44 px tall (the manual's touch size); the manual says so for inline widgets | `11.base-styles` (themed; content's own CSS overrides them) | — |
|
|
973
|
-
| 12 | `sendPrompt` | the
|
|
965
|
+
| 12 | `sendPrompt` | the host asks `confirm` with the whole text, whether a click came with the call or not (no proof of a gesture is asked since 0.16.0, P149); declines count toward a mute; at most 30 a minute | `12.prompt-confirm` (a call on load asks, and a no sends nothing; a click asks; a no sends nothing; a yes reaches the handler), `12.raw-message` (a raw `ui/message` around the shell, no click: asked too, and a no sends nothing), `12.mute`, `12.no-confirm` | `confirm-gate` → prompt-confirm, raw-message, link, mute, no-confirm, `14.windows` |
|
|
974
966
|
| 12 | live data (`readData`, `subscribeData`, P079) | MCP `resources/read`, `resources/subscribe`/`unsubscribe`, `notifications/resources/updated`; the `consent` gate asks the host once per display before the first data call (a no refuses them all; none refuses, fail closed), then the rate; a subscribed read may be answered from the host's cache, marked stale, the fresh one following as an update; a refusal tells content why (`data: { code, message }`, P080) | `test/live-data.test.ts`, `test/refusals.test.ts`; `leak/served/live.spec.ts` (read and followed, consent asked once; cached then fresh; a viewer's no refuses both, no handler runs, `denied` with its sentence; a host refusing all without handlers; a handler's `Refused`) | — |
|
|
975
967
|
| 12 | `openLink` | link clicks go out through `openLink`; the bridge takes http(s) only, without credentials in the URL; confirmed | `12.link` (a web link asks and opens; `javascript:` links and `openLink("javascript:…")` do nothing and are refused) | `link-scheme` → `12.link` |
|
|
976
968
|
| 14 | error reports (`reportError`, S05, P095) | the adapters hand the bridge what content logged as it came; the bridge counts reportError's rate before reading it, then makes bounded text of it (`boundedText`: each object once, `[Circular]`/`[Repeated]`; 1,000 values, 16 levels, 8,000 characters; a BigInt as `"5n"`), scrubs sealed addresses and cuts to 2,000; nothing a log holds throws out of an adapter | `14.error-shapes` (a cycle, a BigInt and a 20-level shared graph from an inline widget and from an MCP Apps view, each reported as bounded text); `test/log-bounds.test.ts` (undeclared or past its rate: nothing of it read) | `report-unbounded` → `14.error-shapes`, `14.silent` (its blocked-load report read as the text it was), on both host pages (P096) |
|
|
977
969
|
| 12 | model context (`setModelContext`, S5, P100) | the `show` gate by default: the bridge hands the host's `show` the whole update (text blocks rebuilt, structured content P095's JSON data, at most `MAX_CONTEXT_CHARS`, no character the person can't see: format characters, variation selectors, private use, lone surrogates, controls but `\n` and `\t`, save the selectors and joiners of real emoji and the joiners that shape Arabic, Indic and Myanmar letters) after every other gate and before the handler; no `show`, or one that throws, refuses it (`no-show`, `not_allowed`), and `close` ends its wait; the manual calls it the content's unconfirmed text, never instructions, and says what is refused; the React provider's default `show` draws `ContextNotice`, whole, and lets a call go once its own update is on the page (one replaced before it was drawn is refused); named gates without `show` and without `withoutShow: true` earn a `ConfigWarning` | `12.model-context` (a raw `ui/update-model-context`: shown whole, then handled; a host without `show`: refused, no handler); `test/model-context.test.ts` (both adapters, the order, the shapes, the size, each invisible character in text, values and keys, the warning); `leak/react.spec.ts` (the default notice is drawn before the handler runs, with its size; two updates in one task: only the drawn one goes; stacked displays all reachable; no provider: refused) | `model-context-show` → `12.model-context` (all three, `scripts/controls.ts`; the kit's harness is built unweakened), and both React cases (measured on Chromium) |
|
|
978
970
|
|
|
979
|
-
Measured: a click in the frame gives the host page user activation (it propagates to
|
|
980
|
-
|
|
981
|
-
clicks
|
|
982
|
-
|
|
983
|
-
for that to lapse and
|
|
971
|
+
Measured: a click in the frame gives the host page user activation (it propagates to ancestors) on
|
|
972
|
+
Chromium, WebKit and Firefox, so the host-side gesture check (`copyText`'s, and any a host names)
|
|
973
|
+
holds for real clicks. It stays advisory: the person may have clicked the host a moment before.
|
|
974
|
+
Playwright's own page evaluations count as gestures, so the gate probes (`12.copy-text`,
|
|
975
|
+
`12.raw-copy`; `shell-gesture` → copy-text, `host-gesture` → raw-copy) wait for that to lapse and
|
|
976
|
+
click with raw input.
|
|
984
977
|
|
|
985
978
|
### Served content, each with its test
|
|
986
979
|
|
|
987
980
|
| What | Mechanism | Tests (all three engines unless noted) | Negative control → fails |
|
|
988
981
|
|------|-----------|-------|------------------|
|
|
989
982
|
| The host's check (P050) | `authorize.check` after a ticket or cookie verifies, before anything is served; a deny is a 403 page saying `denied` and the host's code, and the display's `outcome` says so (after `loaded` too in url mode; a served display that isn't nested is told by its next run's door, which takes a fresh ticket, P125) | `leak/served/authorize.spec.ts`: a revoked subject's ticket (a page, an app); a framed app's next request and reload mid-session (Chromium, Firefox: WebKit keeps no framed cookie, P025); a framed page's next load (every engine: its next run's door); an app and a page in a tab | `authorize` → every case but WebKit's framed app (no framed cookie) |
|
|
990
|
-
| Who may say how loading went (P124, P125) | a frame status (`porthole/notifications/frame-status`) draws the host's fallback, so it is taken only where content can't have said it. **A served display
|
|
983
|
+
| Who may say how loading went (P124, P125) | a frame status (`porthole/notifications/frame-status`) draws the host's fallback, so it is taken only where content can't have said it. **A served display** (a served shell, a page, a view through the sandbox proxy) is framed on its scope's origin, where the scope's others run content: **no frame status from its frame is ever taken** (one `frame-status` host error a run), and its silence is a `timeout`, never `framing`. Its **door** said how loading went first, from a frame of the host's that no content can reach (`open`, or `blocked` and why, P125). An **opaque frame**'s every status is the content's. A **url-mode app**'s is taken, as before (S6). A served location **without a door** (an older server) raises a `hostError` of kind `door` once a mount and is strict (no status taken) | `test/outcome.test.ts` ("who may say how loading went (P124)", "a served display takes no frame status from its frame (P125)", and through `createHost`: the door hand-off, a door block with its code, door silence, a restart's new door); `leak/served/siblings-status.spec.ts`: a same-scope sibling that injects, reloads, stops, wipes a display, attacks the proxy, or reaches for the door, each on all three; `leak/served/outcome.spec.ts`: a served shell's content, a served page, an opaque widget and a nested page each say `blocked` and are shown nothing (the opaque and served-non-nested cases are the ordering rule / the door rule; the opaque rule 1 is proven by `test/outcome.test.ts` only, P124-3; the door's opacity, its namelessness and the sibling's navigation flag by the static sandbox test and `[door-reach]`) | `content-status` → the two served-content cases, `[sibling-inject]`, `[sibling-reload]`, `[proxy]`; `door-status` → `[sibling-inject]`, `[sibling-reload]`, `[proxy]`; `door-silence` → `[sibling-wipe]`; `door-opaque` → `[door-reach]`; `frame-status-order` → the nested case |
|
|
991
984
|
| Url-mode delegation (P049) | `allow` from `permissions`, `""` by default | `leak/served/permissions.spec.ts`: full screen follows it on all three; clipboard writes on Chromium only (WebKit and Firefox let any frame write in a click) | `url-permissions` → the default case (all three) |
|
|
992
985
|
| Siblings on the content domain (P101) | over https only `__Host-porthole-` names are read (a sibling sets any other name for the whole domain, never a `__Host-` one), names trimmed of spaces and tabs only; the entered mark is its label's and path's, read from a nonce cookie only; a url-mode app's request rides its cookie only from its own origin (`Origin`; `Sec-Fetch-Site` `same-origin` or `none`) or as a GET/HEAD navigation, else a 403 before the upstream and the host's check; a socket (`access`, `nodeHost`'s `appSocket`, a Worker's upgrade path) from its own origin only | `test/siblings.test.ts` (planted names, the mark on another label, every kind of request and socket, `nodeHost` over a real socket); `test/workers.test.ts` (workerd: a sibling's POST and socket refused, the app's own open); `served.url.siblings`: another app's frame (Chromium, Firefox: WebKit keeps no framed cookie, P025) or tab loading the app's script is refused, its own loads; `leak/kit.spec.ts`: the app's own WebSocket opens through `nodeHost`, a same-site sibling's doesn't; prod shape: a session copied under an unprefixed name and planted with `Domain=` opens nothing, and the socket case over wss | `url-origin` → `served.url.siblings` on the reference serving (Chromium, Firefox; its labels are cross-site on `*.localhost`, so only the framed half rides a cookie) |
|
|
993
986
|
| Porthole's libraries (P079) | `egress.libraries` (domain isolation; on in `presets.liveWidget`): `script-src <content origin>/__porthole/lib/`; `/server` serves Chart.js 4.5.1 and D3 7.9.0, npm's bytes, on every content origin, without a ticket, immutable | `test/libraries.test.ts` (npm's bytes, pinned, licenses; headers; nothing else under the path); `leak/served/live.spec.ts` (both load and draw in a live widget whose every other load and fetch reaches no oracle) | — (rows 1–2) |
|
|
@@ -1006,26 +999,18 @@ for that to lapse and click with raw input.
|
|
|
1006
999
|
| The runtime: comments write-only (P090) | the bridge answers `comments` with `true` only for a handler's `true`; no read method | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "comments are write-only" | `comments-result` → that case (all three) |
|
|
1007
1000
|
| The runtime: a comment's draft is visible text (P108) | the bridge refuses a draft that isn't a string, is blank, past 2,000 characters, or holds what a person can't see (`unseen`), before any handler | `test/runtime.test.ts`: "a draft (P108)"; `leak/served/runtime.spec.ts`: "a comment's draft is the host's to check" | `comment-draft` → that case (all three) |
|
|
1008
1001
|
| The runtime: a draft is visible text, strictly; the anchor beside it cleaned (P109) | a draft with a joiner (U+200C, U+200D) anywhere but between two letters or marks (first, last, doubled, beside a space or punctuation, in an emoji sequence), a line or paragraph separator, blank-looking text, more than 32 blanks or two blank lines in a row is refused; the label and quote lose what a person can't see, refused if nothing visible is left | `test/runtime.test.ts`: "a draft is visible text, strictly (P109)" | — (unit-tested: the bridge's own check, behind `comment-draft`'s) |
|
|
1009
|
-
| The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
|
|
1010
|
-
| The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
|
|
1011
|
-
| A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows), asking the shell to look as it hears the move; where the host's page sees the pointer over its frames, not with the pointer elsewhere within a second of typing; in a fight over a text field, a frame that takes focus again is judged without the shell and taken back at once, counted (P120); no press within 250 ms of the person's key on the host's page (P122) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three); `pointer-rule` (P120's pointer rule out) → "an activation that came as the person typed…" (all three); `key-press` (P122's 250 ms out) → "an activation that turned on within 250 ms of the person's key…" (all three); `nested-fight` (a frame that takes focus back in a fight let be) → "a page that holds the keyboard from its load…" (Firefox); `leak/served/nested-keyboard.spec.ts` (a page that takes the keyboard as the person types: a race, no control's probe) |
|
|
1012
|
-
| A nested page's real presses, told to its shell (P148) | the shell sends its page a `MessagePort` at each load and hears only the last load's; the page's runtime takes it before content runs (the first listener, capturing; the browser's own message, from the parent read at start, exactly one port; the event stopped) and tells on it only the browser's own events: a mouse down, a finger or pen up, Enter or Space not held on a native control that isn't editable (by tag and type, never `role`), a click on one, but none while a key is down nor a form's own for Enter in a field; installed only under a nested page's plan and only if `document.open`, `write` and `writeln` are fixed shut; the host takes a press told as an activation that turned on (a second, no press or key on its page since, P120's and P122's rules, not within 500 ms of a stall of the shell) | `test/nested.test.ts` "the page's real presses, told to the shell over a port"; `leak/served/nested-press.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `press-untrusted`, `press-role`, `press-editable`, `press-repeat`, `press-key-click`, `press-submit` (with `press-key-click`), `press-touch-down` (Chromium), `press-port-heard`, `press-port-forged` (Chromium, WebKit), `press-open-lock`, `press-still-here` (WebKit), `press-host-input`, `shell-stall` |
|
|
1013
|
-
| A nested page's shell passes the focus on at the host's word (P136) | `display.focus()` sends `porthole/shell/focus`, only a move that landed; the shell acts only while the focus is on its own document, blurring its frame first, and a page's message in its namespace never reaches that code | `test/nested.test.ts` "the host's word that it moved the focus into a nested page's frame"; `leak/served/nested.spec.ts`: "a page that had the focus gets it back by the host's own move…", "a page that never had the focus…", "a second host's move into a page it just handed the focus to…", "the host's move into a page that holds the focus…", "the host's move from its own text field…", "the host's move takes no keyboard…", "the host's move from inside a key's own handler…" (`test.fail` on Firefox) | `shell-focus-held` |
|
|
1014
|
-
| A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket; outside `/server` too (P121), `createHost` refuses a nested page located on any other label, the shell runs on no other origin, and `nestedShellResponse` and `frameShellScript` refuse one; `nestedFileCsp` is the page's and its files' CSP for `/server` and a Worker of a host's own | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"; `test/nested.test.ts` "… (P121)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell; `[nested-label]`: a nested page located on its scope's label is refused, no frame made) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label,nested-host-label,nested-shell-origin` (the shell on the scope's label, the host's and the shell's checks out) → `[nested-siblings]`, `[nested-label]` (all three); `nested-host-label` (the host's check out) → `[nested-label]` (all three) |
|
|
1015
1002
|
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
1016
1003
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
1017
|
-
| An embedded document (P143) | grant `embed` (only with the server's `embeds: true`, anonymous, no level or user, an artifact's page
|
|
1004
|
+
| An embedded document (P143) | grant `embed` (only with the server's `embeds: true`, anonymous, no level or user, an artifact's page; signed into the session as `m` and into the sealed address) → `frame-ancestors *` for that session's answers alone (its document, a file set's pages and files and own frames, assets, renewals, its status and ended-access pages); an embed session's cookie has a name of its own (`e-<key>`) and never stands in for another session; the plan names no host (`origins: []`): the shell asks no host, ends its handshake at once (`"none"`), says nothing to any parent (no `*` notices, no annotation or find report) and hears no one; no door; `statusPage` and `doorStatusResponse` take `embed` (`*`, `data-porthole-hosts="[]"`); the host kit refuses an `access` answer with `embed` (P145: minted through `host.server.issue` alone) | `test/embed.test.ts` (refused without `embeds`, with a viewer, a level or a user, for url mode, a nested display, a served shell or the proxy, at a clean address and at the door; the host kit refuses it from `access` at its issue endpoint, a clean address's resolve and its tab, with `embeds` or without; the flag can't be added or stripped, nor a session moved to the other name; **the bound**: 23 kinds of answer under an embed session say `*` and name no host, and the same under a public and a viewer's session are byte for byte what a server without `embeds` answers, on the same server while an embed session of the same artifact exists, and with both cookies sent; the host's check is told `embed`; cookies host-only, never `Domain=`); `test/shell.test.ts` (P143's handshake); `leak/served/embed.spec.ts`: `[embed.loads]`, `[embed.unheard]` (the words before the document loads too, P145), `[embed.untold]`, `[embed.no-escape]`, `[embed.reader-unframeable]` | `embed-ancestors` → `[embed.reader-unframeable]`; `embed-handshake` → `[embed.untold]`; `embed-origins` → `[embed.unheard]` (all three) |
|
|
1018
1005
|
|
|
1019
1006
|
### The clipboard, and copy buttons
|
|
1020
1007
|
|
|
1021
|
-
Content never writes the clipboard (P051). The frame's `allow` denies
|
|
1022
|
-
`clipboard-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
writes the clipboard, inside the person's click (a click in a frame activates its
|
|
1028
|
-
ancestors), and shows them what went on it.
|
|
1008
|
+
Content never writes the clipboard (P051). The frame's `allow` denies `clipboard-read` and
|
|
1009
|
+
`clipboard-write` by name. The shell makes the async Clipboard API (`write`, `writeText`, `read`,
|
|
1010
|
+
`readText`) and `execCommand`'s `copy`, `cut` and `paste` refuse, and stops copy and cut events at
|
|
1011
|
+
the window before any content listener, so the person's own copy copies their selection as the
|
|
1012
|
+
browser makes it. Copy buttons call `copyText(text)` (P052): the host's page writes the clipboard
|
|
1013
|
+
inside the person's click (a click in a frame activates its ancestors) and shows what went on it.
|
|
1029
1014
|
|
|
1030
1015
|
| # | Channel | Mechanism | Probes | Negative control → fails |
|
|
1031
1016
|
|---|---------|-----------|--------|--------------------------|
|
|
@@ -1034,342 +1019,234 @@ ancestors), and shows them what went on it.
|
|
|
1034
1019
|
| 13 | a copy listener swapping what the person copies (`clipboardData.setData`) | copy and cut events stopped at the window, first | `13.clipboard-event` (the person's own copy works: positive control) | `clipboard` → all three |
|
|
1035
1020
|
| 12 | `copyText` | a click (shell and host), 30 a minute, the host's handler | `12.copy-text` (refused on load; the whole text reaches the handler from a click) | — |
|
|
1036
1021
|
|
|
1037
|
-
Measured before the walls
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
that care point people at copy buttons, whose toast shows exactly what was copied.
|
|
1022
|
+
Measured before the walls: a click in an opaque widget wrote the clipboard on all three engines (the
|
|
1023
|
+
async API on WebKit and Firefox, the copy command and copy listeners everywhere). The oracle is the
|
|
1024
|
+
person's clipboard: copied on the host's page, then pasted back there. Not stoppable: text hidden by
|
|
1025
|
+
CSS inside what the person selects goes with their copy (the browser's own); hosts that care point
|
|
1026
|
+
people at copy buttons, whose toast shows exactly what was copied.
|
|
1043
1027
|
|
|
1044
|
-
|
|
1028
|
+
## Annotations
|
|
1045
1029
|
|
|
1046
|
-
A person points at part of a display to comment on it (P053).
|
|
1047
|
-
|
|
1048
|
-
|
|
1049
|
-
|
|
1030
|
+
A person points at part of a display to comment on it (P053). Where the config declares `annotate`
|
|
1031
|
+
(inline widgets and artifact pages; MCP Apps views where the host chooses), the annotation runtime
|
|
1032
|
+
is in the shell; the host drives it with Porthole's own messages and it reports back. Wiring and
|
|
1033
|
+
host duties: [ADOPTING.md § Annotations](ADOPTING.md#annotations-comments-on-a-display). What a page
|
|
1034
|
+
can learn or fake: [THREAT_MODEL.md § 7](THREAT_MODEL.md#7-the-display-layer-and-the-app-runtime).
|
|
1050
1035
|
|
|
1051
1036
|
| Direction | Message | Params |
|
|
1052
1037
|
|-----------|---------|--------|
|
|
1053
|
-
| host → frame | `porthole/annotate.start` | `{ elements, text, keepSelection? }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects); `keepSelection: true
|
|
1038
|
+
| host → frame | `porthole/annotate.start` | `{ elements, text, keepSelection? }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects); `keepSelection: true`: the host will follow what is selected, so the frame keeps it, and a pick's outline (P140) |
|
|
1054
1039
|
| host → frame | `porthole/annotate.stop` | — |
|
|
1055
|
-
| host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn
|
|
1040
|
+
| host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn in the shell's own layer, found again whenever the content changes; a `count` (0 to 999; the host clamps a larger one, P116) gives a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
|
|
1056
1041
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
1057
1042
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1058
|
-
| host → frame | `porthole/annotate.clearSelection` | —: the page's text selection is taken away (the DOM's own `removeAllRanges`, taken before content runs) with what the shell held of it
|
|
1059
|
-
| host → frame | `porthole/annotate.focusMark` | `{ id, at }`, `at` the host's `Date.now()` as it sent it
|
|
1060
|
-
|
|
|
1043
|
+
| host → frame | `porthole/annotate.clearSelection` | —: the page's text selection is taken away (the DOM's own `removeAllRanges`, taken before content runs) with what the shell held of it; nothing is reported back; marks, drafts and the mode stay (P115) |
|
|
1044
|
+
| host → frame | `porthole/annotate.focusMark` | `{ id, at }`, `at` the host's `Date.now()` as it sent it: the DOM focus goes to that mark's marker once the marks of a `show` are found. Dropped if it had to wait and the focus isn't in the frame's document as it lands (the DOM's own `hasFocus`, P135), if the frame takes it 100 ms or more after `at` by its own clock (the DOM's own `Date.now`), or with no `at` (P137); the built-ins are taken before content runs. Nothing is reported back; with no such marker, or while elements are picked, nothing happens. For after the keyboard closed the host's view: Escape, or a Tab past its ends (P134) |
|
|
1045
|
+
| host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112); `{ id: null, selection: true }`: follow the selection last reported as `selected`, highlighted while followed (P138; an older shell reads it as none) |
|
|
1046
|
+
| frame → host | `porthole/annotate.selected` | `{ anchor, rect, lastLineDocumentRect?, scroll?, pointDocument? }` (`lastLineDocumentRect` and `scroll` only as a pair, P133, P137; `pointDocument` only on an element pick, and with `scroll`, P150); after a scroll, sent again only if its box moved more than 0.5 px, on the follow-ups' clock (P105), and not while the host follows the selection (P138) |
|
|
1061
1047
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1062
1048
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
1063
|
-
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, lastLineDocumentRect?, order? }], scroll? }
|
|
1064
|
-
|
|
|
1065
|
-
| frame → host | `porthole/annotate.
|
|
1066
|
-
| frame → host | `porthole/annotate.
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
`
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
(
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
`
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
the
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
the
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
dashed underline (a dashed outline on an element), a lighter fill, and a hollow
|
|
1182
|
-
marker (a light bubble with a dashed edge and the glyph's outline) with no number.
|
|
1183
|
-
`checkMarks` sends a posted mark as before (no `kind`), a draft without its count,
|
|
1184
|
-
and throws on any other kind; the shell draws no number for a draft and drops a
|
|
1185
|
-
mark of a kind it doesn't know. Its click is `activated`, its place `anchored`,
|
|
1186
|
-
and it is followed after a scroll, as a posted marker's.
|
|
1187
|
-
- **Following** (P104), only while a mark has a marker (a `count`, or a draft:
|
|
1188
|
-
P107). Each mark keeps what the host was last told (state and box); a settled
|
|
1189
|
-
scroll or resize (any scroller), or
|
|
1190
|
-
a quiet run of content changes (one the deadline cut short is checked once quiet),
|
|
1191
|
-
reports only what moved. A selection the host was told is told again after a
|
|
1192
|
-
settled scroll only if its box moved (P105, with or without counts). Both share one
|
|
1193
|
-
clock, at most one report a second (the latest), so honest scrolling takes at most
|
|
1194
|
-
half of the bridge's 120 a minute.
|
|
1195
|
-
- **Settled.** Nothing is reported before the content is in place (marks shown
|
|
1196
|
-
before it arrives are anchored once it has), nor while a run of changes settles; a
|
|
1197
|
-
`focus` asked for meanwhile waits for anchoring, then scrolls and reports, so a
|
|
1198
|
-
focus right after `show` says where the mark is, never `orphaned` first (P057).
|
|
1199
|
-
- **Trust.** The shell shares its realm with the content, which can interfere with
|
|
1200
|
-
all of it, read what `show` sends (ids, anchors, counts), or fake any report. The
|
|
1201
|
-
host takes a selection only while it asked for that kind, a cancel only while
|
|
1202
|
-
picking, results only for its own marks, a marker's click only for a mark it shows
|
|
1203
|
-
with a marker (a count or a draft) and only within a gesture (P105); it rebuilds
|
|
1204
|
-
each from known fields within `ANNOTATION_LIMITS` (a label without what the person can't see, P105) and
|
|
1205
|
-
drops the rest, through the bridge's rate limit. UI hints only, never
|
|
1206
|
-
permissions: what a report says decides where a comment is drawn, never who may
|
|
1207
|
-
see or do anything. A view a report opens or moves guards its presses
|
|
1208
|
-
(THREAT_MODEL §6).
|
|
1209
|
-
- **Host API.** `display.annotations.start(mode?)`, `stop()`, `show(marks)`,
|
|
1210
|
-
`focus(id)`, `track(id)`, `clear()`, `clearSelection()` (P115), `focusMark(id)` (P134), and the
|
|
1211
|
-
`annotation` event (`AnnotationReport`); the state is given to every frame the display runs (not a
|
|
1212
|
-
`clearSelection`: a new frame has no selection; nor a `focusMark`). `parseAnchor` checks an anchor a host
|
|
1213
|
-
stores (its server, before saving a comment).
|
|
1214
|
-
|
|
1215
|
-
Tests (`leak/annotate.spec.ts`, all three engines): a pick outlines and picks
|
|
1216
|
-
without the content seeing the click, by id or by path; Escape cancels; a text
|
|
1217
|
-
selection and its clearing; both modes together; marks shown, one focused into
|
|
1218
|
-
view, one orphaned, all cleared; re-anchoring on a revised page (by id, by words
|
|
1219
|
-
moved, by words respaced, one deleted and orphaned); live changes reported only as
|
|
1220
|
-
they change; an MCP Apps view; and a hostile page faking every report (not asked,
|
|
1221
|
-
malformed, too large, the wrong kind, no such mark, a flood), whose negative
|
|
1222
|
-
control is `annotation-checks`. Markers (P104): drawn with their numbers, a click
|
|
1223
|
-
reported with its id and box and heard by none of the content's listeners, nor a
|
|
1224
|
-
double, right or middle click (`marker-click` → those two cases), by the keyboard
|
|
1225
|
-
too (P133: a button in reading order and named for what it is, Enter and Space
|
|
1226
|
-
reported once, a key held down once, none of it heard, nothing while elements are
|
|
1227
|
-
picked; `marker-key`, `marker-click` too), brought into view by the focus and keeping
|
|
1228
|
-
it through redraws, reached by the host's `focusMark` after its card closed and left
|
|
1229
|
-
alone where there's no such marker, by the kept `focus` (P134, `marker-focus`), a call parked meanwhile
|
|
1230
|
-
dropped once the person has moved on or the focus is on the host's body, and a second after the
|
|
1231
|
-
host's `display.focus()` landing (P135, `marker-late`), by the kept
|
|
1232
|
-
`hasFocus`, which a page's patch can't answer (`marker-has-focus`), a word a busy page takes late
|
|
1233
|
-
held to the same test, by the host's stamp and the kept clock, a calm close landing, and a second
|
|
1234
|
-
word after the host's move landing (P137, `marker-busy`, `marker-clock`, in
|
|
1235
|
-
`nested-late-word.spec.ts` so that full Chromium runs it, where a person's click comes before the
|
|
1236
|
-
word); on a nested page a parked call lands while the focus is in the page, not once the person has
|
|
1237
|
-
moved on (`marker-late`), a late word not either (`marker-busy`), and after
|
|
1238
|
-
the host's move, which the shell passes on (P136, `shell-focus-held`; on Firefox not from inside a
|
|
1239
|
-
key's own handler, `test.fail`), at its paragraph's end past the last word, a nested block's
|
|
1240
|
-
words not its own, a draft's by its words; focus and
|
|
1241
|
-
selection kept, a drag from a marker too (`marker-prevent` → the press case), none
|
|
1242
|
-
without a count, stepping aside while picking, drawn whole at the frame's top; a
|
|
1243
|
-
run of scrolls reported with only the marks that moved, a fixed one never; marks
|
|
1244
|
-
without counts told nothing after a scroll (`follow-count`); a long honest scroll
|
|
1245
|
-
session in comment mode, a selection made, leaving a marker's click its budget,
|
|
1246
|
-
and then, by when each arrives, the selection's re-reports and the marks'
|
|
1247
|
-
follow-ups a second apart however fast the machine (`follow-throttle`,
|
|
1248
|
-
`selection-follow`); a content change that moves one mark
|
|
1249
|
-
reports it alone, even when the deadline cut its run short; a hostile page faking a
|
|
1250
|
-
marker's click for no mark, an unknown id or a mark without a marker, or clicking
|
|
1251
|
-
the layer itself (`annotation-activated`, `annotation-activated-count`,
|
|
1252
|
-
`marker-trusted` → that case), or by itself, without a gesture
|
|
1253
|
-
(`annotation-activated-gesture`); and a page that patches `Event`'s and
|
|
1254
|
-
`MouseEvent`'s prototypes neither hearing a marker's press nor stopping its report
|
|
1255
|
-
(`marker-originals`; `marker-click` too); a tap on a marker reported on each
|
|
1256
|
-
engine, a touch screen and a phone's emulation (iPhone 13, Pixel 5), content hearing
|
|
1257
|
-
none of it (`marker-click`); on a 640 px column and a phone page's lines
|
|
1258
|
-
with one marker each, no marker covering a word (`marker-place`, the marker just
|
|
1259
|
-
past its words as 0.9.0 had it, which a draft's in a line's middle shows); drafts (P107) drawn apart from posted marks on the
|
|
1260
|
-
same anchors (the frame's pixels and the words' own differ; on Chromium every draft's
|
|
1261
|
-
marker and line drawn as a draft's, no number though given a count), a draft's and a
|
|
1262
|
-
posted marker's clicks reported beside each other, none reaching the content
|
|
1263
|
-
(`marker-click` too), the
|
|
1264
|
-
page reading a draft's kind and never its count (`draft-count`), a raw `show` past
|
|
1265
|
-
`checkMarks` drawing a draft given a count without a number and dropping a mark of
|
|
1266
|
-
an unknown kind (`draft-shell-checks`), and drafts alone followed after a scroll; and ADOPTING.md's `guardPresses`, as written
|
|
1267
|
-
there, taking no press within 500 ms of its view opening (a release on a menu item,
|
|
1268
|
-
a double click's second press on a button or a trigger, a press held past the
|
|
1269
|
-
arming) and the person's own press or key after. The host's `clearSelection` (P115) takes
|
|
1270
|
-
a selection away from a page that patched `Selection.prototype.removeAllRanges`, tells
|
|
1271
|
-
nothing back, leaves marks and drafts found, and the same words selected again are told
|
|
1272
|
-
(`clear-selection`).
|
|
1273
|
-
|
|
1274
|
-
### Find in page
|
|
1275
|
-
|
|
1276
|
-
A host's own find bar over a display (P131), where the config declares `find`:
|
|
1277
|
-
|
|
1278
|
-
- **Shell.** `FIND_RUNTIME` (`src/shell/find.ts`), spliced in as the annotation runtime is, before
|
|
1049
|
+
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, lastLineDocumentRect?, order? }], scroll? }`: every mark after `show`, the one after `focus`, every mark when the content changed a state; while any mark has a marker, once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
|
|
1050
|
+
| frame → host | `porthole/annotate.tracked` | `{ id, rect, documentRect?, lastLineDocumentRect?, scroll? }`: the followed mark's box at an animation frame where it moved, at most one every 16 ms; the host takes 60 a second, for that mark only (P112, P132, P133) |
|
|
1051
|
+
| frame → host | `porthole/annotate.selectionTracked` | `{ state: "attached", rect, documentRect, lastLineDocumentRect?, scroll, inView }` or `{ state: "orphaned" }`: the followed selection's boxes, as `tracked`'s, also when the viewport changed size, the first at the frame after the host asks; `orphaned` once while it isn't in the page, found again by its anchor at most twice a second. The host takes it only while it follows the selection (otherwise dropped unread, no refusal, P140), 60 a second with `tracked`, its `rect` clamped, `inView` false unless its box reaches the viewport (P138) |
|
|
1052
|
+
| frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker, or pressed Enter or Space on it (P133); `rect` is the marker's (P104); no gesture is asked of it (P149) |
|
|
1053
|
+
|
|
1054
|
+
- **Anchors** are W3C Web Annotation selectors, at most one of each: `CssSelector` (unique: the
|
|
1055
|
+
nearest id, else `nth-of-type` steps), `TextQuoteSelector` (the words, with 32 characters of
|
|
1056
|
+
context each side), `TextPositionSelector` (offsets into the body's text, without scripts, styles
|
|
1057
|
+
and templates). An element anchor has its selector and first 300 characters of text; a text anchor
|
|
1058
|
+
its words (at most 4,000), position and nearest element.
|
|
1059
|
+
- **Found again**, best-effort. A text anchor: where it was, else its words anywhere (the occurrence
|
|
1060
|
+
whose context matches best), else its words with any spacing. An element anchor: its selector if
|
|
1061
|
+
its text still starts with its words (or the selector is an id, or it has no words), else the
|
|
1062
|
+
element holding its words. Not found: `orphaned`; a host keeps the comment and shows it apart.
|
|
1063
|
+
- **Boxes.** `rect` is in the frame's viewport, CSS px (the host adds the frame element's position
|
|
1064
|
+
and maps it through the frame's transform). `createHost` clamps each `rect` to the frame's
|
|
1065
|
+
viewport (P104): a box wholly outside becomes a zero-size one on the nearest edge; a platform
|
|
1066
|
+
whose `viewport()` answers no size or throws gets nothing at the corner (P105). `documentRect`
|
|
1067
|
+
(P132) is the box plus the document's scroll as read (the report's `scroll`, `{ x, y }`, via the
|
|
1068
|
+
DOM's own `getBoundingClientRect`), so it places a mark outside the frame; `rect` is
|
|
1069
|
+
`documentRect` less `scroll`, before the clamp. `lastLineDocumentRect` (P133) is the last box with
|
|
1070
|
+
a width of the words' client rects (an element's whole box), same coordinates, for a host's UI
|
|
1071
|
+
after a selection or mark. `createHost` checks these as boxes (finite, within the coordinate
|
|
1072
|
+
limit, sizes not negative; a malformed one drops the report) and clamps neither: the host clips
|
|
1073
|
+
what it draws. `pointDocument` (P150), on an element picked by a pointer, is the point it was
|
|
1074
|
+
picked at (the click's or tap's, a held finger's press), plus `scroll`, as these are: for a host's
|
|
1075
|
+
UI where the element is larger than most of the frame. Checked as `scroll` is (two finite numbers
|
|
1076
|
+
within the limit), unclamped; one on a text selection, or without `scroll`, drops the report; a
|
|
1077
|
+
pick from the keyboard has none. A page scrolling a box of its own rather than its document moves
|
|
1078
|
+
its marks' places with it, as `rect`.
|
|
1079
|
+
- **The selection followed** (P138, P140). For a host that follows the selection, or said at `start`
|
|
1080
|
+
it will (`keepSelection`), the shell keeps what each `selected` reported (the element picked, or a
|
|
1081
|
+
copy of the range via the DOM's own `cloneRange`), updated through the page's changes and kept
|
|
1082
|
+
when the page's own selection goes. One thing is followed at a time: a mark's id, `null` or
|
|
1083
|
+
`clear` ends it; `show`, `stop` and a pick's end leave it. Followed, it is drawn in the layer (an
|
|
1084
|
+
element outlined, lighter, without its name; words with a light fill and an underline) and its
|
|
1085
|
+
boxes are told as a followed mark's, with `inView`. Boxes only: no focus moves, no selection
|
|
1086
|
+
changes, no listener added, nothing of the words sent. Under `keepSelection`, before a follow, a
|
|
1087
|
+
just-picked element keeps the same outline, so nothing changes on screen when the follow takes
|
|
1088
|
+
over; it ends as a selection does (the next pick or selection, `clearSelection`, `start`, `stop`,
|
|
1089
|
+
`clear`, Escape, the element leaving the page), on no timer. Ending a follow lets the kept
|
|
1090
|
+
selection go unless `keepSelection` holds; for other hosts nothing is kept and a pick's outline
|
|
1091
|
+
goes with the pick. The React binding sends the follow before a mode change in the same render,
|
|
1092
|
+
and starts the mode with `keepSelection` while `trackedSelection` is given (read at each start,
|
|
1093
|
+
never a reason for one).
|
|
1094
|
+
- **Markers** (P104, P133). A mark with a `count` gets a real `<button>`: a bubble glyph and its
|
|
1095
|
+
number ("99+" above 99; 0 the bubble alone), on an element's top right corner, or at the end of a
|
|
1096
|
+
text anchor's paragraph just past the last word of its last line, or failing that where a draft's
|
|
1097
|
+
goes. A draft's goes beside its own last line: in the gutter past the block's right edge, at the
|
|
1098
|
+
frame's right edge where the frame is too narrow, or just past the line's last word where
|
|
1099
|
+
something else is beside the block (P105, #36). Each place must be clear of the line's words and
|
|
1100
|
+
of anything of the content's but a box holding the anchor (the shell hit-tests it). Markers on one
|
|
1101
|
+
line go together in the order their words end; where the bubble doesn't fit its number alone does
|
|
1102
|
+
(compact); where neither fits they go over the line's end. Pointing at a marker lights its words;
|
|
1103
|
+
an element's mark with a marker is a thin line. Placing costs a bounded number of hit tests per
|
|
1104
|
+
marker in view, none out of view, and reads a line's end only as far as the line goes (P105: 300
|
|
1105
|
+
marks with counts in view, about 20 ms a change).
|
|
1106
|
+
- **The layer** is a closed shadow root, the document's last child, taking no pointer except on
|
|
1107
|
+
markers. A press on a marker, and pointer moves over it, are stopped in the shell's first window
|
|
1108
|
+
listener, read through built-ins kept before content runs (P105); a trusted click or a tap is
|
|
1109
|
+
reported `activated`. On touch (P119), while the last pointer down or moved was a finger or pen
|
|
1110
|
+
(before any, where `(any-pointer: coarse)` matches), each marker also takes the pointer in a box
|
|
1111
|
+
of at least 44 by 44 px centred on its bubble (an invisible `::before` in the layer), the nearest
|
|
1112
|
+
bubble's where two overlap; a mouse move takes the boxes away, so a mouse is hit-tested on bubbles
|
|
1113
|
+
alone. Content that patches no built-in hears none of a press; content that patches others can
|
|
1114
|
+
reach the layer's nodes (P105); either way it can tell a press happened (`:active`,
|
|
1115
|
+
`relatedTarget`, user activation). A pointer press moves no focus. Markers step aside while
|
|
1116
|
+
elements are picked, from Tab too.
|
|
1117
|
+
- **The keyboard** (P133, P134). Each marker has a tab stop after the page's own and a name
|
|
1118
|
+
(`aria-label`: `3 comments on "…"`, `Draft comment on "…"`, an element's tag left out, P134, in
|
|
1119
|
+
English); only markers are exposed to assistive technology. Enter and Space make the focused
|
|
1120
|
+
marker (the shadow root's `activeElement`, kept before content runs) give its own trusted click;
|
|
1121
|
+
those keys are stopped at the window, a held key clicks once, and every other key stays the
|
|
1122
|
+
page's. A real key gives the host's page transient activation as a click does. Focus on a marker
|
|
1123
|
+
lights its words and, out of view, scrolls the document to it (the layer clips rather than hides,
|
|
1124
|
+
so it never scrolls itself). While a marker has focus, a draw moves none and takes markers out of
|
|
1125
|
+
hit tests by `pointer-events`, not `display`. The host's own list of marks stays the keyboard path
|
|
1126
|
+
it can rely on.
|
|
1127
|
+
- **Drafts** (P107). A `kind: "draft"` mark has a marker with or without a count, placed by its own
|
|
1128
|
+
words, drawn apart: a dashed underline (a dashed outline on an element), a lighter fill, a hollow
|
|
1129
|
+
marker with no number. `checkMarks` sends a draft without its count and throws on an unknown kind;
|
|
1130
|
+
the shell draws no number for a draft and drops a mark of an unknown kind. Its click, place and
|
|
1131
|
+
following are a posted marker's.
|
|
1132
|
+
- **Following and budgets** (P104, P105, P057). Only while a mark has a marker (a count or a draft)
|
|
1133
|
+
does each mark keep what the host was last told; a settled scroll or resize (any scroller), or a
|
|
1134
|
+
quiet run of content changes, reports only what moved. A selection already told is told again
|
|
1135
|
+
after a settled scroll only if its box moved. One shared clock, at most one report a second, so
|
|
1136
|
+
honest scrolling takes at most half of the bridge's 120 a minute. Nothing is reported before the
|
|
1137
|
+
content is in place (earlier marks are anchored once it is) or while changes settle; a `focus`
|
|
1138
|
+
asked meanwhile waits, so a focus right after `show` is never `orphaned` first.
|
|
1139
|
+
- **What the host takes** (THREAT_MODEL.md § 7 says what a page can fake). A selection only while it
|
|
1140
|
+
asked for that kind, a cancel only while picking, results only for its own marks, a marker's click
|
|
1141
|
+
only for a mark it shows with a marker, gesture or not (P149); each rebuilt from known fields
|
|
1142
|
+
within `ANNOTATION_LIMITS` (a label stripped of what the person can't see, P105), the rest
|
|
1143
|
+
dropped, at the bridge's rate. A report places a comment, never decides who may see or do
|
|
1144
|
+
anything.
|
|
1145
|
+
- **Host API.** `display.annotations.start(mode?)`, `stop()`, `show(marks)`, `focus(id)`,
|
|
1146
|
+
`track(id)`, `clear()`, `clearSelection()`, `focusMark(id)`, and the `annotation` event
|
|
1147
|
+
(`AnnotationReport`). The state goes to every frame the display runs (not `clearSelection` or
|
|
1148
|
+
`focusMark`). `parseAnchor` checks an anchor a host stores.
|
|
1149
|
+
|
|
1150
|
+
Tests (`leak/annotate.spec.ts`, and `leak/late-word.spec.ts` for a word a busy page takes late,
|
|
1151
|
+
which full Chromium runs too; all three engines): picking and selecting unseen by the content; marks
|
|
1152
|
+
shown, focused, orphaned and found again on a revised page; follow-ups only for what moved, within
|
|
1153
|
+
budget; markers clear of words, reported by click, tap and key, heard by none of the content, also
|
|
1154
|
+
against patched built-ins; `focusMark` landing only when it should; drafts drawn apart; the
|
|
1155
|
+
selection followed; `clearSelection` against a patched `removeAllRanges`; a hostile page faking
|
|
1156
|
+
every report; and ADOPTING.md's `guardPresses`, as written there, taking no press within 500 ms of
|
|
1157
|
+
its view opening and the person's own press or key after. Negative controls: § The negative
|
|
1158
|
+
controls.
|
|
1159
|
+
|
|
1160
|
+
## Find in page
|
|
1161
|
+
|
|
1162
|
+
A host's own find bar over a display (P131), where the config declares `find`. Wiring: [ADOPTING.md
|
|
1163
|
+
§ Find in page](ADOPTING.md#find-in-page-the-hosts-find-bar). What the page learns: [THREAT_MODEL.md
|
|
1164
|
+
§ 7](THREAT_MODEL.md#7-the-display-layer-and-the-app-runtime).
|
|
1165
|
+
|
|
1166
|
+
- **Shell.** `FIND_RUNTIME` (`src/shell/find.ts`) is spliced in like the annotation runtime, before
|
|
1279
1167
|
content runs. It finds a query (`porthole/find.query`, a request) in annotations' text index
|
|
1280
1168
|
(`TEXT_INDEX`, `src/shell/text.ts`, shared), case-insensitive and loose about spacing
|
|
1281
|
-
(`FIND_MATCH`),
|
|
1282
|
-
|
|
1283
|
-
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
(
|
|
1288
|
-
`callOf`; its layer goes in
|
|
1169
|
+
(`FIND_MATCH`), drawn matches only, at most 1,000. It draws them in a layer of its own (a closed
|
|
1170
|
+
shadow root, annotations' layer style; never the CSS Custom Highlight API, which the content can
|
|
1171
|
+
read and rewrite), the current one apart, redrawn on scroll and resize and found again as content
|
|
1172
|
+
changes (`porthole/find.updated`, at most once a second), and brings the current one into view
|
|
1173
|
+
through its scrolling ancestors and the window. While the host says it draws its own bar
|
|
1174
|
+
(`porthole/find.handled`), it cancels the browser's find on a Cmd+F or Ctrl+F the page didn't take
|
|
1175
|
+
(`FIND_SHORTCUT`) and says `porthole/find.requested`. Like the guards (P129), it and the text
|
|
1176
|
+
index call only built-ins captured before content runs, through `callOf`; its layer goes in
|
|
1177
|
+
through the guarded insertion methods (P130,
|
|
1289
1178
|
[insertion-entry-points.md](insertion-entry-points.md) § The shell's own layers).
|
|
1290
1179
|
- **Host API.** `display.find.query(query, { direction, caseSensitive })` → `{ total, active,
|
|
1291
|
-
capped?, rect? }
|
|
1292
|
-
answer
|
|
1293
|
-
latest
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
|
-
and
|
|
1298
|
-
- **Trust.** The page reads every query; what it says back is a find bar's numbers.
|
|
1299
|
-
`test/find.test.ts
|
|
1300
|
-
|
|
1301
|
-
|
|
1302
|
-
|
|
1303
|
-
|
|
1304
|
-
|
|
1180
|
+
capped?, rect? }`, or `"unsupported"` (no `find`, an older shell's `-32601`, a malformed answer,
|
|
1181
|
+
no answer within `FIND_LIMITS.timeoutMs`, a query superseded: the shell searches only a burst's
|
|
1182
|
+
latest, `FIND_LATEST`); `clear()`; `takeShortcut(take)`. A query holds only for the content it was
|
|
1183
|
+
asked of (a new run or other content forgets it). Events `findRequested` (only while taken, with
|
|
1184
|
+
the page's focus in the frame) and `findUpdated` (only while a query is shown), checked and
|
|
1185
|
+
rate-limited through the bridge. React: `onFindRequested`, `onFindUpdated`, the handle's `find`
|
|
1186
|
+
and `clearFind`.
|
|
1187
|
+
- **Trust and tests.** The page reads every query; what it says back is a find bar's numbers.
|
|
1188
|
+
`test/find.test.ts`: matching and its limits, the shortcut rule, the checks, the shell's splice
|
|
1189
|
+
and built-ins, only the latest query, `createHost`'s requests, answers, forgetting and gates, the
|
|
1190
|
+
React handle's scope. `leak/find.spec.ts` on three engines: highlights, next and previous into
|
|
1191
|
+
view, a scrolling box, a change found again, the shortcut the host's only while taken and the
|
|
1192
|
+
page's own find keeping it, and a hostile page's `requested` while the person types in the host's
|
|
1193
|
+
composer dropped (`find-requested-focus`).
|
|
1305
1194
|
|
|
1306
1195
|
## The shell runtime
|
|
1307
1196
|
|
|
1308
|
-
The runtime (`src/shell/runtime.ts`, plain ES2020, no build) runs first in every
|
|
1309
|
-
|
|
1310
|
-
|
|
1311
|
-
|
|
1312
|
-
|
|
1313
|
-
|
|
1314
|
-
|
|
1315
|
-
parsed with `DOMParser` and imported, its scripts recreated in order, then
|
|
1316
|
-
`DOMContentLoaded` and `load`), size and error reports, and link clicks sent out
|
|
1317
|
-
through `openLink`. A view that speaks for itself (`protocol: "none"`, MCP Apps) is
|
|
1318
|
-
rendered the same way from the plan, once the shell's document has loaded.
|
|
1197
|
+
The runtime (`src/shell/runtime.ts`, plain ES2020, no build) runs first in every frame it serves.
|
|
1198
|
+
Before any content: an in-memory `localStorage` (opaque frames), the WebRTC removal (item 3), the
|
|
1199
|
+
frame and hint guards (items 4, 8: the observer, the wrapped `attachShadow`, the synchronous
|
|
1200
|
+
insertion and attribute guards), and the closed parser entry points (P029). Then, when it speaks for
|
|
1201
|
+
the content: the handshake, the theme (P028), the content (§ Streaming), size and error reports,
|
|
1202
|
+
link clicks sent out through `openLink`. A view that speaks for itself (`protocol: "none"`, MCP
|
|
1203
|
+
Apps) is rendered the same way from the plan once the shell's document has loaded.
|
|
1319
1204
|
|
|
1320
1205
|
## Streaming
|
|
1321
1206
|
|
|
1322
|
-
Agents write a widget
|
|
1323
|
-
|
|
1324
|
-
|
|
1325
|
-
|
|
1326
|
-
|
|
1327
|
-
|
|
1328
|
-
|
|
1329
|
-
|
|
1330
|
-
|
|
1331
|
-
test asserts: markup appears as it streams, no script or handler runs until the
|
|
1332
|
-
code is whole, then runs exactly once.
|
|
1207
|
+
Agents write a widget over seconds, so the shell renders it as it grows (PRINCIPLE 10; the manual
|
|
1208
|
+
tells the agent to order it styles → markup → scripts). While incomplete, the **markup is drawn
|
|
1209
|
+
inert**: parsed in a `<template>`, stripped of what runs or navigates (`script`, frames, `on*`
|
|
1210
|
+
handlers, `javascript:` URLs), changing only what changed, so an image doesn't reload and an
|
|
1211
|
+
animation doesn't restart. When complete, the draft is dropped and the content runs once: a fragment
|
|
1212
|
+
parsed in a template, or a document parsed with `DOMParser` and imported (then `DOMContentLoaded`
|
|
1213
|
+
and `load`), its scripts recreated in order, external ones awaited. Partial input never runs code.
|
|
1214
|
+
The adapter carries this as MCP Apps `tool-input-partial` (0..n) then `tool-input` (once). Tested by
|
|
1215
|
+
`11.streaming` (§ Behavior and gates).
|
|
1333
1216
|
|
|
1334
1217
|
## Theme and base styles
|
|
1335
1218
|
|
|
1336
|
-
The
|
|
1337
|
-
`--color-
|
|
1338
|
-
`--
|
|
1339
|
-
|
|
1340
|
-
|
|
1341
|
-
(`
|
|
1342
|
-
|
|
1343
|
-
|
|
1344
|
-
|
|
1345
|
-
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
|
|
1349
|
-
|
|
1350
|
-
document (an artifact page) takes the person's scheme only when it declares it
|
|
1351
|
-
supports both, `<meta name="color-scheme" content="light dark">`, or the host sets
|
|
1352
|
-
`theme.documents: "always"`; otherwise it shows as its author styled it (P039).
|
|
1219
|
+
The vocabulary is the MCP Apps style variables (`--color-background-*`, `--color-text-*`,
|
|
1220
|
+
`--color-border-*`, `--color-ring-*`, `--font-*`, `--border-radius-*`, `--border-width-regular`,
|
|
1221
|
+
`--shadow-*`) plus Porthole's `--color-accent(-soft)` and chart palette (`--color-chart-1…8`,
|
|
1222
|
+
`-seq-1…7`, `-neg/-mid/-pos`), each with a neutral light and dark default
|
|
1223
|
+
(`src/theme/variables.ts`). A host supplies live values for the same names from its tokens
|
|
1224
|
+
(`HostOptions.theme`); `resolveTheme` takes the host's value per declared name, else the default,
|
|
1225
|
+
and drops undeclared names; `null` in a preset's theme drops a default. On a flip the shell applies
|
|
1226
|
+
them in place and fires the theme event; the host's values are read two frames after the flip, so a
|
|
1227
|
+
host restyling on its next frame is read after it has (`refreshTheme()` reads again, P043). Base
|
|
1228
|
+
styles set the body's type and color from the variables; base styles for native form elements
|
|
1229
|
+
(buttons, inputs) are the only further look Porthole adds, as plain CSS (P015). A whole document (an
|
|
1230
|
+
artifact page) takes the person's scheme only if it declares both, `<meta name="color-scheme"
|
|
1231
|
+
content="light dark">`, or the host sets `theme.documents: "always"`; otherwise it shows as its
|
|
1232
|
+
author styled it (P039).
|
|
1353
1233
|
|
|
1354
1234
|
## Guide generation
|
|
1355
1235
|
|
|
1356
|
-
The manual and
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1362
|
-
|
|
1363
|
-
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
|
|
1367
|
-
|
|
1368
|
-
|
|
1369
|
-
|
|
1370
|
-
|
|
1371
|
-
The `widget` topic's "The sandbox:" list states every limit that silently changes
|
|
1372
|
-
how content behaves, each one line derived from the config (`manualLimits`, P064):
|
|
1236
|
+
The manual and tool description are generated lazily from the same config, so they can't teach a
|
|
1237
|
+
variable the shell doesn't inject or a capability the CSP blocks (PRINCIPLE 3, 10). Topics: `widget`
|
|
1238
|
+
(what to pass, where it runs, sizes that read on a phone, what isn't allowed, the network in prose
|
|
1239
|
+
from the CSP's origins, the size limit, libraries when scripts may load, the color variables by
|
|
1240
|
+
group, diagrams); `chart` (form, look, size, libraries or hand-drawn SVG, the chart palette, marks,
|
|
1241
|
+
reading values); `interactive` (one entry per declared capability, its gates in words, and how state
|
|
1242
|
+
behaves under the isolation mode); and the host's own (`guide.topics`) for its tools. A sentence
|
|
1243
|
+
needing an undeclared variable, and an example using one, is left out. The examples
|
|
1244
|
+
(`GUIDE_EXAMPLES`) use only the default theme and no network; the leak suite renders each in the
|
|
1245
|
+
real sandbox at phone and desktop widths, light and dark, and asserts it reads (no overflow, text
|
|
1246
|
+
above a floor size), so the guide's examples are conformance cases.
|
|
1247
|
+
|
|
1248
|
+
The `widget` topic's "The sandbox:" list states every limit that silently changes how content
|
|
1249
|
+
behaves, one line each, derived from the config (`manualLimits`, P064):
|
|
1373
1250
|
|
|
1374
1251
|
| Limit | Says | Stated when | Checks (all three engines) |
|
|
1375
1252
|
|-------|------|-------------|----------------------------|
|
|
@@ -1389,157 +1266,78 @@ how content behaves, each one line derived from the config (`manualLimits`, P064
|
|
|
1389
1266
|
| `shell` | document.write/open throw; nested frames removed (with `nestedFrames: "own"`, P128: but `srcdoc` ones and frames of the page's own files); full screen and clipboard closed | always | `14.shell`, `4.document-write`, `4.light-dom`, `4.own-external` |
|
|
1390
1267
|
| `storage` (interactive topic) | per isolation; in domain mode reads and writes can throw: try/catch | always | `14.storage`, `served.domain.storage-scope` |
|
|
1391
1268
|
|
|
1392
|
-
Three more limits sit outside the list:
|
|
1393
|
-
- `layout` (where it runs): a card whose height follows its content, or `layout.kind:
|
|
1394
|
-
|
|
1395
|
-
|
|
1396
|
-
`
|
|
1269
|
+
Three more limits sit outside the list, config facts a whole-page viewer needed (P065):
|
|
1270
|
+
- `layout` (where it runs): a card whose height follows its content, or `layout.kind: "fill"`: every
|
|
1271
|
+
mount fills its container (`MountOptions.fill`, React `fill`), and the manual says the page fills
|
|
1272
|
+
the app's viewer (as tall as that, often smaller than the window), that `position: fixed` and
|
|
1273
|
+
`sticky` work, and to read the frame's own width, phone width first; it drops the card's height
|
|
1274
|
+
cap and the "no `position: fixed`" line. Checks: `11.size`, `14.fill`.
|
|
1275
|
+
- `theme` (where it runs): the person's theme, a page that declares it, or `theme.documents:
|
|
1276
|
+
"never"` (pages only): light values and a light `color-scheme`, untouched by a host flip, so no
|
|
1277
|
+
theme event. The manual says style it yourself and don't rely on `prefers-color-scheme`; measured
|
|
1278
|
+
with the person on dark, that query says light inside on WebKit and Firefox (they follow the frame
|
|
1279
|
+
element's `color-scheme`) and dark on Chromium. Checks: `11.theme-flip`, `11.document-theme`,
|
|
1397
1280
|
`14.theme-never`.
|
|
1398
|
-
- `errors` (interactive): `errors: "agent" | "host" | "none"
|
|
1399
|
-
|
|
1400
|
-
|
|
1401
|
-
|
|
1402
|
-
|
|
1403
|
-
|
|
1404
|
-
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
|
-
- `limits.maxBytes` is stated in KB or MB (`Keep it under 10 MB.`).
|
|
1412
|
-
- `storage.scope` names what one display's storage is kept for ("this artifact, across its
|
|
1413
|
-
versions"), without `storage.shared`'s prefix advice.
|
|
1414
|
-
- `errors` says where the content's errors go: back to the agent, to the app only, or nowhere
|
|
1415
|
-
(no `reportError`). Absent, the manual keeps its old "reported to the app".
|
|
1416
|
-
|
|
1417
|
-
`test/limits.test.ts` fails if a limit names no check, names one no suite defines,
|
|
1418
|
-
or the list holds a line that isn't a limit. Measured differences, each stated as
|
|
1419
|
-
the behavior safe everywhere:
|
|
1420
|
-
- submit events fire on WebKit only;
|
|
1421
|
-
- `window.open` returns null on Chromium and WebKit and throws on Firefox;
|
|
1422
|
-
- reading `navigator.serviceWorker` in an opaque frame throws on Chromium and
|
|
1423
|
-
WebKit, and `register` rejects on Firefox;
|
|
1424
|
-
- `play()` without a click is refused on Chromium and WebKit, and allowed by
|
|
1425
|
-
Playwright's Firefox;
|
|
1426
|
-
- Web Share is absent on all three desktop engines.
|
|
1427
|
-
|
|
1428
|
-
On a page whose own policy closes blob: workers, `14.workers` reports itself
|
|
1281
|
+
- `errors` (interactive): `errors: "agent" | "host" | "none"`: back to the agent, to the app only,
|
|
1282
|
+
or nowhere (no `reportError`); absent, the manual says "reported to the app". Checks: `14.errors`,
|
|
1283
|
+
`14.error-shapes`.
|
|
1284
|
+
|
|
1285
|
+
The manual also states `limits.maxBytes` in KB or MB (`Keep it under 10 MB.`), and `storage.scope`
|
|
1286
|
+
names what one display's storage is kept for ("this artifact, across its versions"), without
|
|
1287
|
+
`storage.shared`'s prefix advice. `test/limits.test.ts` fails if a limit names no check, names one
|
|
1288
|
+
no suite defines, or the list holds a line that isn't a limit. Measured differences, each stated as
|
|
1289
|
+
the behavior safe everywhere: submit events fire on WebKit only; `window.open` returns null on
|
|
1290
|
+
Chromium and WebKit and throws on Firefox; reading `navigator.serviceWorker` in an opaque frame
|
|
1291
|
+
throws on Chromium and WebKit, and `register` rejects on Firefox; `play()` without a click is
|
|
1292
|
+
refused on Chromium and WebKit and allowed by Playwright's Firefox; Web Share is absent on all three
|
|
1293
|
+
desktop engines. On a page whose own policy closes blob: workers, `14.workers` reports itself
|
|
1429
1294
|
inapplicable (P058).
|
|
1430
1295
|
|
|
1431
|
-
## MCP Apps adapter vs AppBridge
|
|
1432
|
-
|
|
1433
|
-
The official SDK ships `AppBridge` (host side), which extends the MCP SDK's
|
|
1434
|
-
`Protocol` class and pulls in the MCP client/core packages. **Decision: Porthole's
|
|
1435
|
-
MCP adapter reimplements the thin host-side subset of MCP Apps that maps to
|
|
1436
|
-
capabilities; it does not embed AppBridge** (P007), and no AppBridge-backed adapter
|
|
1437
|
-
is offered for now (P014). On the **widget side** we reimplement nothing — authors
|
|
1438
|
-
use the official `App` SDK, which is exactly the point of speaking the standard.
|
|
1439
|
-
Upstream, once the code and tests exist (P018), we contribute what is general: the
|
|
1440
|
-
conformance/leak runner, the container-agnostic framing note (a single hardened
|
|
1441
|
-
frame instead of the mandated double-iframe, where equally secure), and the
|
|
1442
|
-
shadow-root / document-rewrite frame-escape findings.
|
|
1443
|
-
|
|
1444
|
-
## Migration plan: the first host (Ferry)
|
|
1445
|
-
|
|
1446
|
-
Ferry already has a working widget sandbox; it becomes Porthole's first user and
|
|
1447
|
-
proves the API is general (PRINCIPLE 9). This section names Ferry only as that
|
|
1448
|
-
first adopter. Every Ferry feature that shows agent-made or foreign HTML goes
|
|
1449
|
-
through Porthole: widgets (inline widget), shown HTML files (artifact page), and
|
|
1450
|
-
the dev-server preview pane (URL mode).
|
|
1451
|
-
|
|
1452
|
-
**Moved into Porthole** (seeded from Ferry, renamed, wired from the config): the
|
|
1453
|
-
shell (`widget-shell.ts`) → `src/shell/`; its CSP builder → `src/compile/policy.ts`
|
|
1454
|
-
(now without `'self'`, its CDNs an opt-in, `LIBRARY_CDNS`); the embedding-page CSP
|
|
1455
|
-
(`webAppCsp`) → `embedderCsp`; the theme map (`widget-theme.ts`) → the default
|
|
1456
|
-
vocabulary and `resolveTheme` (Ferry's rUI token names become its `theme` function;
|
|
1457
|
-
its chart palette is the default); the guide (`display-guide.ts`) →
|
|
1458
|
-
`src/guide/` (its `file` topic stays Ferry's, as `guide.topics.file`); the frame
|
|
1459
|
-
component (`WidgetFrame.tsx`) → the React binding (live-frame cap, heights).
|
|
1460
|
-
|
|
1461
|
-
**Names that change** for content Ferry already shows: the theme event
|
|
1462
|
-
`ferry:theme` → `config.theme.event` (Ferry may keep its name there, P024); the
|
|
1463
|
-
error method `ferry/notifications/error` → `notifications/message` (level
|
|
1464
|
-
`error`); the tool-input argument `widget_code` → `html` (Ferry maps its tool's
|
|
1465
|
-
argument when it calls `setContent`); the root `#ferry-root` → `#porthole-root`.
|
|
1466
|
-
|
|
1467
|
-
**Stays in Ferry** (product policy and plumbing): the `show_file`/`show_widget`/
|
|
1468
|
-
`display_guide` MCP tools and their receipts/log entries; the daemon upload and
|
|
1469
|
-
attachment storage; the session-log fold that decides where a display draws; the
|
|
1470
|
-
`sendPrompt` send-permission rules (its dialog may stay its own, through
|
|
1471
|
-
`confirm`); lazy-mount/live-frame numbers as config; the preview gateway and its
|
|
1472
|
-
daemon streams (URL mode frames it); anything tied to Ferry's session model.
|
|
1473
|
-
|
|
1474
|
-
**Ferry files that change:** `packages/core` drops the moved modules and depends
|
|
1475
|
-
on `@botiverse/porthole`, re-exporting what its own tools need; `WidgetFrame.tsx`
|
|
1476
|
-
becomes a thin wrapper over `@botiverse/porthole/react` supplying callbacks and
|
|
1477
|
-
theme; `apps/server/src/http.ts`, `apps/web/vite.config.ts` and
|
|
1478
|
-
`apps/desktop/src/main.ts` take the embedding-page CSP from `embedderCsp`;
|
|
1479
|
-
`apps/daemon/src/crew/mcp.ts` builds its tool description and guide from the
|
|
1480
|
-
Porthole config; the preview pane frames through the url preset; the native bridge
|
|
1481
|
-
keeps carrying `@ferry/core`, which re-exports Porthole's shell. Ferry's display
|
|
1482
|
-
decision entry gets a follow-up noting the extraction. The goal is Ferry's widget
|
|
1483
|
-
code reduced to a config plus callbacks (OBJECTIVE 4, the dogfooding success
|
|
1484
|
-
test).
|
|
1485
|
-
|
|
1486
1296
|
## The leak / conformance suite
|
|
1487
1297
|
|
|
1488
1298
|
A Playwright suite (`@botiverse/porthole/conformance`) that:
|
|
1489
|
-
|
|
1490
|
-
|
|
1491
|
-
|
|
1492
|
-
|
|
1493
|
-
|
|
1494
|
-
|
|
1495
|
-
|
|
1496
|
-
|
|
1497
|
-
|
|
1498
|
-
|
|
1499
|
-
|
|
1500
|
-
|
|
1501
|
-
|
|
1502
|
-
|
|
1503
|
-
|
|
1504
|
-
|
|
1505
|
-
|
|
1506
|
-
|
|
1507
|
-
|
|
1508
|
-
|
|
1509
|
-
|
|
1510
|
-
`createHost` in a page; `leak/reference-host.ts`, its `ConformanceHost`; served by
|
|
1511
|
-
`leak/server.ts`, which serves the core's TypeScript stripped as Node does, with the
|
|
1512
|
-
embedding CSP `embedderCsp` derives): `pnpm test:leak` runs Chromium, WebKit and
|
|
1513
|
-
Firefox;
|
|
1514
|
-
`PORTHOLE_LEAK_ENGINES=chromium` runs a subset where an engine's system libraries
|
|
1515
|
-
are missing; `PORTHOLE_LEAK_WEAKEN=<control>[,<control>]` serves the core with
|
|
1516
|
-
defenses taken out (P032; § The negative controls lists what each must fail).
|
|
1517
|
-
`ConformanceHost.launch` called twice on one page shows two displays side by side
|
|
1518
|
-
(`9.siblings`).
|
|
1299
|
+
- drives a **platform host** (the web iframe host, later others) through an **adapter** via a small
|
|
1300
|
+
**test interface** (`ConformanceHost`: launch a display in a fresh page; answer confirmations;
|
|
1301
|
+
read the calls that reached the handlers and the errors; flip the theme), coupled to no host's DOM
|
|
1302
|
+
and aligned with the upstream conformance-interface effort so results can feed it;
|
|
1303
|
+
- is registered by the host in a spec file of its own (`leakTests(host)`, `servedTests(host)`: one
|
|
1304
|
+
entry per probe, `test(each.title, ({ page, browserName }, info) => each.run({ page, browserName
|
|
1305
|
+
}, info))`), so its tests are located and selected there or by probe id; it runs on the host's own
|
|
1306
|
+
Playwright, which Porthole doesn't declare (P041);
|
|
1307
|
+
- runs every probe in the tables above with out-of-band oracles (`httpOracle`: a local HTTP server
|
|
1308
|
+
that also counts TCP connections; `udpOracle`: a UDP listener for STUN), each with its positive
|
|
1309
|
+
control;
|
|
1310
|
+
- runs the MCP Apps examples unmodified, checking lifecycle and interaction, and renders the guide's
|
|
1311
|
+
examples at the target widths and themes.
|
|
1312
|
+
|
|
1313
|
+
Porthole's reference host: `leak/host/reference.ts` (the real `createHost` in a page) and
|
|
1314
|
+
`leak/reference-host.ts` (its `ConformanceHost`), served by `leak/server.ts`, which strips the
|
|
1315
|
+
core's TypeScript as Node does and sends the embedding CSP `embedderCsp` derives. `pnpm test:leak`
|
|
1316
|
+
runs Chromium, WebKit and Firefox; `PORTHOLE_LEAK_ENGINES=chromium` a subset where an engine's
|
|
1317
|
+
system libraries are missing; `PORTHOLE_LEAK_WEAKEN=<control>[,<control>]` serves the core with
|
|
1318
|
+
defenses taken out (P032). `ConformanceHost.launch` twice on one page shows two displays side by
|
|
1319
|
+
side (`9.siblings`).
|
|
1519
1320
|
|
|
1520
1321
|
### The negative controls
|
|
1521
1322
|
|
|
1522
|
-
Every control
|
|
1523
|
-
|
|
1524
|
-
|
|
1525
|
-
|
|
1526
|
-
|
|
1527
|
-
|
|
1528
|
-
|
|
1529
|
-
|
|
1530
|
-
|
|
1531
|
-
|
|
1532
|
-
|
|
1533
|
-
|
|
1534
|
-
|
|
1535
|
-
|
|
1536
|
-
|
|
1537
|
-
|
|
1538
|
-
|
|
1539
|
-
|
|
1540
|
-
(`node scripts/controls.ts --table` prints it; `test/controls.test.ts` holds them equal,
|
|
1541
|
-
every weakening to a control, every control that fails nothing to its reason, and every
|
|
1542
|
-
control the tables above name to the registry):
|
|
1323
|
+
Every control is in one registry (`leak/controls.ts`, P096): the specs it runs with and the tests it
|
|
1324
|
+
must fail on each engine, named exactly (a probe's `[id]`, a served case's id, or a test's whole
|
|
1325
|
+
title). `pnpm --filter @botiverse/porthole test:controls` (`scripts/controls.ts`; in CI, a job per
|
|
1326
|
+
engine) runs each one and requires its tests to fail by their verdicts on every engine asked, and
|
|
1327
|
+
every other test of its specs to pass. A probe's verdict is its deciding `expect`, whose message
|
|
1328
|
+
starts `probe: ` (in the shipped probes and in the spec tests the registry names); a failing setup
|
|
1329
|
+
or positive control is no failure of the wall. The check fails on a run that didn't happen, an
|
|
1330
|
+
engine missing from the report, a probe skipped, never run, timed out or failed by anything but its
|
|
1331
|
+
verdict, or a `test.fail` test that passes. A control that fails nothing on an engine says why:
|
|
1332
|
+
another wall holds (a combined control taking both out fails something there), or no probe can see
|
|
1333
|
+
the wall. One that fails "every other test" takes out what all stand on (`nonce`: the shell), and
|
|
1334
|
+
none may pass. No control runs `kit.spec.ts`: the kit's reference app runs Porthole in Node, where
|
|
1335
|
+
no weakening reaches (`UNWEAKENED`). A whole engine's controls outlast a CI job, so each job runs
|
|
1336
|
+
one of four shards (`--shard k/4`, split by measured weight, stable for a registry) and the
|
|
1337
|
+
`controls` job checks every shard's verdicts (`--summary`): every control ran and held on every
|
|
1338
|
+
engine. `node scripts/controls.ts --table` prints the table below; `test/controls.test.ts` holds it
|
|
1339
|
+
equal to the registry, every weakening to a control, every control that fails nothing to its reason,
|
|
1340
|
+
and every control the tables above name to the registry.
|
|
1543
1341
|
|
|
1544
1342
|
| Control | Run with | Fails on every engine | Fails only on | Where it fails nothing, or may skip, why |
|
|
1545
1343
|
|---------|----------|-----------------------|---------------|-----------------------------|
|
|
@@ -1562,9 +1360,9 @@ control the tables above name to the registry):
|
|
|
1562
1360
|
| `style-split` | `leak.spec.ts` | `[0.app-sdk-inline]`, `[0.app-sdk-artifact]`, `[0.app-sdk-mcp-app]` | — | — |
|
|
1563
1361
|
| `draft-inert` | `leak.spec.ts` | `[11.streaming]` | — | — |
|
|
1564
1362
|
| `document-theme` | `leak.spec.ts` | `[11.document-theme]`, `[14.theme-never]` | — | — |
|
|
1565
|
-
| `confirm-gate` | `leak.spec.ts` | `[12.prompt-
|
|
1566
|
-
| `shell-gesture` | `leak.spec.ts` | `[12.
|
|
1567
|
-
| `host-gesture` | `leak.spec.ts` | `[12.raw-
|
|
1363
|
+
| `confirm-gate` | `leak.spec.ts` | `[12.prompt-confirm]`, `[12.raw-message]`, `[12.link]`, `[12.mute]`, `[12.no-confirm]`, `[14.windows]` | — | — |
|
|
1364
|
+
| `shell-gesture` | `leak.spec.ts` | `[12.copy-text]` | — | — |
|
|
1365
|
+
| `host-gesture` | `leak.spec.ts` | `[12.raw-copy]` | — | — |
|
|
1568
1366
|
| `model-context-show` | `leak.spec.ts` | `[12.model-context]` | — | — |
|
|
1569
1367
|
| `link-scheme` | `leak.spec.ts` | `[12.link]` | — | — |
|
|
1570
1368
|
| `clipboard` | `leak.spec.ts` | `[13.clipboard-command]`, `[13.clipboard-event]` | WebKit, Firefox: `[13.clipboard-api]`, `[14.shell]` | — |
|
|
@@ -1579,18 +1377,17 @@ control the tables above name to the registry):
|
|
|
1579
1377
|
| `marker-place` | `annotate.spec.ts` | `text markers cover no word: on a column page, and on a phone's lines with one marker each (P105, #36)` | — | — |
|
|
1580
1378
|
| `marker-key` | `annotate.spec.ts` | `a marker is a button the keyboard reaches: Tab in reading order, Enter and Space report it once, the content hears neither, and it steps aside while elements are picked (P133)` | — | — |
|
|
1581
1379
|
| `marker-focus` | `annotate.spec.ts` | `a page that patched focus isn't handed the marker the host's focusMark moves to (P134)` | — | — |
|
|
1582
|
-
| `marker-late` | `annotate.spec.ts
|
|
1583
|
-
| `marker-busy` | `
|
|
1584
|
-
| `marker-clock` | `
|
|
1585
|
-
| `marker-has-focus` | `annotate.spec.ts`, `
|
|
1380
|
+
| `marker-late` | `annotate.spec.ts` | `a parked focusMark doesn't land once the person has moved on to the host's button (P135)`, `a focusMark parked with the focus in the frame doesn't land once the person moves on while it waits (P135)`, `a parked focusMark with the focus on the host's body is dropped; after the host's own move into the frame a second one, parked too, lands on the marker (P135)`, `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)` | — | — |
|
|
1381
|
+
| `marker-busy` | `late-word.spec.ts` | `a focusMark a busy page takes late doesn't land once the host's page has moved on (P137)`, `a page that stopped Date.now gets no landing for a word it took late (P137)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)` | — | — |
|
|
1382
|
+
| `marker-clock` | `late-word.spec.ts` | `a page that stopped Date.now gets no landing for a word it took late (P137)` | — | — |
|
|
1383
|
+
| `marker-has-focus` | `annotate.spec.ts`, `late-word.spec.ts` | `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)` | — | — |
|
|
1586
1384
|
| `marker-originals` | `annotate.spec.ts` | `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)` | — | — |
|
|
1587
1385
|
| `follow-throttle` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1588
1386
|
| `selection-follow` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1589
1387
|
| `follow-count` | `annotate.spec.ts` | `following: a host that gives no counts hears no follow-up after a scroll, as before markers` | — | — |
|
|
1590
1388
|
| `draft-count` | `annotate.spec.ts` | `what the page reads of a draft (P107): that it is one, never its count; a posted mark as before` | — | — |
|
|
1591
1389
|
| `draft-shell-checks` | `annotate.spec.ts` | `the shell's own checks on a raw show (P107): a draft draws no number, a kind it doesn't know is no mark` | — | — |
|
|
1592
|
-
| `annotation-
|
|
1593
|
-
| `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved`, `every attached mark's place in the document comes with the scroll it was read at, offscreen ones too, and the followed mark's as the document scrolls (P132)`, `a selection's and a mark's last line come in the document's coordinates with the scroll, offscreen ones too; rect stays clamped (P133)` | — | — |
|
|
1390
|
+
| `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved`, `every attached mark's place in the document comes with the scroll it was read at, offscreen ones too, and the followed mark's as the document scrolls (P132)`, `a selection's and a mark's last line come in the document's coordinates with the scroll, offscreen ones too; rect stays clamped (P133)`, `an element pick says where it was clicked, in the document's coordinates with the scroll; a pick from the keyboard says no point (P150)` | — | — |
|
|
1594
1391
|
| `authorize` | `served/authorize.spec.ts` | `a revoked subject's ticket opens nothing: a page and an app are denied, and the host is told`, `in a tab of its own, a revoked app and page are denied from the next request on`, `a framed page mid-session: its next load after revocation is denied where the engine keeps its cookie` | Chromium, Firefox: `a framed app mid-session: its next request after revocation is denied, and its next load tells the host` | — |
|
|
1595
1392
|
| `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
|
|
1596
1393
|
| `navigate-guard` | `served/live.spec.ts`, `served/files.spec.ts`, `served/served.spec.ts`, `served/tab.spec.ts` | `served.domain.self-navigation`, `served.domain.tab-navigation`, `served.domain.tab-links`, `can't navigate itself away (location): to a site, or to another content origin`, `can't navigate itself away (replace): to a site, or to another content origin`, `can't navigate itself away (open-self): to a site, or to another content origin`, `can't navigate itself away (navigation-api): to a site, or to another content origin`, `a link to another page of the set opens it in the frame; the display goes on`, `a link to another page of the set opens it in the frame when the leaving page's notice is dropped (P098)`, `a link to another page of the set opens it in the frame when the leaving page's notice is late (P098)`, `without the Navigation API, a link to another page of the set opens it in the frame; the display goes on`, `a link down the page scrolls it; the document stays, and so does the display`, `without the Navigation API, a link down the page scrolls it; the document stays, and so does the display`, `a page opens nothing else: not a file that isn't a page, not another path of its origin`, `no report, content error or blocked navigation names the frame's sealed address (P083)` | — | — |
|
|
@@ -1613,10 +1410,7 @@ control the tables above name to the registry):
|
|
|
1613
1410
|
| `runtime-data-names` | `served/runtime.spec.ts` | `a resource outside the page's data names: refused with a viewer and without one, its handler never asked` | — | — |
|
|
1614
1411
|
| `live-held-read` | `served/runtime.spec.ts` | `a read above the viewer's level: a result the host pushed is refused as a cold read is` | — | — |
|
|
1615
1412
|
| `db-private` | `served/runtime.spec.ts` | `a person's own data is theirs: another person's is refused, never reaching the service` | — | — |
|
|
1616
|
-
| `comments-result` | `served/runtime.spec.ts` | `comments are write-only: the composer opens
|
|
1617
|
-
| `focus-guard` | `served/runtime.spec.ts` | `a page that takes the keyboard while the person types in the host's composer gets a key or two at most, and is stopped` | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | — |
|
|
1618
|
-
| `focus-guard-watch` | `served/runtime.spec.ts` | nothing | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | no probe can see it on Chromium and WebKit: they blur the host's window on every move into a frame and a take-back lands, and a page can't take focus back from its own blur there (measured) |
|
|
1619
|
-
| `comments-in-frame` | `served/runtime.spec.ts` | `comments.open while the person types in the host's composer reaches no handler, by the page's own call or the shell's; from a press in the frame it does` | — | — |
|
|
1413
|
+
| `comments-result` | `served/runtime.spec.ts` | `comments are write-only: the composer opens when the page asks, with a click or without one, and content hears only that` | — | — |
|
|
1620
1414
|
| `cancel-any-mode` | `annotate.spec.ts` | `Escape while selecting text is cancelled, and stays the page's key; with no mode on, a page's own cancel isn't heard (P112)`, `a hostile page fakes reports: the host takes none it didn't ask for, nothing malformed, and not a flood` | — | — |
|
|
1621
1415
|
| `track-checks` | `annotate.spec.ts` | `a followed mark's box comes as it moves, for that mark only, at most 60 a second, clamped to the frame, until the host stops (P112)` | — | — |
|
|
1622
1416
|
| `track-selection-checks` | `annotate.spec.ts` | `a followed selection's place comes as it moves, highlighted, out of view and back, gone and found again, only while the host follows it, at most 60 a second (P138)`, `without keepSelection or a follow, a pick's outline goes with the pick and nothing is kept: a follow asked after it has nothing, one asked before it follows it; a page's malformed word is no refusal (P140)` | — | — |
|
|
@@ -1630,77 +1424,9 @@ control the tables above name to the registry):
|
|
|
1630
1424
|
| `embed-ancestors` | `served/embed.spec.ts` | `[embed.reader-unframeable]` | — | — |
|
|
1631
1425
|
| `embed-handshake` | `served/embed.spec.ts` | `[embed.untold]` | — | — |
|
|
1632
1426
|
| `embed-origins` | `served/embed.spec.ts` | `[embed.unheard]` | — | — |
|
|
1633
|
-
| `frame-status-order` | `served/outcome.spec.ts` | `a nested page that says it is blocked, through its shell or past it, is told nothing and shown nothing (P124)` | — | — |
|
|
1634
|
-
| `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
|
|
1635
|
-
| `shell-focus-held` | `served/nested.spec.ts` | `the host's move takes no keyboard from where the host's page went on to in the same task (P136)`, `a second host's move into a page it just handed the focus to leaves it there: no blur, and its field keeps the keyboard (P136)` | — | — |
|
|
1636
|
-
| `shell-label,nested-host-label,nested-shell-origin` | `served/nested-siblings.spec.ts` | `[nested-siblings]`, `[nested-label]` | — | — |
|
|
1637
|
-
| `nested-host-label` | `served/nested-siblings.spec.ts` | `[nested-label]` | — | — |
|
|
1638
|
-
| `nested-shell-origin` | `served/nested-siblings.spec.ts` | nothing | — | the host's mount refuses a shell located on any other label first, and /server serves none there (`shell-label,nested-host-label,nested-shell-origin`) |
|
|
1639
|
-
| `file-sandbox` | `served/nested.spec.ts` | `a page's SVG or XML file opened on a tab of its own is an opaque origin, and its script touches nothing of the shell's (P111, after its review)` | — | — |
|
|
1640
|
-
| `nested-fight` | `served/nested.spec.ts` | nothing | Firefox: `a page that holds the keyboard from its load and takes it back on its own blur gets none of what the person types in the host's composer, and is stopped (P120)` | no probe can see it on Chromium and WebKit: a page can't take focus back from its own blur there, so no fight has a frame take focus again (measured) |
|
|
1641
|
-
| `shell-stall` | `served/nested.spec.ts`, `served/nested-press.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)`, `a press a shell tells after a stall is no one's (P148)` | — | — |
|
|
1642
|
-
| `press-untrusted` | `served/nested-press.spec.ts` | `a press the page makes up is none: a dispatched pointer, key or click tells the shell nothing (P148)` | — | — |
|
|
1643
|
-
| `press-role` | `served/nested-press.spec.ts` | `typing is no press, whatever the content calls the field: a role of button, a custom element's, an editable button (P148)` | — | — |
|
|
1644
|
-
| `press-editable` | `served/nested-press.spec.ts` | `typing is no press, whatever the content calls the field: a role of button, a custom element's, an editable button (P148)` | — | — |
|
|
1645
|
-
| `press-repeat` | `served/nested-press.spec.ts` | `a key held down is one press, however long it repeats (P148)` | — | — |
|
|
1646
|
-
| `press-key-click` | `served/nested-press.spec.ts` | `Enter typed in a text field is no press, though the page moves the focus to its button as the key goes down (P148)`, `a key held down is one press, however long it repeats (P148)` | — | — |
|
|
1647
|
-
| `press-submit` | `served/nested-press.spec.ts` | nothing | — | a key is down while a form clicks its submit button for an Enter, and no click is a press then: that rule refuses the click first (`press-key-click,press-submit`) |
|
|
1648
|
-
| `press-key-click,press-submit` | `served/nested-press.spec.ts` | `Enter typed in a text field is no press, though the page moves the focus to its button as the key goes down (P148)`, `a key held down is one press, however long it repeats (P148)`, `Enter in a form's text field is no press, though the form clicks its submit button (P148)` | — | — |
|
|
1649
|
-
| `press-touch-down` | `served/nested-press.spec.ts` | nothing | Chromium: `a finger that scrolls the page is no press; a tap is (P148)` | no probe can drive a finger's drag on WebKit and Firefox: a test has a tap there and no touch scroll |
|
|
1650
|
-
| `press-port-heard` | `served/nested-press.spec.ts` | `the shell's port is the runtime's alone: content's first listener hears no message that carries one (P148)` | — | — |
|
|
1651
|
-
| `press-port-forged` | `served/nested-press.spec.ts` | nothing | Chromium, WebKit: `a port message content sends itself first is not taken, and takes no place: the person's press still reaches the shell (P148)` | no probe can make the event on Firefox: its MessageEvent constructor takes no window of another origin as a source (measured), and the runtime takes a port from its parent's alone |
|
|
1652
|
-
| `press-open-lock` | `served/nested-press.spec.ts` | `a page can't open its document again to hear the port the shell sends at the next load (P148)`, `nor as soon as it runs, to hear the first port in the runtime's place (P148)` | — | — |
|
|
1653
|
-
| `press-still-here` | `served/nested-press.spec.ts` | nothing | WebKit: `a press after a link within the document is heard: the load WebKit fires for it leaves the first port the one (P148)` | no probe can see it on Chromium and Firefox: they fire no load for a navigation within the document (measured), so the shell sends no second port |
|
|
1654
|
-
| `press-host-input` | `served/nested-press.spec.ts` | `a page's focus() just after a second press in it, the person gone back to the host's composer, is taken back (P148)` | — | — |
|
|
1655
|
-
| `shell-host-input` | `served/nested.spec.ts` | `a page's focus() just after the person pressed it and went back to the host's composer is taken back` | — | — |
|
|
1656
|
-
| `key-press` | `served/nested-key.spec.ts` | `an activation that turned on within 250 ms of the person's key on the host's page is no gesture, where the pointer is never seen too (P122)` | — | — |
|
|
1657
|
-
| `pointer-rule` | `served/nested.spec.ts` | `an activation that came as the person typed, the pointer elsewhere, is no gesture a second on either (P120, after its review)` | — | — |
|
|
1658
1427
|
| `comment-draft` | `served/runtime.spec.ts` | `a comment's draft is the host's to check: past the limit, holding what a person can't see, or not text, it opens no composer (P108)` | — | — |
|
|
1659
1428
|
| `blob-script` | `served/runtime.spec.ts` | nothing | — | an untrusted script asset is served as a download (`blob-script,blob-trusted`) |
|
|
1660
1429
|
| `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
|
|
1661
1430
|
| `blob-script,blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'`, `scripts load from /_blob/ only where uploads are the admins' (a tab, its session)` | — | — |
|
|
1662
1431
|
| `blob-inert` | `served/runtime.spec.ts` | `an asset opened on its own runs nothing, on a tab with the artifact's session` | — | — |
|
|
1663
1432
|
| `find-requested-focus` | `find.spec.ts` | `a hostile page says the find shortcut was pressed while the person types in the host's composer: the host's find bar stays shut (P131)` | — | — |
|
|
1664
|
-
|
|
1665
|
-
## Milestones
|
|
1666
|
-
|
|
1667
|
-
The core (this repository's lead work), in order; each lands when its tests pass:
|
|
1668
|
-
|
|
1669
|
-
1. **M1 — scaffold, config, compiler, presets, interfaces** (done). The workspace
|
|
1670
|
-
and tooling; the config schema and validation; the compiler (CSP, sandbox and
|
|
1671
|
-
`allow`, embedder CSP, shell plan and document, guide and tool description) with
|
|
1672
|
-
the agreement test; the presets as configs; the public interfaces above as typed
|
|
1673
|
-
stubs; the shell's wiring checked in real frames on Chromium and WebKit.
|
|
1674
|
-
2. **M2 — isolation core, shell runtime, egress hardening** (done). The web
|
|
1675
|
-
platform host and transport, `createHost` mounting opaque, domain and url frames
|
|
1676
|
-
(served frames checked by `checkFrameLocation`), the shell adapter and the bridge,
|
|
1677
|
-
the reference host and `defineLeakSuite`, items 1–10 above each with its probes,
|
|
1678
|
-
positive controls and negative controls, green on Chromium and WebKit; the
|
|
1679
|
-
official App SDK connecting under every preset.
|
|
1680
|
-
3. **M3 — streaming, auto-size, theming, the gated bridge** (done). Streaming
|
|
1681
|
-
drafts through the host API, size reporting under the limits, theme apply and
|
|
1682
|
-
flip with the host's live values, base styles for native form elements, and the
|
|
1683
|
-
host-function bridge's gates, each proven in real frames (items 11, 12) with
|
|
1684
|
-
negative controls, and in unit tests (`test/bridge.test.ts`,
|
|
1685
|
-
`test/shell-adapter.test.ts`).
|
|
1686
|
-
4. **M4 — the React binding and its default confirmation dialog** (done).
|
|
1687
|
-
`<PortholeProvider>`, `<PortholeFrame>`, `ConfirmDialog`: streaming through props,
|
|
1688
|
-
height memory per display, the live-frame cap with "Run again", theme flips,
|
|
1689
|
-
navigation recovery, generations, and the default, replaceable dialog, each
|
|
1690
|
-
proven in a real browser.
|
|
1691
|
-
5. **M5 — Firefox** in the gate (done): every Playwright suite (leak, served, MCP
|
|
1692
|
-
examples, React) runs on Chromium, WebKit and Firefox, and every negative control
|
|
1693
|
-
was run on Firefox; its differences are recorded in P035.
|
|
1694
|
-
|
|
1695
|
-
In parallel, against the interfaces: the **MCP Apps adapter** (`/mcp`, running the
|
|
1696
|
-
official ext-apps examples unmodified); the **served modes** (domain mode, `/server`,
|
|
1697
|
-
the artifact page served, the MCP Apps sandbox proxy, URL mode); and the **Ferry
|
|
1698
|
-
migration**.
|
|
1699
|
-
|
|
1700
|
-
## Open questions
|
|
1701
|
-
|
|
1702
|
-
1. ~~URL mode's sandbox tokens~~: popups, modals and downloads are a host's
|
|
1703
|
-
opt-in (P037); clipboard writes and full screen too (P049).
|
|
1704
|
-
2. ~~`'self'` in the embedding page's `frame-src`~~: measured and dropped (P033).
|
|
1705
|
-
3. ~~Clipboard writes from agent-written content~~: closed (P051); copy buttons go
|
|
1706
|
-
through the host (`copyText`, P052).
|