@botiverse/porthole 0.2.4 → 0.3.0
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 +14 -9
- package/dist/check/check.d.ts +83 -0
- package/dist/check/check.js +169 -0
- package/dist/check/drivers.d.ts +24 -0
- package/dist/check/drivers.js +110 -0
- package/dist/check/index.d.ts +8 -0
- package/dist/check/index.js +8 -0
- package/dist/check/lint.d.ts +21 -0
- package/dist/check/lint.js +131 -0
- package/dist/check/page-source.d.ts +2 -0
- package/dist/check/page-source.js +2 -0
- package/dist/check/page.d.ts +51 -0
- package/dist/check/page.js +150 -0
- package/dist/check/tools.d.ts +61 -0
- package/dist/check/tools.js +140 -0
- package/dist/conformance/host-kit.d.ts +10 -2
- package/dist/conformance/host-kit.js +9 -2
- package/dist/displays/displays.d.ts +61 -0
- package/dist/displays/displays.js +113 -0
- package/dist/host/client.d.ts +92 -0
- package/dist/host/client.js +259 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +6 -0
- package/dist/node/index.d.ts +22 -1
- package/dist/node/index.js +46 -1
- package/dist/react/frame.d.ts +71 -3
- package/dist/react/frame.js +120 -19
- package/dist/react/index.d.ts +1 -0
- package/dist/react/index.js +1 -0
- package/dist/react/view.d.ts +54 -0
- package/dist/react/view.js +146 -0
- package/dist/server/bootstrap.d.ts +27 -0
- package/dist/server/bootstrap.js +63 -0
- package/dist/server/host.d.ts +74 -7
- package/dist/server/host.js +237 -9
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +3 -1
- package/dist/server/pages.d.ts +19 -0
- package/dist/server/pages.js +8 -0
- package/dist/server/proxy.d.ts +24 -0
- package/dist/server/proxy.js +67 -0
- package/dist/server/server.js +14 -1
- package/dist/server/types.d.ts +8 -0
- package/docs/ADOPTING.md +191 -104
- package/docs/DECISIONS.md +146 -0
- package/docs/DESIGN.md +58 -0
- package/examples/app.mjs +62 -64
- package/examples/conformance/page.spec.mjs +23 -0
- package/examples/conformance/playwright.config.mjs +1 -1
- package/examples/conformance/porthole.spec.mjs +5 -3
- package/examples/displays.mjs +19 -0
- package/examples/mcp/server.mjs +121 -0
- package/package.json +9 -1
- package/src/check/check.ts +278 -0
- package/src/check/drivers.ts +144 -0
- package/src/check/index.ts +15 -0
- package/src/check/lint.ts +238 -0
- package/src/check/page-source.ts +19 -0
- package/src/check/page.ts +204 -0
- package/src/check/tools.ts +206 -0
- package/src/conformance/host-kit.ts +20 -11
- package/src/displays/displays.ts +191 -0
- package/src/host/client.ts +364 -0
- package/src/index.ts +25 -0
- package/src/node/index.ts +66 -2
- package/src/react/frame.tsx +191 -33
- package/src/react/index.ts +8 -0
- package/src/react/view.tsx +232 -0
- package/src/server/bootstrap.ts +97 -0
- package/src/server/host.ts +331 -15
- package/src/server/index.ts +11 -1
- package/src/server/pages.ts +28 -0
- package/src/server/proxy.ts +86 -0
- package/src/server/server.ts +26 -2
- package/src/server/types.ts +5 -0
package/docs/DESIGN.md
CHANGED
|
@@ -509,6 +509,64 @@ package carries these docs (`docs/`), and `/server` exports the types an app's c
|
|
|
509
509
|
renamed, so there is no compat module. `FrameBlock` gains `sign-in`; `ContentDomain.name` takes
|
|
510
510
|
a `Naming` (any function still fits).
|
|
511
511
|
|
|
512
|
+
### The host kit 0.3: the client, the bootstrap, the relay (P072)
|
|
513
|
+
|
|
514
|
+
What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the walk-through):
|
|
515
|
+
- **`defineDisplays(kinds)`** (core): each kind's preset and options once; opaque and served
|
|
516
|
+
configs (memoized per content source), the kind an instance names, frame sources and the
|
|
517
|
+
`frame-src` directive without a server, and a served kind's config for the manual without a real
|
|
518
|
+
origin. `createContentHost({ displays })` and the conformance runner take it.
|
|
519
|
+
- **`content.routes(viewerOf)`** (/server): one mount under `/porthole` (`prefix`): `POST frames`
|
|
520
|
+
(`issue`, answering `link`, the clean address, where `entry.pathOf` names the path), `GET
|
|
521
|
+
authorize` (its URL now the default `entry.authorizeUrl`), `GET meta` (`ContentClientMeta`:
|
|
522
|
+
served, content source, frame sources, health) and `POST`/`DELETE handoff`.
|
|
523
|
+
`contentHostFor(build)` gives one host per Workers `env`, failing closed with a plain 503;
|
|
524
|
+
`nodeServer({ content, app })` is the whole Node server.
|
|
525
|
+
- **The client:** `portholeClient({ displays, base, headers, credentials, handoff })` is the
|
|
526
|
+
locator and knows each kind's config from the meta (null until known), links, `openInTab`
|
|
527
|
+
(a tab opened in the click, then sent to the address), the handoff, and `entryTarget`.
|
|
528
|
+
`frameFallback(outcome)` words what to offer when a frame shows nothing (`needs-tab`,
|
|
529
|
+
`denied`, `expired`, `failed`, `timeout`). React: `PortholeView` (a display by kind, served or
|
|
530
|
+
opaque, with its fallback), `usePortholeLink`, and the provider's shared `scheme`, `theme`
|
|
531
|
+
(`cssVariableTheme`), `nonce: "auto"`, `handlers`, `openLink`, `notify` and `renderConfirm`.
|
|
532
|
+
- **The viewer handoff** for a page that holds a token: `POST /porthole/handoff` with the app's
|
|
533
|
+
own credential, from the app's own page, sets a 10-minute `HttpOnly` cookie scoped to the
|
|
534
|
+
prefix holding a Porthole-signed key (the viewer's id and expiry), which the authorize route
|
|
535
|
+
reads when `viewerOf` knows no one. `entry.spa` signs a person in through the app's own route.
|
|
536
|
+
- **The url-mode relay kit:** `upstreamHeaders` (the header rewrite `proxyTo` makes, for any
|
|
537
|
+
transport, WebSockets too), `statusPage` (the frame-status page with its script under its hash),
|
|
538
|
+
`nodeHost`'s `appSocket` without Porthole's cookies, `content.forget()` for cached `authorize`
|
|
539
|
+
answers.
|
|
540
|
+
- **Server:** `health.onServedChange(served)`, once per flip; `log` takes a `{ info, warn, error }`
|
|
541
|
+
logger.
|
|
542
|
+
|
|
543
|
+
### The agent's side: lint, check, tools (P073)
|
|
544
|
+
|
|
545
|
+
- **`lintContent(config, content)`** (core, pure): what can be told without running it, each
|
|
546
|
+
finding worded for the agent with its line. Errors only for what certainly fails or is cut:
|
|
547
|
+
over the size, a document where a fragment goes that has no body, nested frames and plugins,
|
|
548
|
+
`document.write`. Warnings for the rest: a document sent as a widget (taken as its body,
|
|
549
|
+
`fragmentOf`), the clipboard, dialogs, forms, hosts outside egress, unpinned CDN libraries,
|
|
550
|
+
`position: fixed` in a flow layout, new windows without `openLink`.
|
|
551
|
+
- **`admitContent(config, content, { refuseOn })`**: the show tool's gate. It refuses errors by
|
|
552
|
+
default with a text that says what to change; otherwise it shows the content (a widget's
|
|
553
|
+
document taken as its body) and returns the warnings as a note.
|
|
554
|
+
- **`checkPage({ config, content, driver })`** (`/check`): the content in the real sandbox at each
|
|
555
|
+
width and scheme (defaults: the manual's phone and desktop widths, light and dark unless
|
|
556
|
+
unthemed). The check page (`src/check/page.ts`, bundled and shipped as `/check/page`) is served
|
|
557
|
+
by the driver at a fixed origin, mounts the content opaque under its own CSP with a small
|
|
558
|
+
instrument first in it, and hears errors, rejections, CSP blocks, failed loads, the console and
|
|
559
|
+
the document's width by `postMessage`; heights come from the display's resize events. The
|
|
560
|
+
report's `text` names each problem once, with where it happened, at most 8. Drivers:
|
|
561
|
+
`playwrightDriver(browser)`, and `cdpDriver(open)` over any CDP session (Cloudflare Browser
|
|
562
|
+
Rendering from a Worker).
|
|
563
|
+
- **Tools:** `showTool`, `guideTool`, `checkTool` give `{ name, description, inputSchema }` from
|
|
564
|
+
the config; `answerGuide` answers the guide tool; `guideChanges(from, to)` is the notice when a
|
|
565
|
+
kind flips between served and opaque. `examples/mcp/server.mjs` wires them over MCP.
|
|
566
|
+
- **The manual's examples pass the check:** `leak/check.spec.ts` runs every `GUIDE_EXAMPLES`
|
|
567
|
+
entry under each preset at the manual's widths in light and dark, on three engines (OBJECTIVES
|
|
568
|
+
criterion 5).
|
|
569
|
+
|
|
512
570
|
### Protocol adapters
|
|
513
571
|
|
|
514
572
|
The core ships the adapter for the MCP Apps subset its own shell speaks
|
package/examples/app.mjs
CHANGED
|
@@ -3,17 +3,10 @@
|
|
|
3
3
|
// clean address. examples/node/server.mjs and examples/workers/worker.mjs only adapt it.
|
|
4
4
|
//
|
|
5
5
|
// What is the app's own here (the policy): who is signed in (a cookie), which pages exist, who
|
|
6
|
-
// may see each. Everything else is Porthole's
|
|
7
|
-
|
|
6
|
+
// may see each, and what a clean address names. Everything else is Porthole's: one mount
|
|
7
|
+
// (`content.routes`, under /porthole) answers frames, the authorize route and the page's meta.
|
|
8
8
|
import { conformancePage, createContentHost, prefixedName } from "@botiverse/porthole/server";
|
|
9
|
-
|
|
10
|
-
/** The config a page is shown under: served on its own origin, or opaque while that's down. */
|
|
11
|
-
export const pageConfig = (contentSource) =>
|
|
12
|
-
presets.artifact({
|
|
13
|
-
// A whole-page viewer: the frame fills its box, and the agent's manual says so.
|
|
14
|
-
layout: { kind: "fill" },
|
|
15
|
-
...(contentSource === null ? {} : { isolation: "domain", contentOrigins: [contentSource] }),
|
|
16
|
-
});
|
|
9
|
+
import { displays, kinds } from "./displays.mjs";
|
|
17
10
|
|
|
18
11
|
/** The stored pages: id → versions. An app keeps them in its database. */
|
|
19
12
|
const PAGES = {
|
|
@@ -60,6 +53,13 @@ export function makeApp(settings) {
|
|
|
60
53
|
};
|
|
61
54
|
pages.private = { owner: "nobody", versions: { 1: "<!doctype html><p>private</p>" } };
|
|
62
55
|
}
|
|
56
|
+
const page = (scope) =>
|
|
57
|
+
pages[scope]
|
|
58
|
+
? scope
|
|
59
|
+
: settings.conformance === true && /^t-[a-z0-9-]{1,40}$/u.test(scope)
|
|
60
|
+
? "conformance"
|
|
61
|
+
: null;
|
|
62
|
+
const latest = (id) => Object.keys(pages[id].versions).at(-1);
|
|
63
63
|
/** Who may see an instance: anyone signed in, but a page with an owner only its owner. */
|
|
64
64
|
const accessOf = (instance, viewer) => {
|
|
65
65
|
const owner = pages[page(instance.scope) ?? ""]?.owner ?? null;
|
|
@@ -67,20 +67,13 @@ export function makeApp(settings) {
|
|
|
67
67
|
? { viewer, subject: viewer }
|
|
68
68
|
: null;
|
|
69
69
|
};
|
|
70
|
-
const page = (scope) =>
|
|
71
|
-
pages[scope]
|
|
72
|
-
? scope
|
|
73
|
-
: settings.conformance === true && /^t-[a-z0-9-]{1,40}$/u.test(scope)
|
|
74
|
-
? "conformance"
|
|
75
|
-
: null;
|
|
76
70
|
|
|
77
71
|
const content = createContentHost({
|
|
78
72
|
domain: settings.contentDomain,
|
|
79
73
|
appOrigins: [appOrigin],
|
|
80
74
|
secret: settings.secret,
|
|
81
75
|
...(settings.tickets === undefined ? {} : { tickets: settings.tickets }),
|
|
82
|
-
|
|
83
|
-
configs: (source) => ({ artifact: pageConfig(source) }),
|
|
76
|
+
displays,
|
|
84
77
|
name: prefixedName("a-"),
|
|
85
78
|
// Policy 1: the instance a frame request proposes. The server picks the scope, never the client.
|
|
86
79
|
instance: (proposal) => {
|
|
@@ -110,18 +103,21 @@ export function makeApp(settings) {
|
|
|
110
103
|
const stored = pages[id]?.versions[version];
|
|
111
104
|
return stored === undefined ? null : { html: stored };
|
|
112
105
|
},
|
|
113
|
-
// Policy 4: what a clean address names: `/` the latest version, `/v/<n>` version n.
|
|
106
|
+
// Policy 4: what a clean address names: `/` the latest version, `/v/<n>` version n. And the
|
|
107
|
+
// reverse (pathOf), so frames come with their clean address for "open in a new tab".
|
|
114
108
|
entry: {
|
|
115
|
-
authorizeUrl: `${appOrigin}/porthole/authorize`,
|
|
116
109
|
at: (scope, path) => {
|
|
117
110
|
const id = page(scope);
|
|
118
111
|
if (id === null) return null;
|
|
119
|
-
const version =
|
|
120
|
-
path === "/" ? Object.keys(pages[id].versions).at(-1) : /^\/v\/(\d+)$/u.exec(path)?.[1];
|
|
112
|
+
const version = path === "/" ? latest(id) : /^\/v\/(\d+)$/u.exec(path)?.[1];
|
|
121
113
|
return pages[id].versions[version] === undefined
|
|
122
114
|
? null
|
|
123
115
|
: { scope, document: { kind: "artifact", id, version } };
|
|
124
116
|
},
|
|
117
|
+
pathOf: (instance) =>
|
|
118
|
+
instance.document.version === latest(page(instance.scope) ?? "hello")
|
|
119
|
+
? "/"
|
|
120
|
+
: `/v/${instance.document.version}`,
|
|
125
121
|
// The app's own sign-in, coming back to the authorize route. Absolute: Node's
|
|
126
122
|
// Response.redirect needs one.
|
|
127
123
|
signIn: (returnTo) =>
|
|
@@ -130,38 +126,47 @@ export function makeApp(settings) {
|
|
|
130
126
|
...(settings.health === undefined ? {} : { health: settings.health }),
|
|
131
127
|
log: (event) => console.log(JSON.stringify(event)),
|
|
132
128
|
});
|
|
133
|
-
|
|
134
|
-
const
|
|
129
|
+
// Frames, the authorize route and the page's meta, under /porthole.
|
|
130
|
+
const routes = content.routes(viewerOf);
|
|
135
131
|
|
|
136
132
|
async function handle(request) {
|
|
137
133
|
const url = new URL(request.url);
|
|
138
134
|
const viewer = viewerOf(request);
|
|
139
|
-
|
|
140
|
-
if (
|
|
135
|
+
const porthole = await routes(request);
|
|
136
|
+
if (porthole !== null) return porthole;
|
|
137
|
+
if (url.pathname === "/porthole-client/displays.mjs") {
|
|
138
|
+
// The page's display kinds: the same as the server's, as a module.
|
|
139
|
+
return new Response(
|
|
140
|
+
`import { defineDisplays } from "@botiverse/porthole";\nexport const displays = defineDisplays(${JSON.stringify(kinds)});\n`,
|
|
141
|
+
{ headers: { "content-type": "text/javascript; charset=utf-8" } },
|
|
142
|
+
);
|
|
143
|
+
}
|
|
141
144
|
if (url.pathname.startsWith("/porthole-client/")) {
|
|
142
145
|
return (
|
|
143
146
|
(await settings.client(url.pathname.slice("/porthole-client".length))) ??
|
|
144
147
|
new Response("not found", { status: 404 })
|
|
145
148
|
);
|
|
146
149
|
}
|
|
147
|
-
if (url.pathname === "/api/
|
|
148
|
-
//
|
|
149
|
-
const
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
150
|
+
if (url.pathname === "/api/page") {
|
|
151
|
+
// The opaque fallback's content: the latest version, for a viewer who may see it.
|
|
152
|
+
const id = url.searchParams.get("id") ?? "";
|
|
153
|
+
const version = pages[id] === undefined ? undefined : latest(id);
|
|
154
|
+
const instance =
|
|
155
|
+
version === undefined ? null : { scope: id, document: { kind: "artifact", id, version } };
|
|
156
|
+
return instance === null || accessOf(instance, viewer) === null
|
|
157
|
+
? new Response("not found", { status: 404 })
|
|
158
|
+
: new Response(pages[id].versions[version], {
|
|
159
|
+
headers: { "content-type": "text/html; charset=utf-8" },
|
|
160
|
+
});
|
|
155
161
|
}
|
|
156
162
|
if (url.pathname === "/login" && request.method === "GET") {
|
|
157
163
|
const next = escape(ownPath(url.searchParams.get("next"), appOrigin));
|
|
158
164
|
return html(
|
|
159
165
|
`<!doctype html><title>Sign in</title><main id="sign-in-page"><form method="post"><input type="hidden" name="next" value="${next}"><button id="sign-in">Sign in as ada</button></form></main>`,
|
|
160
166
|
{
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
"default-src 'none'; frame-ancestors 'none'",
|
|
167
|
+
// No form-action: after the sign-in POST, redirect entry goes on through the content
|
|
168
|
+
// origin, and form-action holds every redirect of a submission (docs/ADOPTING.md).
|
|
169
|
+
"content-security-policy": "default-src 'none'; frame-ancestors 'none'",
|
|
165
170
|
},
|
|
166
171
|
);
|
|
167
172
|
}
|
|
@@ -175,30 +180,16 @@ export function makeApp(settings) {
|
|
|
175
180
|
},
|
|
176
181
|
});
|
|
177
182
|
}
|
|
178
|
-
if (url.pathname === "/api/page") {
|
|
179
|
-
// The opaque fallback's content: the latest version, for a viewer who may see it.
|
|
180
|
-
const id = url.searchParams.get("id") ?? "";
|
|
181
|
-
const latest = pages[id] === undefined ? undefined : Object.keys(pages[id].versions).at(-1);
|
|
182
|
-
const instance =
|
|
183
|
-
latest === undefined
|
|
184
|
-
? null
|
|
185
|
-
: { scope: id, document: { kind: "artifact", id, version: latest } };
|
|
186
|
-
const grant = instance === null ? null : accessOf(instance, viewer);
|
|
187
|
-
return grant === null
|
|
188
|
-
? new Response("not found", { status: 404 })
|
|
189
|
-
: new Response(pages[id].versions[latest], {
|
|
190
|
-
headers: { "content-type": "text/html; charset=utf-8" },
|
|
191
|
-
});
|
|
192
|
-
}
|
|
193
183
|
if (url.pathname === "/") {
|
|
194
184
|
if (viewer === null) return Response.redirect(`${appOrigin}/login?next=/`, 303);
|
|
195
185
|
const id = url.searchParams.get("page") ?? "hello";
|
|
196
186
|
if (pages[id] === undefined) return new Response("not found", { status: 404 });
|
|
187
|
+
const frames = content.frameSources;
|
|
197
188
|
return html(viewerPage(id), {
|
|
198
189
|
// The embedding page's CSP: its scripts by nonce, and frames only from content origins
|
|
199
|
-
// (content.frameSources). An opaque display inherits this policy
|
|
200
|
-
// img/media/font/style/worker open to what inline content uses
|
|
201
|
-
"content-security-policy": `default-src 'self'; script-src 'self' 'nonce-${NONCE}'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; media-src data: blob:; font-src data:; worker-src blob:; frame-src ${
|
|
190
|
+
// and the authorize route (content.frameSources). An opaque display inherits this policy
|
|
191
|
+
// too, so it leaves img/media/font/style/worker open to what inline content uses.
|
|
192
|
+
"content-security-policy": `default-src 'self'; script-src 'self' 'nonce-${NONCE}'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; media-src data: blob:; font-src data:; worker-src blob:; frame-src ${frames.length === 0 ? "'none'" : frames.join(" ")}; base-uri 'none'; frame-ancestors 'none'`,
|
|
202
193
|
});
|
|
203
194
|
}
|
|
204
195
|
return new Response("not found", { status: 404 });
|
|
@@ -210,22 +201,29 @@ export function makeApp(settings) {
|
|
|
210
201
|
id,
|
|
211
202
|
) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Pages</title>
|
|
212
203
|
<style>body{font-family:system-ui;margin:24px} #frame{height:480px;border:1px solid #8884} #problem{color:#b00}</style></head>
|
|
213
|
-
<body><main id="app"><p>Signed in. <
|
|
204
|
+
<body><main id="app"><p>Signed in. <button id="open-tab" type="button">Open in a new tab</button></p>
|
|
214
205
|
<div id="frame"></div><p id="problem" role="alert"></p></main>
|
|
215
206
|
<script type="importmap" nonce="${NONCE}">{"imports":{"@botiverse/porthole":"/porthole-client/index.js"}}</script>
|
|
216
207
|
<script type="module" nonce="${NONCE}">
|
|
217
208
|
const problem = (text) => { document.getElementById("problem").textContent = text; };
|
|
218
209
|
// The client module failing to load would otherwise show nothing at all.
|
|
219
|
-
import("@botiverse/porthole").then(async ({ createHost,
|
|
220
|
-
const
|
|
221
|
-
const
|
|
210
|
+
Promise.all([import("@botiverse/porthole"), import("/porthole-client/displays.mjs")]).then(async ([{ createHost, frameFallback, portholeClient }, { displays }]) => {
|
|
211
|
+
const porthole = portholeClient({ displays }); // the server's /porthole routes
|
|
212
|
+
const meta = await porthole.refresh();
|
|
213
|
+
const instance = { scope: ${JSON.stringify(id)}, document: { kind: "artifact", id: ${JSON.stringify(id)}, version: ${JSON.stringify(latest(id))} } };
|
|
214
|
+
// "Open in a new tab": the clean address, opened inside the click.
|
|
215
|
+
document.getElementById("open-tab").addEventListener("click", () => porthole.openInTab(instance));
|
|
216
|
+
// Served while frames are served (located through /porthole/frames); opaque, inline, while not.
|
|
217
|
+
const host = createHost(porthole.config("artifact"), { locator: porthole, nonce: ${JSON.stringify(NONCE)} });
|
|
222
218
|
const display = host.mount(document.getElementById("frame"), {
|
|
223
219
|
displayId: ${JSON.stringify(id)}, title: ${JSON.stringify(id)}, scheme: "light",
|
|
224
|
-
|
|
225
|
-
|
|
220
|
+
...(meta?.served ? { instance } : {}),
|
|
221
|
+
});
|
|
222
|
+
if (!meta?.served) display.setContent(await (await fetch("/api/page?id=${encodeURIComponent(id)}")).text());
|
|
223
|
+
display.on("outcome", (outcome) => {
|
|
224
|
+
const fallback = frameFallback(outcome);
|
|
225
|
+
if (fallback !== null) problem(fallback.title + ": " + fallback.message);
|
|
226
226
|
});
|
|
227
|
-
if (!meta.served) display.setContent(await (await fetch("/api/page?id=${encodeURIComponent(id)}")).text());
|
|
228
|
-
display.on("outcome", (outcome) => { if (outcome.state !== "loaded") problem("The page couldn't be shown here (" + (outcome.reason ?? outcome.state) + "): open it in a new tab."); });
|
|
229
227
|
display.on("hostError", (error) => problem(error.message));
|
|
230
228
|
}, (error) => problem("Porthole's client didn't load: " + error.message));
|
|
231
229
|
</script></body></html>`;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// The example app's own page, as a person uses it: signed in, its page shown served on its own
|
|
2
|
+
// origin, and "Open in a new tab" opening the clean address.
|
|
3
|
+
import { expect, test } from "@playwright/test";
|
|
4
|
+
|
|
5
|
+
const port = Number(process.env.PORTHOLE_EXAMPLE_PORT ?? 8796);
|
|
6
|
+
const app = `http://localhost:${port}`;
|
|
7
|
+
|
|
8
|
+
test("the viewer shows the page on its own origin, and opens it in a new tab", async ({
|
|
9
|
+
page,
|
|
10
|
+
context,
|
|
11
|
+
}) => {
|
|
12
|
+
await page.goto(`${app}/login?next=/`);
|
|
13
|
+
await Promise.all([page.waitForURL(`${app}/`), page.click("#sign-in")]);
|
|
14
|
+
const frame = page.frameLocator("#frame iframe");
|
|
15
|
+
await expect(frame.locator("h1")).toHaveText("Hello from an agent");
|
|
16
|
+
const element = await page.locator("#frame iframe").elementHandle();
|
|
17
|
+
const origin = await (await element?.contentFrame())?.evaluate(() => location.origin);
|
|
18
|
+
expect(origin).toBe(`http://a-hello.content.localhost:${port}`);
|
|
19
|
+
const [tab] = await Promise.all([context.waitForEvent("page"), page.click("#open-tab")]);
|
|
20
|
+
await tab.waitForURL(`http://a-hello.content.localhost:${port}/`);
|
|
21
|
+
await expect(tab.locator("h1")).toHaveText("Hello from an agent");
|
|
22
|
+
await expect(page.locator("#problem")).toHaveText("");
|
|
23
|
+
});
|
|
@@ -18,7 +18,7 @@ export default defineConfig({
|
|
|
18
18
|
webServer: {
|
|
19
19
|
command: "node ../node/server.mjs",
|
|
20
20
|
cwd: import.meta.dirname,
|
|
21
|
-
url: `http://localhost:${port}/
|
|
21
|
+
url: `http://localhost:${port}/porthole/meta`,
|
|
22
22
|
env: {
|
|
23
23
|
PORT: String(port),
|
|
24
24
|
PORTHOLE_SECRET: "example-secret-for-tests-only-0123456789",
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
// (PORTHOLE_CONFORMANCE=1, examples/app.mjs): pages the suite names itself. Never ship it.
|
|
4
4
|
import { test } from "@playwright/test";
|
|
5
5
|
import { defineHostConformance } from "@botiverse/porthole/conformance";
|
|
6
|
-
import {
|
|
6
|
+
import { displays } from "../displays.mjs";
|
|
7
7
|
|
|
8
8
|
const port = Number(process.env.PORTHOLE_EXAMPLE_PORT ?? 8796);
|
|
9
9
|
const app = `http://localhost:${port}`;
|
|
@@ -16,8 +16,10 @@ defineHostConformance(test, {
|
|
|
16
16
|
await page.goto(`${app}/login?next=/`);
|
|
17
17
|
await Promise.all([page.waitForURL(`${app}/`), page.click("#sign-in")]);
|
|
18
18
|
},
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
// The app's frame endpoint (content.routes), and its display kinds.
|
|
20
|
+
issue: { url: "/porthole/frames" },
|
|
21
|
+
displays,
|
|
22
|
+
contentSource: `http://*.content.localhost:${port}`,
|
|
21
23
|
// A stored-pages app: its test page's two versions (the domain cases run on version 1).
|
|
22
24
|
instances: {
|
|
23
25
|
artifact: (scope, version) => ({
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
// The app's display kinds, in one place (defineDisplays): the server serves under them, the page
|
|
2
|
+
// frames under them, and the agent's tools and manual come from them. Shared by the server, the
|
|
3
|
+
// page (served to it as a module) and the agent's tools (examples/mcp).
|
|
4
|
+
import { defineDisplays } from "@botiverse/porthole";
|
|
5
|
+
|
|
6
|
+
/** The kinds as plain data: the server also hands them to the page as a module. */
|
|
7
|
+
export const kinds = {
|
|
8
|
+
// A stored page: a kind named "artifact" is the preset an artifact instance names by default.
|
|
9
|
+
artifact: {
|
|
10
|
+
preset: "artifact",
|
|
11
|
+
options: {
|
|
12
|
+
// A whole-page viewer: the frame fills its box, and the agent's manual says so.
|
|
13
|
+
layout: { kind: "fill" },
|
|
14
|
+
guide: { toolName: "show_page", guideToolName: "page_guide" },
|
|
15
|
+
},
|
|
16
|
+
},
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
export const displays = defineDisplays(kinds);
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
// The agent's side, as an MCP server over stdio: show_page, page_guide and check_page, each a
|
|
2
|
+
// tool definition Porthole makes from the app's display kind (names, descriptions and JSON
|
|
3
|
+
// Schemas), answered by Porthole's own helpers. With the official MCP SDK, register the same
|
|
4
|
+
// definitions and handlers; this file speaks the protocol by hand to stay dependency-free.
|
|
5
|
+
//
|
|
6
|
+
// node node_modules/@botiverse/porthole/examples/mcp/server.mjs (an MCP client starts it)
|
|
7
|
+
//
|
|
8
|
+
// show_page refuses only what certainly fails (over the size, nested frames, document.write…) and
|
|
9
|
+
// says exactly what to change; everything else comes back as warnings with the result.
|
|
10
|
+
// check_page runs the page in the real sandbox where this machine has a browser (Playwright);
|
|
11
|
+
// without one, it says so and gives the lint alone (docs/ADOPTING.md: hosts without a browser).
|
|
12
|
+
import { createInterface } from "node:readline";
|
|
13
|
+
import {
|
|
14
|
+
admitContent,
|
|
15
|
+
answerGuide,
|
|
16
|
+
checkTool,
|
|
17
|
+
guideTool,
|
|
18
|
+
lintContent,
|
|
19
|
+
showTool,
|
|
20
|
+
} from "@botiverse/porthole";
|
|
21
|
+
import { displays } from "../displays.mjs";
|
|
22
|
+
|
|
23
|
+
// The manual as served pages get it (the kind's served config, no real origin needed).
|
|
24
|
+
const config = displays.guideConfig("artifact", "served");
|
|
25
|
+
const tools = [showTool(config), guideTool(config), checkTool(config)];
|
|
26
|
+
const shown = new Map(); // title → html: an app stores and shows it (examples/app.mjs)
|
|
27
|
+
|
|
28
|
+
/** A browser, if this machine has Playwright: the check's driver. */
|
|
29
|
+
let browser = null;
|
|
30
|
+
async function driver() {
|
|
31
|
+
try {
|
|
32
|
+
const [{ chromium }, { playwrightDriver }] = await Promise.all([
|
|
33
|
+
import("@playwright/test"),
|
|
34
|
+
import("@botiverse/porthole/check"),
|
|
35
|
+
]);
|
|
36
|
+
browser ??= await chromium.launch();
|
|
37
|
+
return playwrightDriver(browser);
|
|
38
|
+
} catch {
|
|
39
|
+
return null;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
const text = (value, isError = false) => ({
|
|
44
|
+
content: [{ type: "text", text: value }],
|
|
45
|
+
...(isError ? { isError: true } : {}),
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
async function call(name, args) {
|
|
49
|
+
if (name === showTool(config).name) {
|
|
50
|
+
const admitted = admitContent(config, String(args?.html ?? ""));
|
|
51
|
+
if (!admitted.ok) return text(admitted.refusal, true);
|
|
52
|
+
shown.set(String(args?.title ?? "Untitled"), admitted.content);
|
|
53
|
+
return text(admitted.note ?? "Shown.");
|
|
54
|
+
}
|
|
55
|
+
if (name === guideTool(config).name) {
|
|
56
|
+
const answer = answerGuide(config, args);
|
|
57
|
+
return "error" in answer ? text(answer.error, true) : text(answer.text);
|
|
58
|
+
}
|
|
59
|
+
if (name === checkTool(config).name) {
|
|
60
|
+
const html = String(args?.html ?? "");
|
|
61
|
+
const check = await driver();
|
|
62
|
+
if (check === null) {
|
|
63
|
+
const findings = lintContent(config, html);
|
|
64
|
+
return text(
|
|
65
|
+
`No browser here, so only what can be told without running it:\n${findings.length === 0 ? "nothing to fix." : findings.map((each) => `- ${each.message}`).join("\n")}`,
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
const { checkPage } = await import("@botiverse/porthole/check");
|
|
69
|
+
const report = await checkPage({
|
|
70
|
+
config,
|
|
71
|
+
content: html,
|
|
72
|
+
driver: check,
|
|
73
|
+
...(Array.isArray(args?.widths) ? { widths: args.widths } : {}),
|
|
74
|
+
...(Array.isArray(args?.schemes) ? { schemes: args.schemes } : {}),
|
|
75
|
+
});
|
|
76
|
+
return text(report.text, !report.ok);
|
|
77
|
+
}
|
|
78
|
+
throw Object.assign(new Error(`No tool ${name}`), { code: -32602 });
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
async function respond(message) {
|
|
82
|
+
switch (message.method) {
|
|
83
|
+
case "initialize":
|
|
84
|
+
return {
|
|
85
|
+
protocolVersion: message.params?.protocolVersion ?? "2025-06-18",
|
|
86
|
+
capabilities: { tools: {} },
|
|
87
|
+
serverInfo: { name: "porthole-example", version: "1" },
|
|
88
|
+
instructions: `Call ${guideTool(config).name} once before your first page, and ${checkTool(config).name} before ${showTool(config).name}.`,
|
|
89
|
+
};
|
|
90
|
+
case "tools/list":
|
|
91
|
+
return { tools };
|
|
92
|
+
case "tools/call":
|
|
93
|
+
return call(message.params?.name, message.params?.arguments ?? {});
|
|
94
|
+
case "ping":
|
|
95
|
+
return {};
|
|
96
|
+
default:
|
|
97
|
+
throw Object.assign(new Error(`No method ${message.method}`), { code: -32601 });
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
const lines = createInterface({ input: process.stdin });
|
|
102
|
+
lines.on("line", (line) => void handleLine(line));
|
|
103
|
+
|
|
104
|
+
async function handleLine(line) {
|
|
105
|
+
let message;
|
|
106
|
+
try {
|
|
107
|
+
message = JSON.parse(line);
|
|
108
|
+
} catch {
|
|
109
|
+
return;
|
|
110
|
+
}
|
|
111
|
+
if (message.id === undefined) return; // a notification
|
|
112
|
+
try {
|
|
113
|
+
const result = await respond(message);
|
|
114
|
+
process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result })}\n`);
|
|
115
|
+
} catch (error) {
|
|
116
|
+
process.stdout.write(
|
|
117
|
+
`${JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: error.code ?? -32603, message: error.message } })}\n`,
|
|
118
|
+
);
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
lines.on("close", () => browser?.close());
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
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
|
"license": "Apache-2.0",
|
|
6
6
|
"bin": {
|
|
@@ -39,6 +39,14 @@
|
|
|
39
39
|
"./node": {
|
|
40
40
|
"types": "./dist/node/index.d.ts",
|
|
41
41
|
"default": "./dist/node/index.js"
|
|
42
|
+
},
|
|
43
|
+
"./check": {
|
|
44
|
+
"types": "./dist/check/index.d.ts",
|
|
45
|
+
"default": "./dist/check/index.js"
|
|
46
|
+
},
|
|
47
|
+
"./check/page": {
|
|
48
|
+
"types": "./dist/check/page-source.d.ts",
|
|
49
|
+
"default": "./dist/check/page-source.js"
|
|
42
50
|
}
|
|
43
51
|
},
|
|
44
52
|
"devDependencies": {
|