@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.
Files changed (38) hide show
  1. package/README.md +83 -0
  2. package/dist/cli.d.ts +6 -0
  3. package/dist/cli.js +51 -0
  4. package/dist/conformance/entry.d.ts +12 -6
  5. package/dist/conformance/entry.js +17 -5
  6. package/dist/conformance/harness.js +8 -8
  7. package/dist/conformance/host-kit.d.ts +43 -13
  8. package/dist/conformance/host-kit.js +83 -6
  9. package/dist/conformance/index.d.ts +1 -1
  10. package/dist/conformance/index.js +1 -1
  11. package/dist/conformance/limits.js +15 -2
  12. package/dist/conformance/page.d.ts +6 -0
  13. package/dist/conformance/page.js +8 -0
  14. package/dist/host/types.d.ts +6 -3
  15. package/dist/isolation/served.js +13 -2
  16. package/dist/react/frame.d.ts +5 -2
  17. package/dist/server/index.d.ts +1 -0
  18. package/dist/server/index.js +2 -0
  19. package/docs/DECISIONS.md +37 -0
  20. package/docs/DESIGN.md +13 -6
  21. package/examples/app.mjs +234 -0
  22. package/examples/conformance/playwright.config.mjs +28 -0
  23. package/examples/conformance/porthole.spec.mjs +36 -0
  24. package/examples/node/server.mjs +75 -0
  25. package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
  26. package/examples/workers/worker.mjs +33 -0
  27. package/examples/workers/wrangler.jsonc +19 -0
  28. package/package.json +7 -2
  29. package/src/cli.ts +54 -0
  30. package/src/conformance/entry.ts +33 -11
  31. package/src/conformance/host-kit.ts +127 -21
  32. package/src/conformance/index.ts +4 -0
  33. package/src/conformance/limits.ts +21 -4
  34. package/src/conformance/page.ts +8 -0
  35. package/src/host/types.ts +6 -3
  36. package/src/isolation/served.ts +12 -2
  37. package/src/react/frame.tsx +5 -2
  38. 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. `shell` runs the
49
- * domain-mode cases; `artifact` (versions of one stored page), `app` (url mode) and `proxy` (the
50
- * MCP Apps sandbox proxy) run theirs where given, and are skipped (with the reason) where not.
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: (scope: string) => string | Promise<string>;
66
- /** Whether `page` shows the app's own sign-in. */
67
- readonly atSignIn: (page: Page) => Promise<boolean>;
68
- /** On the app's sign-in page: signs in, as a person does. */
69
- readonly completeSignIn: (page: Page) => Promise<void>;
70
- /** Addresses on the content domain that name nothing: each a 404 there (P070). */
71
- readonly unknown?: () => readonly string[] | Promise<readonly string[]>;
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
- shell: options.instances.shell,
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
- url: given.url,
344
- denied: given.denied,
345
- atSignIn: given.atSignIn,
346
- completeSignIn: given.completeSignIn,
347
- ...(given.unknown === undefined ? {} : { unknown: given.unknown }),
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<object, object>,
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
  }
@@ -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
- `<style>#styled { width: 37px }</style><div id="styled"></div><img id="inline" src="${pixel}"><img src="${canary.origin}/outside.png">`,
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: the content
62
- * scrolls inside its frame (an artifact viewer's page). The content's sizes are still reported
63
- * (`resize`). A url-mode app always fills.
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
  }
@@ -130,11 +130,12 @@ export function checkFrameLocation(
130
130
  try {
131
131
  url = new URL(location.url);
132
132
  } catch {
133
- throw new TypeError(`The located URL ${JSON.stringify(location.url)} is not a URL`);
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
- `The located URL ${JSON.stringify(location.url)} is not on its origin ${JSON.stringify(location.origin)}`,
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
+ }
@@ -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) and let the content scroll inside, instead of
220
- * growing with the content: an artifact viewer's page. A url-mode app always fills.
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;
@@ -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";