@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.
Files changed (118) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/dist/annotate/types.d.ts +15 -1
  3. package/dist/annotate/validate.js +19 -1
  4. package/dist/bridge/bridge.d.ts +1 -8
  5. package/dist/bridge/bridge.js +0 -7
  6. package/dist/bridge/types.d.ts +1 -1
  7. package/dist/check/page-source.js +1 -1
  8. package/dist/check/page.js +1 -1
  9. package/dist/compile/policy.d.ts +0 -7
  10. package/dist/compile/policy.js +1 -10
  11. package/dist/config/capabilities.d.ts +8 -14
  12. package/dist/config/capabilities.js +4 -5
  13. package/dist/config/schema.d.ts +2 -13
  14. package/dist/config/validate.js +0 -24
  15. package/dist/conformance/behavior.js +26 -37
  16. package/dist/conformance/clipboard.js +47 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/displays/displays.js +1 -3
  19. package/dist/guide/limits.js +1 -1
  20. package/dist/guide/runtime.js +1 -1
  21. package/dist/host/create-host.d.ts +1 -1
  22. package/dist/host/create-host.js +8 -52
  23. package/dist/host/door.d.ts +1 -1
  24. package/dist/host/locate.d.ts +1 -1
  25. package/dist/host/locate.js +2 -2
  26. package/dist/host/outcome.d.ts +5 -12
  27. package/dist/host/outcome.js +8 -16
  28. package/dist/host/types.d.ts +6 -22
  29. package/dist/index.d.ts +2 -4
  30. package/dist/index.js +2 -4
  31. package/dist/isolation/served.d.ts +4 -14
  32. package/dist/isolation/served.js +7 -28
  33. package/dist/isolation/types.d.ts +2 -25
  34. package/dist/isolation/types.js +0 -23
  35. package/dist/platform/focus-field.d.ts +11 -0
  36. package/dist/platform/focus-field.js +18 -0
  37. package/dist/platform/types.d.ts +7 -23
  38. package/dist/platform/web.js +8 -106
  39. package/dist/presets/presets.d.ts +0 -2
  40. package/dist/presets/presets.js +0 -1
  41. package/dist/react/frame.d.ts +0 -8
  42. package/dist/react/frame.js +0 -4
  43. package/dist/runtime/contract.d.ts +2 -2
  44. package/dist/runtime/contract.js +2 -2
  45. package/dist/runtime/types.generated.js +6 -6
  46. package/dist/server/files.js +7 -23
  47. package/dist/server/host.d.ts +1 -1
  48. package/dist/server/index.d.ts +1 -1
  49. package/dist/server/index.js +4 -6
  50. package/dist/server/naming.js +1 -1
  51. package/dist/server/server.js +28 -166
  52. package/dist/server/types.d.ts +7 -7
  53. package/dist/shell/annotate.d.ts +3 -0
  54. package/dist/shell/annotate.js +15 -5
  55. package/dist/shell/plan.d.ts +0 -5
  56. package/dist/shell/plan.js +2 -4
  57. package/dist/shell/runtime.js +1 -268
  58. package/docs/ADOPTING.md +398 -1081
  59. package/docs/DECISIONS.md +172 -10
  60. package/docs/DESIGN.md +1114 -1388
  61. package/docs/PRINCIPLES.md +85 -1
  62. package/docs/THREAT_MODEL.md +658 -1127
  63. package/package.json +1 -1
  64. package/src/annotate/types.ts +12 -1
  65. package/src/annotate/validate.ts +23 -1
  66. package/src/bridge/bridge.ts +1 -17
  67. package/src/bridge/types.ts +1 -1
  68. package/src/check/page.ts +1 -1
  69. package/src/compile/policy.ts +1 -11
  70. package/src/config/capabilities.ts +8 -14
  71. package/src/config/schema.ts +2 -13
  72. package/src/config/validate.ts +0 -28
  73. package/src/conformance/behavior.ts +50 -52
  74. package/src/conformance/clipboard.ts +56 -1
  75. package/src/displays/displays.ts +1 -3
  76. package/src/guide/limits.ts +1 -1
  77. package/src/guide/runtime.ts +1 -1
  78. package/src/host/create-host.ts +8 -53
  79. package/src/host/door.ts +1 -1
  80. package/src/host/locate.ts +2 -2
  81. package/src/host/outcome.ts +8 -21
  82. package/src/host/types.ts +6 -20
  83. package/src/index.ts +2 -4
  84. package/src/isolation/served.ts +6 -34
  85. package/src/isolation/types.ts +2 -31
  86. package/src/platform/focus-field.ts +18 -0
  87. package/src/platform/types.ts +7 -22
  88. package/src/platform/web.ts +8 -129
  89. package/src/presets/presets.ts +0 -3
  90. package/src/react/frame.tsx +0 -10
  91. package/src/runtime/contract.ts +4 -4
  92. package/src/runtime/types.generated.ts +6 -6
  93. package/src/server/files.ts +4 -19
  94. package/src/server/host.ts +1 -1
  95. package/src/server/index.ts +4 -16
  96. package/src/server/naming.ts +1 -1
  97. package/src/server/server.ts +29 -189
  98. package/src/server/types.ts +7 -7
  99. package/src/shell/annotate.ts +15 -5
  100. package/src/shell/plan.ts +2 -9
  101. package/src/shell/runtime.ts +1 -268
  102. package/types/runtime/v1/artifact.d.ts +2 -3
  103. package/types/runtime/v1/assets.d.ts +1 -1
  104. package/types/runtime/v1/chat.d.ts +2 -2
  105. package/types/runtime/v1/comments.d.ts +1 -1
  106. package/types/runtime/v1/downloads.d.ts +2 -2
  107. package/types/runtime/v1/links.d.ts +2 -2
  108. package/dist/platform/focus-guard.d.ts +0 -288
  109. package/dist/platform/focus-guard.js +0 -838
  110. package/dist/server/nested.d.ts +0 -66
  111. package/dist/server/nested.js +0 -121
  112. package/dist/shell/frame.d.ts +0 -28
  113. package/dist/shell/frame.js +0 -407
  114. package/docs/ARCHITECTURE.md +0 -359
  115. package/docs/OBJECTIVES.md +0 -116
  116. package/src/platform/focus-guard.ts +0 -1114
  117. package/src/server/nested.ts +0 -157
  118. package/src/shell/frame.ts +0 -444
@@ -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.
@@ -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.