@botiverse/porthole 0.2.1 → 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 (58) 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 +19 -7
  5. package/dist/conformance/entry.js +39 -12
  6. package/dist/conformance/harness.js +8 -8
  7. package/dist/conformance/host-kit.d.ts +48 -13
  8. package/dist/conformance/host-kit.js +140 -28
  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/conformance/served.d.ts +4 -4
  15. package/dist/conformance/served.js +26 -16
  16. package/dist/host/types.d.ts +6 -3
  17. package/dist/isolation/served.js +13 -2
  18. package/dist/node/index.d.ts +11 -3
  19. package/dist/node/index.js +70 -10
  20. package/dist/react/frame.d.ts +5 -2
  21. package/dist/server/host.d.ts +42 -8
  22. package/dist/server/host.js +35 -5
  23. package/dist/server/index.d.ts +4 -1
  24. package/dist/server/index.js +2 -0
  25. package/dist/server/pages.js +15 -1
  26. package/dist/server/proxy.js +2 -0
  27. package/dist/server/server.js +9 -2
  28. package/dist/server/types.d.ts +15 -6
  29. package/docs/ARCHITECTURE.md +277 -0
  30. package/docs/DECISIONS.md +1811 -0
  31. package/docs/DESIGN.md +1074 -0
  32. package/docs/OBJECTIVES.md +116 -0
  33. package/docs/PRINCIPLES.md +155 -0
  34. package/examples/app.mjs +234 -0
  35. package/examples/conformance/playwright.config.mjs +28 -0
  36. package/examples/conformance/porthole.spec.mjs +36 -0
  37. package/examples/node/server.mjs +75 -0
  38. package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
  39. package/examples/workers/worker.mjs +33 -0
  40. package/examples/workers/wrangler.jsonc +19 -0
  41. package/package.json +9 -3
  42. package/src/cli.ts +54 -0
  43. package/src/conformance/entry.ts +70 -19
  44. package/src/conformance/host-kit.ts +194 -45
  45. package/src/conformance/index.ts +4 -0
  46. package/src/conformance/limits.ts +21 -4
  47. package/src/conformance/page.ts +8 -0
  48. package/src/conformance/served.ts +34 -21
  49. package/src/host/types.ts +6 -3
  50. package/src/isolation/served.ts +12 -2
  51. package/src/node/index.ts +73 -10
  52. package/src/react/frame.tsx +5 -2
  53. package/src/server/host.ts +84 -14
  54. package/src/server/index.ts +6 -0
  55. package/src/server/pages.ts +15 -1
  56. package/src/server/proxy.ts +2 -0
  57. package/src/server/server.ts +11 -2
  58. package/src/server/types.ts +18 -7
@@ -0,0 +1,33 @@
1
+ // The example app on Cloudflare Workers: tickets in D1, Porthole's browser modules as static
2
+ // assets. No nodejs_compat needed.
3
+ //
4
+ // npx porthole d1-schema > migrations/0001_porthole_tickets.sql (already here)
5
+ // echo "PORTHOLE_SECRET=$(npx porthole secret)" > .dev.vars
6
+ // npx wrangler d1 migrations apply porthole-example --local && npx wrangler dev --port 8793
7
+ // open http://localhost:8793 (content: http://*.content.localhost:8793)
8
+ //
9
+ // wrangler.jsonc sets `run_worker_first`: every request, the content domain's included, comes
10
+ // here first, so static assets are never answered on a content origin.
11
+ import { d1TicketStore } from "@botiverse/porthole/server";
12
+ import { makeApp } from "../app.mjs";
13
+
14
+ let app = null; // one per isolate, made from the first request's env
15
+
16
+ export default {
17
+ async fetch(request, env) {
18
+ app ??= makeApp({
19
+ appOrigin: env.APP_ORIGIN,
20
+ contentDomain: env.CONTENT_DOMAIN,
21
+ secret: env.PORTHOLE_SECRET,
22
+ tickets: d1TicketStore(env.DB),
23
+ conformance: env.PORTHOLE_CONFORMANCE === "1",
24
+ // Porthole's browser modules, from the assets directory (the package's dist/).
25
+ client: async (path) => {
26
+ const answer = await env.ASSETS.fetch(new URL(path, env.APP_ORIGIN));
27
+ return answer.ok ? answer : null;
28
+ },
29
+ });
30
+ // The content domain first (Porthole answers every request there), then the app.
31
+ return (await app.content.fetch(request)) ?? app.handle(request);
32
+ },
33
+ };
@@ -0,0 +1,19 @@
1
+ // The example app on Workers. In your app, point `assets.directory` at
2
+ // node_modules/@botiverse/porthole/dist (or your bundle of Porthole's client).
3
+ {
4
+ "name": "porthole-example",
5
+ "main": "worker.mjs",
6
+ "compatibility_date": "2026-10-01",
7
+ "vars": { "APP_ORIGIN": "http://localhost:8793", "CONTENT_DOMAIN": "content.localhost:8793" },
8
+ "d1_databases": [
9
+ {
10
+ "binding": "DB",
11
+ "database_name": "porthole-example",
12
+ "database_id": "00000000-0000-0000-0000-000000000000",
13
+ "migrations_dir": "migrations",
14
+ },
15
+ ],
16
+ // run_worker_first: every request (content origins included) goes through the Worker, so the
17
+ // app's static files are never served on a content origin.
18
+ "assets": { "directory": "../../dist", "binding": "ASSETS", "run_worker_first": true },
19
+ }
package/package.json CHANGED
@@ -1,11 +1,17 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
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
+ "bin": {
7
+ "porthole": "./dist/cli.js"
8
+ },
6
9
  "files": [
7
10
  "src",
8
- "dist"
11
+ "dist",
12
+ "docs",
13
+ "examples",
14
+ "README.md"
9
15
  ],
