@botiverse/porthole 0.16.0 → 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 +12 -0
- package/dist/annotate/types.d.ts +15 -1
- package/dist/annotate/validate.js +19 -1
- package/dist/bridge/types.d.ts +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +2 -1
- package/dist/platform/types.d.ts +1 -1
- package/dist/shell/annotate.d.ts +3 -0
- package/dist/shell/annotate.js +15 -5
- package/docs/ADOPTING.md +393 -980
- package/docs/DECISIONS.md +57 -0
- package/docs/DESIGN.md +1099 -1336
- package/docs/PRINCIPLES.md +85 -1
- package/docs/THREAT_MODEL.md +655 -997
- package/package.json +1 -1
- package/src/annotate/types.ts +12 -1
- package/src/annotate/validate.ts +23 -1
- package/src/bridge/types.ts +1 -1
- package/src/host/create-host.ts +2 -1
- package/src/platform/types.ts +1 -1
- package/src/shell/annotate.ts +15 -5
- package/docs/ARCHITECTURE.md +0 -326
- package/docs/OBJECTIVES.md +0 -116
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.16.
|
|
3
|
+
"version": "0.16.1",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
package/src/annotate/types.ts
CHANGED
|
@@ -53,7 +53,8 @@ export interface AnnotationAnchor {
|
|
|
53
53
|
* outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
|
|
54
54
|
* own layout px: a host that scales or transforms the frame maps it through that transform too
|
|
55
55
|
* (P105). A result's `documentRect` (P132) and a report's `lastLineDocumentRect` (P133) are the
|
|
56
|
-
* same shape in the document's coordinates, and aren't clamped
|
|
56
|
+
* same shape in the document's coordinates, and aren't clamped; nor is a pick's `pointDocument`
|
|
57
|
+
* (P150), a point there.
|
|
57
58
|
*/
|
|
58
59
|
export interface AnnotationRect {
|
|
59
60
|
readonly x: number;
|
|
@@ -180,6 +181,16 @@ export type AnnotationReport =
|
|
|
180
181
|
readonly rect: AnnotationRect;
|
|
181
182
|
readonly lastLineDocumentRect?: AnnotationRect;
|
|
182
183
|
readonly scroll?: AnnotationScroll;
|
|
184
|
+
/**
|
|
185
|
+
* Where the person picked the element (P150): the point a click, a tap or a held finger
|
|
186
|
+
* picked it at, in the coordinates of `documentRect` (the point in the frame's viewport plus
|
|
187
|
+
* `scroll`), unclamped. For a host's UI by what was pointed at, where the element is larger
|
|
188
|
+
* than most of the frame: its place in the frame's viewport is this less `scroll`, which a
|
|
189
|
+
* host clips to the frame's box. Element picks only (a text selection that carries one is
|
|
190
|
+
* dropped), never without `scroll` (P137), and absent from a pick from the keyboard and from
|
|
191
|
+
* an older shell. The page's word: where to put the host's own UI, nothing more.
|
|
192
|
+
*/
|
|
193
|
+
readonly pointDocument?: { readonly x: number; readonly y: number };
|
|
183
194
|
}
|
|
184
195
|
/** The text selection went away. */
|
|
185
196
|
| { readonly type: "unselected" }
|
package/src/annotate/validate.ts
CHANGED
|
@@ -119,6 +119,14 @@ export function parseRect(value: unknown): AnnotationRect | null {
|
|
|
119
119
|
* may be negative: an engine's overscroll); null for anything else.
|
|
120
120
|
*/
|
|
121
121
|
export function parseScroll(value: unknown): AnnotationScroll | null {
|
|
122
|
+
return parsePoint(value);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* A point (a pick's `pointDocument`, P150): two finite numbers within the coordinate limit, as a
|
|
127
|
+
* scroll is; null for anything else.
|
|
128
|
+
*/
|
|
129
|
+
function parsePoint(value: unknown): { x: number; y: number } | null {
|
|
122
130
|
if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
|
|
123
131
|
return null;
|
|
124
132
|
}
|
|
@@ -236,19 +244,33 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
236
244
|
? undefined
|
|
237
245
|
: parseRect(value.lastLineDocumentRect);
|
|
238
246
|
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
239
|
-
|
|
247
|
+
// Where an element was picked (P150), in the document as the last line is.
|
|
248
|
+
const pointDocument =
|
|
249
|
+
value.pointDocument === undefined ? undefined : parsePoint(value.pointDocument);
|
|
250
|
+
if (
|
|
251
|
+
anchor === null ||
|
|
252
|
+
rect === null ||
|
|
253
|
+
lastLineDocumentRect === null ||
|
|
254
|
+
scroll === null ||
|
|
255
|
+
pointDocument === null
|
|
256
|
+
) {
|
|
240
257
|
return null;
|
|
241
258
|
}
|
|
242
259
|
// A pair, here (P137): a selection has never had one without the other.
|
|
243
260
|
if ((lastLineDocumentRect === undefined) !== (scroll === undefined)) {
|
|
244
261
|
return null;
|
|
245
262
|
}
|
|
263
|
+
// A point only for an element, and with its scroll (P150, as P137): text has no point.
|
|
264
|
+
if (pointDocument !== undefined && (anchor.kind !== "element" || scroll === undefined)) {
|
|
265
|
+
return null;
|
|
266
|
+
}
|
|
246
267
|
return {
|
|
247
268
|
type: "selected",
|
|
248
269
|
anchor,
|
|
249
270
|
rect,
|
|
250
271
|
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
251
272
|
...(scroll === undefined ? {} : { scroll }),
|
|
273
|
+
...(pointDocument === undefined ? {} : { pointDocument }),
|
|
252
274
|
};
|
|
253
275
|
}
|
|
254
276
|
case "unselected":
|
package/src/bridge/types.ts
CHANGED
|
@@ -11,7 +11,7 @@ import type { ViewerInfo } from "../runtime/levels.ts";
|
|
|
11
11
|
import type { RefusalReason } from "./refusal.ts";
|
|
12
12
|
|
|
13
13
|
/**
|
|
14
|
-
* The host-function bridge (
|
|
14
|
+
* The host-function bridge (DESIGN.md § Framework layer): carries a capability call from the
|
|
15
15
|
* frame to the host's handler and its result back, checking at the boundary that the capability
|
|
16
16
|
* is declared, that its arguments are well formed, and that every gate passes, in that order.
|
|
17
17
|
* Adapters decode protocol messages into calls; the bridge alone decides whether they run.
|
package/src/host/create-host.ts
CHANGED
|
@@ -383,7 +383,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
383
383
|
* Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
|
|
384
384
|
* places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
|
|
385
385
|
* document's `scroll` (P132) pass as they were checked: where a mark is in the document,
|
|
386
|
-
* offscreen too, which a clamp would erase; the host clips what it draws from them.
|
|
386
|
+
* offscreen too, which a clamp would erase; the host clips what it draws from them. So does a
|
|
387
|
+
* pick's `pointDocument` (P150).
|
|
387
388
|
*/
|
|
388
389
|
const withinFrame = (report: AnnotationReport): AnnotationReport => {
|
|
389
390
|
const viewport = frameViewport();
|
package/src/platform/types.ts
CHANGED
|
@@ -3,7 +3,7 @@ import type { FrameSource } from "../isolation/types.ts";
|
|
|
3
3
|
import type { Transport } from "../transport/types.ts";
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
* The platform-host seam (
|
|
6
|
+
* The platform-host seam (DESIGN.md § Platform hosts): what owns the isolation primitive and
|
|
7
7
|
* the transport. The web's is an `<iframe>` with `postMessage`; a native web view is another
|
|
8
8
|
* implementation of the same interface, not a fork.
|
|
9
9
|
*/
|
package/src/shell/annotate.ts
CHANGED
|
@@ -108,6 +108,9 @@ export const WORD_LATE = String.raw`(at, now) => {
|
|
|
108
108
|
* them placed as the document scrolls, from one report and the followed mark's scroll;
|
|
109
109
|
* - the last line (P133): where a selection or a mark's words end, in the document's coordinates
|
|
110
110
|
* too (`lastLineDocumentRect`), so a host places its UI after them;
|
|
111
|
+
* - the point picked (P150): where a pointer picked an element (the click's or tap's point, a held
|
|
112
|
+
* finger's), in the document's coordinates too (`pointDocument`), so a host places its UI by what
|
|
113
|
+
* the person pointed at in an element larger than the frame;
|
|
111
114
|
* - the selection followed (P138): what the last `selected` reported (the element picked, or the
|
|
112
115
|
* words selected) is kept while the host follows the selection (`track` with `selection`) or said
|
|
113
116
|
* at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
|
|
@@ -389,11 +392,15 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
389
392
|
return rect === null ? null : inDocument(box(rect), scroll);
|
|
390
393
|
};
|
|
391
394
|
// What a selection's report adds to its box (P133): its last line, with the scroll it was
|
|
392
|
-
// read at; neither where nothing of it is drawn.
|
|
393
|
-
|
|
395
|
+
// read at; neither where nothing of it is drawn. An element's pick by a pointer adds where it
|
|
396
|
+
// was picked (P150): that point in the viewport, in the document by the same scroll.
|
|
397
|
+
const placeOf = (found, point) => {
|
|
394
398
|
const scroll = scrollOf();
|
|
395
399
|
const lastLineDocumentRect = lastLineOf(found, scroll);
|
|
396
|
-
|
|
400
|
+
if (lastLineDocumentRect === null) {
|
|
401
|
+
return {};
|
|
402
|
+
}
|
|
403
|
+
return point ? { lastLineDocumentRect, scroll, pointDocument: { x: point.x + scroll.x, y: point.y + scroll.y } } : { lastLineDocumentRect, scroll };
|
|
397
404
|
};
|
|
398
405
|
|
|
399
406
|
// The shell's own layer, over the content: marks, the outline of what would be picked.
|
|
@@ -1713,7 +1720,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1713
1720
|
holdSelected(anchor, { element });
|
|
1714
1721
|
picked = keeping && !followingSelection ? element : null;
|
|
1715
1722
|
redraw();
|
|
1716
|
-
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
|
|
1723
|
+
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element }, { x, y })));
|
|
1717
1724
|
}, HOLD_MS),
|
|
1718
1725
|
};
|
|
1719
1726
|
}, true);
|
|
@@ -1765,7 +1772,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1765
1772
|
// only for a host that will follow it (P140): for any other it goes with the pick.
|
|
1766
1773
|
picked = keeping && !followingSelection ? element : null;
|
|
1767
1774
|
draw();
|
|
1768
|
-
|
|
1775
|
+
// Where it was clicked or tapped (P150), the point the element was found under; a click
|
|
1776
|
+
// from the keyboard (no detail) has no point.
|
|
1777
|
+
const point = event.detail === 0 ? null : { x: event.clientX, y: event.clientY };
|
|
1778
|
+
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element }, point)));
|
|
1769
1779
|
}, true);
|
|
1770
1780
|
window.addEventListener("keydown", (event) => {
|
|
1771
1781
|
if (event.key !== "Escape") {
|
package/docs/ARCHITECTURE.md
DELETED
|
@@ -1,326 +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
|
-
### URL frame
|
|
205
|
-
|
|
206
|
-
```
|
|
207
|
-
Host app Host backend (+ /server) App origin (served)
|
|
208
|
-
│ mount(url preset) │ │
|
|
209
|
-
│── locate ─────────►│ decide the viewer may see it, │
|
|
210
|
-
│◄── ticketed URL ───│ mint a one-time ticket │
|
|
211
|
-
│ frame src = URL ──────────────────────────────────────►│ ticket → cookie
|
|
212
|
-
│ │ (that origin only)
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
No shell and no protocol: the app is someone else's. The embedding page frames
|
|
216
|
-
only the declared content origins.
|
|
217
|
-
|
|
218
|
-
## Trust boundaries
|
|
219
|
-
|
|
220
|
-
The attackers each boundary faces, what is out of scope, and the composition rule for
|
|
221
|
-
several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
|
|
222
|
-
|
|
223
|
-
1. **Host ↔ content.** The hard boundary. The content runs on an origin that is
|
|
224
|
-
never the host's, so same-origin policy denies it the host's DOM, storage,
|
|
225
|
-
cookies and credentials. Everything it wants beyond drawing crosses the bridge
|
|
226
|
-
as a validated, gated capability call. *What each side may know:* the content
|
|
227
|
-
never holds a host secret; whatever it says, the host treats as the content's
|
|
228
|
-
own word and confirms with a person before acting where the capability's gate
|
|
229
|
-
says so.
|
|
230
|
-
|
|
231
|
-
2. **Content ↔ the outside network.** Closed by default and opened only to the
|
|
232
|
-
origins the config's capabilities declare (and, for a served page with files,
|
|
233
|
-
its own version's path on its own origin, and its artifact's asset library at `/_blob/`: the
|
|
234
|
-
host's own server, P082, P089). Two
|
|
235
|
-
kinds of attacker matter:
|
|
236
|
-
- *Attacking the host* (steal credentials, read other data, escape the
|
|
237
|
-
sandbox): stopped by origin isolation — the content is a stranger to the
|
|
238
|
-
host origin.
|
|
239
|
-
- *Leaking or deceiving* (exfiltrate what the content was already given, or
|
|
240
|
-
draw a convincing fake to fool the viewer): origin isolation does not help
|
|
241
|
-
here; egress hardening and gating do. Some channels (a peer connection's
|
|
242
|
-
ICE gathering, a self-navigation of the frame, a nested frame in a fresh
|
|
243
|
-
realm) reach the network outside a frame's own `connect-src`. These are
|
|
244
|
-
closed by in-shell defenses and by the embedding page's own policy, each
|
|
245
|
-
proven by a leak-suite probe (DESIGN.md lists them).
|
|
246
|
-
- *A served page outside its frame* (a public link, a new tab) has no frame's sandbox and no
|
|
247
|
-
embedding page: its own CSP header carries the frame's sandbox tokens, and the shell closes
|
|
248
|
-
`window.open` and stops it navigating away (P099).
|
|
249
|
-
- *An opaque frame is as closed as its page.* A `srcdoc` frame inherits the
|
|
250
|
-
embedding page's whole policy as well as its own, so on a page with
|
|
251
|
-
`default-src 'none'` and a tight `connect-src`/`img-src` its content is more
|
|
252
|
-
closed than its config says: an origin the config opens stays shut. On such
|
|
253
|
-
a page prefer domain mode, whose frames inherit nothing (P058).
|
|
254
|
-
|
|
255
|
-
3. **Host's decision ↔ what a page may do.** Under the capability runtime a page reaches only the
|
|
256
|
-
built-ins and what it declared at publish (stored by the host, given to the mount), and each
|
|
257
|
-
method only for viewers at its level (`view < interact < admin < owner`), which the host's
|
|
258
|
-
access says. The bridge refuses before any handler; the host's own API checks again, since it
|
|
259
|
-
is its data's wall. A person's per-user data is reached by the host's id for them, never the
|
|
260
|
-
content's word.
|
|
261
|
-
|
|
262
|
-
4. **Message boundary.** Every message crossing the frame is validated against a
|
|
263
|
-
schema and checked for sender identity before use; the shell accepts messages
|
|
264
|
-
only from its host, and the host only from its frame. What the frame says about
|
|
265
|
-
itself (its size, its errors, an annotation's anchor and where it is, how many
|
|
266
|
-
matches find found) is the content's word even when the shell says it, since they
|
|
267
|
-
share a realm: the host bounds it and uses it as a UI hint, never as a permission
|
|
268
|
-
(P053, P131). What the host sends in (a mark, a find query) the content can read.
|
|
269
|
-
|
|
270
|
-
5. **Host's decision ↔ content domain.** Authentication and authorization
|
|
271
|
-
*policy* are the host's; carrying the host's decision safely onto the content
|
|
272
|
-
domain is Porthole's *mechanism*. The host decides who may open an instance
|
|
273
|
-
before it calls `issue` (a viewer it knows, or a public link), and may decide
|
|
274
|
-
again on every request (`ServerOptions.authorize`). Porthole carries the decision
|
|
275
|
-
as a one-time ticket, then a signed cookie of that origin and instance only,
|
|
276
|
-
with the host's opaque `subject` inside, and never interprets identity. A deny
|
|
277
|
-
ends access from the next request on and tells the display why.
|
|
278
|
-
|
|
279
|
-
## Extension points
|
|
280
|
-
|
|
281
|
-
- **Capabilities.** New host functions are added to the capability vocabulary
|
|
282
|
-
with a gate, egress need, and guide entry. Adding one extends the bridge, the
|
|
283
|
-
CSP, and the manual together.
|
|
284
|
-
- **Protocol extension points.** MCP Apps gaps go through the spec's own
|
|
285
|
-
mechanisms (experimental capabilities, own-prefixed methods), so the external
|
|
286
|
-
contract stays standard (PRINCIPLE 2).
|
|
287
|
-
- **Theme variables.** The theme map is config; the standard MCP Apps variable
|
|
288
|
-
names are the default vocabulary.
|
|
289
|
-
- **The person's clipboard** is the host's alone: content asks for a copy
|
|
290
|
-
(`copyText`), the host performs it and shows what it copied (P051, P052).
|
|
291
|
-
- **The capability runtime** (`config.runtime`): a contract version's capabilities, each a
|
|
292
|
-
namespace of methods over host functions, with a versioned `.d.ts`; a host offers them through
|
|
293
|
-
its config and serves them through its handlers; an artifact's asset library is served by
|
|
294
|
-
`/server` from the host's store at `/_blob/<id>` on the artifact's origin.
|
|
295
|
-
- **Annotations** (`annotate`): the host drives a select mode and marks anchors in
|
|
296
|
-
the shell; anchors are W3C Web Annotation selectors a host stores with its own
|
|
297
|
-
comments (P053). A mark may carry a count, drawn as a marker, a button at its
|
|
298
|
-
paragraph's end (P133), whose click the host hears and answers with its own UI outside
|
|
299
|
-
the frame (P104), and may be a draft, its author's unposted comment, drawn apart with a
|
|
300
|
-
hollow marker (P107).
|
|
301
|
-
- **Find in page** (`find`): the host draws its own find bar and asks the shell for
|
|
302
|
-
a query (`porthole/find.query`, a request: how many matches, which is current);
|
|
303
|
-
the shell finds it in the same text index annotations read, highlights it in a layer
|
|
304
|
-
of its own, and says when the person pressed Cmd+F or Ctrl+F in the frame, where the
|
|
305
|
-
host takes the shortcut (P131). An older shell answers "isn't offered here", and the
|
|
306
|
-
host calls find unsupported there.
|
|
307
|
-
- **Served content.** A host plugs its own policy and infrastructure into `/server`:
|
|
308
|
-
who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
|
|
309
|
-
how origins are named (`content.name`, other servers' `reserved` namespaces),
|
|
310
|
-
and where apps and artifact versions come from (`upstream`, `artifacts`: a page, or a
|
|
311
|
-
manifest of files and their bytes), and which address means which version (`entry.at`). It runs
|
|
312
|
-
on any runtime with web-standard `Request`/`Response` (Node, Workers).
|
|
313
|
-
|
|
314
|
-
## How a new protocol or platform plugs in
|
|
315
|
-
|
|
316
|
-
- **A new protocol** is a new adapter implementing the capability/lifecycle
|
|
317
|
-
translation. It does not touch the core, the shell mechanisms, or the presets
|
|
318
|
-
beyond adding a preset that selects it. The capability abstraction is the seam.
|
|
319
|
-
- **A new platform** is a new implementation of the platform-host interface
|
|
320
|
-
(create isolated surface, set policy, transport, size, teardown). The framework
|
|
321
|
-
layer, adapters and presets are unchanged; the shell runtime is plain,
|
|
322
|
-
dependency-free script so it runs as-is in a new engine.
|
|
323
|
-
|
|
324
|
-
This is what keeps the three answers independent: *which protocol* (adapter),
|
|
325
|
-
*which platform* (platform host), and *what policy* (preset/config) each vary
|
|
326
|
-
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.
|