@botiverse/porthole 0.2.1 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +83 -0
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +51 -0
- package/dist/conformance/entry.d.ts +19 -7
- package/dist/conformance/entry.js +39 -12
- package/dist/conformance/harness.js +8 -8
- package/dist/conformance/host-kit.d.ts +48 -13
- package/dist/conformance/host-kit.js +140 -28
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/index.js +1 -1
- package/dist/conformance/limits.js +15 -2
- package/dist/conformance/page.d.ts +6 -0
- package/dist/conformance/page.js +8 -0
- package/dist/conformance/served.d.ts +4 -4
- package/dist/conformance/served.js +26 -16
- package/dist/host/types.d.ts +6 -3
- package/dist/isolation/served.js +13 -2
- package/dist/node/index.d.ts +11 -3
- package/dist/node/index.js +70 -10
- package/dist/react/frame.d.ts +5 -2
- package/dist/server/host.d.ts +42 -8
- package/dist/server/host.js +35 -5
- package/dist/server/index.d.ts +4 -1
- package/dist/server/index.js +2 -0
- package/dist/server/pages.js +15 -1
- package/dist/server/proxy.js +2 -0
- package/dist/server/server.js +9 -2
- package/dist/server/types.d.ts +15 -6
- package/docs/ARCHITECTURE.md +277 -0
- package/docs/DECISIONS.md +1811 -0
- package/docs/DESIGN.md +1074 -0
- package/docs/OBJECTIVES.md +116 -0
- package/docs/PRINCIPLES.md +155 -0
- package/examples/app.mjs +234 -0
- package/examples/conformance/playwright.config.mjs +28 -0
- package/examples/conformance/porthole.spec.mjs +36 -0
- package/examples/node/server.mjs +75 -0
- package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
- package/examples/workers/worker.mjs +33 -0
- package/examples/workers/wrangler.jsonc +19 -0
- package/package.json +9 -3
- package/src/cli.ts +54 -0
- package/src/conformance/entry.ts +70 -19
- package/src/conformance/host-kit.ts +194 -45
- package/src/conformance/index.ts +4 -0
- package/src/conformance/limits.ts +21 -4
- package/src/conformance/page.ts +8 -0
- package/src/conformance/served.ts +34 -21
- package/src/host/types.ts +6 -3
- package/src/isolation/served.ts +12 -2
- package/src/node/index.ts +73 -10
- package/src/react/frame.tsx +5 -2
- package/src/server/host.ts +84 -14
- package/src/server/index.ts +6 -0
- package/src/server/pages.ts +15 -1
- package/src/server/proxy.ts +2 -0
- package/src/server/server.ts +11 -2
- package/src/server/types.ts +18 -7
package/dist/react/frame.d.ts
CHANGED
|
@@ -66,8 +66,11 @@ export interface PortholeFrameProps {
|
|
|
66
66
|
/** Run at once, without waiting to near the screen (it still counts toward the page's most). */
|
|
67
67
|
readonly eager?: boolean;
|
|
68
68
|
/**
|
|
69
|
-
* Fill the box (give it, or its parent, a height)
|
|
70
|
-
*
|
|
69
|
+
* Fill the box (give it, or its parent, a height) instead of growing with the content.
|
|
70
|
+
*
|
|
71
|
+
* @deprecated Say it in the config, `layout: { kind: "fill" }`: every frame then fills, and the
|
|
72
|
+
* manual tells the agent so. This prop sizes only this frame, so the manual keeps saying the
|
|
73
|
+
* height follows the content (P071). A url-mode app always fills.
|
|
71
74
|
*/
|
|
72
75
|
readonly fill?: boolean;
|
|
73
76
|
readonly onInitialized?: () => void;
|
package/dist/server/host.d.ts
CHANGED
|
@@ -21,6 +21,12 @@ export interface HealthOptions {
|
|
|
21
21
|
/** How the check is fetched (default: `fetch`; on Node, `nodeProbe()`). */
|
|
22
22
|
readonly probe?: HealthProbe;
|
|
23
23
|
readonly timeoutMs?: number;
|
|
24
|
+
/**
|
|
25
|
+
* Told each time the gate's state changes (P070): checking to healthy or unhealthy, and every
|
|
26
|
+
* flip between them, with the new view. `meta().served` changes with it, so an app that tells
|
|
27
|
+
* its clients whether frames are served pushes it from here.
|
|
28
|
+
*/
|
|
29
|
+
readonly onChange?: (view: ContentHealthView) => void;
|
|
24
30
|
}
|
|
25
31
|
/** Where content stands, for the app's own meta and logs. */
|
|
26
32
|
export interface ContentHealthView {
|
|
@@ -64,7 +70,13 @@ export interface ContentHostOptions<V> {
|
|
|
64
70
|
* that says which scope a label names (`prefixedName` does).
|
|
65
71
|
*/
|
|
66
72
|
readonly name?: Naming;
|
|
67
|
-
/**
|
|
73
|
+
/**
|
|
74
|
+
* Labels the app itself serves on the content domain, which `fetch` hands back (null) so the
|
|
75
|
+
* app's own routes answer there: Ferry's `p-*` previews, another server's namespace it routes
|
|
76
|
+
* on. Not for labels nothing should answer: a label the naming never makes, the bare domain
|
|
77
|
+
* and an address `entry.at` says names nothing all get Porthole's 404, with nothing to list
|
|
78
|
+
* (P070). The health label is reserved by the gate itself.
|
|
79
|
+
*/
|
|
68
80
|
readonly reserved?: readonly string[] | ((label: string) => boolean);
|
|
69
81
|
/**
|
|
70
82
|
* Policy 1, mapping: the instance a request proposes (`{ instance }`), as the app means it,
|
|
@@ -105,17 +117,39 @@ export interface EntryOptions<V> {
|
|
|
105
117
|
/** The app's authorize route (`ContentHost.authorize`), an absolute URL on an app origin. */
|
|
106
118
|
readonly authorizeUrl: string;
|
|
107
119
|
/**
|
|
108
|
-
* Policy 1 for a clean address: the instance a scope's path means, or null
|
|
109
|
-
* the address's pathname; its query rides along but never chooses the
|
|
120
|
+
* Policy 1 for a clean address: the instance a scope's path means, or null/undefined: nothing
|
|
121
|
+
* (404). The path is the address's pathname; its query rides along but never chooses the
|
|
122
|
+
* instance. Asked twice: on the content origin, with no viewer, whether the address names
|
|
123
|
+
* anything at all (nothing: Porthole's 404 there, never the app's sign-in, P070); then at the
|
|
124
|
+
* authorize route with the viewer. Say what exists the same way for both; `access` says who
|
|
125
|
+
* may see it.
|
|
110
126
|
*/
|
|
111
|
-
readonly at: (scope: string, path: string, viewer: V | null, request: Request) => Awaitable<InstanceRef | null>;
|
|
127
|
+
readonly at: (scope: string, path: string, viewer: V | null, request: Request) => Awaitable<InstanceRef | null | undefined>;
|
|
112
128
|
/**
|
|
113
129
|
* The app's own sign-in, which comes back to `returnTo` (the authorize URL) once signed in.
|
|
114
|
-
* Only ever on a tab: in a frame, the person is asked to open a new tab instead.
|
|
130
|
+
* Only ever on a tab: in a frame, the person is asked to open a new tab instead. `entry` is the
|
|
131
|
+
* address being opened, decoded (P070).
|
|
115
132
|
*/
|
|
116
|
-
readonly signIn: (returnTo: string, request: Request) => Awaitable<Response>;
|
|
117
|
-
/**
|
|
118
|
-
|
|
133
|
+
readonly signIn: (returnTo: string, request: Request, entry: EntryContext) => Awaitable<Response>;
|
|
134
|
+
/**
|
|
135
|
+
* The app's refusal page on a tab (a frame gets Porthole's plain one), for the address in
|
|
136
|
+
* `entry`. Nothing (null, undefined): Porthole's own (P070).
|
|
137
|
+
*/
|
|
138
|
+
readonly refusal?: (status: 403 | 404, request: Request, entry: EntryContext) => Awaitable<Response | null | undefined>;
|
|
139
|
+
}
|
|
140
|
+
/** The clean address a redirect entry is opening, as its authorize route decoded it (P070). */
|
|
141
|
+
export interface EntryContext {
|
|
142
|
+
/** The address's label, and the scope it names (null: one the naming never makes). */
|
|
143
|
+
readonly label: string;
|
|
144
|
+
readonly scope: string | null;
|
|
145
|
+
/** The path (and query) asked for. */
|
|
146
|
+
readonly path: string;
|
|
147
|
+
/** The clean address itself: where the person comes back to. */
|
|
148
|
+
readonly url: string;
|
|
149
|
+
/** The instance the path names for this viewer (`entry.at`), or null. */
|
|
150
|
+
readonly instance: InstanceRef | null;
|
|
151
|
+
/** Whether it was asked from a frame. */
|
|
152
|
+
readonly framed: boolean;
|
|
119
153
|
}
|
|
120
154
|
export interface ContentHost<V> {
|
|
121
155
|
/** The parsed content domain, or null (off, or unusable settings under the fallback). */
|
package/dist/server/host.js
CHANGED
|
@@ -88,7 +88,19 @@ export function createContentHost(options) {
|
|
|
88
88
|
...(options.upstream === undefined ? {} : { upstream: options.upstream }),
|
|
89
89
|
...(options.entry === undefined
|
|
90
90
|
? {}
|
|
91
|
-
: {
|
|
91
|
+
: {
|
|
92
|
+
entry: {
|
|
93
|
+
authorizeUrl: options.entry.authorizeUrl,
|
|
94
|
+
// Whether a clean address names anything, before a browser is sent away (P070).
|
|
95
|
+
named: async (label, path, request) => {
|
|
96
|
+
const scope = options.name?.scopeOf?.(label) ?? null;
|
|
97
|
+
const at = options.entry?.at;
|
|
98
|
+
return (scope !== null &&
|
|
99
|
+
at !== undefined &&
|
|
100
|
+
(await at(scope, path, null, request)) != null);
|
|
101
|
+
},
|
|
102
|
+
},
|
|
103
|
+
}),
|
|
92
104
|
...(options.authorize === undefined
|
|
93
105
|
? {}
|
|
94
106
|
: {
|
|
@@ -173,6 +185,14 @@ export function createContentHost(options) {
|
|
|
173
185
|
? { evt: "porthole.content.healthy" }
|
|
174
186
|
: { evt: "porthole.content.unhealthy", reason });
|
|
175
187
|
}
|
|
188
|
+
if (before.state !== view.state) {
|
|
189
|
+
try {
|
|
190
|
+
gate.onChange?.(view);
|
|
191
|
+
}
|
|
192
|
+
catch {
|
|
193
|
+
// The app's listener failing changes nothing here.
|
|
194
|
+
}
|
|
195
|
+
}
|
|
176
196
|
running = null;
|
|
177
197
|
schedule();
|
|
178
198
|
return view;
|
|
@@ -356,18 +376,28 @@ export function createContentHost(options) {
|
|
|
356
376
|
try {
|
|
357
377
|
const instance = scope === null
|
|
358
378
|
? null
|
|
359
|
-
: await entry.at(scope, new URL(state.path, "https://x.invalid").pathname, viewer, request);
|
|
379
|
+
: ((await entry.at(scope, new URL(state.path, "https://x.invalid").pathname, viewer, request)) ?? null);
|
|
360
380
|
const grant = instance === null ? null : await options.access(instance, viewer, request);
|
|
381
|
+
// The address being opened, decoded, for the app's sign-in and refusal pages.
|
|
382
|
+
const context = {
|
|
383
|
+
label: state.label,
|
|
384
|
+
scope,
|
|
385
|
+
path: state.path,
|
|
386
|
+
url: clean,
|
|
387
|
+
instance,
|
|
388
|
+
framed,
|
|
389
|
+
};
|
|
361
390
|
if (instance === null || grant === null) {
|
|
362
391
|
if (viewer === null) {
|
|
363
392
|
// The app's sign-in never shows in a frame: the person opens a tab for it.
|
|
364
393
|
return framed
|
|
365
394
|
? appPage(401, "Open this in a new tab to sign in", "Signing in doesn't work inside a frame.", "sign-in", method)
|
|
366
|
-
: await entry.signIn(request.url, request);
|
|
395
|
+
: await entry.signIn(request.url, request, context);
|
|
367
396
|
}
|
|
368
397
|
const status = instance === null ? 404 : 403;
|
|
369
|
-
|
|
370
|
-
|
|
398
|
+
const own = framed ? null : await entry.refusal?.(status, request, context);
|
|
399
|
+
if (own !== null && own !== undefined) {
|
|
400
|
+
return own;
|
|
371
401
|
}
|
|
372
402
|
return status === 404
|
|
373
403
|
? appPage(404, "Not found", "There is nothing here.", "not-found", method)
|
package/dist/server/index.d.ts
CHANGED
|
@@ -33,10 +33,13 @@
|
|
|
33
33
|
* content without a valid ticket or cookie gets nothing of the content.
|
|
34
34
|
*/
|
|
35
35
|
export { createServer } from "./server.ts";
|
|
36
|
-
export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type EntryOptions, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
|
|
36
|
+
export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type EntryContext, type EntryOptions, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
|
|
37
37
|
export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDomainInfo, type ContentDomainProblem, } from "./domain.ts";
|
|
38
38
|
export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
|
|
39
39
|
export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
40
40
|
export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
|
|
41
|
+
export { conformancePage } from "../conformance/page.ts";
|
|
42
|
+
export type { PortholeConfig } from "../config/schema.ts";
|
|
43
|
+
export type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
|
|
41
44
|
export { proxyTo, type ProxyOptions } from "./proxy.ts";
|
|
42
45
|
export type { Access, ArtifactStore, AuthorizeAnswer, AuthorizeRequest, Authorizer, ContentDomain, EntryState, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";
|
package/dist/server/index.js
CHANGED
|
@@ -38,4 +38,6 @@ export { clashOf, contentDomain, ContentDomainError, hostnameOf, } from "./domai
|
|
|
38
38
|
export { d1TicketSchema, d1TicketStore, memoryTicketStore, } from "./tickets.js";
|
|
39
39
|
export { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
40
40
|
export { isHostLabel, prefixedName } from "./naming.js";
|
|
41
|
+
// The page an app serves in conformance test mode (P071).
|
|
42
|
+
export { conformancePage } from "../conformance/page.js";
|
|
41
43
|
export { proxyTo } from "./proxy.js";
|
package/dist/server/pages.js
CHANGED
|
@@ -14,7 +14,21 @@ export const STATUS_SCRIPT_PATH = "/__porthole/status.js";
|
|
|
14
14
|
export const ENTER_SCRIPT_PATH = "/__porthole/enter.js";
|
|
15
15
|
/** Answers 204 when the request carries a good session for its origin's app, 401 otherwise. */
|
|
16
16
|
export const SESSION_PATH = "/__porthole/session";
|
|
17
|
-
|
|
17
|
+
/**
|
|
18
|
+
* Tells the page that frames this one how loading went, at each web host origin. A desktop app's
|
|
19
|
+
* own scheme (`ferry://app`) is no target origin a browser takes (postMessage throws), so where
|
|
20
|
+
* the host origins hold one, and the parent isn't known to be a web host origin, the word goes to
|
|
21
|
+
* the parent as `*`: these pages' `frame-ancestors` already hold their parent to the host origins,
|
|
22
|
+
* and what they say is no secret (P070). One origin failing never stops the page.
|
|
23
|
+
*/
|
|
24
|
+
const say = () => `const say = (params) => {
|
|
25
|
+
if (window.parent === window) return;
|
|
26
|
+
const message = { jsonrpc: "2.0", method: ${JSON.stringify(FRAME_STATUS_METHOD)}, params };
|
|
27
|
+
const web = hosts.filter((origin) => origin.startsWith("https://") || origin.startsWith("http://"));
|
|
28
|
+
for (const origin of web) { try { window.parent.postMessage(message, origin); } catch (_) {} }
|
|
29
|
+
const parent = location.ancestorOrigins && location.ancestorOrigins.length > 0 ? location.ancestorOrigins[0] : null;
|
|
30
|
+
if (web.length < hosts.length && (parent === null || !web.includes(parent))) { try { window.parent.postMessage(message, "*"); } catch (_) {} }
|
|
31
|
+
};`;
|
|
18
32
|
/** Tells the host the page is blocked, and why (from the page's data attributes). */
|
|
19
33
|
const STATUS_SCRIPT = `(() => {
|
|
20
34
|
const main = document.querySelector("[data-porthole-status]");
|
package/dist/server/proxy.js
CHANGED
|
@@ -96,6 +96,8 @@ export function proxyTo(options = {}) {
|
|
|
96
96
|
method,
|
|
97
97
|
headers: upstreamRequestHeaders(request.headers, access.origin, target),
|
|
98
98
|
redirect: "manual",
|
|
99
|
+
// The browser went away (`nodeHost` aborts it): so does the relay (P070).
|
|
100
|
+
signal: request.signal,
|
|
99
101
|
...(hasBody ? { body: request.body, duplex: "half" } : {}),
|
|
100
102
|
});
|
|
101
103
|
return new Response(method === "HEAD" ? null : answer.body, {
|
package/dist/server/server.js
CHANGED
|
@@ -565,8 +565,15 @@ export function createServer(options) {
|
|
|
565
565
|
* signed state, the browser holding the state's nonce in a cookie of this origin. A path just
|
|
566
566
|
* entered whose cookie still didn't come back is a browser that keeps none here: no loop.
|
|
567
567
|
*/
|
|
568
|
-
function beginEntry(request, url, label, to) {
|
|
568
|
+
async function beginEntry(request, url, label, to) {
|
|
569
569
|
const method = request.method.toUpperCase();
|
|
570
|
+
// An address that names nothing is nothing here (P070): never a trip to the app's sign-in.
|
|
571
|
+
const scopeOf = content.name?.scopeOf;
|
|
572
|
+
const named = options.entry?.named;
|
|
573
|
+
if ((scopeOf !== undefined && scopeOf(label) === null) ||
|
|
574
|
+
(named !== undefined && !(await named(label, url.pathname, request)))) {
|
|
575
|
+
return page(404, "Nothing here", "This address names no content.", method);
|
|
576
|
+
}
|
|
570
577
|
if (method !== "GET" && method !== "HEAD") {
|
|
571
578
|
return page(401, "Open this from the app", "Open this address in a browser.", method, "session");
|
|
572
579
|
}
|
|
@@ -942,7 +949,7 @@ export function createServer(options) {
|
|
|
942
949
|
return await serveAccess(request, entered, null);
|
|
943
950
|
}
|
|
944
951
|
if (options.upstream === undefined || accessOf(request, label, null) === null) {
|
|
945
|
-
return beginEntry(request, url, label, authorizeUrl);
|
|
952
|
+
return await beginEntry(request, url, label, authorizeUrl);
|
|
946
953
|
}
|
|
947
954
|
}
|
|
948
955
|
// Without an upstream, only Porthole's own paths are served here: any other is nothing.
|
package/dist/server/types.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
import type { Naming } from "./naming.ts";
|
|
3
4
|
export interface ContentDomain {
|
|
4
5
|
/**
|
|
5
6
|
* The registrable domain content is served under, used for nothing else
|
|
@@ -16,13 +17,14 @@ export interface ContentDomain {
|
|
|
16
17
|
* names like `a-<id>`) must return one lowercase DNS label, the same for the same scope, a
|
|
17
18
|
* different one for a different scope, and never a `reserved` one.
|
|
18
19
|
*/
|
|
19
|
-
readonly name?:
|
|
20
|
+
readonly name?: Naming;
|
|
20
21
|
/**
|
|
21
|
-
* Labels
|
|
22
|
-
* (`f` for `<instance>.f.<domain>`,
|
|
23
|
-
* `p
|
|
24
|
-
* whether a label is reserved. Requests for them, and for
|
|
25
|
-
* host's routes), so a host routes them without wrapping
|
|
22
|
+
* Labels something else serves on this domain, so this server never names them and hands their
|
|
23
|
+
* requests back: another server's namespace (`f` for `<instance>.f.<domain>`, where that server
|
|
24
|
+
* answers), or the host's own (`p-*`: its previews). Each entry is a whole label, or a prefix
|
|
25
|
+
* ending in `*`; or a function that says whether a label is reserved. Requests for them, and for
|
|
26
|
+
* the names under them, get null (the host's routes), so a host routes them without wrapping
|
|
27
|
+
* `handle`. Labels nothing serves need no entry: they get this server's 404 (P070).
|
|
26
28
|
*/
|
|
27
29
|
readonly reserved?: readonly string[] | ((label: string) => boolean);
|
|
28
30
|
}
|
|
@@ -161,6 +163,13 @@ export interface ServerOptions {
|
|
|
161
163
|
*/
|
|
162
164
|
readonly entry?: {
|
|
163
165
|
readonly authorizeUrl: string;
|
|
166
|
+
/**
|
|
167
|
+
* Whether a clean address names anything (P070): asked before sending a browser away, with
|
|
168
|
+
* the address's label and pathname. False: this server's 404, never the authorize route. A
|
|
169
|
+
* naming that says a label's scope (`Naming.scopeOf`) already answers 404 for a label it never
|
|
170
|
+
* makes.
|
|
171
|
+
*/
|
|
172
|
+
readonly named?: (label: string, path: string, request: Request) => boolean | Promise<boolean>;
|
|
164
173
|
};
|
|
165
174
|
}
|
|
166
175
|
/** A redirect entry's state, as the host's authorize route reads it (`PortholeServer.entryState`). */
|
|
@@ -0,0 +1,277 @@
|
|
|
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).
|
|
6
|
+
|
|
7
|
+
## The core abstraction
|
|
8
|
+
|
|
9
|
+
Porthole renders **agent-drawn HTML plus a declared set of host functions.**
|
|
10
|
+
|
|
11
|
+
- The HTML is untrusted. It may draw anything, but on its own it can only draw.
|
|
12
|
+
- A **host function (capability)** is any power beyond drawing: send a prompt to
|
|
13
|
+
the agent, open a link, read or write state, call a tool, read data, report an
|
|
14
|
+
error. Each is named in the config and carries three facts: its **gate** (needs
|
|
15
|
+
a user gesture, needs a person's confirmation, is rate-limited), its **egress
|
|
16
|
+
needs** (origins it must reach), and its **guide entry** (how the manual
|
|
17
|
+
describes it).
|
|
18
|
+
|
|
19
|
+
One capability list therefore drives three artifacts: the **bridge** (which
|
|
20
|
+
functions the shell wires and the host handles), the **CSP** (what the sandbox
|
|
21
|
+
may reach), and the **manual** (what the agent is told). This is why the config
|
|
22
|
+
is the single source (PRINCIPLE 3) and why "talk to the agent" is not special —
|
|
23
|
+
it is one host function (PRINCIPLE 4).
|
|
24
|
+
|
|
25
|
+
## Layers
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
┌──────────────────────────────────────────────────────────┐
|
|
29
|
+
│ Host app (owns product policy, theme, callbacks) │
|
|
30
|
+
└───────────────┬──────────────────────────────────────────┘
|
|
31
|
+
│ picks a preset, passes theme + callbacks
|
|
32
|
+
┌─────────────────────────▼─────────────────────────────────────────┐
|
|
33
|
+
│ PRESET POLICY LAYER │
|
|
34
|
+
│ inline-widget · artifact · mcp-app · url │
|
|
35
|
+
│ each = a config: CSP+origins, capabilities+gates, theme, guide │
|
|
36
|
+
└─────────────────────────┬─────────────────────────────────────────┘
|
|
37
|
+
│ one config
|
|
38
|
+
┌─────────────────────────▼─────────────────────────────────────────┐
|
|
39
|
+
│ FRAMEWORK LAYER (mechanisms only, no policy) │
|
|
40
|
+
│ │
|
|
41
|
+
│ config compiler ── CSP + sandbox/allow attrs │
|
|
42
|
+
│ └── shell runtime (what to wire) │
|
|
43
|
+
│ └── guide + tool description │
|
|
44
|
+
│ │
|
|
45
|
+
│ isolation core · egress hardening · streaming render · auto-size │
|
|
46
|
+
│ theming · host-function bridge · guide gen · serving (/server) │
|
|
47
|
+
└───────┬───────────────────────────────────────┬────────────────────┘
|
|
48
|
+
│ host side │ in-frame side (shell)
|
|
49
|
+
┌───────▼─────────┐ ┌───────▼──────────────────┐
|
|
50
|
+
│ PROTOCOL ADAPTER│ ◄── transport ──► │ SHELL (runs first in │
|
|
51
|
+
│ (MCP Apps; …) │ (postMessage/ │ the isolated frame; │
|
|
52
|
+
│ │ native bridge) │ renders HTML, wires caps)│
|
|
53
|
+
└───────┬─────────┘ └───────────────────────────┘
|
|
54
|
+
│
|
|
55
|
+
┌───────▼───────────────────────────────────────────────────────────┐
|
|
56
|
+
│ PLATFORM HOST web (iframe) now · WKWebView / Android later │
|
|
57
|
+
└─────────────────────────────────────────────────────────────────── ┘
|
|
58
|
+
|
|
59
|
+
CONFORMANCE / LEAK SUITE drives a platform host through the adapter and
|
|
60
|
+
probes every egress and escape channel (runnable by any host).
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Framework layer (mechanisms)
|
|
64
|
+
|
|
65
|
+
Pure mechanism, no product policy, no host or vendor types.
|
|
66
|
+
|
|
67
|
+
- **Config compiler.** Turns one config into the CSP string, the iframe sandbox
|
|
68
|
+
and `allow` attributes, the shell's wiring, and the guide + tool description.
|
|
69
|
+
Deterministic and pure, so a test can assert the three outputs agree.
|
|
70
|
+
- **Isolation core.** Places the content on an origin that is never the host's,
|
|
71
|
+
with nothing of the host's reachable: an opaque-origin frame, or a served
|
|
72
|
+
origin of its own (domain mode: a subdomain per storage scope on a separate
|
|
73
|
+
registrable domain; url mode: the app's own origin). The mode is chosen by
|
|
74
|
+
config; the rest of the framework does not depend on which.
|
|
75
|
+
- **Egress hardening.** The closed-by-default network and navigation walls, plus
|
|
76
|
+
the in-shell defenses for channels a CSP does not cover (see Trust boundaries).
|
|
77
|
+
- **Shell runtime.** The code that runs first inside the frame: applies theme,
|
|
78
|
+
inserts the HTML (streaming-aware), reports size and errors, and exposes the
|
|
79
|
+
declared host functions to the content.
|
|
80
|
+
- **Host-function bridge.** Carries capability calls from the shell to the host
|
|
81
|
+
and results back, over a transport, with validation and gating at the boundary.
|
|
82
|
+
- **Streaming render, auto-size, theming, guide generator.** The remaining
|
|
83
|
+
mechanisms, each usable on its own. Content is plain HTML and SVG; its look
|
|
84
|
+
comes from the theme variables, never from a component vocabulary (P015).
|
|
85
|
+
- **Serving.** For served modes, a request handler a host's backend mounts: it
|
|
86
|
+
serves documents on their own origins with their CSP in headers, and turns a
|
|
87
|
+
one-time ticket the host minted into a cookie of that origin only.
|
|
88
|
+
|
|
89
|
+
### Preset policy layer
|
|
90
|
+
|
|
91
|
+
A preset is a named config with safe defaults. It fixes the CSP and allowed
|
|
92
|
+
origins, the capabilities and their gates, the theme vocabulary, and the manual.
|
|
93
|
+
A host adopts a preset and overrides only theme and callbacks.
|
|
94
|
+
|
|
95
|
+
- **inline-widget** — host injects agent code into a strict, opaque-origin frame
|
|
96
|
+
with a shell; smallest capability set; for cards inside a conversation.
|
|
97
|
+
- **artifact** — a standalone page: written into an opaque frame where the host
|
|
98
|
+
has it, or served at a URL on a separate registrable domain, CSP in headers,
|
|
99
|
+
versioned.
|
|
100
|
+
- **mcp-app** — renders a standard MCP Apps view (a `ui://` template plus tool
|
|
101
|
+
input/result), using the MCP Apps adapter.
|
|
102
|
+
- **url** — frames a running app by URL (a dev server's preview): isolation and
|
|
103
|
+
access auth only; no shell, no capabilities, no egress control.
|
|
104
|
+
|
|
105
|
+
### Protocol adapters
|
|
106
|
+
|
|
107
|
+
A thin adapter maps the framework's capability and lifecycle events onto a wire
|
|
108
|
+
protocol. **MCP Apps** is the first and default. The adapter is the only layer
|
|
109
|
+
that knows protocol method names and shapes; the core speaks capabilities.
|
|
110
|
+
|
|
111
|
+
### Platform hosts
|
|
112
|
+
|
|
113
|
+
The platform host owns the actual isolation primitive and the transport: an
|
|
114
|
+
`iframe` + `postMessage` on the web now; a `WKWebView` + message handler on iOS
|
|
115
|
+
later. The framework layer is written against a small platform interface so a new
|
|
116
|
+
platform is an implementation of that interface, not a fork.
|
|
117
|
+
|
|
118
|
+
### Conformance / leak suite
|
|
119
|
+
|
|
120
|
+
A standalone test runner that drives a platform host through an adapter and
|
|
121
|
+
attempts every known egress and escape channel, asserting none succeeds. Any host
|
|
122
|
+
can run it against its own integration. It is both our regression gate and the
|
|
123
|
+
artifact we offer upstream (PRINCIPLE 5, 6).
|
|
124
|
+
|
|
125
|
+
## Contracts between layers
|
|
126
|
+
|
|
127
|
+
- **Host → preset:** a preset name, theme tokens (resolved per color scheme), and
|
|
128
|
+
callbacks for each enabled host function. Nothing else is required.
|
|
129
|
+
- **Preset → framework:** one config (capabilities with gates and egress needs,
|
|
130
|
+
allowed origins, theme variable map, limits, layout, mode and isolation).
|
|
131
|
+
- **Config → {CSP, shell, guide}:** derived, never hand-written; a test asserts
|
|
132
|
+
agreement.
|
|
133
|
+
- **Framework ↔ shell:** lifecycle and capability messages over a transport.
|
|
134
|
+
Validated both directions; unknown or malformed messages are dropped.
|
|
135
|
+
- **Framework ↔ adapter:** the adapter translates between capability/lifecycle
|
|
136
|
+
events and protocol messages; it may add protocol-only messages (handshake,
|
|
137
|
+
teardown) that the framework does not model.
|
|
138
|
+
- **Framework ↔ platform host:** create an isolated surface, set its policy
|
|
139
|
+
(CSP/sandbox/allow or the native equivalent), send and receive messages,
|
|
140
|
+
report size, tear down.
|
|
141
|
+
|
|
142
|
+
## Flows per mode
|
|
143
|
+
|
|
144
|
+
### Inline widget
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
Host app Framework/Adapter Shell (opaque frame)
|
|
148
|
+
│ mount(config, cbs) │ │
|
|
149
|
+
│──────────────────────────►│ compile config → CSP, │
|
|
150
|
+
│ │ sandbox attrs, shell doc │
|
|
151
|
+
│ │ create opaque frame ───────►│ (shell runs first)
|
|
152
|
+
│ │◄──── initialize ─────────────│
|
|
153
|
+
│ │──── host context (theme, │
|
|
154
|
+
│ │ capabilities, size) ────►│
|
|
155
|
+
│ content (may stream) ───►│──── content (partial*) ─────►│ draw inert
|
|
156
|
+
│ │──── content (complete) ─────►│ run
|
|
157
|
+
│ │◄──── size / error ───────────│
|
|
158
|
+
│◄── onError / onResize ────│ │
|
|
159
|
+
│ │◄──── capability call ────────│ (e.g. sendPrompt)
|
|
160
|
+
│◄── gate (confirm?) ───────│ validate + gate │
|
|
161
|
+
│── result ────────────────►│──── result ─────────────────►│
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
`*` partial content is drawn inert (no scripts, handlers or navigation) until
|
|
165
|
+
complete; see Streaming in DESIGN.md.
|
|
166
|
+
|
|
167
|
+
### MCP Apps view
|
|
168
|
+
|
|
169
|
+
Same shape, with the adapter speaking MCP Apps: the view is an MCP Apps `App`;
|
|
170
|
+
`initialize`/`initialized` is the handshake; content arrives as tool input
|
|
171
|
+
(streamed as tool-input-partial, then tool-input) and tool result; capability
|
|
172
|
+
calls are `ui/message`, `ui/open-link`, etc., which map to host functions. On the
|
|
173
|
+
web a second-origin sandbox proxy relays messages so arbitrary MCP App HTML
|
|
174
|
+
(which expects `allow-same-origin`) is isolated from the host; the proxy is
|
|
175
|
+
transparent to the view and the host.
|
|
176
|
+
|
|
177
|
+
### Artifact page
|
|
178
|
+
|
|
179
|
+
The content is served as a real document at a URL on a separate registrable
|
|
180
|
+
domain with its CSP in HTTP headers; the host embeds that URL in a frame whose
|
|
181
|
+
`frame-ancestors` names the host. No code injection, and the shell is optional.
|
|
182
|
+
Access is gated by a one-time ticket exchanged for a scoped cookie. Where the host
|
|
183
|
+
holds the page and needs no stable origin, the shell writes it into an opaque
|
|
184
|
+
frame instead.
|
|
185
|
+
|
|
186
|
+
### URL frame
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
Host app Host backend (+ /server) App origin (served)
|
|
190
|
+
│ mount(url preset) │ │
|
|
191
|
+
│── locate ─────────►│ decide the viewer may see it, │
|
|
192
|
+
│◄── ticketed URL ───│ mint a one-time ticket │
|
|
193
|
+
│ frame src = URL ──────────────────────────────────────►│ ticket → cookie
|
|
194
|
+
│ │ (that origin only)
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
No shell and no protocol: the app is someone else's. The embedding page frames
|
|
198
|
+
only the declared content origins.
|
|
199
|
+
|
|
200
|
+
## Trust boundaries
|
|
201
|
+
|
|
202
|
+
1. **Host ↔ content.** The hard boundary. The content runs on an origin that is
|
|
203
|
+
never the host's, so same-origin policy denies it the host's DOM, storage,
|
|
204
|
+
cookies and credentials. Everything it wants beyond drawing crosses the bridge
|
|
205
|
+
as a validated, gated capability call. *What each side may know:* the content
|
|
206
|
+
never holds a host secret; whatever it says, the host treats as the content's
|
|
207
|
+
own word and confirms with a person before acting where the capability's gate
|
|
208
|
+
says so.
|
|
209
|
+
|
|
210
|
+
2. **Content ↔ the outside network.** Closed by default and opened only to the
|
|
211
|
+
origins the config's capabilities declare. Two kinds of attacker matter:
|
|
212
|
+
- *Attacking the host* (steal credentials, read other data, escape the
|
|
213
|
+
sandbox): stopped by origin isolation — the content is a stranger to the
|
|
214
|
+
host origin.
|
|
215
|
+
- *Leaking or deceiving* (exfiltrate what the content was already given, or
|
|
216
|
+
draw a convincing fake to fool the viewer): origin isolation does not help
|
|
217
|
+
here; egress hardening and gating do. Some channels (a peer connection's
|
|
218
|
+
ICE gathering, a self-navigation of the frame, a nested frame in a fresh
|
|
219
|
+
realm) reach the network outside a frame's own `connect-src`. These are
|
|
220
|
+
closed by in-shell defenses and by the embedding page's own policy, each
|
|
221
|
+
proven by a leak-suite probe (DESIGN.md lists them).
|
|
222
|
+
- *An opaque frame is as closed as its page.* A `srcdoc` frame inherits the
|
|
223
|
+
embedding page's whole policy as well as its own, so on a page with
|
|
224
|
+
`default-src 'none'` and a tight `connect-src`/`img-src` its content is more
|
|
225
|
+
closed than its config says: an origin the config opens stays shut. On such
|
|
226
|
+
a page prefer domain mode, whose frames inherit nothing (P058).
|
|
227
|
+
|
|
228
|
+
3. **Message boundary.** Every message crossing the frame is validated against a
|
|
229
|
+
schema and checked for sender identity before use; the shell accepts messages
|
|
230
|
+
only from its host, and the host only from its frame. What the frame says about
|
|
231
|
+
itself (its size, its errors, an annotation's anchor and where it is) is the
|
|
232
|
+
content's word even when the shell says it, since they share a realm: the host
|
|
233
|
+
bounds it and uses it as a UI hint, never as a permission (P053).
|
|
234
|
+
|
|
235
|
+
4. **Host's decision ↔ content domain.** Authentication and authorization
|
|
236
|
+
*policy* are the host's; carrying the host's decision safely onto the content
|
|
237
|
+
domain is Porthole's *mechanism*. The host decides who may open an instance
|
|
238
|
+
before it calls `issue` (a viewer it knows, or a public link), and may decide
|
|
239
|
+
again on every request (`ServerOptions.authorize`). Porthole carries the decision
|
|
240
|
+
as a one-time ticket, then a signed cookie of that origin and instance only,
|
|
241
|
+
with the host's opaque `subject` inside, and never interprets identity. A deny
|
|
242
|
+
ends access from the next request on and tells the display why.
|
|
243
|
+
|
|
244
|
+
## Extension points
|
|
245
|
+
|
|
246
|
+
- **Capabilities.** New host functions are added to the capability vocabulary
|
|
247
|
+
with a gate, egress need, and guide entry. Adding one extends the bridge, the
|
|
248
|
+
CSP, and the manual together.
|
|
249
|
+
- **Protocol extension points.** MCP Apps gaps go through the spec's own
|
|
250
|
+
mechanisms (experimental capabilities, own-prefixed methods), so the external
|
|
251
|
+
contract stays standard (PRINCIPLE 2).
|
|
252
|
+
- **Theme variables.** The theme map is config; the standard MCP Apps variable
|
|
253
|
+
names are the default vocabulary.
|
|
254
|
+
- **The person's clipboard** is the host's alone: content asks for a copy
|
|
255
|
+
(`copyText`), the host performs it and shows what it copied (P051, P052).
|
|
256
|
+
- **Annotations** (`annotate`): the host drives a select mode and marks anchors in
|
|
257
|
+
the shell; anchors are W3C Web Annotation selectors a host stores with its own
|
|
258
|
+
comments (P053).
|
|
259
|
+
- **Served content.** A host plugs its own policy and infrastructure into `/server`:
|
|
260
|
+
who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
|
|
261
|
+
how origins are named (`content.name`, other servers' `reserved` namespaces),
|
|
262
|
+
and where apps and artifact versions come from (`upstream`, `artifacts`). It runs
|
|
263
|
+
on any runtime with web-standard `Request`/`Response` (Node, Workers).
|
|
264
|
+
|
|
265
|
+
## How a new protocol or platform plugs in
|
|
266
|
+
|
|
267
|
+
- **A new protocol** is a new adapter implementing the capability/lifecycle
|
|
268
|
+
translation. It does not touch the core, the shell mechanisms, or the presets
|
|
269
|
+
beyond adding a preset that selects it. The capability abstraction is the seam.
|
|
270
|
+
- **A new platform** is a new implementation of the platform-host interface
|
|
271
|
+
(create isolated surface, set policy, transport, size, teardown). The framework
|
|
272
|
+
layer, adapters and presets are unchanged; the shell runtime is plain,
|
|
273
|
+
dependency-free script so it runs as-is in a new engine.
|
|
274
|
+
|
|
275
|
+
This is what keeps the three answers independent: *which protocol* (adapter),
|
|
276
|
+
*which platform* (platform host), and *what policy* (preset/config) each vary
|
|
277
|
+
without the others changing.
|