@botiverse/porthole 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +3 -2
  2. package/dist/check/check.d.ts +18 -1
  3. package/dist/check/check.js +84 -6
  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/host-kit.d.ts +18 -5
  14. package/dist/conformance/host-kit.js +38 -21
  15. package/dist/conformance/index.d.ts +1 -1
  16. package/dist/conformance/reporter.d.ts +14 -0
  17. package/dist/conformance/reporter.js +28 -0
  18. package/dist/host/client.d.ts +33 -15
  19. package/dist/host/client.js +39 -24
  20. package/dist/node/index.d.ts +6 -2
  21. package/dist/node/index.js +53 -8
  22. package/dist/react/frame.d.ts +13 -5
  23. package/dist/react/frame.js +67 -27
  24. package/dist/react/index.d.ts +1 -1
  25. package/dist/react/view.js +6 -1
  26. package/dist/server/host.d.ts +5 -3
  27. package/dist/server/host.js +41 -12
  28. package/docs/ADOPTING.md +108 -25
  29. package/docs/DECISIONS.md +134 -0
  30. package/docs/DESIGN.md +36 -12
  31. package/examples/app.mjs +23 -17
  32. package/examples/conformance/playwright.config.mjs +2 -1
  33. package/examples/conformance/porthole.spec.mjs +2 -1
  34. package/examples/displays.mjs +2 -0
  35. package/examples/node/server.mjs +16 -34
  36. package/examples/workers/worker.mjs +19 -7
  37. package/package.json +5 -1
  38. package/src/check/check.ts +116 -8
  39. package/src/check/drivers.ts +137 -39
  40. package/src/check/index.ts +8 -1
  41. package/src/check/instrument.ts +138 -0
  42. package/src/check/page.ts +94 -68
  43. package/src/conformance/host-kit.ts +65 -19
  44. package/src/conformance/index.ts +1 -0
  45. package/src/conformance/reporter.ts +38 -0
  46. package/src/host/client.ts +65 -34
  47. package/src/node/index.ts +56 -10
  48. package/src/react/frame.tsx +89 -33
  49. package/src/react/index.ts +1 -0
  50. package/src/react/view.tsx +6 -1
  51. package/src/server/host.ts +53 -15
@@ -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.1",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "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": {
@@ -1,7 +1,21 @@
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
+ import {
8
+ instrumented,
9
+ namedScripts,
10
+ type CheckCall,
11
+ type CheckRunData,
12
+ type CheckRunSpec,
13
+ } from "./instrument.ts";
14
+
15
+ export type { CheckCall } from "./instrument.ts";
16
+
17
+ /** The content source the check's served origins match. */
18
+ const CHECK_SOURCE = `https://*.${CHECK_CONTENT_DOMAIN}`;
5
19
 
6
20
  /**
7
21
  * Checks content before people see it (P073): runs it in the real sandbox at each width and
@@ -17,6 +31,12 @@ export interface CheckSession {
17
31
  setViewport(width: number, height: number): Promise<void>;
18
32
  /** Loads a whole HTML document into the page. */
19
33
  load(html: string): Promise<void>;
34
+ /**
35
+ * Answers every request to the check page's origin and the check's content domain with
36
+ * `handler`, and opens the page (`/`): a served config's content then runs on an origin of its
37
+ * own, as people's browsers run it (P074). Without it, the check runs content opaque.
38
+ */
39
+ serve?(handler: (request: Request) => Promise<Response>): Promise<void>;
20
40
  /** Evaluates a JavaScript expression in the page (a promise is awaited); JSON back. */
21
41
  evaluate<T>(expression: string): Promise<T>;
22
42
  /** A PNG of the element `selector` names, where the driver can. */
