@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.
- package/README.md +83 -0
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +51 -0
- package/dist/conformance/entry.d.ts +19 -7
- package/dist/conformance/entry.js +39 -12
- package/dist/conformance/harness.js +8 -8
- package/dist/conformance/host-kit.d.ts +48 -13
- package/dist/conformance/host-kit.js +140 -28
- 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/conformance/served.d.ts +4 -4
- package/dist/conformance/served.js +26 -16
- package/dist/host/types.d.ts +6 -3
- package/dist/isolation/served.js +13 -2
- package/dist/node/index.d.ts +11 -3
- package/dist/node/index.js +70 -10
- package/dist/react/frame.d.ts +5 -2
- package/dist/server/host.d.ts +42 -8
- package/dist/server/host.js +35 -5
- package/dist/server/index.d.ts +4 -1
- package/dist/server/index.js +2 -0
- package/dist/server/pages.js +15 -1
- package/dist/server/proxy.js +2 -0
- package/dist/server/server.js +9 -2
- package/dist/server/types.d.ts +15 -6
- package/docs/ARCHITECTURE.md +277 -0
- package/docs/DECISIONS.md +1811 -0
- package/docs/DESIGN.md +1074 -0
- package/docs/OBJECTIVES.md +116 -0
- package/docs/PRINCIPLES.md +155 -0
- 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 +9 -3
- package/src/cli.ts +54 -0
- package/src/conformance/entry.ts +70 -19
- package/src/conformance/host-kit.ts +194 -45
- package/src/conformance/index.ts +4 -0
- package/src/conformance/limits.ts +21 -4
- package/src/conformance/page.ts +8 -0
- package/src/conformance/served.ts +34 -21
- package/src/host/types.ts +6 -3
- package/src/isolation/served.ts +12 -2
- package/src/node/index.ts +73 -10
- package/src/react/frame.tsx +5 -2
- package/src/server/host.ts +84 -14
- package/src/server/index.ts +6 -0
- package/src/server/pages.ts +15 -1
- package/src/server/proxy.ts +2 -0
- package/src/server/server.ts +11 -2
- 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.
|
|
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
|
+
}
|
package/src/conformance/entry.ts
CHANGED
|
@@ -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
|
-
/**
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
|
|
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
|
|
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(
|
|
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 {
|
|
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
|
|
48
|
-
*
|
|
49
|
-
*
|
|
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
|
-
/**
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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
|
-
|
|
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
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
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<
|
|
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
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
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
|
}
|
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";
|