@botiverse/porthole 0.2.2 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +83 -0
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +51 -0
- package/dist/conformance/entry.d.ts +12 -6
- package/dist/conformance/entry.js +17 -5
- package/dist/conformance/harness.js +8 -8
- package/dist/conformance/host-kit.d.ts +43 -13
- package/dist/conformance/host-kit.js +83 -6
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/index.js +1 -1
- package/dist/conformance/limits.js +15 -2
- package/dist/conformance/page.d.ts +6 -0
- package/dist/conformance/page.js +8 -0
- package/dist/host/types.d.ts +6 -3
- package/dist/isolation/served.js +13 -2
- package/dist/react/frame.d.ts +5 -2
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +2 -0
- package/docs/DECISIONS.md +37 -0
- package/docs/DESIGN.md +13 -6
- package/examples/app.mjs +234 -0
- package/examples/conformance/playwright.config.mjs +28 -0
- package/examples/conformance/porthole.spec.mjs +36 -0
- package/examples/node/server.mjs +75 -0
- package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
- package/examples/workers/worker.mjs +33 -0
- package/examples/workers/wrangler.jsonc +19 -0
- package/package.json +7 -2
- package/src/cli.ts +54 -0
- package/src/conformance/entry.ts +33 -11
- package/src/conformance/host-kit.ts +127 -21
- package/src/conformance/index.ts +4 -0
- package/src/conformance/limits.ts +21 -4
- package/src/conformance/page.ts +8 -0
- package/src/host/types.ts +6 -3
- package/src/isolation/served.ts +12 -2
- package/src/react/frame.tsx +5 -2
- package/src/server/index.ts +2 -0
|
@@ -2,6 +2,7 @@ import { type Page, type TestType } from "@playwright/test";
|
|
|
2
2
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
3
3
|
import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
|
|
4
4
|
import { type EntryConformanceHost } from "./entry.ts";
|
|
5
|
+
export { conformancePage } from "./page.ts";
|
|
5
6
|
import type { ConformanceHost } from "./index.ts";
|
|
6
7
|
import { type ServedConformanceHost } from "./served.ts";
|
|
7
8
|
/**
|
|
@@ -40,11 +41,16 @@ export interface HostConformanceOptions {
|
|
|
40
41
|
/** The config a served instance is framed under (the app's served config for its preset). */
|
|
41
42
|
readonly config: (instance: InstanceRef) => PortholeConfig;
|
|
42
43
|
/**
|
|
43
|
-
* The instances the served cases ask for, each for the scope a case names
|
|
44
|
-
*
|
|
45
|
-
*
|
|
44
|
+
* The instances the served cases ask for, each for the scope a case names (may be async: a
|
|
45
|
+
* page published on demand, `onDemand`). Give what the app serves; the cases for the rest are
|
|
46
|
+
* skipped, each with its reason:
|
|
47
|
+
* - `shell`: a served shell (domain mode). An app that serves only stored pages leaves it out:
|
|
48
|
+
* the domain-mode cases then run on `artifact(scope, "1")`;
|
|
49
|
+
* - `artifact(scope, version)`: versions "1" and "2" of one stored page on `scope`'s origin,
|
|
50
|
+
* each exactly `conformancePage(version)`;
|
|
51
|
+
* - `app`: a url-mode app; `proxy`: the MCP Apps sandbox proxy.
|
|
46
52
|
*/
|
|
47
|
-
readonly instances: Pick<ServedConformanceHost, "shell"
|
|
53
|
+
readonly instances: Partial<Pick<ServedConformanceHost, "shell" | "artifact" | "app" | "proxy">>;
|
|
48
54
|
/**
|
|
49
55
|
* Redirect entry (P068), where the app serves clean addresses: the cases open them directly,
|
|
50
56
|
* signed in and out, and in a frame.
|
|
@@ -55,14 +61,20 @@ export interface HostConformanceOptions {
|
|
|
55
61
|
* on demand.
|
|
56
62
|
*/
|
|
57
63
|
readonly url: (scope: string) => string | Promise<string>;
|
|
58
|
-
/** A clean address the signed-in viewer may not open. */
|
|
59
|
-
readonly denied
|
|
60
|
-
/**
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
64
|
+
/** A clean address the signed-in viewer may not open. Absent: that case is skipped. */
|
|
65
|
+
readonly denied?: (scope: string) => string | Promise<string>;
|
|
66
|
+
/**
|
|
67
|
+
* Whether `page` shows the app's own sign-in. Absent: the browser left the content origin and
|
|
68
|
+
* shows no content.
|
|
69
|
+
*/
|
|
70
|
+
readonly atSignIn?: (page: Page) => Promise<boolean>;
|
|
71
|
+
/** On the app's sign-in page: signs in, as a person does. Absent: the case stops there. */
|
|
72
|
+
readonly completeSignIn?: (page: Page) => Promise<void>;
|
|
73
|
+
/**
|
|
74
|
+
* Addresses on the content domain that name nothing: each a 404 there (P070). `"derive"`:
|
|
75
|
+
* `www`, the bare domain and a label no naming makes, under the domain of `url`'s address.
|
|
76
|
+
*/
|
|
77
|
+
readonly unknown?: "derive" | (() => readonly string[] | Promise<readonly string[]>);
|
|
66
78
|
};
|
|
67
79
|
/** Case ids to skip, each with its reason (shown in the report). */
|
|
68
80
|
readonly skip?: Readonly<Record<string, string>>;
|
|
@@ -82,9 +94,27 @@ export interface HostConformance {
|
|
|
82
94
|
}
|
|
83
95
|
/** The leak and served hosts on an app's real page, for an app that registers the cases itself. */
|
|
84
96
|
export declare function hostConformance(options: HostConformanceOptions): HostConformance;
|
|
97
|
+
/**
|
|
98
|
+
* A memo for fixtures made on demand (a page published the first time a case asks for it): one
|
|
99
|
+
* promise per key, per worker (P071).
|
|
100
|
+
*/
|
|
101
|
+
export declare function onDemand<V>(make: (key: string) => Promise<V>): (key: string) => Promise<V>;
|
|
102
|
+
/** One Playwright project per engine Porthole supports, as Porthole's own suites run them. */
|
|
103
|
+
export interface ConformanceProject {
|
|
104
|
+
readonly name: "chromium" | "webkit" | "firefox";
|
|
105
|
+
readonly use: Record<string, unknown>;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* The Playwright projects to run the suite on: Chromium, WebKit and Firefox, Firefox with the
|
|
109
|
+
* preferences its WebRTC probe needs (loopback ICE). Pass `devices` from `@playwright/test`
|
|
110
|
+
* (P071).
|
|
111
|
+
*/
|
|
112
|
+
export declare function conformanceProjects(devices: Readonly<Record<string, Record<string, unknown>>>, options?: {
|
|
113
|
+
readonly engines?: readonly ("chromium" | "webkit" | "firefox")[];
|
|
114
|
+
}): ConformanceProject[];
|
|
85
115
|
/**
|
|
86
116
|
* Registers the leak and served suites against an app's real page, in a spec file of the app's
|
|
87
117
|
* (so `-g "\[1\.connect\]"` selects one). The served cases for instances the app didn't give are
|
|
88
118
|
* skipped, each with its reason.
|
|
89
119
|
*/
|
|
90
|
-
export declare function defineHostConformance(test: TestType<
|
|
120
|
+
export declare function defineHostConformance<T extends object, W extends object>(test: TestType<T, W>, options: HostConformanceOptions): void;
|
|
@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
|
|
|
3
3
|
import { runInThisContext } from "node:vm";
|
|
4
4
|
import { expect } from "@playwright/test";
|
|
5
5
|
import { entryTests } from "./entry.js";
|
|
6
|
+
export { conformancePage } from "./page.js";
|
|
6
7
|
import { leakTests } from "./probes.js";
|
|
7
8
|
import { servedTests } from "./served.js";
|
|
8
9
|
const CANARY = "https://porthole-canary.example";
|
|
@@ -204,7 +205,11 @@ export function hostConformance(options) {
|
|
|
204
205
|
},
|
|
205
206
|
canary: (name) => Promise.resolve(`${CANARY}/${name}`),
|
|
206
207
|
canaryHits: (name) => Promise.resolve(hits.get(name) ?? 0),
|
|
207
|
-
|
|
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")),
|
|
208
213
|
// Asked for only by cases that run where the app gave them (`defineHostConformance` skips).
|
|
209
214
|
artifact: artifact ??
|
|
210
215
|
((scope, version) => ({ scope, document: { kind: "artifact", id: "page", version } })),
|
|
@@ -216,16 +221,22 @@ export function hostConformance(options) {
|
|
|
216
221
|
? null
|
|
217
222
|
: {
|
|
218
223
|
name: options.name,
|
|
224
|
+
url: given.url,
|
|
219
225
|
// Signed in on the app's page, the harness there (a frame needs it).
|
|
220
226
|
signIn: async (page) => {
|
|
221
227
|
await open(page);
|
|
222
228
|
await ready(page);
|
|
223
229
|
},
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
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
|
+
}),
|
|
229
240
|
async frame(page, url) {
|
|
230
241
|
await ready(page);
|
|
231
242
|
const instance = await served.artifact("entry", "1");
|
|
@@ -289,6 +300,69 @@ const URL_CASES = [
|
|
|
289
300
|
"served.url.framed",
|
|
290
301
|
];
|
|
291
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
|
+
}
|
|
292
366
|
/**
|
|
293
367
|
* Registers the leak and served suites against an app's real page, in a spec file of the app's
|
|
294
368
|
* (so `-g "\[1\.connect\]"` selects one). The served cases for instances the app didn't give are
|
|
@@ -306,6 +380,9 @@ export function defineHostConformance(test, options) {
|
|
|
306
380
|
if (options.instances.artifact === undefined) {
|
|
307
381
|
absent(["served.artifact.versions"], "the app serves no versions of a stored page");
|
|
308
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
|
+
}
|
|
309
386
|
if (options.instances.app === undefined) {
|
|
310
387
|
absent(URL_CASES, "the app serves no url-mode apps");
|
|
311
388
|
}
|
|
@@ -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
|
+
}
|
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/react/frame.d.ts
CHANGED
|
@@ -66,8 +66,11 @@ export interface PortholeFrameProps {
|
|
|
66
66
|
/** Run at once, without waiting to near the screen (it still counts toward the page's most). */
|
|
67
67
|
readonly eager?: boolean;
|
|
68
68
|
/**
|
|
69
|
-
* Fill the box (give it, or its parent, a height)
|
|
70
|
-
*
|
|
69
|
+
* Fill the box (give it, or its parent, a height) instead of growing with the content.
|
|
70
|
+
*
|
|
71
|
+
* @deprecated Say it in the config, `layout: { kind: "fill" }`: every frame then fills, and the
|
|
72
|
+
* manual tells the agent so. This prop sizes only this frame, so the manual keeps saying the
|
|
73
|
+
* height follows the content (P071). A url-mode app always fills.
|
|
71
74
|
*/
|
|
72
75
|
readonly fill?: boolean;
|
|
73
76
|
readonly onInitialized?: () => void;
|
package/dist/server/index.d.ts
CHANGED
|
@@ -38,6 +38,7 @@ export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDom
|
|
|
38
38
|
export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
|
|
39
39
|
export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
40
40
|
export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
|
|
41
|
+
export { conformancePage } from "../conformance/page.ts";
|
|
41
42
|
export type { PortholeConfig } from "../config/schema.ts";
|
|
42
43
|
export type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
|
|
43
44
|
export { proxyTo, type ProxyOptions } from "./proxy.ts";
|
package/dist/server/index.js
CHANGED
|
@@ -38,4 +38,6 @@ export { clashOf, contentDomain, ContentDomainError, hostnameOf, } from "./domai
|
|
|
38
38
|
export { d1TicketSchema, d1TicketStore, memoryTicketStore, } from "./tickets.js";
|
|
39
39
|
export { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
40
40
|
export { isHostLabel, prefixedName } from "./naming.js";
|
|
41
|
+
// The page an app serves in conformance test mode (P071).
|
|
42
|
+
export { conformancePage } from "../conformance/page.js";
|
|
41
43
|
export { proxyTo } from "./proxy.js";
|
package/docs/DECISIONS.md
CHANGED
|
@@ -1772,3 +1772,40 @@ own served flag in the `log` callback, a `-g` filter to find its tests.
|
|
|
1772
1772
|
**Revisit when** an app needs an address that exists but must not be told apart from one that
|
|
1773
1773
|
doesn't (then `at` grows a way to say "ask the app").
|
|
1774
1774
|
|
|
1775
|
+
## P071 · 2026-10-12 · Adopting from the package alone: a README, examples, ADOPTING.md, and fixes a cold adopter hit · Accepted
|
|
1776
|
+
|
|
1777
|
+
**Decision.** A fresh agent adopted 0.2.2 from the npm package alone (Node and Workers, about 25
|
|
1778
|
+
minutes, 130 lines); everything it hit was documentation, or small. 0.2.3:
|
|
1779
|
+
- **Docs in the package:** a README with a quickstart; `docs/ADOPTING.md`, the adopter's path
|
|
1780
|
+
apart from DESIGN (the server, the page, its CSP, Workers, local development, the agent's
|
|
1781
|
+
tools, conformance, expected noise); DESIGN's snippet fixed (`Response.redirect` needs an
|
|
1782
|
+
absolute URL outside a browser; `configs` keyed `artifact`, the preset an artifact names by
|
|
1783
|
+
default; one secret name, `PORTHOLE_SECRET`).
|
|
1784
|
+
- **Runnable examples in the package:** `examples/app.mjs` (one app, runtime-agnostic, with a
|
|
1785
|
+
conformance test mode), `examples/node/`, `examples/workers/` (D1 migration, `wrangler.jsonc`
|
|
1786
|
+
with `run_worker_first`), `examples/conformance/` (the suite against it, three engines). The
|
|
1787
|
+
page reports a client module that fails to load; the sign-in page has no `form-action`, which
|
|
1788
|
+
would hold the redirect back to the content origin.
|
|
1789
|
+
- **`npx porthole`:** `secret` makes a `PORTHOLE_SECRET`; `d1-schema` prints the migration.
|
|
1790
|
+
- **One way to fill:** the config's `layout.kind: "fill"`, which the manual follows.
|
|
1791
|
+
`MountOptions.fill` and `<PortholeFrame fill>` are deprecated (they size the frame only).
|
|
1792
|
+
- **`'unsafe-eval'` in content's CSP is kept, and said:** content is the agent's own script
|
|
1793
|
+
(`'unsafe-inline'`), so eval adds no capability; libraries content uses (Vue's in-browser
|
|
1794
|
+
build, Alpine.js, Vega) and WebAssembly need it. Isolation comes from the origin, the sandbox and
|
|
1795
|
+
egress.
|
|
1796
|
+
- **Conformance for an app that serves only stored pages:** `instances.shell` is optional (the
|
|
1797
|
+
domain cases run on `artifact(scope, "1")`); `conformancePage(version)` is the exact test page
|
|
1798
|
+
(also from `/server`, free of Playwright); `entry.denied`, `atSignIn` and `completeSignIn` are
|
|
1799
|
+
optional; `entry.unknown: "derive"`; `conformanceProjects(devices)`; `onDemand`;
|
|
1800
|
+
`defineHostConformance` takes any `TestType` without a cast. Test mode is documented with its
|
|
1801
|
+
warning: never ship it.
|
|
1802
|
+
- **`14.inline-assets`** reports itself inapplicable where the page's own CSP (which an opaque
|
|
1803
|
+
frame inherits) blocks data: images or inline styles, as its siblings do (P058).
|
|
1804
|
+
- **Host errors never quote a located URL** (it carries a ticket): they name its origin.
|
|
1805
|
+
|
|
1806
|
+
**Why.** The cold adopter's top ten were all here: no README, the runnable example unshipped,
|
|
1807
|
+
adopter docs buried in DESIGN, no client snippet, a conformance runner that demanded what an
|
|
1808
|
+
artifact-only app lacks, two snippet bugs, no word on the page's CSP, two ways to fill (one of
|
|
1809
|
+
which left the manual wrong), Workers specifics, and local development.
|
|
1810
|
+
**Revisit when** a second cold adoption (after 0.3) finds friction these don't cover.
|
|
1811
|
+
|
package/docs/DESIGN.md
CHANGED
|
@@ -4,6 +4,9 @@ The stable shape is in [ARCHITECTURE.md](ARCHITECTURE.md) and the reasons in
|
|
|
4
4
|
[DECISIONS.md](DECISIONS.md). This is the concrete phase-1 plan. Web first:
|
|
5
5
|
a framework-agnostic TypeScript core plus a thin React binding.
|
|
6
6
|
|
|
7
|
+
Adopting Porthole? Start with [ADOPTING.md](ADOPTING.md) and the package's `examples/`. Paths
|
|
8
|
+
below like `leak/…` and `ops/…` are Porthole's own repository, not the package.
|
|
9
|
+
|
|
7
10
|
## Threat model
|
|
8
11
|
|
|
9
12
|
Two classes of attacker, handled by different layers (ARCHITECTURE § Trust
|
|
@@ -121,7 +124,9 @@ realm) and by the host where the engine passes the gesture up.
|
|
|
121
124
|
`compile(config)` (`src/compile/compile.ts`) validates the config and returns:
|
|
122
125
|
|
|
123
126
|
- `csp` / `cspDirectives`: the frame's policy. `default-src 'none'`; scripts may be
|
|
124
|
-
inline (agent content is inline)
|
|
127
|
+
inline (agent content is inline), `'unsafe-eval'` (content is the agent's own script already,
|
|
128
|
+
so eval adds no capability, and libraries content uses compile with it, WebAssembly too: P071),
|
|
129
|
+
plus `blob:` and the script origins; each other
|
|
125
130
|
kind opens only to its origins; `connect-src 'none'` unless something is
|
|
126
131
|
declared; `frame-src`, `object-src`, `base-uri`, `form-action` all `'none'`;
|
|
127
132
|
`webrtc 'block'`. Never `'self'` (P022). Empty in url mode.
|
|
@@ -351,15 +356,16 @@ with redirect entry):
|
|
|
351
356
|
- `source`: a stored page by id and version;
|
|
352
357
|
- `entry.at`: the instance a clean address's path names (redirect entry).
|
|
353
358
|
|
|
354
|
-
**An adopter's whole wiring** (the
|
|
355
|
-
|
|
359
|
+
**An adopter's whole wiring** (the package's `examples/app.mjs` is this, runnable on Node and
|
|
360
|
+
Workers; docs/ADOPTING.md walks through it):
|
|
356
361
|
|
|
357
362
|
```ts
|
|
358
363
|
const content = createContentHost<Viewer>({
|
|
359
364
|
domain: env.CONTENT_DOMAIN, // "content.example.com" | "content.localhost:8790"; "" = off
|
|
360
365
|
appOrigins: [env.APP_ORIGIN], // frame-ancestors, and the clash guard
|
|
361
|
-
secret: env.
|
|
362
|
-
|
|
366
|
+
secret: env.PORTHOLE_SECRET, tickets: d1TicketStore(env.DB), // npx porthole secret
|
|
367
|
+
// Keyed by the preset a stored page names: an artifact's is "artifact" unless it says otherwise.
|
|
368
|
+
configs: (source) => ({ artifact: presets.artifact({ isolation: "domain", contentOrigins: [source] }) }),
|
|
363
369
|
name: prefixedName("a-"), reserved: ["p-*"], // only labels the app itself serves there
|
|
364
370
|
instance: (proposal, viewer) => mapToMyInstance(proposal), // a proposal: validate, derive the scope
|
|
365
371
|
access: async (instance, viewer) =>
|
|
@@ -369,7 +375,8 @@ const content = createContentHost<Viewer>({
|
|
|
369
375
|
entry: {
|
|
370
376
|
authorizeUrl: `${env.APP_ORIGIN}/porthole/authorize`,
|
|
371
377
|
at: (scope, path) => pageAt(scope, path), // "/" → latest, "/v/3" → version 3
|
|
372
|
-
|
|
378
|
+
// Absolute: outside a browser, Response.redirect has no base URL.
|
|
379
|
+
signIn: (returnTo) => Response.redirect(`${env.APP_ORIGIN}/login?next=${encodeURIComponent(returnTo)}`, 303),
|
|
373
380
|
},
|
|
374
381
|
health: { probe: nodeProbe(), onChange: (view) => pushToClients(view) }, // optional: the opaque fallback
|
|
375
382
|
});
|