@@ -68,11 +88,20 @@ export interface CheckRun {
68
88
  readonly blocked: readonly { readonly url: string; readonly directive: string }[];
69
89
  readonly failedLoads: readonly { readonly url: string; readonly tag: string }[];
70
90
  readonly console: readonly { readonly level: "error" | "warning"; readonly text: string }[];
91
+ /**
92
+ * The host functions it called (P074), each answered as a host that declines would. One a
93
+ * host's gates refuse whatever the person says (no click, bad arguments, not offered, too
94
+ * often) is a problem; one a person or host may decline is a note.
95
+ */
96
+ readonly calls: readonly CheckCall[];
71
97
  readonly screenshot?: Uint8Array;
72
98
  }
73
99
 
74
100
  export interface CheckReport {
75
- /** Nothing failed: no errors, blocks, failed loads, console errors, overflow or cut, no lint error. */
101
+ /**
102
+ * Nothing failed: no errors, blocks, failed loads, console errors, host-function calls a host
103
+ * refuses, overflow or cut, no lint error.
104
+ */
76
105
  readonly ok: boolean;
77
106
  readonly lint: readonly Finding[];
78
107
  readonly runs: readonly CheckRun[];
@@ -84,8 +113,9 @@ const noun = (config: PortholeConfig) =>
84
113
  config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
85
114
 
86
115
  /**
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).
116
+ * The config the check runs content under where it can't serve it (a driver without `serve`):
117
+ * opaque (a served config's content with the same CSP); an MCP Apps view as a page with the view's
118
+ * egress (its protocol is its host's).
89
119
  */
90
120
  function checkedAs(config: PortholeConfig): PortholeConfig {
91
121
  const opaque: PortholeConfig =
@@ -127,20 +157,69 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
127
157
  const schemes = options.schemes ?? (unthemed ? ["light"] : ["light", "dark"]);
128
158
  const settle = options.settleMs ?? 1_500;
129
159
  const fills = config.layout.kind === "fill";
130
- const shown = checkedAs(config);
131
160
  const script = await pageScript(options.page);
132
161
  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>`;
162
+ // Its inline scripts named, so an error says the line in the content as written (P074).
163
+ const { content, scriptLines } = namedScripts(options.content);
133
164
 
134
165
  const session = await options.driver.open();
166
+ // A served config runs served, on a content origin the driver answers, under Porthole's own
167
+ // server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
168
+ const servedHere =
169
+ config.isolation === "domain" && config.mode !== "mcp-app" && session.serve !== undefined;
170
+ const servedConfig: PortholeConfig = { ...config, contentOrigins: [CHECK_SOURCE] };
171
+ const server = servedHere
172
+ ? createServer({
173
+ content: { domain: CHECK_CONTENT_DOMAIN, scheme: "https" },
174
+ secret: crypto.getRandomValues(new Uint8Array(32)),
175
+ hostOrigins: [CHECK_ORIGIN],
176
+ configs: { check: servedConfig },
177
+ artifacts: { get: () => Promise.resolve({ html: instrumented(content) }) },
178
+ })
179
+ : null;
180
+ const handler = async (request: Request): Promise<Response> => {
181
+ const url = new URL(request.url);
182
+ if (url.origin === CHECK_ORIGIN) {
183
+ if (url.pathname === "/") {
184
+ return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });
185
+ }
186
+ if (url.pathname === "/issue" && server !== null) {
187
+ const asked = (await request.json()) as { instance: InstanceRef };
188
+ return Response.json(await server.issue(asked.instance, { viewer: "check" }));
189
+ }
190
+ return new Response("not found", { status: 404 });
191
+ }
192
+ return (await server?.handle(request)) ?? new Response("not found", { status: 404 });
193
+ };
194
+ const shown = servedHere ? servedConfig : checkedAs(config);
195
+ let runIndex = 0;
196
+
135
197
  const runs: CheckRun[] = [];
136
198
  try {
137
199
  for (const width of widths) {
138
200
  await session.setViewport(width + 40, fills ? 760 : 900);
139
- await session.load(html);
201
+ if (servedHere && session.serve !== undefined) {
202
+ await session.serve(handler);
203
+ } else {
204
+ await session.load(html);
205
+ }
140
206
  for (const scheme of schemes) {
207
+ runIndex += 1;
208
+ // Each run on an origin of its own: its storage starts empty, as a new page's does.
209
+ const instance: InstanceRef | undefined = servedHere
210
+ ? {
211
+ scope: `check-${runIndex}`,
212
+ document:
213
+ config.mode === "inline"
214
+ ? { kind: "shell", preset: "check" }
215
+ : { kind: "artifact", id: "check", version: "1", preset: "check" },
216
+ }
217
+ : undefined;
141
218
  const spec: CheckRunSpec = {
142
219
  config: shown,
143
- content: options.content,
220
+ content,
221
+ scriptLines,
222
+ ...(instance === undefined ? {} : { instance }),
144
223
  widthPx: width,
145
224
  ...(fills ? { heightPx: 700 } : {}),
146
225
  scheme,
@@ -176,6 +255,7 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
176
255
  blocked: uniqueBy(data?.blocked ?? [], (each) => `${each.url} ${each.directive}`),
177
256
  failedLoads: uniqueBy(data?.failedLoads ?? [], (each) => each.url),
178
257
  console: uniqueBy(data?.console ?? [], (each) => `${each.level} ${each.text}`),
258
+ calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
179
259
  ...(screenshot === undefined ? {} : { screenshot }),
180
260
  });
181
261
  }
@@ -188,12 +268,24 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
188
268
  run.blocked.length > 0 ||
189
269
  run.failedLoads.length > 0 ||
190
270
  run.console.some((each) => each.level === "error") ||
271
+ run.calls.some((each) => REFUSED[each.outcome] !== undefined) ||
191
272
  run.overflowX ||
192
273
  run.clipped;
193
274
  const ok = !lint.some((each) => each.severity === "error") && !runs.some(failed);
194
275
  return { ok, lint, runs, text: summary(config, lint, runs, options.maxProblems ?? 8) };
195
276
  }
196
277
 
278
+ /** Calls a host refuses whatever the person says: problems, worded for the agent. */
279
+ const REFUSED: Readonly<Record<string, (capability: string) => string>> = {
280
+ "no-user-activation": (name) =>
281
+ `It called ${name} at load, with no click: hosts refuse that. Call ${name} from a click`,
282
+ invalid: (name) =>
283
+ `It called ${name} with arguments hosts refuse: see what the manual says ${name} takes`,
284
+ "not-declared": (name) => `It called ${name}, which this host doesn't offer: leave it out`,
285
+ "rate-limited": (name) => `It called ${name} more often than hosts allow, and was refused`,
286
+ "no-confirm": (name) => `It called ${name}, which this host can't confirm, and was refused`,
287
+ };
288
+
197
289
  const unique = (values: readonly string[]) => [...new Set(values)];
198
290
  function uniqueBy<T>(values: readonly T[], key: (value: T) => string): T[] {
199
291
  const seen = new Set<string>();
@@ -227,7 +319,19 @@ function summary(
227
319
  list.push(`${run.width} px ${run.scheme}`);
228
320
  where.set(problem, list);
229
321
  };
322
+ // Calls a person or host may decline: the content should still work when they do.
323
+ const notes = new Set<string>();
230
324
  for (const run of runs) {
325
+ for (const call of run.calls) {
326
+ const refused = REFUSED[call.outcome];
327
+ if (refused === undefined) {
328
+ notes.add(
329
+ `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.`,
330
+ );
331
+ } else {
332
+ add(refused(call.capability), run);
333
+ }
334
+ }
231
335
  for (const error of run.errors) {
232
336
  add(`It threw: ${clip(error)}`, run);
233
337
  }
@@ -266,7 +370,10 @@ function summary(
266
370
  ];
267
371
  const ran = `${[...new Set(runs.map((run) => `${run.width} px`))].join(" and ")}, ${[...new Set(runs.map((run) => run.scheme))].join(" and ")}`;
268
372
  if (lines.length === 0) {
269
- return `OK: the ${it} ran at ${ran} with no errors, blocks, failed loads or overflow.`;
373
+ return [
374
+ `OK: the ${it} ran at ${ran} with no errors, blocks, failed loads or overflow.`,
375
+ ...notes,
376
+ ].join("\n");
270
377
  }
271
378
  const shown = lines.slice(0, most);
272
379
  const more = lines.length - shown.length;
@@ -274,5 +381,6 @@ function summary(
274
381
  `The ${it} has ${lines.length} problem${lines.length === 1 ? "" : "s"} (ran at ${ran}):`,
275
382
  ...shown.map((line) => `- ${line}`),
276
383
  ...(more > 0 ? [`- and ${more} more.`] : []),
384
+ ...notes,
277
385
  ].join("\n");
278
386
  }
@@ -5,22 +5,78 @@ import type { CheckDriver, CheckSession } from "./check.ts";
5
5
  * Drivers for `checkPage` (P073): Playwright's browser on Node, or any Chrome DevTools Protocol
6
6
  * session (Puppeteer's `page.createCDPSession()`, `@cloudflare/puppeteer` on Cloudflare Browser
7
7
  * Rendering from a Worker).
8
+ *
9
+ * A driver answers two names no network has itself: the check page's origin (a host's), and a
10
+ * content domain, where a served config's content runs on an origin of its own as people's
11
+ * browsers run it (P074).
8
12
  */
9
13
 
14
+ /** Where the check page is served from. */
15
+ export const CHECK_ORIGIN = "https://porthole-check.invalid";
16
+ /** The content domain a served config's content runs under in the check: another site. */
17
+ export const CHECK_CONTENT_DOMAIN = "porthole-check-content.invalid";
18
+
19
+ const CHECK_HOST = new URL(CHECK_ORIGIN).hostname;
20
+ /** Whether the driver answers a URL itself. */
21
+ const answered = (url: URL): boolean =>
22
+ url.hostname === CHECK_HOST || url.hostname.endsWith(`.${CHECK_CONTENT_DOMAIN}`);
23
+
24
+ type Handler = (request: Request) => Promise<Response>;
25
+
26
+ /** A page that answers the check's own names: `/` the given document, the rest 404. */
27
+ const pageOnly =
28
+ (html: string): Handler =>
29
+ (request) =>
30
+ Promise.resolve(
31
+ new URL(request.url).hostname === CHECK_HOST && new URL(request.url).pathname === "/"
32
+ ? new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } })
33
+ : new Response("not found", { status: 404 }),
34
+ );
35
+
10
36
  /** Checks in a page of a Playwright browser (`chromium.launch()`), one page per check. */
