@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/ARCHITECTURE.md
DELETED
|
@@ -1,359 +0,0 @@
|
|
|
1
|
-
# Architecture
|
|
2
|
-
|
|
3
|
-
This describes the layers, their contracts, the flows and trust boundaries, and
|
|
4
|
-
the extension points. It is meant to stay stable while concrete APIs change; the
|
|
5
|
-
phase-1 API lives in [DESIGN.md](DESIGN.md). What the boundaries protect, from whom,
|
|
6
|
-
and what each use guarantees and leaves to the host is in
|
|
7
|
-
[THREAT_MODEL.md](THREAT_MODEL.md).
|
|
8
|
-
|
|
9
|
-
## The core abstraction
|
|
10
|
-
|
|
11
|
-
Porthole renders **agent-drawn HTML plus a declared set of host functions.**
|
|
12
|
-
|
|
13
|
-
- The HTML is untrusted. It may draw anything, but on its own it can only draw.
|
|
14
|
-
- A **host function (capability)** is any power beyond drawing: send a prompt to
|
|
15
|
-
the agent, open a link, read or write state, call a tool, read data, report an
|
|
16
|
-
error. Each is named in the config and carries three facts: its **gate** (needs
|
|
17
|
-
a user gesture, needs a person's confirmation, is shown to the person first, is
|
|
18
|
-
rate-limited), its **egress
|
|
19
|
-
needs** (origins it must reach), and its **guide entry** (how the manual
|
|
20
|
-
describes it).
|
|
21
|
-
|
|
22
|
-
A page published as an artifact may be an app: under the **capability runtime**, an optional
|
|
23
|
-
layer over the display (THREAT_MODEL.md says what each guarantees), it reaches its
|
|
24
|
-
host through one global, `porthole.use(name)`, for the capabilities it declared and its viewer's
|
|
25
|
-
level allows. The runtime is how content reaches host functions, not new ones: each of its
|
|
26
|
-
methods is served by a host function the config declares, and the bridge alone decides each call
|
|
27
|
-
(the page's declaration, the viewer's level, the gates). The services behind them (a document
|
|
28
|
-
store, an asset library, versions, comments) are the host's.
|
|
29
|
-
|
|
30
|
-
One capability list therefore drives three artifacts: the **bridge** (which
|
|
31
|
-
functions the shell wires and the host handles), the **CSP** (what the sandbox
|
|
32
|
-
may reach), and the **manual** (what the agent is told). This is why the config
|
|
33
|
-
is the single source (PRINCIPLE 3) and why "talk to the agent" is not special —
|
|
34
|
-
it is one host function (PRINCIPLE 4).
|
|
35
|
-
|
|
36
|
-
## Layers
|
|
37
|
-
|
|
38
|
-
```
|
|
39
|
-
┌──────────────────────────────────────────────────────────┐
|
|
40
|
-
│ Host app (owns product policy, theme, callbacks) │
|
|
41
|
-
└───────────────┬──────────────────────────────────────────┘
|
|
42
|
-
│ picks a preset, passes theme + callbacks
|
|
43
|
-
┌─────────────────────────▼─────────────────────────────────────────┐
|
|
44
|
-
│ PRESET POLICY LAYER │
|
|
45
|
-
│ inline-widget · artifact · mcp-app · url │
|
|
46
|
-
│ each = a config: CSP+origins, capabilities+gates, theme, guide │
|
|
47
|
-
└─────────────────────────┬─────────────────────────────────────────┘
|
|
48
|
-
│ one config
|
|
49
|
-
┌─────────────────────────▼─────────────────────────────────────────┐
|
|
50
|
-
│ FRAMEWORK LAYER (mechanisms only, no policy) │
|
|
51
|
-
│ │
|
|
52
|
-
│ config compiler ── CSP + sandbox/allow attrs │
|
|
53
|
-
│ └── shell runtime (what to wire) │
|
|
54
|
-
│ └── guide + tool description │
|
|
55
|
-
│ │
|
|
56
|
-
│ isolation core · egress hardening · streaming render · auto-size │
|
|
57
|
-
│ theming · host-function bridge · guide gen · serving (/server) │
|
|
58
|
-
└───────┬───────────────────────────────────────┬────────────────────┘
|
|
59
|
-
│ host side │ in-frame side (shell)
|
|
60
|
-
┌───────▼─────────┐ ┌───────▼──────────────────┐
|
|
61
|
-
│ PROTOCOL ADAPTER│ ◄── transport ──► │ SHELL (runs first in │
|
|
62
|
-
│ (MCP Apps; …) │ (postMessage/ │ the isolated frame; │
|
|
63
|
-
│ │ native bridge) │ renders HTML, wires caps)│
|
|
64
|
-
└───────┬─────────┘ └───────────────────────────┘
|
|
65
|
-
│
|
|
66
|
-
┌───────▼───────────────────────────────────────────────────────────┐
|
|
67
|
-
│ PLATFORM HOST web (iframe) now · WKWebView / Android later │
|
|
68
|
-
└─────────────────────────────────────────────────────────────────── ┘
|
|
69
|
-
|
|
70
|
-
CONFORMANCE / LEAK SUITE drives a platform host through the adapter and
|
|
71
|
-
probes every egress and escape channel (runnable by any host).
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### Framework layer (mechanisms)
|
|
75
|
-
|
|
76
|
-
Pure mechanism, no product policy, no host or vendor types.
|
|
77
|
-
|
|
78
|
-
- **Config compiler.** Turns one config into the CSP string, the iframe sandbox
|
|
79
|
-
and `allow` attributes, the shell's wiring, and the guide + tool description.
|
|
80
|
-
Deterministic and pure, so a test can assert the three outputs agree.
|
|
81
|
-
- **Isolation core.** Places the content on an origin that is never the host's,
|
|
82
|
-
with nothing of the host's reachable: an opaque-origin frame, or a served
|
|
83
|
-
origin of its own (domain mode: a subdomain per storage scope on a separate
|
|
84
|
-
registrable domain; url mode: the app's own origin). The mode is chosen by
|
|
85
|
-
config; the rest of the framework does not depend on which.
|
|
86
|
-
- **Egress hardening.** The closed-by-default network and navigation walls, plus
|
|
87
|
-
the in-shell defenses for channels a CSP does not cover (see Trust boundaries).
|
|
88
|
-
- **Shell runtime.** The code that runs first inside the frame: applies theme,
|
|
89
|
-
inserts the HTML (streaming-aware), reports size and errors, and exposes the
|
|
90
|
-
declared host functions to the content.
|
|
91
|
-
- **Host-function bridge.** Carries capability calls from the shell to the host
|
|
92
|
-
and results back, over a transport, with validation and gating at the boundary.
|
|
93
|
-
- **Streaming render, auto-size, theming, guide generator.** The remaining
|
|
94
|
-
mechanisms, each usable on its own. Content is plain HTML and SVG; its look
|
|
95
|
-
comes from the theme variables, never from a component vocabulary (P015).
|
|
96
|
-
- **Serving.** For served modes, a request handler a host's backend mounts: it
|
|
97
|
-
serves documents on their own origins with their CSP in headers, and turns a
|
|
98
|
-
one-time ticket the host minted into a cookie of that origin only. A stored
|
|
99
|
-
version may be one page or a set of files: each file is looked up in the
|
|
100
|
-
version's manifest only, typed by Porthole's own table, and served under that
|
|
101
|
-
version's own address, so a page's relative addresses are its version's.
|
|
102
|
-
|
|
103
|
-
### Preset policy layer
|
|
104
|
-
|
|
105
|
-
A preset is a named config with safe defaults. It fixes the CSP and allowed
|
|
106
|
-
origins, the capabilities and their gates, the theme vocabulary, and the manual.
|
|
107
|
-
A host adopts a preset and overrides only theme and callbacks.
|
|
108
|
-
|
|
109
|
-
- **inline-widget** — host injects agent code into a strict, opaque-origin frame
|
|
110
|
-
with a shell; smallest capability set; for cards inside a conversation.
|
|
111
|
-
- **artifact** — a standalone page: written into an opaque frame where the host
|
|
112
|
-
has it, or served at a URL on a separate registrable domain, CSP in headers,
|
|
113
|
-
versioned.
|
|
114
|
-
- **mcp-app** — renders a standard MCP Apps view (a `ui://` template plus tool
|
|
115
|
-
input/result), using the MCP Apps adapter.
|
|
116
|
-
- **url** — frames a running app by URL (a dev server's preview): isolation and
|
|
117
|
-
access auth only; no shell, no capabilities, no egress control.
|
|
118
|
-
|
|
119
|
-
### Protocol adapters
|
|
120
|
-
|
|
121
|
-
A thin adapter maps the framework's capability and lifecycle events onto a wire
|
|
122
|
-
protocol. **MCP Apps** is the first and default. The adapter is the only layer
|
|
123
|
-
that knows protocol method names and shapes; the core speaks capabilities.
|
|
124
|
-
|
|
125
|
-
### Platform hosts
|
|
126
|
-
|
|
127
|
-
The platform host owns the actual isolation primitive and the transport: an
|
|
128
|
-
`iframe` + `postMessage` on the web now; a `WKWebView` + message handler on iOS
|
|
129
|
-
later. The framework layer is written against a small platform interface so a new
|
|
130
|
-
platform is an implementation of that interface, not a fork.
|
|
131
|
-
|
|
132
|
-
### Conformance / leak suite
|
|
133
|
-
|
|
134
|
-
A standalone test runner that drives a platform host through an adapter and
|
|
135
|
-
attempts every known egress and escape channel, asserting none succeeds. Any host
|
|
136
|
-
can run it against its own integration. It is both our regression gate and the
|
|
137
|
-
artifact we offer upstream (PRINCIPLE 5, 6).
|
|
138
|
-
|
|
139
|
-
## Contracts between layers
|
|
140
|
-
|
|
141
|
-
- **Host → preset:** a preset name, theme tokens (resolved per color scheme), and
|
|
142
|
-
callbacks for each enabled host function. Nothing else is required.
|
|
143
|
-
- **Preset → framework:** one config (capabilities with gates and egress needs,
|
|
144
|
-
allowed origins, theme variable map, limits, layout, mode and isolation).
|
|
145
|
-
- **Config → {CSP, shell, guide}:** derived, never hand-written; a test asserts
|
|
146
|
-
agreement.
|
|
147
|
-
- **Framework ↔ shell:** lifecycle and capability messages over a transport.
|
|
148
|
-
Validated both directions; unknown or malformed messages are dropped.
|
|
149
|
-
- **Framework ↔ adapter:** the adapter translates between capability/lifecycle
|
|
150
|
-
events and protocol messages; it may add protocol-only messages (handshake,
|
|
151
|
-
teardown) that the framework does not model.
|
|
152
|
-
- **Framework ↔ platform host:** create an isolated surface, set its policy
|
|
153
|
-
(CSP/sandbox/allow or the native equivalent), send and receive messages,
|
|
154
|
-
report size, tear down.
|
|
155
|
-
|
|
156
|
-
## Flows per mode
|
|
157
|
-
|
|
158
|
-
### Inline widget
|
|
159
|
-
|
|
160
|
-
```
|
|
161
|
-
Host app Framework/Adapter Shell (opaque frame)
|
|
162
|
-
│ mount(config, cbs) │ │
|
|
163
|
-
│──────────────────────────►│ compile config → CSP, │
|
|
164
|
-
│ │ sandbox attrs, shell doc │
|
|
165
|
-
│ │ create opaque frame ───────►│ (shell runs first)
|
|
166
|
-
│ │◄──── initialize ─────────────│
|
|
167
|
-
│ │──── host context (theme, │
|
|
168
|
-
│ │ capabilities, size) ────►│
|
|
169
|
-
│ content (may stream) ───►│──── content (partial*) ─────►│ draw inert
|
|
170
|
-
│ │──── content (complete) ─────►│ run
|
|
171
|
-
│ │◄──── size / error ───────────│
|
|
172
|
-
│◄── onError / onResize ────│ │
|
|
173
|
-
│ │◄──── capability call ────────│ (e.g. sendPrompt)
|
|
174
|
-
│◄── gate (confirm?) ───────│ validate + gate │
|
|
175
|
-
│── result ────────────────►│──── result ─────────────────►│
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
`*` partial content is drawn inert (no scripts, handlers or navigation) until
|
|
179
|
-
complete; see Streaming in DESIGN.md.
|
|
180
|
-
|
|
181
|
-
### MCP Apps view
|
|
182
|
-
|
|
183
|
-
Same shape, with the adapter speaking MCP Apps: the view is an MCP Apps `App`;
|
|
184
|
-
`initialize`/`initialized` is the handshake; content arrives as tool input
|
|
185
|
-
(streamed as tool-input-partial, then tool-input) and tool result; capability
|
|
186
|
-
calls are `ui/message`, `ui/open-link`, etc., which map to host functions. On the
|
|
187
|
-
web a second-origin sandbox proxy relays messages so arbitrary MCP App HTML
|
|
188
|
-
(which expects `allow-same-origin`) is isolated from the host; the proxy is
|
|
189
|
-
transparent to the view and the host.
|
|
190
|
-
|
|
191
|
-
### Artifact page
|
|
192
|
-
|
|
193
|
-
The content is served as a real document at a URL on a separate registrable
|
|
194
|
-
domain with its CSP in HTTP headers; the host embeds that URL in a frame whose
|
|
195
|
-
`frame-ancestors` names the host. No code injection, and the shell is optional.
|
|
196
|
-
A page may come with files of its own (stylesheets, scripts, data, images, other
|
|
197
|
-
pages): they are served beside it, under its version's own address, and its CSP
|
|
198
|
-
opens that path and nothing else of its origin; every page of the set gets the
|
|
199
|
-
shell.
|
|
200
|
-
Access is gated by a one-time ticket exchanged for a scoped cookie. Where the host
|
|
201
|
-
holds the page and needs no stable origin, the shell writes it into an opaque
|
|
202
|
-
frame instead.
|
|
203
|
-
|
|
204
|
-
A **nested** page (P111) splits the shell from the page. The address the host frames
|
|
205
|
-
serves Porthole's shell alone: a document with no content, on an origin of its own (a
|
|
206
|
-
label of the scope's, `porthole-<…>`, on which nothing else is ever served, P114). It
|
|
207
|
-
frames the page in a child sandboxed without `allow-same-origin` (an opaque origin) at
|
|
208
|
-
the page's sealed files' address on that origin, fetched without a cookie, and passes
|
|
209
|
-
messages between the host and the page:
|
|
210
|
-
|
|
211
|
-
```
|
|
212
|
-
Host app Shell (its own origin) Page (opaque child)
|
|
213
|
-
│ frame src = ticketed URL ──►│ frames the sealed address ───►│ runtime + page
|
|
214
|
-
│◄── the page's messages ──────│◄── postMessage (by source) ───│
|
|
215
|
-
│── the host's messages ──────►│── postMessage ───────────────►│
|
|
216
|
-
│◄── porthole/shell/state ─────│ its own activation, its focus │
|
|
217
|
-
│── porthole/shell/look ──────►│ look now (as a move is heard) │
|
|
218
|
-
│── porthole/shell/focus ─────►│ display.focus(): on to the ──►│ the page's window
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
### URL frame
|
|
222
|
-
|
|
223
|
-
```
|
|
224
|
-
Host app Host backend (+ /server) App origin (served)
|
|
225
|
-
│ mount(url preset) │ │
|
|
226
|
-
│── locate ─────────►│ decide the viewer may see it, │
|
|
227
|
-
│◄── ticketed URL ───│ mint a one-time ticket │
|
|
228
|
-
│ frame src = URL ──────────────────────────────────────►│ ticket → cookie
|
|
229
|
-
│ │ (that origin only)
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
No shell and no protocol: the app is someone else's. The embedding page frames
|
|
233
|
-
only the declared content origins.
|
|
234
|
-
|
|
235
|
-
## Trust boundaries
|
|
236
|
-
|
|
237
|
-
The attackers each boundary faces, what is out of scope, and the composition rule for
|
|
238
|
-
several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
|
|
239
|
-
|
|
240
|
-
1. **Host ↔ content.** The hard boundary. The content runs on an origin that is
|
|
241
|
-
never the host's, so same-origin policy denies it the host's DOM, storage,
|
|
242
|
-
cookies and credentials. Everything it wants beyond drawing crosses the bridge
|
|
243
|
-
as a validated, gated capability call. *What each side may know:* the content
|
|
244
|
-
never holds a host secret; whatever it says, the host treats as the content's
|
|
245
|
-
own word and confirms with a person before acting where the capability's gate
|
|
246
|
-
says so.
|
|
247
|
-
|
|
248
|
-
2. **Content ↔ the outside network.** Closed by default and opened only to the
|
|
249
|
-
origins the config's capabilities declare (and, for a served page with files,
|
|
250
|
-
its own version's path on its own origin, and its artifact's asset library at `/_blob/`: the
|
|
251
|
-
host's own server, P082, P089). Two
|
|
252
|
-
kinds of attacker matter:
|
|
253
|
-
- *Attacking the host* (steal credentials, read other data, escape the
|
|
254
|
-
sandbox): stopped by origin isolation — the content is a stranger to the
|
|
255
|
-
host origin.
|
|
256
|
-
- *Leaking or deceiving* (exfiltrate what the content was already given, or
|
|
257
|
-
draw a convincing fake to fool the viewer): origin isolation does not help
|
|
258
|
-
here; egress hardening and gating do. Some channels (a peer connection's
|
|
259
|
-
ICE gathering, a self-navigation of the frame, a nested frame in a fresh
|
|
260
|
-
realm) reach the network outside a frame's own `connect-src`. These are
|
|
261
|
-
closed by in-shell defenses and by the embedding page's own policy, each
|
|
262
|
-
proven by a leak-suite probe (DESIGN.md lists them).
|
|
263
|
-
- *A served page outside its frame* (a public link, a new tab) has no frame's sandbox and no
|
|
264
|
-
embedding page: its own CSP header carries the frame's sandbox tokens, and the shell closes
|
|
265
|
-
`window.open` and stops it navigating away (P099).
|
|
266
|
-
- *An opaque frame is as closed as its page.* A `srcdoc` frame inherits the
|
|
267
|
-
embedding page's whole policy as well as its own, so on a page with
|
|
268
|
-
`default-src 'none'` and a tight `connect-src`/`img-src` its content is more
|
|
269
|
-
closed than its config says: an origin the config opens stays shut. On such
|
|
270
|
-
a page prefer domain mode, whose frames inherit nothing (P058).
|
|
271
|
-
|
|
272
|
-
3. **Host's decision ↔ what a page may do.** Under the capability runtime a page reaches only the
|
|
273
|
-
built-ins and what it declared at publish (stored by the host, given to the mount), and each
|
|
274
|
-
method only for viewers at its level (`view < interact < admin < owner`), which the host's
|
|
275
|
-
access says. The bridge refuses before any handler; the host's own API checks again, since it
|
|
276
|
-
is its data's wall. A person's per-user data is reached by the host's id for them, never the
|
|
277
|
-
content's word.
|
|
278
|
-
|
|
279
|
-
4. **Message boundary.** Every message crossing the frame is validated against a
|
|
280
|
-
schema and checked for sender identity before use; the shell accepts messages
|
|
281
|
-
only from its host, and the host only from its frame. What the frame says about
|
|
282
|
-
itself (its size, its errors, an annotation's anchor and where it is, how many
|
|
283
|
-
matches find found) is the content's word even when the shell says it, since they
|
|
284
|
-
share a realm: the host bounds it and uses it as a UI hint, never as a permission
|
|
285
|
-
(P053, P131). What the host sends in (a mark, a find query) the content can read.
|
|
286
|
-
A nested page (P111) is the one place they don't: the shell is a document of its
|
|
287
|
-
own, the page's parent, on another origin than the page's (opaque), so the page
|
|
288
|
-
reaches nothing of the shell's realm. Nor does any other content: the shell's
|
|
289
|
-
origin is a label of its own that hosts nothing but nested pages' shells, their
|
|
290
|
-
opaque pages, those pages' files and status pages (P114), never the scope's
|
|
291
|
-
origin, where the scope's other displays run content with `allow-same-origin`
|
|
292
|
-
(porthole#56). The server holds that rule, not the host's layout. The shell trusts the page's messages by
|
|
293
|
-
`event.source` alone and passes them on unchanged, never in its own namespace
|
|
294
|
-
(`porthole/shell/`); what it says in that namespace is the shell's own word (its
|
|
295
|
-
transient activation, which only a press or key in the page turns on, and whether
|
|
296
|
-
focus is in it), and the host, which knows the frame is nested from its config
|
|
297
|
-
only, uses it to tell the person's gesture from the page's (the focus guard,
|
|
298
|
-
`comments.open`). The host's own words in that namespace (its ask to look, P120)
|
|
299
|
-
go to the shell alone. A key and a press look the same in that word, so the host
|
|
300
|
-
doesn't ask it while it fights a frame for the keyboard (P120). Everything else
|
|
301
|
-
the page says is still the content's word.
|
|
302
|
-
|
|
303
|
-
5. **Host's decision ↔ content domain.** Authentication and authorization
|
|
304
|
-
*policy* are the host's; carrying the host's decision safely onto the content
|
|
305
|
-
domain is Porthole's *mechanism*. The host decides who may open an instance
|
|
306
|
-
before it calls `issue` (a viewer it knows, or a public link), and may decide
|
|
307
|
-
again on every request (`ServerOptions.authorize`). Porthole carries the decision
|
|
308
|
-
as a one-time ticket, then a signed cookie of that origin and instance only,
|
|
309
|
-
with the host's opaque `subject` inside, and never interprets identity. A deny
|
|
310
|
-
ends access from the next request on and tells the display why.
|
|
311
|
-
|
|
312
|
-
## Extension points
|
|
313
|
-
|
|
314
|
-
- **Capabilities.** New host functions are added to the capability vocabulary
|
|
315
|
-
with a gate, egress need, and guide entry. Adding one extends the bridge, the
|
|
316
|
-
CSP, and the manual together.
|
|
317
|
-
- **Protocol extension points.** MCP Apps gaps go through the spec's own
|
|
318
|
-
mechanisms (experimental capabilities, own-prefixed methods), so the external
|
|
319
|
-
contract stays standard (PRINCIPLE 2).
|
|
320
|
-
- **Theme variables.** The theme map is config; the standard MCP Apps variable
|
|
321
|
-
names are the default vocabulary.
|
|
322
|
-
- **The person's clipboard** is the host's alone: content asks for a copy
|
|
323
|
-
(`copyText`), the host performs it and shows what it copied (P051, P052).
|
|
324
|
-
- **The capability runtime** (`config.runtime`): a contract version's capabilities, each a
|
|
325
|
-
namespace of methods over host functions, with a versioned `.d.ts`; a host offers them through
|
|
326
|
-
its config and serves them through its handlers; an artifact's asset library is served by
|
|
327
|
-
`/server` from the host's store at `/_blob/<id>` on the artifact's origin.
|
|
328
|
-
- **Annotations** (`annotate`): the host drives a select mode and marks anchors in
|
|
329
|
-
the shell; anchors are W3C Web Annotation selectors a host stores with its own
|
|
330
|
-
comments (P053). A mark may carry a count, drawn as a marker, a button at its
|
|
331
|
-
paragraph's end (P133), whose click the host hears and answers with its own UI outside
|
|
332
|
-
the frame (P104), and may be a draft, its author's unposted comment, drawn apart with a
|
|
333
|
-
hollow marker (P107).
|
|
334
|
-
- **Find in page** (`find`): the host draws its own find bar and asks the shell for
|
|
335
|
-
a query (`porthole/find.query`, a request: how many matches, which is current);
|
|
336
|
-
the shell finds it in the same text index annotations read, highlights it in a layer
|
|
337
|
-
of its own, and says when the person pressed Cmd+F or Ctrl+F in the frame, where the
|
|
338
|
-
host takes the shortcut (P131). An older shell answers "isn't offered here", and the
|
|
339
|
-
host calls find unsupported there.
|
|
340
|
-
- **Served content.** A host plugs its own policy and infrastructure into `/server`:
|
|
341
|
-
who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
|
|
342
|
-
how origins are named (`content.name`, other servers' `reserved` namespaces),
|
|
343
|
-
and where apps and artifact versions come from (`upstream`, `artifacts`: a page, or a
|
|
344
|
-
manifest of files and their bytes), and which address means which version (`entry.at`). It runs
|
|
345
|
-
on any runtime with web-standard `Request`/`Response` (Node, Workers).
|
|
346
|
-
|
|
347
|
-
## How a new protocol or platform plugs in
|
|
348
|
-
|
|
349
|
-
- **A new protocol** is a new adapter implementing the capability/lifecycle
|
|
350
|
-
translation. It does not touch the core, the shell mechanisms, or the presets
|
|
351
|
-
beyond adding a preset that selects it. The capability abstraction is the seam.
|
|
352
|
-
- **A new platform** is a new implementation of the platform-host interface
|
|
353
|
-
(create isolated surface, set policy, transport, size, teardown). The framework
|
|
354
|
-
layer, adapters and presets are unchanged; the shell runtime is plain,
|
|
355
|
-
dependency-free script so it runs as-is in a new engine.
|
|
356
|
-
|
|
357
|
-
This is what keeps the three answers independent: *which protocol* (adapter),
|
|
358
|
-
*which platform* (platform host), and *what policy* (preset/config) each vary
|
|
359
|
-
without the others changing.
|
package/docs/OBJECTIVES.md
DELETED
|
@@ -1,116 +0,0 @@
|
|
|
1
|
-
# Objectives
|
|
2
|
-
|
|
3
|
-
## What Porthole is for
|
|
4
|
-
|
|
5
|
-
Any app that wants the "show content made by an agent" ability — like the inline
|
|
6
|
-
visuals and standalone pages in ChatGPT and the Claude app — should be able to
|
|
7
|
-
embed Porthole and get a working, safe display out of the box, plus the manual
|
|
8
|
-
that teaches the agent to write for it.
|
|
9
|
-
|
|
10
|
-
The library has two layers:
|
|
11
|
-
|
|
12
|
-
- a **framework layer** of mechanisms (isolation, egress hardening, the in-frame
|
|
13
|
-
shell, streaming, sizing, theming, the host-function bridge, the guide
|
|
14
|
-
generator); and
|
|
15
|
-
- a **preset policy layer** of ready-made bundles a host adopts with near-zero
|
|
16
|
-
config: **inline widget**, **artifact** (a standalone page), **MCP Apps** (the
|
|
17
|
-
standard protocol), and **URL** (a running app framed by URL, such as a dev
|
|
18
|
-
server's preview).
|
|
19
|
-
|
|
20
|
-
The subject, stated generally, is **HTML drawn by an agent that may optionally
|
|
21
|
-
interact with the agent** — and that interaction is just one host function among
|
|
22
|
-
several. "Out of the box" means: a host picks a preset, passes theme tokens and
|
|
23
|
-
callbacks, and receives a safe display plus a generated agent manual.
|
|
24
|
-
|
|
25
|
-
## Objectives and success criteria
|
|
26
|
-
|
|
27
|
-
1. **Show untrusted agent HTML without putting the host at risk.**
|
|
28
|
-
- *Success:* the conformance/leak suite passes on Chromium, WebKit and
|
|
29
|
-
Firefox — every egress and escape probe attempts its channel and observes
|
|
30
|
-
nothing; the content cannot reach the host origin, its storage, its DOM, or
|
|
31
|
-
its credentials.
|
|
32
|
-
|
|
33
|
-
2. **One config generates the sandbox, the shell, and the manual, in agreement.**
|
|
34
|
-
- *Success:* for every preset, a test derives the CSP, the shell's wired host
|
|
35
|
-
functions, and the generated guide from the same config and asserts they
|
|
36
|
-
match — the guide names only variables the shell injects and only
|
|
37
|
-
capabilities the CSP and bridge allow; changing the config changes all
|
|
38
|
-
three together.
|
|
39
|
-
|
|
40
|
-
3. **Speak the MCP Apps standard, proven against the reference implementation.**
|
|
41
|
-
- *Success:* the MCP Apps preset renders and interacts with the official
|
|
42
|
-
ext-apps example servers **unmodified** (initialize handshake, tool input
|
|
43
|
-
and result, size and theme changes, open-link and message), driven in the
|
|
44
|
-
leak suite.
|
|
45
|
-
|
|
46
|
-
4. **Embed with near-zero config across the modes.**
|
|
47
|
-
- *Success:* a host mounts an inline widget, an artifact page, an MCP Apps
|
|
48
|
-
view and a URL frame each in a few lines using only a preset, theme tokens
|
|
49
|
-
and callbacks; the framework-agnostic core and the React binding both do
|
|
50
|
-
this; no host-specific code lives in the core.
|
|
51
|
-
|
|
52
|
-
5. **Ship the agent manual as a first-class output.**
|
|
53
|
-
- *Success:* each preset produces an agent-facing guide and tool description
|
|
54
|
-
from its config; a real agent that reads the guide produces content that
|
|
55
|
-
renders within the sandbox and reads correctly at the target widths in light
|
|
56
|
-
and dark, checked by rendering the guide's own examples in the leak suite.
|
|
57
|
-
|
|
58
|
-
## Non-goals
|
|
59
|
-
|
|
60
|
-
- **Host-drawn DSL rendering.** Rendering a JSON/JSX/remote-DOM UI description
|
|
61
|
-
with the host's own native components (A2UI, json-render, remote-dom, JSX
|
|
62
|
-
preview) is a separate concern and a different project. Porthole is the HTML
|
|
63
|
-
sandbox only.
|
|
64
|
-
- **A component vocabulary inside the sandbox.** Content is plain HTML and SVG,
|
|
65
|
-
taught by the generated manual; a consistent look comes from the injected theme
|
|
66
|
-
variables and, at most, plain base CSS for native elements, never from tags and
|
|
67
|
-
props an agent must learn (P015). Nor is Porthole a design-system library.
|
|
68
|
-
- **A new widget-side protocol.** The contract is MCP Apps; we do not define an
|
|
69
|
-
alternative (PRINCIPLE 2).
|
|
70
|
-
- **A shell or egress control for URL mode.** A URL frame is someone else's
|
|
71
|
-
running app: Porthole gives it isolation and access auth, nothing more (P020).
|
|
72
|
-
- **Operating infrastructure.** The serving part (`/server`) is a request handler a
|
|
73
|
-
host mounts in its own backend; Porthole runs no service, domain or certificate
|
|
74
|
-
of its own.
|
|
75
|
-
- **Being an agent framework or an MCP server.** Porthole is host-side rendering
|
|
76
|
-
and isolation. It does not run models, implement an MCP server, or decide
|
|
77
|
-
product policy (PRINCIPLE 8).
|
|
78
|
-
|
|
79
|
-
## Who the users are
|
|
80
|
-
|
|
81
|
-
- **Host app developers** who want to show agent-made HTML in a chat or canvas UI
|
|
82
|
-
and do not want to build or audit an isolation layer themselves. They are the
|
|
83
|
-
primary users: they embed the library and pick a preset.
|
|
84
|
-
- **Agents (and the people prompting them)** who write the HTML. They are served
|
|
85
|
-
indirectly: the generated manual is written for them, and the sandbox is the
|
|
86
|
-
environment their code runs in.
|
|
87
|
-
- **MCP App authors** who build standard MCP Apps and want them to render in any
|
|
88
|
-
Porthole-based host unmodified.
|
|
89
|
-
|
|
90
|
-
The first adopter is a normal user of the public API, with no privileged path
|
|
91
|
-
(PRINCIPLE 9).
|
|
92
|
-
|
|
93
|
-
## What "done" means for phase 1
|
|
94
|
-
|
|
95
|
-
Phase 1 is done when:
|
|
96
|
-
|
|
97
|
-
- the framework-agnostic web core and the React binding (with its default,
|
|
98
|
-
replaceable confirmation dialog) exist, with opaque-origin isolation, egress
|
|
99
|
-
hardening, the shell runtime, streaming render, auto-sizing, theming, and the
|
|
100
|
-
host-function bridge;
|
|
101
|
-
- the served modes exist: domain mode (a stable origin per storage scope, CSP in
|
|
102
|
-
headers, ticket → cookie for private content) with its `/server` request
|
|
103
|
-
handler, the artifact page on it, and URL mode (frame, isolation and access
|
|
104
|
-
auth only);
|
|
105
|
-
- the presets exist (inline widget, artifact page, MCP Apps view, URL), each
|
|
106
|
-
generating its CSP and frame policy, and all but URL its shell and manual, from
|
|
107
|
-
one config;
|
|
108
|
-
- the MCP Apps adapter runs the official ext-apps examples unmodified;
|
|
109
|
-
- the leak/conformance suite passes on Chromium and WebKit, then Firefox, and is
|
|
110
|
-
runnable by any host; and
|
|
111
|
-
- the first host has migrated onto it (dogfooding), every one of its features
|
|
112
|
-
that shows agent-made or foreign HTML (widgets, shown HTML files, the dev-server
|
|
113
|
-
preview) going through Porthole, with its own code reduced to configuration
|
|
114
|
-
plus callbacks.
|
|
115
|
-
|
|
116
|
-
Native hosts (WKWebView, maybe Android) are phase 2.
|