@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.
Files changed (56) hide show
  1. package/README.md +3 -2
  2. package/dist/check/check.d.ts +20 -3
  3. package/dist/check/check.js +88 -25
  4. package/dist/check/drivers.d.ts +25 -6
  5. package/dist/check/drivers.js +99 -28
  6. package/dist/check/index.d.ts +2 -2
  7. package/dist/check/index.js +1 -1
  8. package/dist/check/instrument.d.ts +71 -0
  9. package/dist/check/instrument.js +84 -0
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/page.d.ts +2 -40
  12. package/dist/check/page.js +63 -43
  13. package/dist/conformance/harness-source.d.ts +2 -0
  14. package/dist/conformance/harness-source.js +2 -0
  15. package/dist/conformance/host-kit.d.ts +20 -7
  16. package/dist/conformance/host-kit.js +42 -48
  17. package/dist/conformance/index.d.ts +1 -1
  18. package/dist/conformance/reporter.d.ts +14 -0
  19. package/dist/conformance/reporter.js +28 -0
  20. package/dist/host/client.d.ts +33 -15
  21. package/dist/host/client.js +39 -24
  22. package/dist/node/index.d.ts +6 -2
  23. package/dist/node/index.js +53 -8
  24. package/dist/react/frame.d.ts +13 -5
  25. package/dist/react/frame.js +67 -27
  26. package/dist/react/index.d.ts +1 -1
  27. package/dist/react/view.js +6 -1
  28. package/dist/server/host.d.ts +5 -3
  29. package/dist/server/host.js +41 -12
  30. package/docs/ADOPTING.md +115 -26
  31. package/docs/DECISIONS.md +167 -0
  32. package/docs/DESIGN.md +38 -13
  33. package/examples/app.mjs +23 -17
  34. package/examples/conformance/playwright.config.mjs +2 -1
  35. package/examples/conformance/porthole.spec.mjs +2 -1
  36. package/examples/displays.mjs +2 -0
  37. package/examples/node/server.mjs +16 -34
  38. package/examples/workers/worker.mjs +19 -7
  39. package/package.json +9 -3
  40. package/src/check/check.ts +122 -25
  41. package/src/check/drivers.ts +137 -39
  42. package/src/check/index.ts +8 -1
  43. package/src/check/instrument.ts +138 -0
  44. package/src/check/page-source.ts +4 -3
  45. package/src/check/page.ts +94 -68
  46. package/src/conformance/harness-source.ts +23 -0
  47. package/src/conformance/host-kit.ts +69 -46
  48. package/src/conformance/index.ts +1 -0
  49. package/src/conformance/reporter.ts +38 -0
  50. package/src/host/client.ts +65 -34
  51. package/src/node/index.ts +56 -10
  52. package/src/react/frame.tsx +89 -33
  53. package/src/react/index.ts +1 -0
  54. package/src/react/view.tsx +6 -1
  55. package/src/server/host.ts +53 -15
  56. 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), `GET
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`) 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).
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 only adapt it.
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 { conformancePage, createContentHost, prefixedName } from "@botiverse/porthole/server";
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
- const content = createContentHost({
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
- async function handle(request) {
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
- const porthole = await routes(request);
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(ownPath(url.searchParams.get("next"), appOrigin));
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 = ownPath(new URLSearchParams(await request.text()).get("next"), appOrigin);
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 { content, handle };
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
- reporter: [["list"]],
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
- contentSource: `http://*.content.localhost:${port}`,
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) => ({
@@ -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
  },
@@ -1,4 +1,5 @@
1
- // The example app on Node: node:http, with Porthole's Node adapter in front of it.
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 { createServer } from "node:http";
11
- import { memoryTicketStore } from "@botiverse/porthole/server";
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
- if (!secret) throw new Error("Set PORTHOLE_SECRET (npx porthole secret)");
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 { content, handle } = makeApp({
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) => new Response(body, { headers: { "content-type": TYPES[".js"] } }),
41
+ (body) =>
42
+ new Response(body, { headers: { "content-type": "text/javascript; charset=utf-8" } }),
38
43
  () => null,
39
44
  );
40
45
  },
41
46
  });
42
- // Content hosts go to Porthole; everything else to the app.
43
- const porthole = nodeHost(content, {
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
- let app = null; // one per isolate, made from the first request's env
15
-
16
- export default {
17
- async fetch(request, env) {
18
- app ??= makeApp({
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 app.content.fetch(request)) ?? app.handle(request);
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.0",
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
  }
@@ -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
- import type { CheckRunData, CheckRunSpec } from "./page.ts";
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 (`import page from "@botiverse/porthole/check/page"`). Node finds it
54
- * itself; a bundled runtime (a Worker) passes it.
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
- /** Nothing failed: no errors, blocks, failed loads, console errors, overflow or cut, no lint error. */
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: opaque (a served config's content is checked with the
88
- * same CSP); an MCP Apps view as a page with the view's egress (its protocol is its host'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 shown = checkedAs(config);
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
- await session.load(html);
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: options.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 `OK: the ${it} ran at ${ran} with no errors, blocks, failed loads or overflow.`;
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
  }