10
16
  "type": "module",
11
17
  "sideEffects": false,
@@ -62,7 +68,7 @@
62
68
  "node": ">=24"
63
69
  },
64
70
  "scripts": {
65
- "build": "tsc -p tsconfig.build.json && node scripts/build-harness.ts",
71
+ "build": "tsc -p tsconfig.build.json && node scripts/build-harness.ts && node scripts/copy-docs.ts",
66
72
  "test:leak": "playwright test -c leak/playwright.config.ts"
67
73
  }
68
74
  }
package/src/cli.ts ADDED
@@ -0,0 +1,54 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `npx porthole <command>`: the setup steps an adopter would otherwise script (P071).
4
+ *
5
+ * porthole secret a new PORTHOLE_SECRET (32 random bytes, base64url)
6
+ * porthole d1-schema [table] the D1 ticket table's SQL, for a migration file
7
+ * (npx porthole d1-schema > migrations/0001_porthole_tickets.sql)
8
+ */
9
+ import { d1TicketSchema } from "./server/tickets.ts";
10
+
11
+ const USAGE = `Usage: porthole <command>
12
+
13
+ secret Print a new PORTHOLE_SECRET: 32 random bytes, base64url.
14
+ wrangler secret put PORTHOLE_SECRET, or your platform's secret store.
15
+ d1-schema [table] Print the D1 ticket table's SQL (default table porthole_tickets):
16
+ npx porthole d1-schema > migrations/0001_porthole_tickets.sql
17
+ `;
18
+
19
+ function base64url(bytes: Uint8Array): string {
20
+ let text = "";
21
+ for (const byte of bytes) {
22
+ text += String.fromCharCode(byte);
23
+ }
24
+ return btoa(text).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "");
25
+ }
26
+
27
+ /** Runs one command; returns what to print and the exit code. */
28
+ export function run(args: readonly string[]): { readonly out: string; readonly code: number } {
29
+ const [command, ...rest] = args;
30
+ try {
31
+ switch (command) {
32
+ case "secret":
33
+ return { out: `${base64url(crypto.getRandomValues(new Uint8Array(32)))}\n`, code: 0 };
34
+ case "d1-schema":
35
+ return { out: `${d1TicketSchema(rest[0])}\n`, code: 0 };
36
+ case undefined:
37
+ case "help":
38
+ case "--help":
39
+ case "-h":
40
+ return { out: USAGE, code: command === undefined ? 1 : 0 };
41
+ default:
42
+ return { out: `Unknown command ${JSON.stringify(command)}.\n\n${USAGE}`, code: 1 };
43
+ }
44
+ } catch (error) {
45
+ return { out: `${error instanceof Error ? error.message : String(error)}\n`, code: 1 };
46
+ }
47
+ }
48
+
49
+ // Run as a program (`porthole …`), not when imported (its test).
50
+ if (import.meta.main) {
51
+ const { out, code } = run(process.argv.slice(2));
52
+ (code === 0 ? process.stdout : process.stderr).write(out);
53
+ process.exitCode = code;
54
+ }
@@ -17,13 +17,25 @@ export interface EntryConformanceHost {
17
17
  * The clean address of a stored page the signed-in viewer may open (`ContentHost.urlOf`), for
18
18
  * `scope`: it draws `<main id="artifact">version 1</main>`.
19
19
  */
20
- url(scope: string): string;
21
- /** A clean address the signed-in viewer may not open. */
22
- denied(scope: string): string;
23
- /** Whether `page` shows the app's own sign-in. */
24
- atSignIn(page: Page): Promise<boolean>;
25
- /** On the app's sign-in page: signs in, as a person does (and the app goes back). */
26
- completeSignIn(page: Page): Promise<void>;
20
+ url(scope: string): string | Promise<string>;
21
+ /** A clean address the signed-in viewer may not open. Absent: `served.entry.denied` is skipped. */
22
+ denied?(scope: string): string | Promise<string>;
23
+ /**
24
+ * Addresses on the content domain that name nothing (a label the app never assigns, the bare
25
+ * domain, a path no instance has): each must be Porthole's 404 there, never the app's sign-in
26
+ * (P070). Absent: the case is skipped.
27
+ */
28
+ unknown?(): readonly string[] | Promise<readonly string[]>;
29
+ /**
30
+ * Whether `page` shows the app's own sign-in. Absent: the browser left the content origin for
31
+ * another (the app's) and shows no content.
32
+ */
33
+ atSignIn?(page: Page): Promise<boolean>;
34
+ /**
35
+ * On the app's sign-in page: signs in, as a person does (and the app goes back). Absent: the
36
+ * signed-out case stops at the sign-in.
37
+ */
38
+ completeSignIn?(page: Page): Promise<void>;
27
39
  /**
28
40
  * Frames a clean address on the app's page as the app would (a location of that address),
29
41
  * returning the frame and the display's outcome once it has one.
@@ -86,7 +98,7 @@ export function entryTests(
86
98
  "a clean address opens directly for a signed-in viewer, and stays clean; a reload rides on its cookie",
87
99
  async ({ page }) => {
88
100
  await host.signIn(page);
89
- const url = host.url("entry-direct");
101
+ const url = await host.url("entry-direct");
90
102
  await page.goto(url);
91
103
  await expect(page.locator("#artifact")).toHaveText("version 1");
92
104
  expect(page.url(), "the address bar shows the clean address, no code").toBe(url);
@@ -105,11 +117,22 @@ export function entryTests(
105
117
  define(
106
118
  "served.entry.signed-out",
107
119
  "signed out, a clean address goes to the app's own sign-in, then back to the content",
108
- async ({ page }) => {
109
- const url = host.url("entry-signed-out");
120
+ async ({ page }, info) => {
121
+ const url = await host.url("entry-signed-out");
110
122
  await page.goto(url);
111
- expect(await host.atSignIn(page), "the app's sign-in").toBe(true);
123
+ const atSignIn =
124
+ host.atSignIn === undefined
125
+ ? new URL(page.url()).origin !== new URL(url).origin
126
+ : await host.atSignIn(page);
127
+ expect(atSignIn, `the app's sign-in (ended at ${page.url()})`).toBe(true);
112
128
  expect(await shows(page)).toBe(false);
129
+ if (host.completeSignIn === undefined) {
130
+ info.annotations.push({
131
+ type: "note",
132
+ description: "the sign-in wasn't completed: entry.completeSignIn not given",
133
+ });
134
+ return;
135
+ }
113
136
  await host.completeSignIn(page);
114
137
  await expect(page.locator("#artifact")).toHaveText("version 1");
115
138
  expect(page.url()).toBe(url);
@@ -119,9 +142,13 @@ export function entryTests(
119
142
  define(
120
143
  "served.entry.denied",
121
144
  "a viewer without access gets the app's refusal, never the content",
122
- async ({ page }) => {
145
+ async ({ page }, info) => {
146
+ info.skip(
147
+ host.denied === undefined,
148
+ "the host gave no address its viewer may not open (denied)",
149
+ );
123
150
  await host.signIn(page);
124
- const url = host.denied("entry-denied");
151
+ const url = (await host.denied?.("entry-denied")) ?? "";
125
152
  const answer = await page.goto(url);
126
153
  expect(answer?.status()).toBe(403);
127
154
  expect(await shows(page)).toBe(false);
@@ -129,12 +156,35 @@ export function entryTests(
129
156
  },
130
157
  );
131
158
 
159
+ define(
160
+ "served.entry.unknown",
161
+ "an address that names nothing is a 404 on the content domain: never a trip to the app's sign-in",
162
+ async ({ page }, info) => {
163
+ info.skip(
164
+ host.unknown === undefined,
165
+ "the host gave no addresses that name nothing (unknown)",
166
+ );
167
+ const request = page.context().request;
168
+ for (const url of (await host.unknown?.()) ?? []) {
169
+ const answer = await request.get(url, {
170
+ maxRedirects: 0,
171
+ headers: { "sec-fetch-dest": "document" },
172
+ });
173
+ expect(answer.status(), url).toBe(404);
174
+ expect(answer.headers().location, url).toBeUndefined();
175
+ const opened = await page.goto(url);
176
+ expect(opened?.status(), url).toBe(404);
177
+ expect(new URL(page.url()).origin, url).toBe(new URL(url).origin);
178
+ }
179
+ },
180
+ );
181
+
132
182
  define(
133
183
  "served.entry.code-once",
134
184
  "an entry code works once: replayed, it opens nothing",
135
185
  async ({ page }) => {
136
186
  await host.signIn(page);
137
- const code = await codeFor(page, host.url("entry-once"));
187
+ const code = await codeFor(page, await host.url("entry-once"));
138
188
  const request = page.context().request;
139
189
  const top = { "sec-fetch-dest": "document" };
140
190
  const first = await request.get(code, { maxRedirects: 0, headers: top });
@@ -150,8 +200,8 @@ export function entryTests(
150
200
  "an entry code taken to another instance's origin opens nothing there",
151
201
  async ({ page }) => {
152
202
  await host.signIn(page);
153
- const code = new URL(await codeFor(page, host.url("entry-mine")));
154
- const other = new URL(host.url("entry-theirs"));
203
+ const code = new URL(await codeFor(page, await host.url("entry-mine")));
204
+ const other = new URL(await host.url("entry-theirs"));
155
205
  const request = page.context().request;
156
206
  const answer = await request.get(`${other.origin}${code.pathname}${code.search}`, {
157
207
  maxRedirects: 0,
@@ -167,10 +217,11 @@ export function entryTests(
167
217
  "a clean address in a frame shows the content where the browser keeps the cookies, else asks for a tab: never the app's sign-in",
168
218
  async ({ page, browserName }, info) => {
169
219
  await host.signIn(page);
170
- const shown = await host.frame(page, host.url("entry-framed"));
220
+ const before = page.url();
221
+ const shown = await host.frame(page, await host.url("entry-framed"));
171
222
  const outcome = await shown.outcome();
172
223
  const frame = await shown.frame();
173
- expect(await host.atSignIn(page)).toBe(false);
224
+ expect(page.url(), "the app's page stays where it was").toBe(before);
174
225
  expect(new URL(frame.url()).pathname).not.toMatch(/sign-?in/iu);
175
226
  if (outcome.state === "loaded") {
176
227
  await expect(frame.locator("#artifact")).toHaveText("version 1");
@@ -194,7 +245,7 @@ export function entryTests(
194
245
  await host.signIn(page);
195
246
  // The app's page stays; the browser forgets every sign-in.
196
247
  await page.context().clearCookies();
197
- const shown = await host.frame(page, host.url("entry-framed-out"));
248
+ const shown = await host.frame(page, await host.url("entry-framed-out"));
198
249
  expect(await shown.outcome()).toMatchObject({ state: "blocked", reason: "sign-in" });
199
250
  const frame = await shown.frame();
200
251
  await expect(frame.locator("h1")).toHaveText("Open this in a new tab to sign in");
@@ -1,13 +1,15 @@
1
1
  import { readFile } from "node:fs/promises";
2
2
  import { fileURLToPath } from "node:url";
3
- import { expect, type Frame, type Page, type TestType } from "@playwright/test";
3
+ import { runInThisContext } from "node:vm";
4
+ import { expect, type Frame, type Page, type TestInfo, type TestType } from "@playwright/test";
4
5
  import type { PortholeConfig } from "../config/schema.ts";
5
6
  import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
6
7
  import { entryTests, type EntryConformanceHost } from "./entry.ts";
8
+ export { conformancePage } from "./page.ts";
7
9
  import type { ConformanceHarness } from "./harness/page.ts";
8
10
  import type { FrameOutcome } from "../host/types.ts";
9
11
  import type { ConformanceHost, LaunchedDisplay, LaunchSpec } from "./index.ts";
10
- import { leakTests, type ConformanceFixtures } from "./probes.ts";
12
+ import { leakTests, type ConformanceFixtures, type ConformanceTest } from "./probes.ts";
11
13
  import { servedTests, type ServedConformanceHost, type ServedDisplay } from "./served.ts";
12
14
 
13
15
  /**
@@ -44,25 +46,40 @@ export interface HostConformanceOptions {
44
46
  /** The config a served instance is framed under (the app's served config for its preset). */
45
47
  readonly config: (instance: InstanceRef) => PortholeConfig;
46
48
  /**
47
- * The instances the served cases ask for, each for the scope a case names. `shell` runs the
48
- * domain-mode cases; `artifact` (versions of one stored page), `app` (url mode) and `proxy` (the
49
- * 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.
50
57
  */
51
- readonly instances: Pick<ServedConformanceHost, "shell"> &
52
- Partial<Pick<ServedConformanceHost, "artifact" | "app" | "proxy">>;
58
+ readonly instances: Partial<Pick<ServedConformanceHost, "shell" | "artifact" | "app" | "proxy">>;
53
59
  /**
54
60
  * Redirect entry (P068), where the app serves clean addresses: the cases open them directly,
55
61
  * signed in and out, and in a frame.
56
62
  */
57
63
  readonly entry?: {
58
- /** The clean address of `instances.artifact(scope, "1")` (`ContentHost.urlOf`). */
59
- readonly url: (scope: string) => string;
60
- /** A clean address the signed-in viewer may not open. */
61
- readonly denied: (scope: string) => string;
62
- /** Whether `page` shows the app's own sign-in. */
63
- readonly atSignIn: (page: Page) => Promise<boolean>;
64
- /** On the app's sign-in page: signs in, as a person does. */
65
- readonly completeSignIn: (page: Page) => Promise<void>;
64
+ /**
65
+ * The clean address of `instances.artifact(scope, "1")` (`ContentHost.urlOf`); may publish it
66
+ * on demand.
67
+ */
68
+ readonly url: (scope: string) => string | Promise<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[]>);
66
83
  };
