@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.
- package/README.md +3 -2
- package/dist/check/check.d.ts +18 -1
- package/dist/check/check.js +84 -6
- 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/host-kit.d.ts +18 -5
- package/dist/conformance/host-kit.js +38 -21
- 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 +108 -25
- package/docs/DECISIONS.md +134 -0
- package/docs/DESIGN.md +36 -12
- 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 +5 -1
- package/src/check/check.ts +116 -8
- 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.ts +94 -68
- package/src/conformance/host-kit.ts +65 -19
- 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/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.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": {
|
package/src/check/check.ts
CHANGED
|
@@ -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
|
|
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
|
-
/**
|
|
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
|
|
88
|
-
* same CSP); an MCP Apps view as a page with the view'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
|
-
|
|
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
|
|
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
|
|
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
|
}
|
package/src/check/drivers.ts
CHANGED
|
@@ -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
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
|
111
|
+
const bytesToBase64 = (bytes: Uint8Array): string => {
|
|
47
112
|
let binary = "";
|
|
48
|
-
for (const byte of
|
|
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
|
|
69
|
-
// The check
|
|
70
|
-
await session.send("Fetch.enable", {
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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
|
-
|
|
108
|
-
await
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
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) {
|
package/src/check/index.ts
CHANGED
|
@@ -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 {
|
|
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";
|