@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
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { readFile } from "node:fs/promises";
|
|
2
2
|
import { fileURLToPath } from "node:url";
|
|
3
|
+
import { runInThisContext } from "node:vm";
|
|
3
4
|
import { expect } from "@playwright/test";
|
|
4
5
|
import { entryTests } from "./entry.js";
|
|
6
|
+
export { conformancePage } from "./page.js";
|
|
5
7
|
import { leakTests } from "./probes.js";
|
|
6
8
|
import { servedTests } from "./served.js";
|
|
7
9
|
const CANARY = "https://porthole-canary.example";
|
|
@@ -203,7 +205,11 @@ export function hostConformance(options) {
|
|
|
203
205
|
},
|
|
204
206
|
canary: (name) => Promise.resolve(`${CANARY}/${name}`),
|
|
205
207
|
canaryHits: (name) => Promise.resolve(hits.get(name) ?? 0),
|
|
206
|
-
|
|
208
|
+
// An app that serves only stored pages: the domain-mode cases on its page's first version.
|
|
209
|
+
shell: options.instances.shell ??
|
|
210
|
+
(artifact === undefined
|
|
211
|
+
? (scope) => ({ scope, document: { kind: "shell", preset: "inlineWidget" } })
|
|
212
|
+
: (scope) => artifact(scope, "1")),
|
|
207
213
|
// Asked for only by cases that run where the app gave them (`defineHostConformance` skips).
|
|
208
214
|
artifact: artifact ??
|
|
209
215
|
((scope, version) => ({ scope, document: { kind: "artifact", id: "page", version } })),
|
|
@@ -215,18 +221,25 @@ export function hostConformance(options) {
|
|
|
215
221
|
? null
|
|
216
222
|
: {
|
|
217
223
|
name: options.name,
|
|
224
|
+
url: given.url,
|
|
218
225
|
// Signed in on the app's page, the harness there (a frame needs it).
|
|
219
226
|
signIn: async (page) => {
|
|
220
227
|
await open(page);
|
|
221
228
|
await ready(page);
|
|
222
229
|
},
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
230
|
+
...(given.denied === undefined ? {} : { denied: given.denied }),
|
|
231
|
+
...(given.atSignIn === undefined ? {} : { atSignIn: given.atSignIn }),
|
|
232
|
+
...(given.completeSignIn === undefined ? {} : { completeSignIn: given.completeSignIn }),
|
|
233
|
+
...(given.unknown === undefined
|
|
234
|
+
? {}
|
|
235
|
+
: {
|
|
236
|
+
unknown: given.unknown === "derive"
|
|
237
|
+
? async () => derivedUnknown(await given.url("entry-unknown"))
|
|
238
|
+
: given.unknown,
|
|
239
|
+
}),
|
|
227
240
|
async frame(page, url) {
|
|
228
241
|
await ready(page);
|
|
229
|
-
const instance = served.artifact("entry", "1");
|
|
242
|
+
const instance = await served.artifact("entry", "1");
|
|
230
243
|
const id = await invoke(page, "show", options.config(instance), instance, {
|
|
231
244
|
location: { url, origin: new URL(url).origin },
|
|
232
245
|
});
|
|
@@ -287,6 +300,69 @@ const URL_CASES = [
|
|
|
287
300
|
"served.url.framed",
|
|
288
301
|
];
|
|
289
302
|
const PROXY_CASES = ["served.proxy.view", "served.proxy.parent-only", "served.proxy.egress"];
|
|
303
|
+
const DOMAIN_CASES = [
|
|
304
|
+
"served.domain.origin",
|
|
305
|
+
"served.domain.no-reach",
|
|
306
|
+
"served.domain.no-top-navigation",
|
|
307
|
+
"served.domain.no-popups",
|
|
308
|
+
"served.domain.address",
|
|
309
|
+
"served.domain.storage-scope",
|
|
310
|
+
"served.domain.ticket-once",
|
|
311
|
+
"served.domain.frame-ancestors",
|
|
312
|
+
"served.domain.egress",
|
|
313
|
+
];
|
|
314
|
+
/**
|
|
315
|
+
* Addresses that name nothing, under the content domain of a clean address: `www`, the bare
|
|
316
|
+
* domain, and a label no naming makes (P071).
|
|
317
|
+
*/
|
|
318
|
+
function derivedUnknown(clean) {
|
|
319
|
+
const url = new URL(clean);
|
|
320
|
+
const domain = url.hostname.split(".").slice(1).join(".");
|
|
321
|
+
const port = url.port === "" ? "" : `:${url.port}`;
|
|
322
|
+
return ["www.", "", "zz-porthole-nothing."].map((label) => `${url.protocol}//${label}${domain}${port}/`);
|
|
323
|
+
}
|
|
324
|
+
/**
|
|
325
|
+
* A memo for fixtures made on demand (a page published the first time a case asks for it): one
|
|
326
|
+
* promise per key, per worker (P071).
|
|
327
|
+
*/
|
|
328
|
+
export function onDemand(make) {
|
|
329
|
+
const made = new Map();
|
|
330
|
+
return (key) => {
|
|
331
|
+
let found = made.get(key);
|
|
332
|
+
if (found === undefined) {
|
|
333
|
+
found = make(key);
|
|
334
|
+
made.set(key, found);
|
|
335
|
+
// A failure is tried again by the next case, not remembered.
|
|
336
|
+
found.catch(() => made.delete(key));
|
|
337
|
+
}
|
|
338
|
+
return found;
|
|
339
|
+
};
|
|
340
|
+
}
|
|
341
|
+
/**
|
|
342
|
+
* The Playwright projects to run the suite on: Chromium, WebKit and Firefox, Firefox with the
|
|
343
|
+
* preferences its WebRTC probe needs (loopback ICE). Pass `devices` from `@playwright/test`
|
|
344
|
+
* (P071).
|
|
345
|
+
*/
|
|
346
|
+
export function conformanceProjects(devices, options = {}) {
|
|
347
|
+
const all = [
|
|
348
|
+
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
|
|
349
|
+
{ name: "webkit", use: { ...devices["Desktop Safari"] } },
|
|
350
|
+
{
|
|
351
|
+
name: "firefox",
|
|
352
|
+
use: {
|
|
353
|
+
...devices["Desktop Firefox"],
|
|
354
|
+
launchOptions: {
|
|
355
|
+
firefoxUserPrefs: {
|
|
356
|
+
"media.peerconnection.ice.loopback": true,
|
|
357
|
+
"media.peerconnection.ice.obfuscate_host_addresses": false,
|
|
358
|
+
},
|
|
359
|
+
},
|
|
360
|
+
},
|
|
361
|
+
},
|
|
362
|
+
];
|
|
363
|
+
const engines = options.engines ?? ["chromium", "webkit", "firefox"];
|
|
364
|
+
return all.filter((project) => engines.includes(project.name));
|
|
365
|
+
}
|
|
290
366
|
/**
|
|
291
367
|
* Registers the leak and served suites against an app's real page, in a spec file of the app's
|
|
292
368
|
* (so `-g "\[1\.connect\]"` selects one). The served cases for instances the app didn't give are
|
|
@@ -304,38 +380,74 @@ export function defineHostConformance(test, options) {
|
|
|
304
380
|
if (options.instances.artifact === undefined) {
|
|
305
381
|
absent(["served.artifact.versions"], "the app serves no versions of a stored page");
|
|
306
382
|
}
|
|
383
|
+
if (options.instances.shell === undefined && options.instances.artifact === undefined) {
|
|
384
|
+
absent(DOMAIN_CASES, "the app serves no documents on content origins (instances.shell or .artifact)");
|
|
385
|
+
}
|
|
307
386
|
if (options.instances.app === undefined) {
|
|
308
387
|
absent(URL_CASES, "the app serves no url-mode apps");
|
|
309
388
|
}
|
|
310
389
|
if (options.instances.proxy === undefined) {
|
|
311
390
|
absent(PROXY_CASES, "the app serves no MCP Apps views");
|
|
312
391
|
}
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
typed(each.title, async ({ page, browserName }, info) => {
|
|
325
|
-
await hosts.begin(page);
|
|
326
|
-
await each.run({ page, browserName }, info);
|
|
327
|
-
});
|
|
328
|
-
}
|
|
329
|
-
});
|
|
330
|
-
const entry = hosts.entry;
|
|
331
|
-
if (entry !== null) {
|
|
332
|
-
typed.describe(`Porthole redirect entry (${options.name})`, () => {
|
|
333
|
-
for (const each of entryTests(entry, { skip })) {
|
|
334
|
-
typed(each.title, async ({ page, browserName }, info) => {
|
|
392
|
+
// Registered as the app's own spec file's (P070): Playwright locates a test where `test()` is
|
|
393
|
+
// called, so `playwright test <spec>` and `<spec>:<line>` select these.
|
|
394
|
+
const at = callerOf(defineHostConformance);
|
|
395
|
+
const describeOf = Reflect.get(test, "describe");
|
|
396
|
+
const describe = calledFrom(describeOf, at);
|
|
397
|
+
const register = calledFrom(typed, at);
|
|
398
|
+
const suite = (title, tests) => {
|
|
399
|
+
describe(title, () => {
|
|
400
|
+
for (const each of tests) {
|
|
401
|
+
// Playwright reads the fixtures a test uses from its parameter's destructuring.
|
|
402
|
+
register(each.title, async ({ page, browserName }, info) => {
|
|
335
403
|
await hosts.begin(page);
|
|
336
404
|
await each.run({ page, browserName }, info);
|
|
337
405
|
});
|
|
338
406
|
}
|
|
339
407
|
});
|
|
408
|
+
};
|
|
409
|
+
suite(`Porthole leak suite (${options.name})`, leakTests(hosts.leak, { skip }));
|
|
410
|
+
suite(`Porthole served modes (${options.name})`, servedTests(hosts.served, { skip }));
|
|
411
|
+
if (hosts.entry !== null) {
|
|
412
|
+
suite(`Porthole redirect entry (${options.name})`, entryTests(hosts.entry, { skip }));
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
/** Where a function was called from: the caller's file and line, or null. */
|
|
416
|
+
function callerOf(callee) {
|
|
417
|
+
const holder = {};
|
|
418
|
+
Error.captureStackTrace(holder, callee);
|
|
419
|
+
// The first frame is the caller's: " at file:///…/app.spec.ts:16:1" or " at fn (/…/app.spec.ts:16:1)".
|
|
420
|
+
const frame = (holder.stack ?? "")
|
|
421
|
+
.split("\n")
|
|
422
|
+
.map((line) => line.trim())
|
|
423
|
+
.find((line) => line.startsWith("at "));
|
|
424
|
+
const where = (frame ?? "").slice(3).replace(/^.*\((.*)\)$/u, "$1");
|
|
425
|
+
const found = /^(.+):(\d+):\d+$/u.exec(where);
|
|
426
|
+
if (found?.[1] === undefined || found[2] === undefined) {
|
|
427
|
+
return null;
|
|
428
|
+
}
|
|
429
|
+
try {
|
|
430
|
+
return {
|
|
431
|
+
file: found[1].startsWith("file://") ? fileURLToPath(found[1]) : found[1],
|
|
432
|
+
line: Number(found[2]),
|
|
433
|
+
};
|
|
340
434
|
}
|
|
435
|
+
catch {
|
|
436
|
+
return null;
|
|
437
|
+
}
|
|
438
|
+
}
|
|
439
|
+
/**
|
|
440
|
+
* `register` (Playwright's `test` or `test.describe`), called from a function compiled as the
|
|
441
|
+
* caller's file and line (`vm`'s `filename` and `lineOffset`), so the tests it makes are located
|
|
442
|
+
* there. Without a caller, `register` itself.
|
|
443
|
+
*/
|
|
444
|
+
function calledFrom(register, at) {
|
|
445
|
+
if (at === null) {
|
|
446
|
+
return (title, body) => register(title, body);
|
|
447
|
+
}
|
|
448
|
+
const call = runInThisContext("(register, title, body) => register(title, body)", {
|
|
449
|
+
filename: at.file,
|
|
450
|
+
lineOffset: Math.max(0, at.line - 1),
|
|
451
|
+
});
|
|
452
|
+
return (title, body) => call(register, title, body);
|
|
341
453
|
}
|
|
@@ -102,4 +102,4 @@ export { defineLeakSuite, leakTests, PROBES, type ConformanceFixtures, type Conf
|
|
|
102
102
|
export { httpOracle, settle, udpOracle, type HttpOracle, type UdpOracle } from "./oracles.ts";
|
|
103
103
|
export { defineServedSuite, servedTests, type ServedConformanceHost, type ServedDisplay, type ServedSuiteOptions, } from "./served.ts";
|
|
104
104
|
export { entryTests, type EntryConformanceHost, type EntrySuiteOptions } from "./entry.ts";
|
|
105
|
-
export { defineHostConformance, harnessScript, hostConformance, type HostConformance, type HostConformanceOptions, } from "./host-kit.ts";
|
|
105
|
+
export { conformancePage, conformanceProjects, defineHostConformance, harnessScript, hostConformance, onDemand, type ConformanceProject, type HostConformance, type HostConformanceOptions, } from "./host-kit.ts";
|
|
@@ -5,4 +5,4 @@ export { defineServedSuite, servedTests, } from "./served.js";
|
|
|
5
5
|
// Redirect entry's cases (P068).
|
|
6
6
|
export { entryTests } from "./entry.js";
|
|
7
7
|
// The runner an app points at its real page and issue endpoint (P066).
|
|
8
|
-
export { defineHostConformance, harnessScript, hostConformance, } from "./host-kit.js";
|
|
8
|
+
export { conformancePage, conformanceProjects, defineHostConformance, harnessScript, hostConformance, onDemand, } from "./host-kit.js";
|
|
@@ -37,6 +37,8 @@ function watch(page) {
|
|
|
37
37
|
/** A WAV of silence, small enough to inline. */
|
|
38
38
|
const SILENCE = "data:audio/wav;base64,UklGRkQDAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YSADAACAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgA==";
|
|
39
39
|
const RECORDER = "<script>window.r = {};</script>";
|
|
40
|
+
/** A one-pixel GIF, inline. */
|
|
41
|
+
const PIXEL = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
|
|
40
42
|
export const LIMIT_PROBES = [
|
|
41
43
|
{
|
|
42
44
|
id: "14.fill",
|
|
@@ -166,16 +168,27 @@ export const LIMIT_PROBES = [
|
|
|
166
168
|
title: "assets inline as data: URLs and CSS in a <style> work where nothing outside is open",
|
|
167
169
|
async run(context) {
|
|
168
170
|
const canary = await context.http();
|
|
169
|
-
const pixel = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
|
|
170
171
|
const display = await context.launch({
|
|
171
172
|
config: inline(),
|
|
172
173
|
content: attack(`
|
|
173
174
|
const image = document.getElementById("inline");
|
|
174
175
|
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); });
|
|
175
|
-
r.styled = getComputedStyle(document.getElementById("styled")).width
|
|
176
|
+
r.styled = getComputedStyle(document.getElementById("styled")).width;
|
|
177
|
+
if (r.inline !== "loaded") {
|
|
178
|
+
r.dataBlocked = await inheritedBlocks("data", () => { new Image().src = ${js(PIXEL)}; });
|
|
179
|
+
}
|
|
180
|
+
if (r.styled !== "37px") {
|
|
181
|
+
r.styleBlocked = await inheritedBlocks("inline", () => { const style = document.createElement("style"); style.textContent = "#styled { width: 38px }"; document.head.append(style); });
|
|
182
|
+
}`, `<style>#styled { width: 37px }</style><div id="styled"></div><img id="inline" src="${PIXEL}"><img src="${canary.origin}/outside.png">`),
|
|
176
183
|
});
|
|
177
184
|
const verdict = await context.result(display);
|
|
178
185
|
await settle();
|
|
186
|
+
// The frame's own policy allows data: images and inline styles: a block of either is the
|
|
187
|
+
// page's own CSP, which an opaque frame inherits (P058, P071).
|
|
188
|
+
if ((verdict.inline !== "loaded" && verdict.dataBlocked === true) ||
|
|
189
|
+
(verdict.styled !== "37px" && verdict.styleBlocked === true)) {
|
|
190
|
+
context.inapplicable("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");
|
|
191
|
+
}
|
|
179
192
|
expect(verdict).toMatchObject({ inline: "loaded", styled: "37px" });
|
|
180
193
|
expect(canary.requests()).toEqual([]);
|
|
181
194
|
},
|
|
@@ -0,0 +1,6 @@
|
|
|
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 declare function conformancePage(version: "1" | "2"): string;
|
|
@@ -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) {
|
|
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
|
+
}
|
|
@@ -53,20 +53,20 @@ export interface ServedConformanceHost {
|
|
|
53
53
|
/** How many requests reached `canary(name)`. */
|
|
54
54
|
canaryHits(name: string): Promise<number>;
|
|
55
55
|
/** A served shell (domain isolation) for `scope`. */
|
|
56
|
-
shell(scope: string): InstanceRef
|
|
56
|
+
shell(scope: string): InstanceRef | Promise<InstanceRef>;
|
|
57
57
|
/**
|
|
58
58
|
* A url-mode app for `scope`: its page loads a script from its own origin that sets
|
|
59
59
|
* `document.documentElement.dataset.app = "ready"`.
|
|
60
60
|
*/
|
|
61
|
-
app(scope: string): InstanceRef
|
|
61
|
+
app(scope: string): InstanceRef | Promise<InstanceRef>;
|
|
62
62
|
/**
|
|
63
63
|
* A stored artifact page (domain isolation) for `scope`: version `"1"` and `"2"` of one page,
|
|
64
64
|
* each with `<main id="artifact">version N</main>` and a script that records
|
|
65
65
|
* `document.documentElement.dataset.rtc = typeof RTCPeerConnection`.
|
|
66
66
|
*/
|
|
67
|
-
artifact(scope: string, version: "1" | "2"): InstanceRef
|
|
67
|
+
artifact(scope: string, version: "1" | "2"): InstanceRef | Promise<InstanceRef>;
|
|
68
68
|
/** The MCP Apps sandbox proxy (domain isolation) for `scope`, opening the view's `egress`. */
|
|
69
|
-
proxy(scope: string, egress?: EgressConfig): InstanceRef
|
|
69
|
+
proxy(scope: string, egress?: EgressConfig): InstanceRef | Promise<InstanceRef>;
|
|
70
70
|
}
|
|
71
71
|
export interface ServedSuiteOptions {
|
|
72
72
|
/** Case ids to skip, each with the reason (shown in the report). */
|
|
@@ -112,7 +112,7 @@ export function servedTests(host, options = {}) {
|
|
|
112
112
|
["url", (scope) => host.app(scope)],
|
|
113
113
|
];
|
|
114
114
|
// A served shell draws (and has a height to click in) once its host gives it content.
|
|
115
|
-
const showMode = (page, mode, instance) => host.show(page, instance, mode === "domain" ? { content: SHELL_CONTENT } : {});
|
|
115
|
+
const showMode = async (page, mode, instance) => host.show(page, await instance, mode === "domain" ? { content: SHELL_CONTENT } : {});
|
|
116
116
|
for (const [mode, instance] of modes) {
|
|
117
117
|
define(`served.${mode}.origin`, "content runs on its own origin, never the host's", async ({ page }) => {
|
|
118
118
|
const display = await showMode(page, mode, instance(`${mode}-origin`));
|
|
@@ -190,7 +190,9 @@ export function servedTests(host, options = {}) {
|
|
|
190
190
|
});
|
|
191
191
|
}
|
|
192
192
|
define("served.domain.address", "a served frame's address is its own, carrying at most Porthole's ticket: never the app's", async ({ page }) => {
|
|
193
|
-
const display = await host.show(page, host.shell("address"), {
|
|
193
|
+
const display = await host.show(page, await host.shell("address"), {
|
|
194
|
+
content: SHELL_CONTENT,
|
|
195
|
+
});
|
|
194
196
|
const frame = await display.frame();
|
|
195
197
|
const seen = await frame.evaluate(() => ({
|
|
196
198
|
origin: location.origin,
|
|
@@ -203,19 +205,25 @@ export function servedTests(host, options = {}) {
|
|
|
203
205
|
expect(seen.origin).not.toBe(new URL(page.url()).origin);
|
|
204
206
|
});
|
|
205
207
|
define("served.domain.storage-scope", "storage persists within a scope and is never shared across scopes", async ({ page }) => {
|
|
206
|
-
const first = await host.show(page, host.shell("scope-a"), {
|
|
208
|
+
const first = await host.show(page, await host.shell("scope-a"), {
|
|
209
|
+
content: SHELL_CONTENT,
|
|
210
|
+
});
|
|
207
211
|
await (await first.frame()).evaluate(() => localStorage.setItem("kept", "a"));
|
|
208
212
|
await first.destroy();
|
|
209
|
-
const again = await host.show(page, host.shell("scope-a"), {
|
|
213
|
+
const again = await host.show(page, await host.shell("scope-a"), {
|
|
214
|
+
content: SHELL_CONTENT,
|
|
215
|
+
});
|
|
210
216
|
expect(await (await again.frame()).evaluate(() => localStorage.getItem("kept"))).toBe("a");
|
|
211
217
|
expect(again.origin).toBe(first.origin);
|
|
212
|
-
const other = await host.show(page, host.shell("scope-b"), {
|
|
218
|
+
const other = await host.show(page, await host.shell("scope-b"), {
|
|
219
|
+
content: SHELL_CONTENT,
|
|
220
|
+
});
|
|
213
221
|
expect(other.origin).not.toBe(first.origin);
|
|
214
222
|
expect(await (await other.frame()).evaluate(() => localStorage.getItem("kept"))).toBeNull();
|
|
215
223
|
});
|
|
216
224
|
define("served.artifact.versions", "each version of a page shows as stored, on its scope's origin, hardened before it runs", async ({ page }) => {
|
|
217
|
-
const one = await host.show(page, host.artifact("artifact-scope", "1"));
|
|
218
|
-
const two = await host.show(page, host.artifact("artifact-scope", "2"));
|
|
225
|
+
const one = await host.show(page, await host.artifact("artifact-scope", "1"));
|
|
226
|
+
const two = await host.show(page, await host.artifact("artifact-scope", "2"));
|
|
219
227
|
expect(two.origin).toBe(one.origin);
|
|
220
228
|
for (const [display, version] of [
|
|
221
229
|
[one, "1"],
|
|
@@ -227,7 +235,7 @@ export function servedTests(host, options = {}) {
|
|
|
227
235
|
}
|
|
228
236
|
});
|
|
229
237
|
define("served.domain.ticket-once", "a ticket opens its content once; without it there is nothing", async ({ page, browserName }) => {
|
|
230
|
-
const location = await host.locate(host.shell("ticket-once"));
|
|
238
|
+
const location = await host.locate(await host.shell("ticket-once"));
|
|
231
239
|
const first = await page.goto(location.url);
|
|
232
240
|
expect(first?.status()).toBe(200);
|
|
233
241
|
// A fresh browser state: no cookie, only the used ticket.
|
|
@@ -243,7 +251,7 @@ export function servedTests(host, options = {}) {
|
|
|
243
251
|
}
|
|
244
252
|
});
|
|
245
253
|
define("served.domain.frame-ancestors", "only the host's origins may frame content", async ({ page }) => {
|
|
246
|
-
const location = await host.locate(host.shell("foreign"));
|
|
254
|
+
const location = await host.locate(await host.shell("foreign"));
|
|
247
255
|
await host.frameFromForeignOrigin(page, location.url);
|
|
248
256
|
await page.waitForTimeout(SETTLE_MS);
|
|
249
257
|
for (const frame of page.frames().slice(1)) {
|
|
@@ -264,7 +272,9 @@ export function servedTests(host, options = {}) {
|
|
|
264
272
|
}
|
|
265
273
|
});
|
|
266
274
|
define("served.domain.egress", "the CSP in the document's headers closes egress; only what the config opens to any https site (images, media) reaches it", async ({ page }) => {
|
|
267
|
-
const display = await host.show(page, host.shell("egress"), {
|
|
275
|
+
const display = await host.show(page, await host.shell("egress"), {
|
|
276
|
+
content: SHELL_CONTENT,
|
|
277
|
+
});
|
|
268
278
|
const frame = await display.frame();
|
|
269
279
|
const kinds = ["fetch", "img", "media", "script", "style", "frame"];
|
|
270
280
|
const urls = Object.fromEntries(await Promise.all(kinds.map(async (kind) => [kind, await host.canary(`egress-${kind}`)])));
|
|
@@ -343,7 +353,7 @@ export function servedTests(host, options = {}) {
|
|
|
343
353
|
.poll(async () => methodsOf(await display.received()))
|
|
344
354
|
.toContain(MCP_APPS_METHODS.sandboxProxyReady);
|
|
345
355
|
define("served.proxy.view", "the sandbox proxy becomes the view, hardened, talking to its host directly", async ({ page }) => {
|
|
346
|
-
const display = await host.show(page, host.proxy("proxy-view"));
|
|
356
|
+
const display = await host.show(page, await host.proxy("proxy-view"));
|
|
347
357
|
await proxyReady(display);
|
|
348
358
|
const canary = await host.canary("proxy-undeclared");
|
|
349
359
|
await display.post(resourceReady(PROBE_VIEW(canary)));
|
|
@@ -357,7 +367,7 @@ export function servedTests(host, options = {}) {
|
|
|
357
367
|
expect(await host.canaryHits("proxy-undeclared")).toBe(0);
|
|
358
368
|
});
|
|
359
369
|
define("served.proxy.parent-only", "the sandbox proxy takes a view only from its host", async ({ page }) => {
|
|
360
|
-
const display = await host.show(page, host.proxy("proxy-parent"));
|
|
370
|
+
const display = await host.show(page, await host.proxy("proxy-parent"));
|
|
361
371
|
await proxyReady(display);
|
|
362
372
|
const frame = await display.frame();
|
|
363
373
|
await frame.evaluate((message) => window.postMessage(message, "*"), resourceReady('<p id="view">Not from the host.</p>'));
|
|
@@ -366,7 +376,7 @@ export function servedTests(host, options = {}) {
|
|
|
366
376
|
});
|
|
367
377
|
define("served.proxy.egress", "the sandbox proxy opens what the view declares, and nothing else", async ({ page }) => {
|
|
368
378
|
const canary = await host.canary("proxy-declared");
|
|
369
|
-
const display = await host.show(page, host.proxy("proxy-egress", { connect: [new URL(canary).origin] }));
|
|
379
|
+
const display = await host.show(page, await host.proxy("proxy-egress", { connect: [new URL(canary).origin] }));
|
|
370
380
|
await proxyReady(display);
|
|
371
381
|
await display.post(resourceReady(PROBE_VIEW(canary)));
|
|
372
382
|
const frame = await display.frame();
|
|
@@ -374,7 +384,7 @@ export function servedTests(host, options = {}) {
|
|
|
374
384
|
expect(await host.canaryHits("proxy-declared")).toBe(1);
|
|
375
385
|
});
|
|
376
386
|
define("served.url.ticket", "an app shows nothing to a browser without its ticket's cookie", async ({ page }) => {
|
|
377
|
-
const location = await host.locate(host.app("url-ticket"));
|
|
387
|
+
const location = await host.locate(await host.app("url-ticket"));
|
|
378
388
|
// A fresh browser: no cookie of the content's, none of the app's. Porthole refuses it, or
|
|
379
389
|
// (redirect entry, P068) hands it to the app's authorize route, which asks it to sign in.
|
|
380
390
|
const fresh = await page.context().browser().newContext();
|
|
@@ -390,7 +400,7 @@ export function servedTests(host, options = {}) {
|
|
|
390
400
|
}
|
|
391
401
|
});
|
|
392
402
|
define("served.url.tab", "an app opened on a tab of its own runs, its requests riding on its cookie", async ({ page }) => {
|
|
393
|
-
const location = await host.locate(host.app("url-tab"));
|
|
403
|
+
const location = await host.locate(await host.app("url-tab"));
|
|
394
404
|
await page.goto(location.url);
|
|
395
405
|
await expect(page.locator("html")).toHaveAttribute("data-app", "ready");
|
|
396
406
|
});
|
|
@@ -398,7 +408,7 @@ export function servedTests(host, options = {}) {
|
|
|
398
408
|
// Measured (P025): WebKit keeps no cookie in a cross-site frame, partitioned or not, so a
|
|
399
409
|
// framed app's subresources are refused there; such hosts open the app on a tab.
|
|
400
410
|
typed.fail(browserName === "webkit", "WebKit keeps no cookie in a cross-site frame");
|
|
401
|
-
const display = await host.show(page, host.app("url-framed"));
|
|
411
|
+
const display = await host.show(page, await host.app("url-framed"));
|
|
402
412
|
const frame = await display.frame();
|
|
403
413
|
await expect
|
|
404
414
|
.poll(() => frame.evaluate(() => document.documentElement.dataset.app ?? null), {
|
package/dist/host/types.d.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/dist/isolation/served.js
CHANGED
|
@@ -102,10 +102,12 @@ export function checkFrameLocation(location, contentOrigins, hostOrigin) {
|
|
|
102
102
|
url = new URL(location.url);
|
|
103
103
|
}
|
|
104
104
|
catch {
|
|
105
|
-
throw new TypeError(
|
|
105
|
+
throw new TypeError("The located URL is not a URL");
|
|
106
106
|
}
|
|
107
107
|
if (origin === null || url.origin !== location.origin) {
|
|
108
|
-
throw new TypeError(
|
|
108
|
+
throw new TypeError(
|
|
109
|
+
// Named by its origin only: a located URL carries a ticket, which never goes in a message.
|
|
110
|
+
`The located URL is not on its origin ${JSON.stringify(location.origin)} (it is on ${JSON.stringify(safeOrigin(location.url))})`);
|
|
109
111
|
}
|
|
110
112
|
if (!contentOrigins.some((source) => originMatchesSource(location.origin, source))) {
|
|
111
113
|
throw new TypeError(`The located origin ${location.origin} is not one of the config's content origins`);
|
|
@@ -115,3 +117,12 @@ export function checkFrameLocation(location, contentOrigins, hostOrigin) {
|
|
|
115
117
|
throw new TypeError(`The located origin ${location.origin} may be the same site as the host (${hostOrigin}): content must be served from a registrable domain the host uses for nothing else`);
|
|
116
118
|
}
|
|
117
119
|
}
|
|
120
|
+
/** A URL's origin, for a message: never its path or query (a ticket). */
|
|
121
|
+
function safeOrigin(url) {
|
|
122
|
+
try {
|
|
123
|
+
return new URL(url).origin;
|
|
124
|
+
}
|
|
125
|
+
catch {
|
|
126
|
+
return "an unparsable address";
|
|
127
|
+
}
|
|
128
|
+
}
|
package/dist/node/index.d.ts
CHANGED
|
@@ -27,9 +27,17 @@ export interface NodeHost {
|
|
|
27
27
|
readonly request: RequestListener;
|
|
28
28
|
readonly upgrade: UpgradeListener;
|
|
29
29
|
}
|
|
30
|
-
/**
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
/**
|
|
31
|
+
* The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). `signal`
|
|
32
|
+
* (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work.
|
|
33
|
+
*/
|
|
34
|
+
export declare function toRequest(request: IncomingMessage, scheme: "https" | "http", signal?: AbortSignal): Request;
|
|
35
|
+
/**
|
|
36
|
+
* Writes a fetch `Response` to a Node response, cookies one header each (P070): it waits for the
|
|
37
|
+
* socket to drain before reading on (a slow client never makes it buffer the body), cancels the
|
|
38
|
+
* body when the client goes away (an event stream ends with the page that asked for it), and on
|
|
39
|
+
* an error mid-body destroys the response rather than end it looking complete.
|
|
40
|
+
*/
|
|
33
41
|
export declare function sendResponse(response: ServerResponse, answer: Response): Promise<void>;
|
|
34
42
|
export declare function nodeHost<V>(content: ContentHost<V>, app: NodeHostOptions): NodeHost;
|
|
35
43
|
/**
|
package/dist/node/index.js
CHANGED
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
import { request as httpRequest } from "node:http";
|
|
2
2
|
import { request as httpsRequest } from "node:https";
|
|
3
3
|
import { Readable } from "node:stream";
|
|
4
|
-
/**
|
|
5
|
-
|
|
4
|
+
/**
|
|
5
|
+
* The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). `signal`
|
|
6
|
+
* (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work.
|
|
7
|
+
*/
|
|
8
|
+
export function toRequest(request, scheme, signal) {
|
|
6
9
|
const headers = new Headers();
|
|
7
10
|
for (const [name, value] of Object.entries(request.headers)) {
|
|
8
11
|
for (const each of Array.isArray(value) ? value : value === undefined ? [] : [value]) {
|
|
@@ -15,9 +18,20 @@ export function toRequest(request, scheme) {
|
|
|
15
18
|
: target;
|
|
16
19
|
const method = request.method ?? "GET";
|
|
17
20
|
const body = method === "GET" || method === "HEAD" ? null : Readable.toWeb(request);
|
|
18
|
-
return new Request(url, {
|
|
21
|
+
return new Request(url, {
|
|
22
|
+
method,
|
|
23
|
+
headers,
|
|
24
|
+
body,
|
|
25
|
+
duplex: "half",
|
|
26
|
+
...(signal === undefined ? {} : { signal }),
|
|
27
|
+
});
|
|
19
28
|
}
|
|
20
|
-
/**
|
|
29
|
+
/**
|
|
30
|
+
* Writes a fetch `Response` to a Node response, cookies one header each (P070): it waits for the
|
|
31
|
+
* socket to drain before reading on (a slow client never makes it buffer the body), cancels the
|
|
32
|
+
* body when the client goes away (an event stream ends with the page that asked for it), and on
|
|
33
|
+
* an error mid-body destroys the response rather than end it looking complete.
|
|
34
|
+
*/
|
|
21
35
|
export async function sendResponse(response, answer) {
|
|
22
36
|
const headers = {};
|
|
23
37
|
for (const [name, value] of answer.headers) {
|
|
@@ -34,10 +48,46 @@ export async function sendResponse(response, answer) {
|
|
|
34
48
|
response.end();
|
|
35
49
|
return;
|
|
36
50
|
}
|
|
37
|
-
|
|
38
|
-
|
|
51
|
+
const reader = answer.body.getReader();
|
|
52
|
+
let gone = false;
|
|
53
|
+
const leave = () => {
|
|
54
|
+
gone = true;
|
|
55
|
+
reader.cancel().catch(() => undefined);
|
|
56
|
+
};
|
|
57
|
+
// The client went away before the end: stop reading, and let the body's source know.
|
|
58
|
+
response.once("close", () => {
|
|
59
|
+
if (!response.writableFinished) {
|
|
60
|
+
leave();
|
|
61
|
+
}
|
|
62
|
+
});
|
|
63
|
+
try {
|
|
64
|
+
for (;;) {
|
|
65
|
+
const { done, value } = await reader.read();
|
|
66
|
+
if (done || gone) {
|
|
67
|
+
break;
|
|
68
|
+
}
|
|
69
|
+
if (!response.write(value)) {
|
|
70
|
+
await new Promise((resolve) => {
|
|
71
|
+
const on = () => {
|
|
72
|
+
response.off("drain", on);
|
|
73
|
+
response.off("close", on);
|
|
74
|
+
resolve();
|
|
75
|
+
};
|
|
76
|
+
response.on("drain", on);
|
|
77
|
+
response.on("close", on);
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
catch (error) {
|
|
83
|
+
// The head is sent: a body cut short must not look whole.
|
|
84
|
+
leave();
|
|
85
|
+
response.destroy(error instanceof Error ? error : new Error(String(error)));
|
|
86
|
+
return;
|
|
87
|
+
}
|
|
88
|
+
if (!gone) {
|
|
89
|
+
response.end();
|
|
39
90
|
}
|
|
40
|
-
response.end();
|
|
41
91
|
}
|
|
42
92
|
/** Whether a Node request's Host (or absolute-form target) is under the content domain. */
|
|
43
93
|
function forContent(content, request) {
|
|
@@ -67,7 +117,15 @@ export function nodeHost(content, app) {
|
|
|
67
117
|
app.request(request, response);
|
|
68
118
|
return;
|
|
69
119
|
}
|
|
70
|
-
|
|
120
|
+
// Aborted when the client goes away first, so an upstream (a proxied app's event stream)
|
|
121
|
+
// stops with it.
|
|
122
|
+
const gone = new AbortController();
|
|
123
|
+
response.once("close", () => {
|
|
124
|
+
if (!response.writableFinished) {
|
|
125
|
+
gone.abort();
|
|
126
|
+
}
|
|
127
|
+
});
|
|
128
|
+
content.fetch(toRequest(request, scheme(), gone.signal)).then((answer) => {
|
|
71
129
|
if (answer === null) {
|
|
72
130
|
// A label the app routes itself.
|
|
73
131
|
app.request(request, response);
|
|
@@ -75,9 +133,11 @@ export function nodeHost(content, app) {
|
|
|
75
133
|
}
|
|
76
134
|
return sendResponse(response, answer);
|
|
77
135
|
}, () => {
|
|
78
|
-
if (
|
|
79
|
-
response.
|
|
136
|
+
if (response.headersSent) {
|
|
137
|
+
response.destroy();
|
|
138
|
+
return;
|
|
80
139
|
}
|
|
140
|
+
response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
|
|
81
141
|
response.end("Content couldn't be served.");
|
|
82
142
|
});
|
|
83
143
|
},
|