67
84
  /** Case ids to skip, each with its reason (shown in the report). */
68
85
  readonly skip?: Readonly<Record<string, string>>;
@@ -314,7 +331,12 @@ export function hostConformance(options: HostConformanceOptions): HostConformanc
314
331
  },
315
332
  canary: (name) => Promise.resolve(`${CANARY}/${name}`),
316
333
  canaryHits: (name) => Promise.resolve(hits.get(name) ?? 0),
317
- 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")),
318
340
  // Asked for only by cases that run where the app gave them (`defineHostConformance` skips).
319
341
  artifact:
320
342
  artifact ??
@@ -329,18 +351,26 @@ export function hostConformance(options: HostConformanceOptions): HostConformanc
329
351
  ? null
330
352
  : {
331
353
  name: options.name,
354
+ url: given.url,
332
355
  // Signed in on the app's page, the harness there (a frame needs it).
333
356
  signIn: async (page) => {
334
357
  await open(page);
335
358
  await ready(page);
336
359
  },
337
- url: given.url,
338
- denied: given.denied,
339
- atSignIn: given.atSignIn,
340
- completeSignIn: given.completeSignIn,
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
+ }),
341
371
  async frame(page, url) {
342
372
  await ready(page);
343
- const instance = served.artifact("entry", "1");
373
+ const instance = await served.artifact("entry", "1");
344
374
  const id = await invoke(page, "show", options.config(instance), instance, {
345
375
  location: { url, origin: new URL(url).origin },
346
376
  });
@@ -408,14 +438,91 @@ const URL_CASES = [
408
438
  "served.url.framed",
409
439
  ];
410
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
+ }
411
518
 