11
37
  export function playwrightDriver(browser: Browser): CheckDriver {
12
38
  return {
13
39
  async open(): Promise<CheckSession> {
14
40
  const page = await browser.newPage();
15
- let html = "";
16
- // The check page needs an origin of its own (a host's): served from a name no network has.
17
- await page.route(`${CHECK_ORIGIN}/**`, (route) =>
18
- route.fulfill({ status: 200, contentType: "text/html; charset=utf-8", body: html }),
19
- );
41
+ let handler: Handler = pageOnly("");
42
+ await page.route(answered, async (route) => {
43
+ const asked = route.request();
44
+ const headers = Object.entries(await asked.allHeaders()).filter(
45
+ ([name]) => !name.startsWith(":"),
46
+ );
47
+ const method = asked.method();
48
+ const body = method === "GET" || method === "HEAD" ? null : asked.postDataBuffer();
49
+ const answer = await handler(
50
+ new Request(asked.url(), {
51
+ method,
52
+ headers,
53
+ ...(body === null ? {} : { body: new Uint8Array(body) }),
54
+ }),
55
+ );
56
+ const out: Record<string, string> = {};
57
+ for (const [name, value] of answer.headers) {
58
+ if (name !== "set-cookie") {
59
+ out[name] = value;
60
+ }
61
+ }
62
+ const cookies = answer.headers.getSetCookie();
63
+ if (cookies.length > 0) {
64
+ out["set-cookie"] = cookies.join("\n");
65
+ }
66
+ await route.fulfill({
67
+ status: answer.status,
68
+ headers: out,
69
+ body: Buffer.from(await answer.arrayBuffer()),
70
+ });
71
+ });
20
72
  return {
21
73
  setViewport: (width, height) => page.setViewportSize({ width, height }),
22
74
  async load(document) {
23
- html = document;
75
+ handler = pageOnly(document);
76
+ await page.goto(`${CHECK_ORIGIN}/`, { waitUntil: "load" });
77
+ },
78
+ async serve(given) {
79
+ handler = given;
24
80
  await page.goto(`${CHECK_ORIGIN}/`, { waitUntil: "load" });
25
81
  },
26
82
  evaluate: (expression) => page.evaluate(expression),
@@ -31,21 +87,30 @@ export function playwrightDriver(browser: Browser): CheckDriver {
31
87
  };
32
88
  }
33
89
 
34
- /** Where the check page is served from: a name no network has, answered by the driver. */
35
- export const CHECK_ORIGIN = "https://porthole-check.invalid";
36
-
37
- /** A Chrome DevTools Protocol session: its commands and its events (Puppeteer's `CDPSession`). */
90
+ /**
91
+ * A Chrome DevTools Protocol session: its commands and its events. The least the driver uses, so
92
+ * Puppeteer's `CDPSession` (`@cloudflare/puppeteer`'s too) and Playwright's fit as they are, with
93
+ * no cast (P074).
94
+ */
38
95
  export interface CdpSession {
39
96
  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
40
- on(
41
- event: "Fetch.requestPaused",
42
- listener: (params: { readonly requestId: string }) => void,
43
- ): unknown;
97
+ on(event: "Fetch.requestPaused", listener: (params: PausedRequest) => void): unknown;
98
+ }
99
+
100
+ /** What CDP says of a request it paused. */
101
+ interface PausedRequest {
102
+ readonly requestId: string;
103
+ readonly request?: {
104
+ readonly url: string;
105
+ readonly method: string;
106
+ readonly headers?: Readonly<Record<string, string>>;
107
+ readonly postData?: string;
108
+ };
44
109
  }
45
110
 
46
- const toBase64 = (text: string): string => {
111
+ const bytesToBase64 = (bytes: Uint8Array): string => {
47
112
  let binary = "";
48
- for (const byte of new TextEncoder().encode(text)) {
113
+ for (const byte of bytes) {
49
114
  binary += String.fromCharCode(byte);
50
115
  }
51
116
  return btoa(binary);
@@ -65,16 +130,42 @@ export function cdpDriver(open: () => Promise<CdpSession>): CheckDriver {
65
130
  const session = await open();
66
131
  await session.send("Page.enable");
67
132
  await session.send("Runtime.enable");
68
- let html = "";
69
- // The check page needs an origin of its own: the driver answers its address itself.
70
- await session.send("Fetch.enable", { patterns: [{ urlPattern: `${CHECK_ORIGIN}/*` }] });
71
- session.on("Fetch.requestPaused", (event: { requestId: string }) => {
72
- void session.send("Fetch.fulfillRequest", {
73
- requestId: event.requestId,
74
- responseCode: 200,
75
- responseHeaders: [{ name: "content-type", value: "text/html; charset=utf-8" }],
76
- body: toBase64(html),
77
- });
133
+ let handler: Handler = pageOnly("");
134
+ // The check's own names are answered here; everything else goes on.
135
+ await session.send("Fetch.enable", {
136
+ patterns: [
137
+ { urlPattern: `${CHECK_ORIGIN}/*` },
138
+ { urlPattern: `https://*.${CHECK_CONTENT_DOMAIN}/*` },
139
+ ],
140
+ });
141
+ session.on("Fetch.requestPaused", (event) => {
142
+ void (async () => {
143
+ const asked = event.request;
144
+ if (asked === undefined || !answered(new URL(asked.url))) {
145
+ await session.send("Fetch.continueRequest", { requestId: event.requestId });
146
+ return;
147
+ }
148
+ const body =
149
+ asked.method === "GET" || asked.method === "HEAD" ? null : (asked.postData ?? null);
150
+ const answer = await handler(
151
+ new Request(asked.url, {
152
+ method: asked.method,
153
+ headers: Object.entries(asked.headers ?? {}),
154
+ ...(body === null ? {} : { body }),
155
+ }),
156
+ );
157
+ await session.send("Fetch.fulfillRequest", {
158
+ requestId: event.requestId,
159
+ responseCode: answer.status,
160
+ responseHeaders: [
161
+ ...[...answer.headers]
162
+ .filter(([name]) => name !== "set-cookie")
163
+ .map(([name, value]) => ({ name, value })),
164
+ ...answer.headers.getSetCookie().map((value) => ({ name: "set-cookie", value })),
165
+ ],
166
+ body: bytesToBase64(new Uint8Array(await answer.arrayBuffer())),
167
+ });
168
+ })();
78
169
  });
79
170
  const evaluate = async <T>(expression: string): Promise<T> => {
80
171
  const answer = (await session.send("Runtime.evaluate", {
@@ -94,6 +185,20 @@ export function cdpDriver(open: () => Promise<CdpSession>): CheckDriver {
94
185
  }
95
186
  return answer.result?.value as T;
96
187
  };
188
+ const goto = async () => {
189
+ await session.send("Page.navigate", { url: `${CHECK_ORIGIN}/` });
190
+ // The page's script runs when it loads: wait until it says so.
191
+ for (let tries = 0; tries < 100; tries += 1) {
192
+ const ready = await evaluate<boolean>(
193
+ 'document.documentElement?.dataset.portholeCheck === "ready"',
194
+ ).catch(() => false);
195
+ if (ready) {
196
+ return;
197
+ }
198
+ await new Promise((resolve) => setTimeout(resolve, 50));
199
+ }
200
+ throw new Error("The check page didn't start");
201
+ };
97
202
  return {
98
203
  async setViewport(width, height) {
99
204
  await session.send("Emulation.setDeviceMetricsOverride", {
@@ -104,19 +209,12 @@ export function cdpDriver(open: () => Promise<CdpSession>): CheckDriver {
104
209
  });
105
210
  },
106
211
  async load(document) {
107
- html = document;
108
- await session.send("Page.navigate", { url: `${CHECK_ORIGIN}/` });
109
- // The page's script runs when it loads: wait until it says so.
110
- for (let tries = 0; tries < 100; tries += 1) {
111
- const ready = await evaluate<boolean>(
112
- 'document.documentElement?.dataset.portholeCheck === "ready"',
113
- ).catch(() => false);
114
- if (ready) {
115
- return;
116
- }
117
- await new Promise((resolve) => setTimeout(resolve, 50));
118
- }
119
- throw new Error("The check page didn't start");
212
+ handler = pageOnly(document);
213
+ await goto();
214
+ },
215
+ async serve(given) {
216
+ handler = given;
217
+ await goto();
120
218
  },
121
219
  evaluate,
122
220
  async screenshot(selector) {
@@ -5,11 +5,18 @@
5
5
  */
6
6
  export {
7
7
  checkPage,
8
+ type CheckCall,
8
9
  type CheckDriver,
9
10
  type CheckOptions,
10
11
  type CheckReport,
11
12
  type CheckRun,
12
13
  type CheckSession,
13
14
  } from "./check.ts";
14
- export { cdpDriver, playwrightDriver, type CdpSession } from "./drivers.ts";
15
+ export {
16
+ CHECK_CONTENT_DOMAIN,
17
+ CHECK_ORIGIN,
18
+ cdpDriver,
19
+ playwrightDriver,
20
+ type CdpSession,
21
+ } from "./drivers.ts";
15
22
  export { lintContent, type Finding, type LintRule } from "./lint.ts";