@botiverse/porthole 0.3.0 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -2
- package/dist/check/check.d.ts +20 -3
- package/dist/check/check.js +88 -25
- package/dist/check/drivers.d.ts +25 -6
- package/dist/check/drivers.js +99 -28
- package/dist/check/index.d.ts +2 -2
- package/dist/check/index.js +1 -1
- package/dist/check/instrument.d.ts +71 -0
- package/dist/check/instrument.js +84 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.d.ts +2 -40
- package/dist/check/page.js +63 -43
- package/dist/conformance/harness-source.d.ts +2 -0
- package/dist/conformance/harness-source.js +2 -0
- package/dist/conformance/host-kit.d.ts +20 -7
- package/dist/conformance/host-kit.js +42 -48
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/reporter.d.ts +14 -0
- package/dist/conformance/reporter.js +28 -0
- package/dist/host/client.d.ts +33 -15
- package/dist/host/client.js +39 -24
- package/dist/node/index.d.ts +6 -2
- package/dist/node/index.js +53 -8
- package/dist/react/frame.d.ts +13 -5
- package/dist/react/frame.js +67 -27
- package/dist/react/index.d.ts +1 -1
- package/dist/react/view.js +6 -1
- package/dist/server/host.d.ts +5 -3
- package/dist/server/host.js +41 -12
- package/docs/ADOPTING.md +115 -26
- package/docs/DECISIONS.md +167 -0
- package/docs/DESIGN.md +38 -13
- package/examples/app.mjs +23 -17
- package/examples/conformance/playwright.config.mjs +2 -1
- package/examples/conformance/porthole.spec.mjs +2 -1
- package/examples/displays.mjs +2 -0
- package/examples/node/server.mjs +16 -34
- package/examples/workers/worker.mjs +19 -7
- package/package.json +9 -3
- package/src/check/check.ts +122 -25
- package/src/check/drivers.ts +137 -39
- package/src/check/index.ts +8 -1
- package/src/check/instrument.ts +138 -0
- package/src/check/page-source.ts +4 -3
- package/src/check/page.ts +94 -68
- package/src/conformance/harness-source.ts +23 -0
- package/src/conformance/host-kit.ts +69 -46
- package/src/conformance/index.ts +1 -0
- package/src/conformance/reporter.ts +38 -0
- package/src/host/client.ts +65 -34
- package/src/node/index.ts +56 -10
- package/src/react/frame.tsx +89 -33
- package/src/react/index.ts +1 -0
- package/src/react/view.tsx +6 -1
- package/src/server/host.ts +53 -15
- package/dist/conformance/harness.js +0 -1662
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@ npm install @botiverse/porthole
|
|
|
9
9
|
```
|
|
10
10
|
|
|
11
11
|
Node 24 or later, or Cloudflare Workers. The browser part is plain ES modules with no
|
|
12
|
-
dependencies (bundle it, or serve `dist/`).
|
|
12
|
+
dependencies (bundle it, or serve `dist/` with an import map: docs/ADOPTING.md § 4).
|
|
13
13
|
|
|
14
14
|
## Two ways to show content
|
|
15
15
|
|
|
@@ -30,7 +30,8 @@ PORTHOLE_SECRET=$(npx porthole secret) node node_modules/@botiverse/porthole/exa
|
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
- `examples/app.mjs`: the app (policy, routes, page), runtime-agnostic.
|
|
33
|
-
- `examples/node/server.mjs
|
|
33
|
+
- `examples/node/server.mjs` (`nodeServer`), `examples/workers/` (`contentHostFor`, with its D1
|
|
34
|
+
migration and `wrangler.jsonc`).
|
|
34
35
|
- `examples/conformance/`: Porthole's conformance suite run against it, on three engines.
|
|
35
36
|
- `examples/mcp/server.mjs`: the agent's tools (show, guide, check) as an MCP server.
|
|
36
37
|
|
package/dist/check/check.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import { type Finding } from "./lint.ts";
|
|
3
|
+
import { type CheckCall } from "./instrument.ts";
|
|
4
|
+
export type { CheckCall } from "./instrument.ts";
|
|
3
5
|
/**
|
|
4
6
|
* Checks content before people see it (P073): runs it in the real sandbox at each width and
|
|
5
7
|
* scheme, through a driver (a browser the host has: Playwright, or any CDP session, Cloudflare
|
|
@@ -13,6 +15,12 @@ export interface CheckSession {
|
|
|
13
15
|
setViewport(width: number, height: number): Promise<void>;
|
|
14
16
|
/** Loads a whole HTML document into the page. */
|
|
15
17
|
load(html: string): Promise<void>;
|
|
18
|
+
/**
|
|
19
|
+
* Answers every request to the check page's origin and the check's content domain with
|
|
20
|
+
* `handler`, and opens the page (`/`): a served config's content then runs on an origin of its
|
|
21
|
+
* own, as people's browsers run it (P074). Without it, the check runs content opaque.
|
|
22
|
+
*/
|
|
23
|
+
serve?(handler: (request: Request) => Promise<Response>): Promise<void>;
|
|
16
24
|
/** Evaluates a JavaScript expression in the page (a promise is awaited); JSON back. */
|
|
17
25
|
evaluate<T>(expression: string): Promise<T>;
|
|
18
26
|
/** A PNG of the element `selector` names, where the driver can. */
|
|
@@ -44,8 +52,8 @@ export interface CheckOptions {
|
|
|
44
52
|
/** The most distinct problems `text` names (default 8): the rest are counted. */
|
|
45
53
|
readonly maxProblems?: number;
|
|
46
54
|
/**
|
|
47
|
-
* The check page's script
|
|
48
|
-
*
|
|
55
|
+
* The check page's script. Default: Porthole's own (`@botiverse/porthole/check/page`), imported
|
|
56
|
+
* with this module, so a bundle (a Worker, a single executable) has it too (P075).
|
|
49
57
|
*/
|
|
50
58
|
readonly page?: string;
|
|
51
59
|
}
|
|
@@ -70,10 +78,19 @@ export interface CheckRun {
|
|
|
70
78
|
readonly level: "error" | "warning";
|
|
71
79
|
readonly text: string;
|
|
72
80
|
}[];
|
|
81
|
+
/**
|
|
82
|
+
* The host functions it called (P074), each answered as a host that declines would. One a
|
|
83
|
+
* host's gates refuse whatever the person says (no click, bad arguments, not offered, too
|
|
84
|
+
* often) is a problem; one a person or host may decline is a note.
|
|
85
|
+
*/
|
|
86
|
+
readonly calls: readonly CheckCall[];
|
|
73
87
|
readonly screenshot?: Uint8Array;
|
|
74
88
|
}
|
|
75
89
|
export interface CheckReport {
|
|
76
|
-
/**
|
|
90
|
+
/**
|
|
91
|
+
* Nothing failed: no errors, blocks, failed loads, console errors, host-function calls a host
|
|
92
|
+
* refuses, overflow or cut, no lint error.
|
|
93
|
+
*/
|
|
77
94
|
readonly ok: boolean;
|
|
78
95
|
readonly lint: readonly Finding[];
|
|
79
96
|
readonly runs: readonly CheckRun[];
|
package/dist/check/check.js
CHANGED
|
@@ -1,17 +1,18 @@
|
|
|
1
|
-
var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
|
|
2
|
-
if (typeof path === "string" && /^\.\.?\//.test(path)) {
|
|
3
|
-
return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
|
|
4
|
-
return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
|
|
5
|
-
});
|
|
6
|
-
}
|
|
7
|
-
return path;
|
|
8
|
-
};
|
|
9
1
|
import { presets } from "../presets/presets.js";
|
|
2
|
+
import { createServer } from "../server/server.js";
|
|
3
|
+
import { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN } from "./drivers.js";
|
|
10
4
|
import { lintContent } from "./lint.js";
|
|
5
|
+
// The check page's script, imported as a module so a bundler takes it in (P075): no file is
|
|
6
|
+
// looked up beside this one at run time.
|
|
7
|
+
import PAGE_SCRIPT from "./page-source.js";
|
|
8
|
+
import { instrumented, namedScripts, } from "./instrument.js";
|
|
9
|
+
/** The content source the check's served origins match. */
|
|
10
|
+
const CHECK_SOURCE = `https://*.${CHECK_CONTENT_DOMAIN}`;
|
|
11
11
|
const noun = (config) => config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
|
|
12
12
|
/**
|
|
13
|
-
* The config the check runs content under
|
|
14
|
-
* same CSP); an MCP Apps view as a page with the view's
|
|
13
|
+
* The config the check runs content under where it can't serve it (a driver without `serve`):
|
|
14
|
+
* opaque (a served config's content with the same CSP); an MCP Apps view as a page with the view's
|
|
15
|
+
* egress (its protocol is its host's).
|
|
15
16
|
*/
|
|
16
17
|
function checkedAs(config) {
|
|
17
18
|
const opaque = config.isolation === "opaque" ? config : { ...config, isolation: "opaque", contentOrigins: [] };
|
|
@@ -19,16 +20,6 @@ function checkedAs(config) {
|
|
|
19
20
|
? presets.artifact({ egress: opaque.egress, limits: opaque.limits })
|
|
20
21
|
: opaque;
|
|
21
22
|
}
|
|
22
|
-
/** The check page's script: given, or (Node) the package's own. */
|
|
23
|
-
async function pageScript(given) {
|
|
24
|
-
if (given !== undefined) {
|
|
25
|
-
return given;
|
|
26
|
-
}
|
|
27
|
-
// Not a literal: a bundler for a Worker leaves it alone (a Worker passes `page`).
|
|
28
|
-
const where = new URL(import.meta.url.endsWith(".ts") ? "./page-source.ts" : "./page-source.js", import.meta.url).href;
|
|
29
|
-
const loaded = (await import(__rewriteRelativeImportExtension(where)));
|
|
30
|
-
return loaded.default;
|
|
31
|
-
}
|
|
32
23
|
const escapeScript = (code) => code.replace(/<\/script/giu, "<\\/script");
|
|
33
24
|
export async function checkPage(options) {
|
|
34
25
|
const { config } = options;
|
|
@@ -46,19 +37,66 @@ export async function checkPage(options) {
|
|
|
46
37
|
const schemes = options.schemes ?? (unthemed ? ["light"] : ["light", "dark"]);
|
|
47
38
|
const settle = options.settleMs ?? 1_500;
|
|
48
39
|
const fills = config.layout.kind === "fill";
|
|
49
|
-
const
|
|
50
|
-
const script = await pageScript(options.page);
|
|
40
|
+
const script = options.page ?? PAGE_SCRIPT;
|
|
51
41
|
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>`;
|
|
42
|
+
// Its inline scripts named, so an error says the line in the content as written (P074).
|
|
43
|
+
const { content, scriptLines } = namedScripts(options.content);
|
|
52
44
|
const session = await options.driver.open();
|
|
45
|
+
// A served config runs served, on a content origin the driver answers, under Porthole's own
|
|
46
|
+
// server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
|
|
47
|
+
const servedHere = config.isolation === "domain" && config.mode !== "mcp-app" && session.serve !== undefined;
|
|
48
|
+
const servedConfig = { ...config, contentOrigins: [CHECK_SOURCE] };
|
|
49
|
+
const server = servedHere
|
|
50
|
+
? createServer({
|
|
51
|
+
content: { domain: CHECK_CONTENT_DOMAIN, scheme: "https" },
|
|
52
|
+
secret: crypto.getRandomValues(new Uint8Array(32)),
|
|
53
|
+
hostOrigins: [CHECK_ORIGIN],
|
|
54
|
+
configs: { check: servedConfig },
|
|
55
|
+
artifacts: { get: () => Promise.resolve({ html: instrumented(content) }) },
|
|
56
|
+
})
|
|
57
|
+
: null;
|
|
58
|
+
const handler = async (request) => {
|
|
59
|
+
const url = new URL(request.url);
|
|
60
|
+
if (url.origin === CHECK_ORIGIN) {
|
|
61
|
+
if (url.pathname === "/") {
|
|
62
|
+
return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });
|
|
63
|
+
}
|
|
64
|
+
if (url.pathname === "/issue" && server !== null) {
|
|
65
|
+
const asked = (await request.json());
|
|
66
|
+
return Response.json(await server.issue(asked.instance, { viewer: "check" }));
|
|
67
|
+
}
|
|
68
|
+
return new Response("not found", { status: 404 });
|
|
69
|
+
}
|
|
70
|
+
return (await server?.handle(request)) ?? new Response("not found", { status: 404 });
|
|
71
|
+
};
|
|
72
|
+
const shown = servedHere ? servedConfig : checkedAs(config);
|
|
73
|
+
let runIndex = 0;
|
|
53
74
|
const runs = [];
|
|
54
75
|
try {
|
|
55
76
|
for (const width of widths) {
|
|
56
77
|
await session.setViewport(width + 40, fills ? 760 : 900);
|
|
57
|
-
|
|
78
|
+
if (servedHere && session.serve !== undefined) {
|
|
79
|
+
await session.serve(handler);
|
|
80
|
+
}
|
|
81
|
+
else {
|
|
82
|
+
await session.load(html);
|
|
83
|
+
}
|
|
58
84
|
for (const scheme of schemes) {
|
|
85
|
+
runIndex += 1;
|
|
86
|
+
// Each run on an origin of its own: its storage starts empty, as a new page's does.
|
|
87
|
+
const instance = servedHere
|
|
88
|
+
? {
|
|
89
|
+
scope: `check-${runIndex}`,
|
|
90
|
+
document: config.mode === "inline"
|
|
91
|
+
? { kind: "shell", preset: "check" }
|
|
92
|
+
: { kind: "artifact", id: "check", version: "1", preset: "check" },
|
|
93
|
+
}
|
|
94
|
+
: undefined;
|
|
59
95
|
const spec = {
|
|
60
96
|
config: shown,
|
|
61
|
-
content
|
|
97
|
+
content,
|
|
98
|
+
scriptLines,
|
|
99
|
+
...(instance === undefined ? {} : { instance }),
|
|
62
100
|
widthPx: width,
|
|
63
101
|
...(fills ? { heightPx: 700 } : {}),
|
|
64
102
|
scheme,
|
|
@@ -88,6 +126,7 @@ export async function checkPage(options) {
|
|
|
88
126
|
blocked: uniqueBy(data?.blocked ?? [], (each) => `${each.url} ${each.directive}`),
|
|
89
127
|
failedLoads: uniqueBy(data?.failedLoads ?? [], (each) => each.url),
|
|
90
128
|
console: uniqueBy(data?.console ?? [], (each) => `${each.level} ${each.text}`),
|
|
129
|
+
calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
|
|
91
130
|
...(screenshot === undefined ? {} : { screenshot }),
|
|
92
131
|
});
|
|
93
132
|
}
|
|
@@ -100,11 +139,20 @@ export async function checkPage(options) {
|
|
|
100
139
|
run.blocked.length > 0 ||
|
|
101
140
|
run.failedLoads.length > 0 ||
|
|
102
141
|
run.console.some((each) => each.level === "error") ||
|
|
142
|
+
run.calls.some((each) => REFUSED[each.outcome] !== undefined) ||
|
|
103
143
|
run.overflowX ||
|
|
104
144
|
run.clipped;
|
|
105
145
|
const ok = !lint.some((each) => each.severity === "error") && !runs.some(failed);
|
|
106
146
|
return { ok, lint, runs, text: summary(config, lint, runs, options.maxProblems ?? 8) };
|
|
107
147
|
}
|
|
148
|
+
/** Calls a host refuses whatever the person says: problems, worded for the agent. */
|
|
149
|
+
const REFUSED = {
|
|
150
|
+
"no-user-activation": (name) => `It called ${name} at load, with no click: hosts refuse that. Call ${name} from a click`,
|
|
151
|
+
invalid: (name) => `It called ${name} with arguments hosts refuse: see what the manual says ${name} takes`,
|
|
152
|
+
"not-declared": (name) => `It called ${name}, which this host doesn't offer: leave it out`,
|
|
153
|
+
"rate-limited": (name) => `It called ${name} more often than hosts allow, and was refused`,
|
|
154
|
+
"no-confirm": (name) => `It called ${name}, which this host can't confirm, and was refused`,
|
|
155
|
+
};
|
|
108
156
|
const unique = (values) => [...new Set(values)];
|
|
109
157
|
function uniqueBy(values, key) {
|
|
110
158
|
const seen = new Set();
|
|
@@ -130,7 +178,18 @@ function summary(config, lint, runs, most) {
|
|
|
130
178
|
list.push(`${run.width} px ${run.scheme}`);
|
|
131
179
|
where.set(problem, list);
|
|
132
180
|
};
|
|
181
|
+
// Calls a person or host may decline: the content should still work when they do.
|
|
182
|
+
const notes = new Set();
|
|
133
183
|
for (const run of runs) {
|
|
184
|
+
for (const call of run.calls) {
|
|
185
|
+
const refused = REFUSED[call.outcome];
|
|
186
|
+
if (refused === undefined) {
|
|
187
|
+
notes.add(`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.`);
|
|
188
|
+
}
|
|
189
|
+
else {
|
|
190
|
+
add(refused(call.capability), run);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
134
193
|
for (const error of run.errors) {
|
|
135
194
|
add(`It threw: ${clip(error)}`, run);
|
|
136
195
|
}
|
|
@@ -157,7 +216,10 @@ function summary(config, lint, runs, most) {
|
|
|
157
216
|
];
|
|
158
217
|
const ran = `${[...new Set(runs.map((run) => `${run.width} px`))].join(" and ")}, ${[...new Set(runs.map((run) => run.scheme))].join(" and ")}`;
|
|
159
218
|
if (lines.length === 0) {
|
|
160
|
-
return
|
|
219
|
+
return [
|
|
220
|
+
`OK: the ${it} ran at ${ran} with no errors, blocks, failed loads or overflow.`,
|
|
221
|
+
...notes,
|
|
222
|
+
].join("\n");
|
|
161
223
|
}
|
|
162
224
|
const shown = lines.slice(0, most);
|
|
163
225
|
const more = lines.length - shown.length;
|
|
@@ -165,5 +227,6 @@ function summary(config, lint, runs, most) {
|
|
|
165
227
|
`The ${it} has ${lines.length} problem${lines.length === 1 ? "" : "s"} (ran at ${ran}):`,
|
|
166
228
|
...shown.map((line) => `- ${line}`),
|
|
167
229
|
...(more > 0 ? [`- and ${more} more.`] : []),
|
|
230
|
+
...notes,
|
|
168
231
|
].join("\n");
|
|
169
232
|
}
|
package/dist/check/drivers.d.ts
CHANGED
|
@@ -4,17 +4,35 @@ import type { CheckDriver } from "./check.ts";
|
|
|
4
4
|
* Drivers for `checkPage` (P073): Playwright's browser on Node, or any Chrome DevTools Protocol
|
|
5
5
|
* session (Puppeteer's `page.createCDPSession()`, `@cloudflare/puppeteer` on Cloudflare Browser
|
|
6
6
|
* Rendering from a Worker).
|
|
7
|
+
*
|
|
8
|
+
* A driver answers two names no network has itself: the check page's origin (a host's), and a
|
|
9
|
+
* content domain, where a served config's content runs on an origin of its own as people's
|
|
10
|
+
* browsers run it (P074).
|
|
7
11
|
*/
|
|
12
|
+
/** Where the check page is served from. */
|
|
13
|
+
export declare const CHECK_ORIGIN = "https://porthole-check.invalid";
|
|
14
|
+
/** The content domain a served config's content runs under in the check: another site. */
|
|
15
|
+
export declare const CHECK_CONTENT_DOMAIN = "porthole-check-content.invalid";
|
|
8
16
|
/** Checks in a page of a Playwright browser (`chromium.launch()`), one page per check. */
|
|
9
17
|
export declare function playwrightDriver(browser: Browser): CheckDriver;
|
|
10
|
-
/**
|
|
11
|
-
|
|
12
|
-
|
|
18
|
+
/**
|
|
19
|
+
* A Chrome DevTools Protocol session: its commands and its events. The least the driver uses, so
|
|
20
|
+
* Puppeteer's `CDPSession` (`@cloudflare/puppeteer`'s too) and Playwright's fit as they are, with
|
|
21
|
+
* no cast (P074).
|
|
22
|
+
*/
|
|
13
23
|
export interface CdpSession {
|
|
14
24
|
send(method: string, params?: Record<string, unknown>): Promise<unknown>;
|
|
15
|
-
on(event: "Fetch.requestPaused", listener: (params:
|
|
16
|
-
|
|
17
|
-
|
|
25
|
+
on(event: "Fetch.requestPaused", listener: (params: PausedRequest) => void): unknown;
|
|
26
|
+
}
|
|
27
|
+
/** What CDP says of a request it paused. */
|
|
28
|
+
interface PausedRequest {
|
|
29
|
+
readonly requestId: string;
|
|
30
|
+
readonly request?: {
|
|
31
|
+
readonly url: string;
|
|
32
|
+
readonly method: string;
|
|
33
|
+
readonly headers?: Readonly<Record<string, string>>;
|
|
34
|
+
readonly postData?: string;
|
|
35
|
+
};
|
|
18
36
|
}
|
|
19
37
|
/**
|
|
20
38
|
* Checks over a CDP session to a page (P073): `cdpDriver(() => page.createCDPSession())` with
|
|
@@ -22,3 +40,4 @@ export interface CdpSession {
|
|
|
22
40
|
* asked for a session per check; the caller closes its page.
|
|
23
41
|
*/
|
|
24
42
|
export declare function cdpDriver(open: () => Promise<CdpSession>): CheckDriver;
|
|
43
|
+
export {};
|
package/dist/check/drivers.js
CHANGED
|
@@ -2,19 +2,62 @@
|
|
|
2
2
|
* Drivers for `checkPage` (P073): Playwright's browser on Node, or any Chrome DevTools Protocol
|
|
3
3
|
* session (Puppeteer's `page.createCDPSession()`, `@cloudflare/puppeteer` on Cloudflare Browser
|
|
4
4
|
* Rendering from a Worker).
|
|
5
|
+
*
|
|
6
|
+
* A driver answers two names no network has itself: the check page's origin (a host's), and a
|
|
7
|
+
* content domain, where a served config's content runs on an origin of its own as people's
|
|
8
|
+
* browsers run it (P074).
|
|
5
9
|
*/
|
|
10
|
+
/** Where the check page is served from. */
|
|
11
|
+
export const CHECK_ORIGIN = "https://porthole-check.invalid";
|
|
12
|
+
/** The content domain a served config's content runs under in the check: another site. */
|
|
13
|
+
export const CHECK_CONTENT_DOMAIN = "porthole-check-content.invalid";
|
|
14
|
+
const CHECK_HOST = new URL(CHECK_ORIGIN).hostname;
|
|
15
|
+
/** Whether the driver answers a URL itself. */
|
|
16
|
+
const answered = (url) => url.hostname === CHECK_HOST || url.hostname.endsWith(`.${CHECK_CONTENT_DOMAIN}`);
|
|
17
|
+
/** A page that answers the check's own names: `/` the given document, the rest 404. */
|
|
18
|
+
const pageOnly = (html) => (request) => Promise.resolve(new URL(request.url).hostname === CHECK_HOST && new URL(request.url).pathname === "/"
|
|
19
|
+
? new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } })
|
|
20
|
+
: new Response("not found", { status: 404 }));
|
|
6
21
|
/** Checks in a page of a Playwright browser (`chromium.launch()`), one page per check. */
|
|
7
22
|
export function playwrightDriver(browser) {
|
|
8
23
|
return {
|
|
9
24
|
async open() {
|
|
10
25
|
const page = await browser.newPage();
|
|
11
|
-
let
|
|
12
|
-
|
|
13
|
-
|
|
26
|
+
let handler = pageOnly("");
|
|
27
|
+
await page.route(answered, async (route) => {
|
|
28
|
+
const asked = route.request();
|
|
29
|
+
const headers = Object.entries(await asked.allHeaders()).filter(([name]) => !name.startsWith(":"));
|
|
30
|
+
const method = asked.method();
|
|
31
|
+
const body = method === "GET" || method === "HEAD" ? null : asked.postDataBuffer();
|
|
32
|
+
const answer = await handler(new Request(asked.url(), {
|
|
33
|
+
method,
|
|
34
|
+
headers,
|
|
35
|
+
...(body === null ? {} : { body: new Uint8Array(body) }),
|
|
36
|
+
}));
|
|
37
|
+
const out = {};
|
|
38
|
+
for (const [name, value] of answer.headers) {
|
|
39
|
+
if (name !== "set-cookie") {
|
|
40
|
+
out[name] = value;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
const cookies = answer.headers.getSetCookie();
|
|
44
|
+
if (cookies.length > 0) {
|
|
45
|
+
out["set-cookie"] = cookies.join("\n");
|
|
46
|
+
}
|
|
47
|
+
await route.fulfill({
|
|
48
|
+
status: answer.status,
|
|
49
|
+
headers: out,
|
|
50
|
+
body: Buffer.from(await answer.arrayBuffer()),
|
|
51
|
+
});
|
|
52
|
+
});
|
|
14
53
|
return {
|
|
15
54
|
setViewport: (width, height) => page.setViewportSize({ width, height }),
|
|
16
55
|
async load(document) {
|
|
17
|
-
|
|
56
|
+
handler = pageOnly(document);
|
|
57
|
+
await page.goto(`${CHECK_ORIGIN}/`, { waitUntil: "load" });
|
|
58
|
+
},
|
|
59
|
+
async serve(given) {
|
|
60
|
+
handler = given;
|
|
18
61
|
await page.goto(`${CHECK_ORIGIN}/`, { waitUntil: "load" });
|
|
19
62
|
},
|
|
20
63
|
evaluate: (expression) => page.evaluate(expression),
|
|
@@ -24,11 +67,9 @@ export function playwrightDriver(browser) {
|
|
|
24
67
|
},
|
|
25
68
|
};
|
|
26
69
|
}
|
|
27
|
-
|
|
28
|
-
export const CHECK_ORIGIN = "https://porthole-check.invalid";
|
|
29
|
-
const toBase64 = (text) => {
|
|
70
|
+
const bytesToBase64 = (bytes) => {
|
|
30
71
|
let binary = "";
|
|
31
|
-
for (const byte of
|
|
72
|
+
for (const byte of bytes) {
|
|
32
73
|
binary += String.fromCharCode(byte);
|
|
33
74
|
}
|
|
34
75
|
return btoa(binary);
|
|
@@ -45,16 +86,39 @@ export function cdpDriver(open) {
|
|
|
45
86
|
const session = await open();
|
|
46
87
|
await session.send("Page.enable");
|
|
47
88
|
await session.send("Runtime.enable");
|
|
48
|
-
let
|
|
49
|
-
// The check
|
|
50
|
-
await session.send("Fetch.enable", {
|
|
89
|
+
let handler = pageOnly("");
|
|
90
|
+
// The check's own names are answered here; everything else goes on.
|
|
91
|
+
await session.send("Fetch.enable", {
|
|
92
|
+
patterns: [
|
|
93
|
+
{ urlPattern: `${CHECK_ORIGIN}/*` },
|
|
94
|
+
{ urlPattern: `https://*.${CHECK_CONTENT_DOMAIN}/*` },
|
|
95
|
+
],
|
|
96
|
+
});
|
|
51
97
|
session.on("Fetch.requestPaused", (event) => {
|
|
52
|
-
void
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
98
|
+
void (async () => {
|
|
99
|
+
const asked = event.request;
|
|
100
|
+
if (asked === undefined || !answered(new URL(asked.url))) {
|
|
101
|
+
await session.send("Fetch.continueRequest", { requestId: event.requestId });
|
|
102
|
+
return;
|
|
103
|
+
}
|
|
104
|
+
const body = asked.method === "GET" || asked.method === "HEAD" ? null : (asked.postData ?? null);
|
|
105
|
+
const answer = await handler(new Request(asked.url, {
|
|
106
|
+
method: asked.method,
|
|
107
|
+
headers: Object.entries(asked.headers ?? {}),
|
|
108
|
+
...(body === null ? {} : { body }),
|
|
109
|
+
}));
|
|
110
|
+
await session.send("Fetch.fulfillRequest", {
|
|
111
|
+
requestId: event.requestId,
|
|
112
|
+
responseCode: answer.status,
|
|
113
|
+
responseHeaders: [
|
|
114
|
+
...[...answer.headers]
|
|
115
|
+
.filter(([name]) => name !== "set-cookie")
|
|
116
|
+
.map(([name, value]) => ({ name, value })),
|
|
117
|
+
...answer.headers.getSetCookie().map((value) => ({ name: "set-cookie", value })),
|
|
118
|
+
],
|
|
119
|
+
body: bytesToBase64(new Uint8Array(await answer.arrayBuffer())),
|
|
120
|
+
});
|
|
121
|
+
})();
|
|
58
122
|
});
|
|
59
123
|
const evaluate = async (expression) => {
|
|
60
124
|
const answer = (await session.send("Runtime.evaluate", {
|
|
@@ -69,6 +133,18 @@ export function cdpDriver(open) {
|
|
|
69
133
|
}
|
|
70
134
|
return answer.result?.value;
|
|
71
135
|
};
|
|
136
|
+
const goto = async () => {
|
|
137
|
+
await session.send("Page.navigate", { url: `${CHECK_ORIGIN}/` });
|
|
138
|
+
// The page's script runs when it loads: wait until it says so.
|
|
139
|
+
for (let tries = 0; tries < 100; tries += 1) {
|
|
140
|
+
const ready = await evaluate('document.documentElement?.dataset.portholeCheck === "ready"').catch(() => false);
|
|
141
|
+
if (ready) {
|
|
142
|
+
return;
|
|
143
|
+
}
|
|
144
|
+
await new Promise((resolve) => setTimeout(resolve, 50));
|
|
145
|
+
}
|
|
146
|
+
throw new Error("The check page didn't start");
|
|
147
|
+
};
|
|
72
148
|
return {
|
|
73
149
|
async setViewport(width, height) {
|
|
74
150
|
await session.send("Emulation.setDeviceMetricsOverride", {
|
|
@@ -79,17 +155,12 @@ export function cdpDriver(open) {
|
|
|
79
155
|
});
|
|
80
156
|
},
|
|
81
157
|
async load(document) {
|
|
82
|
-
|
|
83
|
-
await
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
return;
|
|
89
|
-
}
|
|
90
|
-
await new Promise((resolve) => setTimeout(resolve, 50));
|
|
91
|
-
}
|
|
92
|
-
throw new Error("The check page didn't start");
|
|
158
|
+
handler = pageOnly(document);
|
|
159
|
+
await goto();
|
|
160
|
+
},
|
|
161
|
+
async serve(given) {
|
|
162
|
+
handler = given;
|
|
163
|
+
await goto();
|
|
93
164
|
},
|
|
94
165
|
evaluate,
|
|
95
166
|
async screenshot(selector) {
|
package/dist/check/index.d.ts
CHANGED
|
@@ -3,6 +3,6 @@
|
|
|
3
3
|
* the real sandbox through a driver (`playwrightDriver`, `cdpDriver`); `lintContent` and the tool
|
|
4
4
|
* definitions are in the core (`@botiverse/porthole`), since they need no browser.
|
|
5
5
|
*/
|
|
6
|
-
export { checkPage, type CheckDriver, type CheckOptions, type CheckReport, type CheckRun, type CheckSession, } from "./check.ts";
|
|
7
|
-
export { cdpDriver, playwrightDriver, type CdpSession } from "./drivers.ts";
|
|
6
|
+
export { checkPage, type CheckCall, type CheckDriver, type CheckOptions, type CheckReport, type CheckRun, type CheckSession, } from "./check.ts";
|
|
7
|
+
export { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN, cdpDriver, playwrightDriver, type CdpSession, } from "./drivers.ts";
|
|
8
8
|
export { lintContent, type Finding, type LintRule } from "./lint.ts";
|
package/dist/check/index.js
CHANGED
|
@@ -4,5 +4,5 @@
|
|
|
4
4
|
* definitions are in the core (`@botiverse/porthole`), since they need no browser.
|
|
5
5
|
*/
|
|
6
6
|
export { checkPage, } from "./check.js";
|
|
7
|
-
export { cdpDriver, playwrightDriver } from "./drivers.js";
|
|
7
|
+
export { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN, cdpDriver, playwrightDriver, } from "./drivers.js";
|
|
8
8
|
export { lintContent } from "./lint.js";
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import type { InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
/**
|
|
4
|
+
* What the check puts in the content it runs (P073, P074): a small script first that reports
|
|
5
|
+
* what happens inside to the page that frames it, and a name on each inline script so an error
|
|
6
|
+
* says the line in the content as written. Pure: the check (any runtime) and its page both use it.
|
|
7
|
+
*/
|
|
8
|
+
export interface CheckRunSpec {
|
|
9
|
+
readonly config: PortholeConfig;
|
|
10
|
+
readonly content: string;
|
|
11
|
+
/** Where each inline script's text starts in the content as written (file lines), by index. */
|
|
12
|
+
readonly scriptLines: readonly number[];
|
|
13
|
+
/** A served config's instance (located through the check's own server), else opaque. */
|
|
14
|
+
readonly instance?: InstanceRef;
|
|
15
|
+
readonly widthPx: number;
|
|
16
|
+
readonly heightPx?: number;
|
|
17
|
+
readonly scheme: ColorScheme;
|
|
18
|
+
readonly hostTheme?: Readonly<Record<string, string>>;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* A host function the content called (P074): `answered` where the call reached the check's stub
|
|
22
|
+
* (which answers no, as a declining host would), else the refusal a host's gates gave it
|
|
23
|
+
* (`no-user-activation` for a call on load, `declined` where a person was asked).
|
|
24
|
+
*/
|
|
25
|
+
export interface CheckCall {
|
|
26
|
+
readonly capability: string;
|
|
27
|
+
readonly outcome: string;
|
|
28
|
+
}
|
|
29
|
+
export interface CheckRunData {
|
|
30
|
+
readonly errors: string[];
|
|
31
|
+
readonly calls: CheckCall[];
|
|
32
|
+
readonly blocked: {
|
|
33
|
+
readonly url: string;
|
|
34
|
+
readonly directive: string;
|
|
35
|
+
}[];
|
|
36
|
+
readonly failedLoads: {
|
|
37
|
+
readonly url: string;
|
|
38
|
+
readonly tag: string;
|
|
39
|
+
}[];
|
|
40
|
+
readonly console: {
|
|
41
|
+
readonly level: "error" | "warning";
|
|
42
|
+
readonly text: string;
|
|
43
|
+
}[];
|
|
44
|
+
readonly height: number | null;
|
|
45
|
+
readonly scrollWidth: number | null;
|
|
46
|
+
readonly clientWidth: number | null;
|
|
47
|
+
readonly outcome: string | null;
|
|
48
|
+
}
|
|
49
|
+
/** Each inline script's name (`//# sourceURL`): its index in the content. */
|
|
50
|
+
export declare const SCRIPT_NAME = "porthole-script-";
|
|
51
|
+
/** Put first in the content: it reports to the page that frames it. */
|
|
52
|
+
export declare const INSTRUMENT = "<script>(() => {\n const send = (kind, data) => { try { parent.postMessage({ portholeCheck: kind, data }, \"*\"); } catch (_) {} };\n const text = (value) => { try { return String(value && value.stack ? value.message || value : value); } catch (_) { return \"?\"; } };\n for (const [method, level] of [[\"error\", \"error\"], [\"warn\", \"warning\"]]) {\n const original = console[method];\n console[method] = (...args) => { send(\"console\", { level, text: args.map(text).join(\" \").slice(0, 400) }); return original.apply(console, args); };\n }\n addEventListener(\"error\", (event) => {\n const target = event.target;\n if (target && target !== window && (target.src || target.href)) {\n send(\"load\", { url: String(target.src || target.href).slice(0, 400), tag: String(target.tagName || \"\").toLowerCase() });\n } else if (event.message || event.error) {\n const error = event.error;\n send(\"error\", {\n message: (error && error.message ? (error.name || \"Error\") + \": \" + error.message : String(event.message)).slice(0, 400),\n file: String(event.filename || \"\"),\n line: event.lineno || 0,\n stack: error && error.stack ? String(error.stack).slice(0, 1000) : \"\",\n });\n }\n }, true);\n addEventListener(\"unhandledrejection\", (event) => send(\"error\", {\n message: (\"Unhandled rejection: \" + text(event.reason)).slice(0, 400),\n file: \"\", line: 0,\n stack: event.reason && event.reason.stack ? String(event.reason.stack).slice(0, 1000) : \"\",\n }));\n addEventListener(\"securitypolicyviolation\", (event) => send(\"blocked\", { url: String(event.blockedURI || \"inline\").slice(0, 400), directive: String(event.effectiveDirective) }));\n addEventListener(\"message\", (event) => {\n if (event.source === parent && event.data && event.data.portholeCheck === \"measure\") {\n const root = document.documentElement;\n send(\"measure\", { scrollWidth: Math.max(root.scrollWidth, document.body ? document.body.scrollWidth : 0), clientWidth: root.clientWidth });\n }\n });\n})();</script>";
|
|
53
|
+
/** The content with the instrument first: after a document's <head>, or before a fragment. */
|
|
54
|
+
export declare function instrumented(content: string): string;
|
|
55
|
+
/**
|
|
56
|
+
* The content with each inline script named (`//# sourceURL=porthole-script-<n>`, after its
|
|
57
|
+
* last line, so no line moves), and where each one's text starts in the content as written.
|
|
58
|
+
*/
|
|
59
|
+
export declare function namedScripts(content: string): {
|
|
60
|
+
content: string;
|
|
61
|
+
scriptLines: number[];
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* An error's line in the content as written: from its script's name (the event's file, or its
|
|
65
|
+
* stack's first frame there) and its line in that script; null where it can't be told.
|
|
66
|
+
*/
|
|
67
|
+
export declare function contentLine(error: {
|
|
68
|
+
readonly file: string;
|
|
69
|
+
readonly line: number;
|
|
70
|
+
readonly stack: string;
|
|
71
|
+
}, scriptLines: readonly number[]): number | null;
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/** Each inline script's name (`//# sourceURL`): its index in the content. */
|
|
2
|
+
export const SCRIPT_NAME = "porthole-script-";
|
|
3
|
+
/** Put first in the content: it reports to the page that frames it. */
|
|
4
|
+
export const INSTRUMENT = `<script>(() => {
|
|
5
|
+
const send = (kind, data) => { try { parent.postMessage({ portholeCheck: kind, data }, "*"); } catch (_) {} };
|
|
6
|
+
const text = (value) => { try { return String(value && value.stack ? value.message || value : value); } catch (_) { return "?"; } };
|
|
7
|
+
for (const [method, level] of [["error", "error"], ["warn", "warning"]]) {
|
|
8
|
+
const original = console[method];
|
|
9
|
+
console[method] = (...args) => { send("console", { level, text: args.map(text).join(" ").slice(0, 400) }); return original.apply(console, args); };
|
|
10
|
+
}
|
|
11
|
+
addEventListener("error", (event) => {
|
|
12
|
+
const target = event.target;
|
|
13
|
+
if (target && target !== window && (target.src || target.href)) {
|
|
14
|
+
send("load", { url: String(target.src || target.href).slice(0, 400), tag: String(target.tagName || "").toLowerCase() });
|
|
15
|
+
} else if (event.message || event.error) {
|
|
16
|
+
const error = event.error;
|
|
17
|
+
send("error", {
|
|
18
|
+
message: (error && error.message ? (error.name || "Error") + ": " + error.message : String(event.message)).slice(0, 400),
|
|
19
|
+
file: String(event.filename || ""),
|
|
20
|
+
line: event.lineno || 0,
|
|
21
|
+
stack: error && error.stack ? String(error.stack).slice(0, 1000) : "",
|
|
22
|
+
});
|
|
23
|
+
}
|
|
24
|
+
}, true);
|
|
25
|
+
addEventListener("unhandledrejection", (event) => send("error", {
|
|
26
|
+
message: ("Unhandled rejection: " + text(event.reason)).slice(0, 400),
|
|
27
|
+
file: "", line: 0,
|
|
28
|
+
stack: event.reason && event.reason.stack ? String(event.reason.stack).slice(0, 1000) : "",
|
|
29
|
+
}));
|
|
30
|
+
addEventListener("securitypolicyviolation", (event) => send("blocked", { url: String(event.blockedURI || "inline").slice(0, 400), directive: String(event.effectiveDirective) }));
|
|
31
|
+
addEventListener("message", (event) => {
|
|
32
|
+
if (event.source === parent && event.data && event.data.portholeCheck === "measure") {
|
|
33
|
+
const root = document.documentElement;
|
|
34
|
+
send("measure", { scrollWidth: Math.max(root.scrollWidth, document.body ? document.body.scrollWidth : 0), clientWidth: root.clientWidth });
|
|
35
|
+
}
|
|
36
|
+
});
|
|
37
|
+
})();</script>`;
|
|
38
|
+
/** The content with the instrument first: after a document's <head>, or before a fragment. */
|
|
39
|
+
export function instrumented(content) {
|
|
40
|
+
const head = /<head[^>]*>/iu.exec(content);
|
|
41
|
+
if (head !== null) {
|
|
42
|
+
const at = head.index + head[0].length;
|
|
43
|
+
return `${content.slice(0, at)}${INSTRUMENT}${content.slice(at)}`;
|
|
44
|
+
}
|
|
45
|
+
const html = /<html[^>]*>/iu.exec(content);
|
|
46
|
+
if (html !== null) {
|
|
47
|
+
const at = html.index + html[0].length;
|
|
48
|
+
return `${content.slice(0, at)}<head>${INSTRUMENT}</head>${content.slice(at)}`;
|
|
49
|
+
}
|
|
50
|
+
return /^\s*<!doctype/iu.test(content)
|
|
51
|
+
? content.replace(/^(\s*<!doctype[^>]*>)/iu, `$1${INSTRUMENT}`)
|
|
52
|
+
: `${INSTRUMENT}${content}`;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* The content with each inline script named (`//# sourceURL=porthole-script-<n>`, after its
|
|
56
|
+
* last line, so no line moves), and where each one's text starts in the content as written.
|
|
57
|
+
*/
|
|
58
|
+
export function namedScripts(content) {
|
|
59
|
+
const scriptLines = [];
|
|
60
|
+
const named = content.replace(/(<script\b(?![^>]*\bsrc\s*=)[^>]*>)([\s\S]*?)(<\/script>)/giu, (whole, open, body, close, offset) => {
|
|
61
|
+
const index = scriptLines.length;
|
|
62
|
+
scriptLines.push(content.slice(0, offset + open.length).split("\n").length);
|
|
63
|
+
return `${open}${body}\n//# sourceURL=${SCRIPT_NAME}${index}\n${close}`;
|
|
64
|
+
});
|
|
65
|
+
return { content: named, scriptLines };
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* An error's line in the content as written: from its script's name (the event's file, or its
|
|
69
|
+
* stack's first frame there) and its line in that script; null where it can't be told.
|
|
70
|
+
*/
|
|
71
|
+
export function contentLine(error, scriptLines) {
|
|
72
|
+
const named = new RegExp(`${SCRIPT_NAME}(\\d+)(?::(\\d+))?`, "u");
|
|
73
|
+
const fromFile = named.exec(error.file);
|
|
74
|
+
if (fromFile?.[1] !== undefined && error.line > 0) {
|
|
75
|
+
const start = scriptLines[Number(fromFile[1])];
|
|
76
|
+
return start === undefined ? null : start + error.line - 1;
|
|
77
|
+
}
|
|
78
|
+
const fromStack = named.exec(error.stack);
|
|
79
|
+
if (fromStack?.[1] !== undefined && fromStack[2] !== undefined) {
|
|
80
|
+
const start = scriptLines[Number(fromStack[1])];
|
|
81
|
+
return start === undefined ? null : start + Number(fromStack[2]) - 1;
|
|
82
|
+
}
|
|
83
|
+
return null;
|
|
84
|
+
}
|