412
519
  /**
413
520
  * Registers the leak and served suites against an app's real page, in a spec file of the app's
414
521
  * (so `-g "\[1\.connect\]"` selects one). The served cases for instances the app didn't give are
415
522
  * skipped, each with its reason.
416
523
  */
417
- export function defineHostConformance(
418
- test: TestType<object, object>,
524
+ export function defineHostConformance<T extends object, W extends object>(
525
+ test: TestType<T, W>,
419
526
  options: HostConformanceOptions,
420
527
  ): void {
421
528
  const typed = test as unknown as TestType<ConformanceFixtures, object>;
@@ -429,38 +536,80 @@ export function defineHostConformance(
429
536
  if (options.instances.artifact === undefined) {
430
537
  absent(["served.artifact.versions"], "the app serves no versions of a stored page");
431
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
+ }
432
545
  if (options.instances.app === undefined) {
433
546
  absent(URL_CASES, "the app serves no url-mode apps");
434
547
  }
435
548
  if (options.instances.proxy === undefined) {
436
549
  absent(PROXY_CASES, "the app serves no MCP Apps views");
437
550
  }
438
- typed.describe(`Porthole leak suite (${options.name})`, () => {
439
- for (const each of leakTests(hosts.leak, { skip })) {
440
- // Playwright reads the fixtures a test uses from its parameter's destructuring.
441
- typed(each.title, async ({ page, browserName }, info) => {
442
- await hosts.begin(page);
443
- await each.run({ page, browserName }, info);
444
- });
445
- }
446
- });
447
- typed.describe(`Porthole served modes (${options.name})`, () => {
448
- for (const each of servedTests(hosts.served, { skip })) {
449
- typed(each.title, async ({ page, browserName }, info) => {
450
- await hosts.begin(page);
451
- await each.run({ page, browserName }, info);
452
- });
453
- }
454
- });
455
- const entry = hosts.entry;
456
- if (entry !== null) {
457
- typed.describe(`Porthole redirect entry (${options.name})`, () => {
458
- for (const each of entryTests(entry, { skip })) {
459
- typed(each.title, async ({ page, browserName }, info) => {
551
+ // Registered as the app's own spec file's (P070): Playwright locates a test where `test()` is
552
+ // called, so `playwright test <spec>` and `<spec>:<line>` select these.
553
+ const at = callerOf(defineHostConformance);
554
+ const describeOf = Reflect.get(test, "describe") as unknown as Register;
555
+ const describe = calledFrom(describeOf, at);
556
+ const register = calledFrom(typed as unknown as Register, at);
557
+ const suite = (title: string, tests: readonly ConformanceTest[]) => {
558
+ describe(title, () => {
559
+ for (const each of tests) {
560
+ // Playwright reads the fixtures a test uses from its parameter's destructuring.
561
+ register(each.title, async ({ page, browserName }: ConformanceFixtures, info: TestInfo) => {
460
562
  await hosts.begin(page);
461
563
  await each.run({ page, browserName }, info);
462
564
  });
463
565
  }
464
566
  });
567
+ };
568
+ suite(`Porthole leak suite (${options.name})`, leakTests(hosts.leak, { skip }));
569
+ suite(`Porthole served modes (${options.name})`, servedTests(hosts.served, { skip }));
570
+ if (hosts.entry !== null) {
571
+ suite(`Porthole redirect entry (${options.name})`, entryTests(hosts.entry, { skip }));
572
+ }
573
+ }
574
+
575
+ /** Where a function was called from: the caller's file and line, or null. */
576
+ function callerOf(callee: (...args: never[]) => unknown): { file: string; line: number } | null {
577
+ const holder: { stack?: string } = {};
578
+ Error.captureStackTrace(holder, callee);
579
+ // The first frame is the caller's: " at file:///…/app.spec.ts:16:1" or " at fn (/…/app.spec.ts:16:1)".
580
+ const frame = (holder.stack ?? "")
581
+ .split("\n")
582
+ .map((line) => line.trim())
583
+ .find((line) => line.startsWith("at "));
584
+ const where = (frame ?? "").slice(3).replace(/^.*\((.*)\)$/u, "$1");
585
+ const found = /^(.+):(\d+):\d+$/u.exec(where);
586
+ if (found?.[1] === undefined || found[2] === undefined) {
587
+ return null;
588
+ }
589
+ try {
590
+ return {
591
+ file: found[1].startsWith("file://") ? fileURLToPath(found[1]) : found[1],
592
+ line: Number(found[2]),
593
+ };
594
+ } catch {
595
+ return null;
596
+ }
597
+ }
598
+
599
+ type Register = (title: string, body: unknown) => void;
600
+
601
+ /**
602
+ * `register` (Playwright's `test` or `test.describe`), called from a function compiled as the
603
+ * caller's file and line (`vm`'s `filename` and `lineOffset`), so the tests it makes are located
604
+ * there. Without a caller, `register` itself.
605
+ */
606
+ function calledFrom(register: Register, at: { file: string; line: number } | null): Register {
607
+ if (at === null) {
608
+ return (title, body) => register(title, body);
465
609
  }
610
+ const call = runInThisContext("(register, title, body) => register(title, body)", {
611
+ filename: at.file,
612
+ lineOffset: Math.max(0, at.line - 1),
613
+ }) as (register: Register, title: string, body: unknown) => void;
614
+ return (title, body) => call(register, title, body);
466
615
  }
@@ -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";