@botiverse/porthole 0.3.0 → 0.3.2
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 +3 -2
- package/dist/check/check.d.ts +20 -3
- package/dist/check/check.js +88 -25
- package/dist/check/drivers.d.ts +25 -6
- package/dist/check/drivers.js +99 -28
- package/dist/check/index.d.ts +2 -2
- package/dist/check/index.js +1 -1
- package/dist/check/instrument.d.ts +71 -0
- package/dist/check/instrument.js +84 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.d.ts +2 -40
- package/dist/check/page.js +63 -43
- package/dist/conformance/harness-source.d.ts +2 -0
- package/dist/conformance/harness-source.js +2 -0
- package/dist/conformance/host-kit.d.ts +20 -7
- package/dist/conformance/host-kit.js +42 -48
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/reporter.d.ts +14 -0
- package/dist/conformance/reporter.js +28 -0
- package/dist/host/client.d.ts +33 -15
- package/dist/host/client.js +39 -24
- package/dist/node/index.d.ts +6 -2
- package/dist/node/index.js +53 -8
- package/dist/react/frame.d.ts +13 -5
- package/dist/react/frame.js +67 -27
- package/dist/react/index.d.ts +1 -1
- package/dist/react/view.js +6 -1
- package/dist/server/host.d.ts +5 -3
- package/dist/server/host.js +41 -12
- package/docs/ADOPTING.md +115 -26
- package/docs/DECISIONS.md +167 -0
- package/docs/DESIGN.md +38 -13
- package/examples/app.mjs +23 -17
- package/examples/conformance/playwright.config.mjs +2 -1
- package/examples/conformance/porthole.spec.mjs +2 -1
- package/examples/displays.mjs +2 -0
- package/examples/node/server.mjs +16 -34
- package/examples/workers/worker.mjs +19 -7
- package/package.json +9 -3
- package/src/check/check.ts +122 -25
- package/src/check/drivers.ts +137 -39
- package/src/check/index.ts +8 -1
- package/src/check/instrument.ts +138 -0
- package/src/check/page-source.ts +4 -3
- package/src/check/page.ts +94 -68
- package/src/conformance/harness-source.ts +23 -0
- package/src/conformance/host-kit.ts +69 -46
- package/src/conformance/index.ts +1 -0
- package/src/conformance/reporter.ts +38 -0
- package/src/host/client.ts +65 -34
- package/src/node/index.ts +56 -10
- package/src/react/frame.tsx +89 -33
- package/src/react/index.ts +1 -0
- package/src/react/view.tsx +6 -1
- package/src/server/host.ts +53 -15
- package/dist/conformance/harness.js +0 -1662
package/docs/DESIGN.md
CHANGED
|
@@ -437,7 +437,10 @@ a link sent to someone with access.
|
|
|
437
437
|
frame, never the sign-in**: a plain page asking for a new tab (`blocked: sign-in`). No
|
|
438
438
|
access: the app's refusal on a tab (`refusal(status, request, entry)`; nothing returned:
|
|
439
439
|
Porthole's page), a plain page in a frame; never content. Both hooks get the address decoded
|
|
440
|
-
(`EntryContext`: label, scope, path, clean URL, the instance, framed).
|
|
440
|
+
(`EntryContext`: label, scope, path, clean URL, the instance, framed). `returnTo` (and
|
|
441
|
+
`entry.spa`'s `next`) is `authorizeUrl` with the request's query: the app as it is reached,
|
|
442
|
+
never the request's own URL, whose scheme and host behind a TLS edge or a dev proxy are
|
|
443
|
+
another's (P074).
|
|
441
444
|
3. Granted, a 302 back to `/__porthole/entry?code=…`: a one-time code (60 s), bound to the
|
|
442
445
|
label, the path and the nonce. The content origin redeems it only on that label and only with
|
|
443
446
|
the nonce's cookie, sets the session (bound to the path) and 303s to the clean address. The
|
|
@@ -489,7 +492,11 @@ The tests are located in the app's own spec file, at the `defineHostConformance`
|
|
|
489
492
|
addresses may be async (an app publishes a test page on demand and returns its real instance,
|
|
490
493
|
which the issue endpoint then gets); `entry.unknown` lists addresses that name nothing, each of
|
|
491
494
|
which must be a 404 on the content domain. `hostConformance(options)` gives the hosts for an app
|
|
492
|
-
that registers the cases itself.
|
|
495
|
+
that registers the cases itself. Playwright's list and line reporters show a skipped case without
|
|
496
|
+
its reason; `@botiverse/porthole/conformance/reporter` prints each reason after the run (P074).
|
|
497
|
+
`contentSource` may be a function, asked per case (a port known only once the server runs), and
|
|
498
|
+
`conformanceProjects` merges an app's own `use` and per-engine `launchOptions` (a system
|
|
499
|
+
browser) with Porthole's (P074).
|
|
493
500
|
|
|
494
501
|
**Prod shape** (`ops/prod-shape/`, `ops/prod-shape/run.sh`). Docker compose: Caddy's internal
|
|
495
502
|
CA serving `app.test`, `*.content.test` (same-site siblings, as in production without a Public
|
|
@@ -517,18 +524,24 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
|
|
|
517
524
|
`frame-src` directive without a server, and a served kind's config for the manual without a real
|
|
518
525
|
origin. `createContentHost({ displays })` and the conformance runner take it.
|
|
519
526
|
- **`content.routes(viewerOf)`** (/server): one mount under `/porthole` (`prefix`): `POST frames`
|
|
520
|
-
(`issue`, answering `link`, the clean address, where `entry.pathOf` names the path
|
|
527
|
+
(`issue`, answering `link`, the clean address, where `entry.pathOf` names the path, which it
|
|
528
|
+
may look up: a promise, P074), `GET
|
|
521
529
|
authorize` (its URL now the default `entry.authorizeUrl`), `GET meta` (`ContentClientMeta`:
|
|
522
530
|
served, content source, frame sources, health) and `POST`/`DELETE handoff`.
|
|
523
531
|
`contentHostFor(build)` gives one host per Workers `env`, failing closed with a plain 503;
|
|
524
|
-
`nodeServer({ content, app })` is the whole Node server
|
|
532
|
+
`nodeServer({ content, app })` is the whole Node server (`content` may be a function giving the
|
|
533
|
+
host once made, P074). A missing or short secret throws, naming `PORTHOLE_SECRET`.
|
|
525
534
|
- **The client:** `portholeClient({ displays, base, headers, credentials, handoff })` is the
|
|
526
535
|
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
|
|
536
|
+
(a tab opened in the click, then sent to the address), the handoff, and `entryTarget` (the
|
|
537
|
+
authorize route only; with `{ app: true }` also a path or address on the app's origin, P074).
|
|
528
538
|
`frameFallback(outcome)` words what to offer when a frame shows nothing (`needs-tab`,
|
|
529
539
|
`denied`, `expired`, `failed`, `timeout`). React: `PortholeView` (a display by kind, served or
|
|
530
540
|
opaque, with its fallback), `usePortholeLink`, and the provider's shared `scheme`, `theme`
|
|
531
|
-
(`cssVariableTheme`), `nonce: "auto"`, `handlers`, `openLink`, `notify` and `renderConfirm
|
|
541
|
+
(`cssVariableTheme`), `nonce: "auto"`, `handlers`, `openLink`, `notify` and `renderConfirm`
|
|
542
|
+
(`accept`, `decline`, and `redirect`: `"redirected"`, which doesn't count toward muting, P074).
|
|
543
|
+
A flip of the provider's scheme or a new themeKey re-themes running frames in place: no effect
|
|
544
|
+
that makes a display depends on the context value those renew (#9, P074).
|
|
532
545
|
- **The viewer handoff** for a page that holds a token: `POST /porthole/handoff` with the app's
|
|
533
546
|
own credential, from the app's own page, sets a 10-minute `HttpOnly` cookie scoped to the
|
|
534
547
|
prefix holding a Porthole-signed key (the viewer's id and expiry), which the authorize route
|
|
@@ -553,13 +566,25 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
|
|
|
553
566
|
document taken as its body) and returns the warnings as a note.
|
|
554
567
|
- **`checkPage({ config, content, driver })`** (`/check`): the content in the real sandbox at each
|
|
555
568
|
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
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
569
|
+
unthemed). The check page (`src/check/page.ts`, bundled and shipped as `/check/page`, a module
|
|
570
|
+
`checkPage` imports, so a bundle carries it, P075) is served
|
|
571
|
+
by the driver at a fixed origin (`https://porthole-check.invalid`), mounts the content with a
|
|
572
|
+
small instrument first in it, and hears errors, rejections, CSP blocks, failed loads, the
|
|
573
|
+
console and the document's width by `postMessage`; heights come from the display's resize
|
|
574
|
+
events. A served config runs served (P074): the driver also answers a reserved content domain
|
|
575
|
+
(`*.porthole-check-content.invalid`) with an in-process `createServer` (a random secret, the
|
|
576
|
+
check page as its only host origin), so the content gets its own origin, the served CSP in
|
|
577
|
+
headers, the shell, storage and cookies, each run on a new origin; an opaque config, an MCP
|
|
578
|
+
Apps view (as a page with the view's egress) and a driver without `serve` run opaque. Each
|
|
579
|
+
inline script is named (`//# sourceURL=porthole-script-<n>`) and its first line recorded, so an
|
|
580
|
+
error's line is the content's own line, as lint numbers it. Every host function the config
|
|
581
|
+
declares is answered as a host that declines (`confirm` says no; each handler answers no), and
|
|
582
|
+
each call the host sees is reported (`run.calls`): refused by a gate whatever the person says (no
|
|
583
|
+
click, bad arguments, too often) a problem, declined or answered a note. A global the shell
|
|
584
|
+
refuses itself without a click (`sendPrompt`) rejects in the content, so it shows as an error. The report's `text` names each
|
|
585
|
+
problem once, with where it happened, at most 8. Drivers: `playwrightDriver(browser)` (requests
|
|
586
|
+
answered by `page.route`), and `cdpDriver(open)` over any CDP session (`Fetch` interception;
|
|
587
|
+
Cloudflare Browser Rendering from a Worker).
|
|
563
588
|
- **Tools:** `showTool`, `guideTool`, `checkTool` give `{ name, description, inputSchema }` from
|
|
564
589
|
the config; `answerGuide` answers the guide tool; `guideChanges(from, to)` is the notice when a
|
|
565
590
|
kind flips between served and opaque. `examples/mcp/server.mjs` wires them over MCP.
|
package/examples/app.mjs
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
// A whole Porthole app, runtime-agnostic (a web `Request` in, a `Response` out): agents' HTML
|
|
2
2
|
// pages, each version on an origin of its own, framed in the app's viewer and openable at a
|
|
3
|
-
// clean address. examples/node/server.mjs and examples/workers/worker.mjs
|
|
3
|
+
// clean address. examples/node/server.mjs (`nodeServer`) and examples/workers/worker.mjs
|
|
4
|
+
// (`contentHostFor`) only run it.
|
|
4
5
|
//
|
|
5
6
|
// What is the app's own here (the policy): who is signed in (a cookie), which pages exist, who
|
|
6
7
|
// may see each, and what a clean address names. Everything else is Porthole's: one mount
|
|
7
8
|
// (`content.routes`, under /porthole) answers frames, the authorize route and the page's meta.
|
|
8
|
-
import {
|
|
9
|
+
import { entryTarget } from "@botiverse/porthole";
|
|
10
|
+
import { conformancePage, prefixedName } from "@botiverse/porthole/server";
|
|
9
11
|
import { displays, kinds } from "./displays.mjs";
|
|
10
12
|
|
|
11
13
|
/** The stored pages: id → versions. An app keeps them in its database. */
|
|
@@ -30,18 +32,21 @@ const html = (body, headers = {}) =>
|
|
|
30
32
|
|
|
31
33
|
const escape = (text) => text.replace(/[&<>"']/gu, (char) => `&#${char.charCodeAt(0)};`);
|
|
32
34
|
|
|
33
|
-
/** Only a path of the app's own comes back from sign-in: never another site's address. */
|
|
34
|
-
const ownPath = (next, appOrigin) => {
|
|
35
|
-
if (next?.startsWith(`${appOrigin}/`)) next = next.slice(appOrigin.length);
|
|
36
|
-
return next?.startsWith("/") && !next.startsWith("//") && !next.includes("\\") ? next : "/";
|
|
37
|
-
};
|
|
38
|
-
|
|
39
35
|
/**
|
|
36
|
+
* The app: `options`, its content host's (its policy), and `handle(request, content)`, its own
|
|
37
|
+
* requests, given that host. A runtime makes the host from the options and sends the content
|
|
38
|
+
* domain's requests to it.
|
|
39
|
+
*
|
|
40
40
|
* @param {{ appOrigin: string, contentDomain: string, secret: string, tickets?: import("@botiverse/porthole/server").TicketStore,
|
|
41
41
|
* health?: import("@botiverse/porthole/server").HealthOptions, conformance?: boolean, client: (path: string) => Promise<Response | null> }} settings
|
|
42
42
|
*/
|
|
43
43
|
export function makeApp(settings) {
|
|
44
44
|
const { appOrigin } = settings;
|
|
45
|
+
// Where redirect entry comes back after sign-in: `<first app origin>/porthole/authorize`, the
|
|
46
|
+
// default (`entry.authorizeUrl` names another).
|
|
47
|
+
const authorizeUrl = `${appOrigin}/porthole/authorize`;
|
|
48
|
+
/** Where sign-in goes on to: the authorize route or a page of the app's own, never another site. */
|
|
49
|
+
const backTo = (next) => entryTarget(next, authorizeUrl, { app: true }) ?? `${appOrigin}/`;
|
|
45
50
|
const pages = { ...PAGES };
|
|
46
51
|
// TEST MODE, for Porthole's conformance runner only (examples/conformance): pages the suite
|
|
47
52
|
// names itself, and one page no one may see. NEVER enable it in production: anyone signed in
|
|
@@ -68,7 +73,8 @@ export function makeApp(settings) {
|
|
|
68
73
|
: null;
|
|
69
74
|
};
|
|
70
75
|
|
|
71
|
-
|
|
76
|
+
/** @type {import("@botiverse/porthole/server").ContentHostOptions<string>} */
|
|
77
|
+
const options = {
|
|
72
78
|
domain: settings.contentDomain,
|
|
73
79
|
appOrigins: [appOrigin],
|
|
74
80
|
secret: settings.secret,
|
|
@@ -125,14 +131,14 @@ export function makeApp(settings) {
|
|
|
125
131
|
},
|
|
126
132
|
...(settings.health === undefined ? {} : { health: settings.health }),
|
|
127
133
|
log: (event) => console.log(JSON.stringify(event)),
|
|
128
|
-
}
|
|
129
|
-
// Frames, the authorize route and the page's meta, under /porthole.
|
|
130
|
-
const routes = content.routes(viewerOf);
|
|
134
|
+
};
|
|
131
135
|
|
|
132
|
-
|
|
136
|
+
/** @param {Request} request @param {import("@botiverse/porthole/server").ContentHost<string>} content */
|
|
137
|
+
async function handle(request, content) {
|
|
133
138
|
const url = new URL(request.url);
|
|
134
139
|
const viewer = viewerOf(request);
|
|
135
|
-
|
|
140
|
+
// Frames, the authorize route and the page's meta, under /porthole.
|
|
141
|
+
const porthole = await content.routes(viewerOf)(request);
|
|
136
142
|
if (porthole !== null) return porthole;
|
|
137
143
|
if (url.pathname === "/porthole-client/displays.mjs") {
|
|
138
144
|
// The page's display kinds: the same as the server's, as a module.
|
|
@@ -160,7 +166,7 @@ export function makeApp(settings) {
|
|
|
160
166
|
});
|
|
161
167
|
}
|
|
162
168
|
if (url.pathname === "/login" && request.method === "GET") {
|
|
163
|
-
const next = escape(
|
|
169
|
+
const next = escape(backTo(url.searchParams.get("next")));
|
|
164
170
|
return html(
|
|
165
171
|
`<!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>`,
|
|
166
172
|
{
|
|
@@ -171,7 +177,7 @@ export function makeApp(settings) {
|
|
|
171
177
|
);
|
|
172
178
|
}
|
|
173
179
|
if (url.pathname === "/login" && request.method === "POST") {
|
|
174
|
-
const next =
|
|
180
|
+
const next = backTo(new URLSearchParams(await request.text()).get("next"));
|
|
175
181
|
return new Response(null, {
|
|
176
182
|
status: 303,
|
|
177
183
|
headers: {
|
|
@@ -228,5 +234,5 @@ Promise.all([import("@botiverse/porthole"), import("/porthole-client/displays.mj
|
|
|
228
234
|
}, (error) => problem("Porthole's client didn't load: " + error.message));
|
|
229
235
|
</script></body></html>`;
|
|
230
236
|
|
|
231
|
-
return {
|
|
237
|
+
return { options, handle };
|
|
232
238
|
}
|
|
@@ -11,7 +11,8 @@ export default defineConfig({
|
|
|
11
11
|
testMatch: "*.spec.mjs",
|
|
12
12
|
outputDir: process.env.PORTHOLE_EXAMPLE_RESULTS ?? "test-results",
|
|
13
13
|
fullyParallel: true,
|
|
14
|
-
|
|
14
|
+
// The list, and why each skipped case was skipped (an inapplicable probe says which directive).
|
|
15
|
+
reporter: [["list"], ["@botiverse/porthole/conformance/reporter"]],
|
|
15
16
|
projects: conformanceProjects(devices, {
|
|
16
17
|
engines: (process.env.PORTHOLE_ENGINES ?? "chromium,webkit,firefox").split(","),
|
|
17
18
|
}),
|
|
@@ -19,7 +19,8 @@ defineHostConformance(test, {
|
|
|
19
19
|
// The app's frame endpoint (content.routes), and its display kinds.
|
|
20
20
|
issue: { url: "/porthole/frames" },
|
|
21
21
|
displays,
|
|
22
|
-
|
|
22
|
+
// Asked when a case needs it: a function, so a port known only once the server runs works too.
|
|
23
|
+
contentSource: () => `http://*.content.localhost:${port}`,
|
|
23
24
|
// A stored-pages app: its test page's two versions (the domain cases run on version 1).
|
|
24
25
|
instances: {
|
|
25
26
|
artifact: (scope, version) => ({
|
package/examples/displays.mjs
CHANGED
|
@@ -11,6 +11,8 @@ export const kinds = {
|
|
|
11
11
|
options: {
|
|
12
12
|
// A whole-page viewer: the frame fills its box, and the agent's manual says so.
|
|
13
13
|
layout: { kind: "fill" },
|
|
14
|
+
// Optional: the tools default to these names (show_page, page_guide, check_page); naming
|
|
15
|
+
// them here also has the manual name them.
|
|
14
16
|
guide: { toolName: "show_page", guideToolName: "page_guide" },
|
|
15
17
|
},
|
|
16
18
|
},
|
package/examples/node/server.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
// The example app on Node:
|
|
1
|
+
// The example app on Node: `nodeServer` sends the content domain to Porthole and everything else
|
|
2
|
+
// to the app, WebSockets included, and runs the health gate while it listens.
|
|
2
3
|
//
|
|
3
4
|
// PORTHOLE_SECRET=$(npx porthole secret) node node_modules/@botiverse/porthole/examples/node/server.mjs
|
|
4
5
|
// open http://localhost:8790 (content is served on http://*.content.localhost:8790, the same server)
|
|
@@ -6,24 +7,27 @@
|
|
|
6
7
|
// Locally the app is http://localhost:<port> and content http://*.content.localhost:<port>: every
|
|
7
8
|
// *.localhost name is loopback in browsers, and each is a site of its own, so they never share
|
|
8
9
|
// cookies or storage. In production: https://app.example.com and content.example-usercontent.com.
|
|
10
|
+
//
|
|
11
|
+
// An app that keeps its own node:http server (or Express, Fastify) uses `nodeHost(content, { request })`
|
|
12
|
+
// instead: its `request` and `upgrade` listeners, with `content.start()` once listening.
|
|
9
13
|
import { readFile } from "node:fs/promises";
|
|
10
|
-
import {
|
|
11
|
-
import {
|
|
12
|
-
import { nodeHost, nodeProbe, sendResponse, toRequest } from "@botiverse/porthole/node";
|
|
14
|
+
import { createContentHost, memoryTicketStore } from "@botiverse/porthole/server";
|
|
15
|
+
import { nodeProbe, nodeServer } from "@botiverse/porthole/node";
|
|
13
16
|
import { makeApp } from "../app.mjs";
|
|
14
17
|
|
|
15
18
|
/** Porthole's browser modules (the package's dist/), served to the app's page. */
|
|
16
19
|
const dist = new URL("../dist/", import.meta.resolve("@botiverse/porthole"));
|
|
17
|
-
const TYPES = { ".js": "text/javascript; charset=utf-8" };
|
|
18
20
|
|
|
19
21
|
export function start({
|
|
20
22
|
port = 8790,
|
|
21
23
|
secret = process.env.PORTHOLE_SECRET,
|
|
22
24
|
conformance = process.env.PORTHOLE_CONFORMANCE === "1",
|
|
23
25
|
} = {}) {
|
|
24
|
-
|
|
26
|
+
// Under the health gate, createContentHost takes a missing secret as a lasting misconfiguration
|
|
27
|
+
// (frames opaque, the log says why); an example says so at once.
|
|
28
|
+
if (!secret) throw new Error("Set PORTHOLE_SECRET (npx porthole secret makes one)");
|
|
25
29
|
const appOrigin = `http://localhost:${port}`;
|
|
26
|
-
const
|
|
30
|
+
const app = makeApp({
|
|
27
31
|
appOrigin,
|
|
28
32
|
contentDomain: `content.localhost:${port}`,
|
|
29
33
|
secret,
|
|
@@ -34,38 +38,16 @@ export function start({
|
|
|
34
38
|
client: async (path) => {
|
|
35
39
|
if (!/^\/[\w/.-]+\.js$/u.test(path) || path.includes("..")) return null;
|
|
36
40
|
return readFile(new URL(`.${path}`, dist)).then(
|
|
37
|
-
(body) =>
|
|
41
|
+
(body) =>
|
|
42
|
+
new Response(body, { headers: { "content-type": "text/javascript; charset=utf-8" } }),
|
|
38
43
|
() => null,
|
|
39
44
|
);
|
|
40
45
|
},
|
|
41
46
|
});
|
|
42
|
-
|
|
43
|
-
const
|
|
44
|
-
request: (request, response) => {
|
|
45
|
-
handle(toRequest(request, "http")).then(
|
|
46
|
-
(answer) => sendResponse(response, answer),
|
|
47
|
-
(error) => {
|
|
48
|
-
console.error(error);
|
|
49
|
-
response.writeHead(500).end();
|
|
50
|
-
},
|
|
51
|
-
);
|
|
52
|
-
},
|
|
53
|
-
});
|
|
54
|
-
const server = createServer(porthole.request);
|
|
55
|
-
server.on("upgrade", porthole.upgrade);
|
|
47
|
+
const content = createContentHost(app.options);
|
|
48
|
+
const server = nodeServer({ content, app: (request) => app.handle(request, content) });
|
|
56
49
|
return new Promise((resolve) =>
|
|
57
|
-
server.listen(port, () => {
|
|
58
|
-
content.start();
|
|
59
|
-
resolve({
|
|
60
|
-
server,
|
|
61
|
-
content,
|
|
62
|
-
appOrigin,
|
|
63
|
-
close: () => {
|
|
64
|
-
content.close();
|
|
65
|
-
server.close();
|
|
66
|
-
},
|
|
67
|
-
});
|
|
68
|
-
}),
|
|
50
|
+
server.listen(port, () => resolve({ server, content, appOrigin, close: () => server.close() })),
|
|
69
51
|
);
|
|
70
52
|
}
|
|
71
53
|
|
|
@@ -8,14 +8,15 @@
|
|
|
8
8
|
//
|
|
9
9
|
// wrangler.jsonc sets `run_worker_first`: every request, the content domain's included, comes
|
|
10
10
|
// here first, so static assets are never answered on a content origin.
|
|
11
|
-
import { d1TicketStore } from "@botiverse/porthole/server";
|
|
11
|
+
import { contentHostFor, d1TicketStore } from "@botiverse/porthole/server";
|
|
12
12
|
import { makeApp } from "../app.mjs";
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
14
|
+
/** The app for a Worker's settings (its `env`): made once per settings object. */
|
|
15
|
+
const apps = new WeakMap();
|
|
16
|
+
const appOf = (env) => {
|
|
17
|
+
let app = apps.get(env);
|
|
18
|
+
if (app === undefined) {
|
|
19
|
+
app = makeApp({
|
|
19
20
|
appOrigin: env.APP_ORIGIN,
|
|
20
21
|
contentDomain: env.CONTENT_DOMAIN,
|
|
21
22
|
secret: env.PORTHOLE_SECRET,
|
|
@@ -27,7 +28,18 @@ export default {
|
|
|
27
28
|
return answer.ok ? answer : null;
|
|
28
29
|
},
|
|
29
30
|
});
|
|
31
|
+
apps.set(env, app);
|
|
32
|
+
}
|
|
33
|
+
return app;
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
// One content host per `env`. Settings that can't be served (no PORTHOLE_SECRET, a content
|
|
37
|
+
// domain that shares a site with the app) answer every request with a 503 naming the problem.
|
|
38
|
+
const porthole = contentHostFor((env) => appOf(env).options, { log: console.error });
|
|
39
|
+
|
|
40
|
+
export default {
|
|
41
|
+
async fetch(request, env) {
|
|
30
42
|
// The content domain first (Porthole answers every request there), then the app.
|
|
31
|
-
return (await
|
|
43
|
+
return (await porthole.fetch(request, env)) ?? appOf(env).handle(request, porthole.host(env));
|
|
32
44
|
},
|
|
33
45
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
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": {
|
|
@@ -47,6 +47,10 @@
|
|
|
47
47
|
"./check/page": {
|
|
48
48
|
"types": "./dist/check/page-source.d.ts",
|
|
49
49
|
"default": "./dist/check/page-source.js"
|
|
50
|
+
},
|
|
51
|
+
"./conformance/reporter": {
|
|
52
|
+
"types": "./dist/conformance/reporter.d.ts",
|
|
53
|
+
"default": "./dist/conformance/reporter.js"
|
|
50
54
|
}
|
|
51
55
|
},
|
|
52
56
|
"devDependencies": {
|
|
@@ -62,6 +66,7 @@
|
|
|
62
66
|
"miniflare": "4.20260730.0",
|
|
63
67
|
"react": "19.3.0",
|
|
64
68
|
"react-dom": "19.3.0",
|
|
69
|
+
"rolldown": "1.2.11",
|
|
65
70
|
"typescript": "7.0.2"
|
|
66
71
|
},
|
|
67
72
|
"peerDependencies": {
|
|
@@ -76,7 +81,8 @@
|
|
|
76
81
|
"node": ">=24"
|
|
77
82
|
},
|
|
78
83
|
"scripts": {
|
|
79
|
-
"build": "tsc -p tsconfig.build.json && node scripts/build-harness.ts && node scripts/copy-docs.ts",
|
|
80
|
-
"test:leak": "playwright test -c leak/playwright.config.ts"
|
|
84
|
+
"build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node scripts/build-harness.ts && node scripts/copy-docs.ts",
|
|
85
|
+
"test:leak": "playwright test -c leak/playwright.config.ts",
|
|
86
|
+
"test:bundle": "node scripts/bundle-test.ts"
|
|
81
87
|
}
|
|
82
88
|
}
|
package/src/check/check.ts
CHANGED
|
@@ -1,7 +1,24 @@
|
|
|
1
1
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import type { InstanceRef } from "../isolation/types.ts";
|
|
2
3
|
import { presets } from "../presets/presets.ts";
|
|
4
|
+
import { createServer } from "../server/server.ts";
|
|
5
|
+
import { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN } from "./drivers.ts";
|
|
3
6
|
import { lintContent, type Finding } from "./lint.ts";
|
|
4
|
-
|
|
7
|
+
// The check page's script, imported as a module so a bundler takes it in (P075): no file is
|
|
8
|
+
// looked up beside this one at run time.
|
|
9
|
+
import PAGE_SCRIPT from "./page-source.ts";
|
|
10
|
+
import {
|
|
11
|
+
instrumented,
|
|
12
|
+
namedScripts,
|
|
13
|
+
type CheckCall,
|
|
14
|
+
type CheckRunData,
|
|
15
|
+
type CheckRunSpec,
|
|
16
|
+
} from "./instrument.ts";
|
|
17
|
+
|
|
18
|
+
export type { CheckCall } from "./instrument.ts";
|
|
19
|
+
|
|
20
|
+
/** The content source the check's served origins match. */
|
|
21
|
+
const CHECK_SOURCE = `https://*.${CHECK_CONTENT_DOMAIN}`;
|
|
5
22
|
|
|
6
23
|
/**
|
|
7
24
|
* Checks content before people see it (P073): runs it in the real sandbox at each width and
|
|
@@ -17,6 +34,12 @@ export interface CheckSession {
|
|
|
17
34
|
setViewport(width: number, height: number): Promise<void>;
|
|
18
35
|
/** Loads a whole HTML document into the page. */
|
|
19
36
|
load(html: string): Promise<void>;
|
|
37
|
+
/**
|
|
38
|
+
* Answers every request to the check page's origin and the check's content domain with
|
|
39
|
+
* `handler`, and opens the page (`/`): a served config's content then runs on an origin of its
|
|
40
|
+
* own, as people's browsers run it (P074). Without it, the check runs content opaque.
|
|
41
|
+
*/
|
|
42
|
+
serve?(handler: (request: Request) => Promise<Response>): Promise<void>;
|
|
20
43
|
/** Evaluates a JavaScript expression in the page (a promise is awaited); JSON back. */
|
|
21
44
|
evaluate<T>(expression: string): Promise<T>;
|
|
22
45
|
/** A PNG of the element `selector` names, where the driver can. */
|
|
@@ -50,8 +73,8 @@ export interface CheckOptions {
|
|
|
50
73
|
/** The most distinct problems `text` names (default 8): the rest are counted. */
|
|
51
74
|
readonly maxProblems?: number;
|
|
52
75
|
/**
|
|
53
|
-
* The check page's script
|
|
54
|
-
*
|
|
76
|
+
* The check page's script. Default: Porthole's own (`@botiverse/porthole/check/page`), imported
|
|
77
|
+
* with this module, so a bundle (a Worker, a single executable) has it too (P075).
|
|
55
78
|
*/
|
|
56
79
|
readonly page?: string;
|
|
57
80
|
}
|
|
@@ -68,11 +91,20 @@ export interface CheckRun {
|
|
|
68
91
|
readonly blocked: readonly { readonly url: string; readonly directive: string }[];
|
|
69
92
|
readonly failedLoads: readonly { readonly url: string; readonly tag: string }[];
|
|
70
93
|
readonly console: readonly { readonly level: "error" | "warning"; readonly text: string }[];
|
|
94
|
+
/**
|
|
95
|
+
* The host functions it called (P074), each answered as a host that declines would. One a
|
|
96
|
+
* host's gates refuse whatever the person says (no click, bad arguments, not offered, too
|
|
97
|
+
* often) is a problem; one a person or host may decline is a note.
|
|
98
|
+
*/
|
|
99
|
+
readonly calls: readonly CheckCall[];
|
|
71
100
|
readonly screenshot?: Uint8Array;
|
|
72
101
|
}
|
|
73
102
|
|
|
74
103
|
export interface CheckReport {
|
|
75
|
-
/**
|
|
104
|
+
/**
|
|
105
|
+
* Nothing failed: no errors, blocks, failed loads, console errors, host-function calls a host
|
|
106
|
+
* refuses, overflow or cut, no lint error.
|
|
107
|
+
*/
|
|
76
108
|
readonly ok: boolean;
|
|
77
109
|
readonly lint: readonly Finding[];
|
|
78
110
|
readonly runs: readonly CheckRun[];
|
|
@@ -84,8 +116,9 @@ const noun = (config: PortholeConfig) =>
|
|
|
84
116
|
config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
|
|
85
117
|
|
|
86
118
|
/**
|
|
87
|
-
* The config the check runs content under
|
|
88
|
-
* same CSP); an MCP Apps view as a page with the view's
|
|
119
|
+
* The config the check runs content under where it can't serve it (a driver without `serve`):
|
|
120
|
+
* opaque (a served config's content with the same CSP); an MCP Apps view as a page with the view's
|
|
121
|
+
* egress (its protocol is its host's).
|
|
89
122
|
*/
|
|
90
123
|
function checkedAs(config: PortholeConfig): PortholeConfig {
|
|
91
124
|
const opaque: PortholeConfig =
|
|
@@ -95,20 +128,6 @@ function checkedAs(config: PortholeConfig): PortholeConfig {
|
|
|
95
128
|
: opaque;
|
|
96
129
|
}
|
|
97
130
|
|
|
98
|
-
/** The check page's script: given, or (Node) the package's own. */
|
|
99
|
-
async function pageScript(given: string | undefined): Promise<string> {
|
|
100
|
-
if (given !== undefined) {
|
|
101
|
-
return given;
|
|
102
|
-
}
|
|
103
|
-
// Not a literal: a bundler for a Worker leaves it alone (a Worker passes `page`).
|
|
104
|
-
const where = new URL(
|
|
105
|
-
import.meta.url.endsWith(".ts") ? "./page-source.ts" : "./page-source.js",
|
|
106
|
-
import.meta.url,
|
|
107
|
-
).href;
|
|
108
|
-
const loaded = (await import(where)) as { default: string };
|
|
109
|
-
return loaded.default;
|
|
110
|
-
}
|
|
111
|
-
|
|
112
131
|
const escapeScript = (code: string) => code.replace(/<\/script/giu, "<\\/script");
|
|
113
132
|
|
|
114
133
|
export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
@@ -127,20 +146,69 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
127
146
|
const schemes = options.schemes ?? (unthemed ? ["light"] : ["light", "dark"]);
|
|
128
147
|
const settle = options.settleMs ?? 1_500;
|
|
129
148
|
const fills = config.layout.kind === "fill";
|
|
130
|
-
const
|
|
131
|
-
const script = await pageScript(options.page);
|
|
149
|
+
const script = options.page ?? PAGE_SCRIPT;
|
|
132
150
|
const html = `<!doctype html><html><head><meta charset="utf-8"><title>Porthole check</title><style>body{margin:0;padding:8px}section{margin-bottom:16px}</style></head><body><script>${escapeScript(script)}</script></body></html>`;
|
|
151
|
+
// Its inline scripts named, so an error says the line in the content as written (P074).
|
|
152
|
+
const { content, scriptLines } = namedScripts(options.content);
|
|
133
153
|
|
|
134
154
|
const session = await options.driver.open();
|
|
155
|
+
// A served config runs served, on a content origin the driver answers, under Porthole's own
|
|
156
|
+
// server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
|
|
157
|
+
const servedHere =
|
|
158
|
+
config.isolation === "domain" && config.mode !== "mcp-app" && session.serve !== undefined;
|
|
159
|
+
const servedConfig: PortholeConfig = { ...config, contentOrigins: [CHECK_SOURCE] };
|
|
160
|
+
const server = servedHere
|
|
161
|
+
? createServer({
|
|
162
|
+
content: { domain: CHECK_CONTENT_DOMAIN, scheme: "https" },
|
|
163
|
+
secret: crypto.getRandomValues(new Uint8Array(32)),
|
|
164
|
+
hostOrigins: [CHECK_ORIGIN],
|
|
165
|
+
configs: { check: servedConfig },
|
|
166
|
+
artifacts: { get: () => Promise.resolve({ html: instrumented(content) }) },
|
|
167
|
+
})
|
|
168
|
+
: null;
|
|
169
|
+
const handler = async (request: Request): Promise<Response> => {
|
|
170
|
+
const url = new URL(request.url);
|
|
171
|
+
if (url.origin === CHECK_ORIGIN) {
|
|
172
|
+
if (url.pathname === "/") {
|
|
173
|
+
return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });
|
|
174
|
+
}
|
|
175
|
+
if (url.pathname === "/issue" && server !== null) {
|
|
176
|
+
const asked = (await request.json()) as { instance: InstanceRef };
|
|
177
|
+
return Response.json(await server.issue(asked.instance, { viewer: "check" }));
|
|
178
|
+
}
|
|
179
|
+
return new Response("not found", { status: 404 });
|
|
180
|
+
}
|
|
181
|
+
return (await server?.handle(request)) ?? new Response("not found", { status: 404 });
|
|
182
|
+
};
|
|
183
|
+
const shown = servedHere ? servedConfig : checkedAs(config);
|
|
184
|
+
let runIndex = 0;
|
|
185
|
+
|
|
135
186
|
const runs: CheckRun[] = [];
|
|
136
187
|
try {
|
|
137
188
|
for (const width of widths) {
|
|
138
189
|
await session.setViewport(width + 40, fills ? 760 : 900);
|
|
139
|
-
|
|
190
|
+
if (servedHere && session.serve !== undefined) {
|
|
191
|
+
await session.serve(handler);
|
|
192
|
+
} else {
|
|
193
|
+
await session.load(html);
|
|
194
|
+
}
|
|
140
195
|
for (const scheme of schemes) {
|
|
196
|
+
runIndex += 1;
|
|
197
|
+
// Each run on an origin of its own: its storage starts empty, as a new page's does.
|
|
198
|
+
const instance: InstanceRef | undefined = servedHere
|
|
199
|
+
? {
|
|
200
|
+
scope: `check-${runIndex}`,
|
|
201
|
+
document:
|
|
202
|
+
config.mode === "inline"
|
|
203
|
+
? { kind: "shell", preset: "check" }
|
|
204
|
+
: { kind: "artifact", id: "check", version: "1", preset: "check" },
|
|
205
|
+
}
|
|
206
|
+
: undefined;
|
|
141
207
|
const spec: CheckRunSpec = {
|
|
142
208
|
config: shown,
|
|
143
|
-
content
|
|
209
|
+
content,
|
|
210
|
+
scriptLines,
|
|
211
|
+
...(instance === undefined ? {} : { instance }),
|
|
144
212
|
widthPx: width,
|
|
145
213
|
...(fills ? { heightPx: 700 } : {}),
|
|
146
214
|
scheme,
|
|
@@ -176,6 +244,7 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
176
244
|
blocked: uniqueBy(data?.blocked ?? [], (each) => `${each.url} ${each.directive}`),
|
|
177
245
|
failedLoads: uniqueBy(data?.failedLoads ?? [], (each) => each.url),
|
|
178
246
|
console: uniqueBy(data?.console ?? [], (each) => `${each.level} ${each.text}`),
|
|
247
|
+
calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
|
|
179
248
|
...(screenshot === undefined ? {} : { screenshot }),
|
|
180
249
|
});
|
|
181
250
|
}
|
|
@@ -188,12 +257,24 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
188
257
|
run.blocked.length > 0 ||
|
|
189
258
|
run.failedLoads.length > 0 ||
|
|
190
259
|
run.console.some((each) => each.level === "error") ||
|
|
260
|
+
run.calls.some((each) => REFUSED[each.outcome] !== undefined) ||
|
|
191
261
|
run.overflowX ||
|
|
192
262
|
run.clipped;
|
|
193
263
|
const ok = !lint.some((each) => each.severity === "error") && !runs.some(failed);
|
|
194
264
|
return { ok, lint, runs, text: summary(config, lint, runs, options.maxProblems ?? 8) };
|
|
195
265
|
}
|
|
196
266
|
|
|
267
|
+
/** Calls a host refuses whatever the person says: problems, worded for the agent. */
|
|
268
|
+
const REFUSED: Readonly<Record<string, (capability: string) => string>> = {
|
|
269
|
+
"no-user-activation": (name) =>
|
|
270
|
+
`It called ${name} at load, with no click: hosts refuse that. Call ${name} from a click`,
|
|
271
|
+
invalid: (name) =>
|
|
272
|
+
`It called ${name} with arguments hosts refuse: see what the manual says ${name} takes`,
|
|
273
|
+
"not-declared": (name) => `It called ${name}, which this host doesn't offer: leave it out`,
|
|
274
|
+
"rate-limited": (name) => `It called ${name} more often than hosts allow, and was refused`,
|
|
275
|
+
"no-confirm": (name) => `It called ${name}, which this host can't confirm, and was refused`,
|
|
276
|
+
};
|
|
277
|
+
|
|
197
278
|
const unique = (values: readonly string[]) => [...new Set(values)];
|
|
198
279
|
function uniqueBy<T>(values: readonly T[], key: (value: T) => string): T[] {
|
|
199
280
|
const seen = new Set<string>();
|
|
@@ -227,7 +308,19 @@ function summary(
|
|
|
227
308
|
list.push(`${run.width} px ${run.scheme}`);
|
|
228
309
|
where.set(problem, list);
|
|
229
310
|
};
|
|
311
|
+
// Calls a person or host may decline: the content should still work when they do.
|
|
312
|
+
const notes = new Set<string>();
|
|
230
313
|
for (const run of runs) {
|
|
314
|
+
for (const call of run.calls) {
|
|
315
|
+
const refused = REFUSED[call.outcome];
|
|
316
|
+
if (refused === undefined) {
|
|
317
|
+
notes.add(
|
|
318
|
+
`Note: it called ${call.capability} at load; the check answered no, as a host or a person may. Make sure the ${it} still works then.`,
|
|
319
|
+
);
|
|
320
|
+
} else {
|
|
321
|
+
add(refused(call.capability), run);
|
|
322
|
+
}
|
|
323
|
+
}
|
|
231
324
|
for (const error of run.errors) {
|
|
232
325
|
add(`It threw: ${clip(error)}`, run);
|
|
233
326
|
}
|
|
@@ -266,7 +359,10 @@ function summary(
|
|
|
266
359
|
];
|
|
267
360
|
const ran = `${[...new Set(runs.map((run) => `${run.width} px`))].join(" and ")}, ${[...new Set(runs.map((run) => run.scheme))].join(" and ")}`;
|
|
268
361
|
if (lines.length === 0) {
|
|
269
|
-
return
|
|
362
|
+
return [
|
|
363
|
+
`OK: the ${it} ran at ${ran} with no errors, blocks, failed loads or overflow.`,
|
|
364
|
+
...notes,
|
|
365
|
+
].join("\n");
|
|
270
366
|
}
|
|
271
367
|
const shown = lines.slice(0, most);
|
|
272
368
|
const more = lines.length - shown.length;
|
|
@@ -274,5 +370,6 @@ function summary(
|
|
|
274
370
|
`The ${it} has ${lines.length} problem${lines.length === 1 ? "" : "s"} (ran at ${ran}):`,
|
|
275
371
|
...shown.map((line) => `- ${line}`),
|
|
276
372
|
...(more > 0 ? [`- and ${more} more.`] : []),
|
|
373
|
+
...notes,
|
|
277
374
|
].join("\n");
|
|
278
375
|
}
|