@botiverse/porthole 0.2.2 → 0.2.3
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 +83 -0
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +51 -0
- package/dist/conformance/entry.d.ts +12 -6
- package/dist/conformance/entry.js +17 -5
- package/dist/conformance/harness.js +8 -8
- package/dist/conformance/host-kit.d.ts +43 -13
- package/dist/conformance/host-kit.js +83 -6
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/index.js +1 -1
- package/dist/conformance/limits.js +15 -2
- package/dist/conformance/page.d.ts +6 -0
- package/dist/conformance/page.js +8 -0
- package/dist/host/types.d.ts +6 -3
- package/dist/isolation/served.js +13 -2
- package/dist/react/frame.d.ts +5 -2
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +2 -0
- package/docs/DECISIONS.md +37 -0
- package/docs/DESIGN.md +13 -6
- package/examples/app.mjs +234 -0
- package/examples/conformance/playwright.config.mjs +28 -0
- package/examples/conformance/porthole.spec.mjs +36 -0
- package/examples/node/server.mjs +75 -0
- package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
- package/examples/workers/worker.mjs +33 -0
- package/examples/workers/wrangler.jsonc +19 -0
- package/package.json +7 -2
- package/src/cli.ts +54 -0
- package/src/conformance/entry.ts +33 -11
- package/src/conformance/host-kit.ts +127 -21
- package/src/conformance/index.ts +4 -0
- package/src/conformance/limits.ts +21 -4
- package/src/conformance/page.ts +8 -0
- package/src/host/types.ts +6 -3
- package/src/isolation/served.ts +12 -2
- package/src/react/frame.tsx +5 -2
- package/src/server/index.ts +2 -0
|
@@ -5,6 +5,7 @@ import { expect, type Frame, type Page, type TestInfo, type TestType } from "@pl
|
|
|
5
5
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
6
6
|
import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
|
|
7
7
|
import { entryTests, type EntryConformanceHost } from "./entry.ts";
|
|
8
|
+
export { conformancePage } from "./page.ts";
|
|
8
9
|
import type { ConformanceHarness } from "./harness/page.ts";
|
|
9
10
|
import type { FrameOutcome } from "../host/types.ts";
|
|
10
11
|
import type { ConformanceHost, LaunchedDisplay, LaunchSpec } from "./index.ts";
|
|
@@ -45,12 +46,16 @@ export interface HostConformanceOptions {
|
|
|
45
46
|
/** The config a served instance is framed under (the app's served config for its preset). */
|
|
46
47
|
readonly config: (instance: InstanceRef) => PortholeConfig;
|
|
47
48
|
/**
|
|
48
|
-
* The instances the served cases ask for, each for the scope a case names
|
|
49
|
-
*
|
|
50
|
-
*
|
|
49
|
+
* The instances the served cases ask for, each for the scope a case names (may be async: a
|
|
50
|
+
* page published on demand, `onDemand`). Give what the app serves; the cases for the rest are
|
|
51
|
+
* skipped, each with its reason:
|
|
52
|
+
* - `shell`: a served shell (domain mode). An app that serves only stored pages leaves it out:
|
|
53
|
+
* the domain-mode cases then run on `artifact(scope, "1")`;
|
|
54
|
+
* - `artifact(scope, version)`: versions "1" and "2" of one stored page on `scope`'s origin,
|
|
55
|
+
* each exactly `conformancePage(version)`;
|
|
56
|
+
* - `app`: a url-mode app; `proxy`: the MCP Apps sandbox proxy.
|
|
51
57
|
*/
|
|
52
|
-
readonly instances: Pick<ServedConformanceHost, "shell"
|
|
53
|
-
Partial<Pick<ServedConformanceHost, "artifact" | "app" | "proxy">>;
|
|
58
|
+
readonly instances: Partial<Pick<ServedConformanceHost, "shell" | "artifact" | "app" | "proxy">>;
|
|
54
59
|
/**
|
|
55
60
|
* Redirect entry (P068), where the app serves clean addresses: the cases open them directly,
|
|
56
61
|
* signed in and out, and in a frame.
|
|
@@ -61,14 +66,20 @@ export interface HostConformanceOptions {
|
|
|
61
66
|
* on demand.
|
|
62
67
|
*/
|
|
63
68
|
readonly url: (scope: string) => string | Promise<string>;
|
|
64
|
-
/** A clean address the signed-in viewer may not open. */
|
|
65
|
-
readonly denied
|
|
66
|
-
/**
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
69
|
+
/** A clean address the signed-in viewer may not open. Absent: that case is skipped. */
|
|
70
|
+
readonly denied?: (scope: string) => string | Promise<string>;
|
|
71
|
+
/**
|
|
72
|
+
* Whether `page` shows the app's own sign-in. Absent: the browser left the content origin and
|
|
73
|
+
* shows no content.
|
|
74
|
+
*/
|
|
75
|
+
readonly atSignIn?: (page: Page) => Promise<boolean>;
|
|
76
|
+
/** On the app's sign-in page: signs in, as a person does. Absent: the case stops there. */
|
|
77
|
+
readonly completeSignIn?: (page: Page) => Promise<void>;
|
|
78
|
+
/**
|
|
79
|
+
* Addresses on the content domain that name nothing: each a 404 there (P070). `"derive"`:
|
|
80
|
+
* `www`, the bare domain and a label no naming makes, under the domain of `url`'s address.
|
|
81
|
+
*/
|
|
82
|
+
readonly unknown?: "derive" | (() => readonly string[] | Promise<readonly string[]>);
|
|
72
83
|
};
|
|
73
84
|
/** Case ids to skip, each with its reason (shown in the report). */
|
|
74
85
|
readonly skip?: Readonly<Record<string, string>>;
|
|
@@ -320,7 +331,12 @@ export function hostConformance(options: HostConformanceOptions): HostConformanc
|
|
|
320
331
|
},
|
|
321
332
|
canary: (name) => Promise.resolve(`${CANARY}/${name}`),
|
|
322
333
|
canaryHits: (name) => Promise.resolve(hits.get(name) ?? 0),
|
|
323
|
-
|
|
334
|
+
// An app that serves only stored pages: the domain-mode cases on its page's first version.
|
|
335
|
+
shell:
|
|
336
|
+
options.instances.shell ??
|
|
337
|
+
(artifact === undefined
|
|
338
|
+
? (scope) => ({ scope, document: { kind: "shell", preset: "inlineWidget" } })
|
|
339
|
+
: (scope) => artifact(scope, "1")),
|
|
324
340
|
// Asked for only by cases that run where the app gave them (`defineHostConformance` skips).
|
|
325
341
|
artifact:
|
|
326
342
|
artifact ??
|
|
@@ -335,16 +351,23 @@ export function hostConformance(options: HostConformanceOptions): HostConformanc
|
|
|
335
351
|
? null
|
|
336
352
|
: {
|
|
337
353
|
name: options.name,
|
|
354
|
+
url: given.url,
|
|
338
355
|
// Signed in on the app's page, the harness there (a frame needs it).
|
|
339
356
|
signIn: async (page) => {
|
|
340
357
|
await open(page);
|
|
341
358
|
await ready(page);
|
|
342
359
|
},
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
360
|
+
...(given.denied === undefined ? {} : { denied: given.denied }),
|
|
361
|
+
...(given.atSignIn === undefined ? {} : { atSignIn: given.atSignIn }),
|
|
362
|
+
...(given.completeSignIn === undefined ? {} : { completeSignIn: given.completeSignIn }),
|
|
363
|
+
...(given.unknown === undefined
|
|
364
|
+
? {}
|
|
365
|
+
: {
|
|
366
|
+
unknown:
|
|
367
|
+
given.unknown === "derive"
|
|
368
|
+
? async () => derivedUnknown(await given.url("entry-unknown"))
|
|
369
|
+
: given.unknown,
|
|
370
|
+
}),
|
|
348
371
|
async frame(page, url) {
|
|
349
372
|
await ready(page);
|
|
350
373
|
const instance = await served.artifact("entry", "1");
|
|
@@ -415,14 +438,91 @@ const URL_CASES = [
|
|
|
415
438
|
"served.url.framed",
|
|
416
439
|
];
|
|
417
440
|
const PROXY_CASES = ["served.proxy.view", "served.proxy.parent-only", "served.proxy.egress"];
|
|
441
|
+
const DOMAIN_CASES = [
|
|
442
|
+
"served.domain.origin",
|
|
443
|
+
"served.domain.no-reach",
|
|
444
|
+
"served.domain.no-top-navigation",
|
|
445
|
+
"served.domain.no-popups",
|
|
446
|
+
"served.domain.address",
|
|
447
|
+
"served.domain.storage-scope",
|
|
448
|
+
"served.domain.ticket-once",
|
|
449
|
+
"served.domain.frame-ancestors",
|
|
450
|
+
"served.domain.egress",
|
|
451
|
+
];
|
|
452
|
+
|
|
453
|
+
/**
|
|
454
|
+
* Addresses that name nothing, under the content domain of a clean address: `www`, the bare
|
|
455
|
+
* domain, and a label no naming makes (P071).
|
|
456
|
+
*/
|
|
457
|
+
function derivedUnknown(clean: string): string[] {
|
|
458
|
+
const url = new URL(clean);
|
|
459
|
+
const domain = url.hostname.split(".").slice(1).join(".");
|
|
460
|
+
const port = url.port === "" ? "" : `:${url.port}`;
|
|
461
|
+
return ["www.", "", "zz-porthole-nothing."].map(
|
|
462
|
+
(label) => `${url.protocol}//${label}${domain}${port}/`,
|
|
463
|
+
);
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
/**
|
|
467
|
+
* A memo for fixtures made on demand (a page published the first time a case asks for it): one
|
|
468
|
+
* promise per key, per worker (P071).
|
|
469
|
+
*/
|
|
470
|
+
export function onDemand<V>(make: (key: string) => Promise<V>): (key: string) => Promise<V> {
|
|
471
|
+
const made = new Map<string, Promise<V>>();
|
|
472
|
+
return (key) => {
|
|
473
|
+
let found = made.get(key);
|
|
474
|
+
if (found === undefined) {
|
|
475
|
+
found = make(key);
|
|
476
|
+
made.set(key, found);
|
|
477
|
+
// A failure is tried again by the next case, not remembered.
|
|
478
|
+
found.catch(() => made.delete(key));
|
|
479
|
+
}
|
|
480
|
+
return found;
|
|
481
|
+
};
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
/** One Playwright project per engine Porthole supports, as Porthole's own suites run them. */
|
|
485
|
+
export interface ConformanceProject {
|
|
486
|
+
readonly name: "chromium" | "webkit" | "firefox";
|
|
487
|
+
readonly use: Record<string, unknown>;
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
/**
|
|
491
|
+
* The Playwright projects to run the suite on: Chromium, WebKit and Firefox, Firefox with the
|
|
492
|
+
* preferences its WebRTC probe needs (loopback ICE). Pass `devices` from `@playwright/test`
|
|
493
|
+
* (P071).
|
|
494
|
+
*/
|
|
495
|
+
export function conformanceProjects(
|
|
496
|
+
devices: Readonly<Record<string, Record<string, unknown>>>,
|
|
497
|
+
options: { readonly engines?: readonly ("chromium" | "webkit" | "firefox")[] } = {},
|
|
498
|
+
): ConformanceProject[] {
|
|
499
|
+
const all: ConformanceProject[] = [
|
|
500
|
+
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
|
|
501
|
+
{ name: "webkit", use: { ...devices["Desktop Safari"] } },
|
|
502
|
+
{
|
|
503
|
+
name: "firefox",
|
|
504
|
+
use: {
|
|
505
|
+
...devices["Desktop Firefox"],
|
|
506
|
+
launchOptions: {
|
|
507
|
+
firefoxUserPrefs: {
|
|
508
|
+
"media.peerconnection.ice.loopback": true,
|
|
509
|
+
"media.peerconnection.ice.obfuscate_host_addresses": false,
|
|
510
|
+
},
|
|
511
|
+
},
|
|
512
|
+
},
|
|
513
|
+
},
|
|
514
|
+
];
|
|
515
|
+
const engines = options.engines ?? ["chromium", "webkit", "firefox"];
|
|
516
|
+
return all.filter((project) => engines.includes(project.name));
|
|
517
|
+
}
|
|
418
518
|
|
|
419
519
|
/**
|
|
420
520
|
* Registers the leak and served suites against an app's real page, in a spec file of the app's
|
|
421
521
|
* (so `-g "\[1\.connect\]"` selects one). The served cases for instances the app didn't give are
|
|
422
522
|
* skipped, each with its reason.
|
|
423
523
|
*/
|
|
424
|
-
export function defineHostConformance(
|
|
425
|
-
test: TestType<
|
|
524
|
+
export function defineHostConformance<T extends object, W extends object>(
|
|
525
|
+
test: TestType<T, W>,
|
|
426
526
|
options: HostConformanceOptions,
|
|
427
527
|
): void {
|
|
428
528
|
const typed = test as unknown as TestType<ConformanceFixtures, object>;
|
|
@@ -436,6 +536,12 @@ export function defineHostConformance(
|
|
|
436
536
|
if (options.instances.artifact === undefined) {
|
|
437
537
|
absent(["served.artifact.versions"], "the app serves no versions of a stored page");
|
|
438
538
|
}
|
|
539
|
+
if (options.instances.shell === undefined && options.instances.artifact === undefined) {
|
|
540
|
+
absent(
|
|
541
|
+
DOMAIN_CASES,
|
|
542
|
+
"the app serves no documents on content origins (instances.shell or .artifact)",
|
|
543
|
+
);
|
|
544
|
+
}
|
|
439
545
|
if (options.instances.app === undefined) {
|
|
440
546
|
absent(URL_CASES, "the app serves no url-mode apps");
|
|
441
547
|
}
|
package/src/conformance/index.ts
CHANGED
|
@@ -122,9 +122,13 @@ export { entryTests, type EntryConformanceHost, type EntrySuiteOptions } from ".
|
|
|
122
122
|
|
|
123
123
|
// The runner an app points at its real page and issue endpoint (P066).
|
|
124
124
|
export {
|
|
125
|
+
conformancePage,
|
|
126
|
+
conformanceProjects,
|
|
125
127
|
defineHostConformance,
|
|
126
128
|
harnessScript,
|
|
127
129
|
hostConformance,
|
|
130
|
+
onDemand,
|
|
131
|
+
type ConformanceProject,
|
|
128
132
|
type HostConformance,
|
|
129
133
|
type HostConformanceOptions,
|
|
130
134
|
} from "./host-kit.ts";
|
|
@@ -54,6 +54,9 @@ const SILENCE =
|
|
|
54
54
|
|
|
55
55
|
const RECORDER = "<script>window.r = {};</script>";
|
|
56
56
|
|
|
57
|
+
/** A one-pixel GIF, inline. */
|
|
58
|
+
const PIXEL = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
|
|
59
|
+
|
|
57
60
|
export const LIMIT_PROBES: readonly Probe[] = [
|
|
58
61
|
{
|
|
59
62
|
id: "14.fill",
|
|
@@ -205,20 +208,34 @@ export const LIMIT_PROBES: readonly Probe[] = [
|
|
|
205
208
|
title: "assets inline as data: URLs and CSS in a <style> work where nothing outside is open",
|
|
206
209
|
async run(context) {
|
|
207
210
|
const canary = await context.http();
|
|
208
|
-
const pixel =
|
|
209
|
-
"data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
|
|
210
211
|
const display = await context.launch({
|
|
211
212
|
config: inline(),
|
|
212
213
|
content: attack(
|
|
213
214
|
`
|
|
214
215
|
const image = document.getElementById("inline");
|
|
215
216
|
r.inline = await new Promise((resolve) => { if (image.complete && image.naturalWidth > 0) resolve("loaded"); image.addEventListener("load", () => resolve("loaded")); image.addEventListener("error", () => resolve("failed")); setTimeout(() => resolve("pending"), 3000); });
|
|
216
|
-
r.styled = getComputedStyle(document.getElementById("styled")).width
|
|
217
|
-
|
|
217
|
+
r.styled = getComputedStyle(document.getElementById("styled")).width;
|
|
218
|
+
if (r.inline !== "loaded") {
|
|
219
|
+
r.dataBlocked = await inheritedBlocks("data", () => { new Image().src = ${js(PIXEL)}; });
|
|
220
|
+
}
|
|
221
|
+
if (r.styled !== "37px") {
|
|
222
|
+
r.styleBlocked = await inheritedBlocks("inline", () => { const style = document.createElement("style"); style.textContent = "#styled { width: 38px }"; document.head.append(style); });
|
|
223
|
+
}`,
|
|
224
|
+
`<style>#styled { width: 37px }</style><div id="styled"></div><img id="inline" src="${PIXEL}"><img src="${canary.origin}/outside.png">`,
|
|
218
225
|
),
|
|
219
226
|
});
|
|
220
227
|
const verdict = await context.result(display);
|
|
221
228
|
await settle();
|
|
229
|
+
// The frame's own policy allows data: images and inline styles: a block of either is the
|
|
230
|
+
// page's own CSP, which an opaque frame inherits (P058, P071).
|
|
231
|
+
if (
|
|
232
|
+
(verdict.inline !== "loaded" && verdict.dataBlocked === true) ||
|
|
233
|
+
(verdict.styled !== "37px" && verdict.styleBlocked === true)
|
|
234
|
+
) {
|
|
235
|
+
context.inapplicable(
|
|
236
|
+
"the page's own CSP, which an opaque frame inherits, blocks data: images or inline styles (img-src, style-src): opaque content here can't inline its assets, whatever its config",
|
|
237
|
+
);
|
|
238
|
+
}
|
|
222
239
|
expect(verdict).toMatchObject({ inline: "loaded", styled: "37px" });
|
|
223
240
|
expect(canary.requests()).toEqual([]);
|
|
224
241
|
},
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The stored page the served and entry cases ask for, version "1" or "2": what an app's
|
|
3
|
+
* `instances.artifact(scope, version)` must serve, exactly (P071). Free of Playwright, so an app
|
|
4
|
+
* in test mode serves it from `@botiverse/porthole/server`.
|
|
5
|
+
*/
|
|
6
|
+
export function conformancePage(version: "1" | "2"): string {
|
|
7
|
+
return `<!doctype html><html><head><title>Page</title></head><body><main id="artifact">version ${version}</main><script>document.documentElement.dataset.rtc = typeof RTCPeerConnection;</script></body></html>`;
|
|
8
|
+
}
|
package/src/host/types.ts
CHANGED
|
@@ -58,9 +58,12 @@ export interface MountOptions {
|
|
|
58
58
|
/** The height to start at, before the content reports its own. */
|
|
59
59
|
readonly initialHeightPx?: number;
|
|
60
60
|
/**
|
|
61
|
-
* Fill the container (give it a height) instead of taking the content's height
|
|
62
|
-
*
|
|
63
|
-
*
|
|
61
|
+
* Fill the container (give it a height) instead of taking the content's height.
|
|
62
|
+
*
|
|
63
|
+
* @deprecated Say it in the config, `layout: { kind: "fill" }`: every mount then fills, and the
|
|
64
|
+
* manual tells the agent so (a page that scrolls itself, `position: fixed` works). This option
|
|
65
|
+
* sizes only this frame, so the manual keeps saying the height follows the content (P071). A
|
|
66
|
+
* url-mode app always fills.
|
|
64
67
|
*/
|
|
65
68
|
readonly fill?: boolean;
|
|
66
69
|
}
|
package/src/isolation/served.ts
CHANGED
|
@@ -130,11 +130,12 @@ export function checkFrameLocation(
|
|
|
130
130
|
try {
|
|
131
131
|
url = new URL(location.url);
|
|
132
132
|
} catch {
|
|
133
|
-
throw new TypeError(
|
|
133
|
+
throw new TypeError("The located URL is not a URL");
|
|
134
134
|
}
|
|
135
135
|
if (origin === null || url.origin !== location.origin) {
|
|
136
136
|
throw new TypeError(
|
|
137
|
-
|
|
137
|
+
// Named by its origin only: a located URL carries a ticket, which never goes in a message.
|
|
138
|
+
`The located URL is not on its origin ${JSON.stringify(location.origin)} (it is on ${JSON.stringify(safeOrigin(location.url))})`,
|
|
138
139
|
);
|
|
139
140
|
}
|
|
140
141
|
if (!contentOrigins.some((source) => originMatchesSource(location.origin, source))) {
|
|
@@ -149,3 +150,12 @@ export function checkFrameLocation(
|
|
|
149
150
|
);
|
|
150
151
|
}
|
|
151
152
|
}
|
|
153
|
+
|
|
154
|
+
/** A URL's origin, for a message: never its path or query (a ticket). */
|
|
155
|
+
function safeOrigin(url: string): string {
|
|
156
|
+
try {
|
|
157
|
+
return new URL(url).origin;
|
|
158
|
+
} catch {
|
|
159
|
+
return "an unparsable address";
|
|
160
|
+
}
|
|
161
|
+
}
|
package/src/react/frame.tsx
CHANGED
|
@@ -216,8 +216,11 @@ export interface PortholeFrameProps {
|
|
|
216
216
|
/** Run at once, without waiting to near the screen (it still counts toward the page's most). */
|
|
217
217
|
readonly eager?: boolean;
|
|
218
218
|
/**
|
|
219
|
-
* Fill the box (give it, or its parent, a height)
|
|
220
|
-
*
|
|
219
|
+
* Fill the box (give it, or its parent, a height) instead of growing with the content.
|
|
220
|
+
*
|
|
221
|
+
* @deprecated Say it in the config, `layout: { kind: "fill" }`: every frame then fills, and the
|
|
222
|
+
* manual tells the agent so. This prop sizes only this frame, so the manual keeps saying the
|
|
223
|
+
* height follows the content (P071). A url-mode app always fills.
|
|
221
224
|
*/
|
|
222
225
|
readonly fill?: boolean;
|
|
223
226
|
readonly onInitialized?: () => void;
|
package/src/server/index.ts
CHANGED
|
@@ -63,6 +63,8 @@ export {
|
|
|
63
63
|
} from "./tickets.ts";
|
|
64
64
|
export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
65
65
|
export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
|
|
66
|
+
// The page an app serves in conformance test mode (P071).
|
|
67
|
+
export { conformancePage } from "../conformance/page.ts";
|
|
66
68
|
// The types an app's callbacks take and give (P070).
|
|
67
69
|
export type { PortholeConfig } from "../config/schema.ts";
|
|
68
70
|
export type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
|