@botiverse/porthole 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +83 -0
  2. package/dist/cli.d.ts +6 -0
  3. package/dist/cli.js +51 -0
  4. package/dist/conformance/entry.d.ts +12 -6
  5. package/dist/conformance/entry.js +17 -5
  6. package/dist/conformance/harness.js +8 -8
  7. package/dist/conformance/host-kit.d.ts +43 -13
  8. package/dist/conformance/host-kit.js +83 -6
  9. package/dist/conformance/index.d.ts +1 -1
  10. package/dist/conformance/index.js +1 -1
  11. package/dist/conformance/limits.js +15 -2
  12. package/dist/conformance/page.d.ts +6 -0
  13. package/dist/conformance/page.js +8 -0
  14. package/dist/host/types.d.ts +6 -3
  15. package/dist/isolation/served.js +13 -2
  16. package/dist/react/frame.d.ts +5 -2
  17. package/dist/server/index.d.ts +1 -0
  18. package/dist/server/index.js +2 -0
  19. package/docs/ADOPTING.md +269 -0
  20. package/docs/DECISIONS.md +37 -0
  21. package/docs/DESIGN.md +13 -6
  22. package/examples/app.mjs +234 -0
  23. package/examples/conformance/playwright.config.mjs +28 -0
  24. package/examples/conformance/porthole.spec.mjs +36 -0
  25. package/examples/node/server.mjs +75 -0
  26. package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
  27. package/examples/workers/worker.mjs +33 -0
  28. package/examples/workers/wrangler.jsonc +19 -0
  29. package/package.json +7 -2
  30. package/src/cli.ts +54 -0
  31. package/src/conformance/entry.ts +33 -11
  32. package/src/conformance/host-kit.ts +127 -21
  33. package/src/conformance/index.ts +4 -0
  34. package/src/conformance/limits.ts +21 -4
  35. package/src/conformance/page.ts +8 -0
  36. package/src/host/types.ts +6 -3
  37. package/src/isolation/served.ts +12 -2
  38. package/src/react/frame.tsx +5 -2
  39. 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. `shell` runs the
44
- * domain-mode cases; `artifact` (versions of one stored page), `app` (url mode) and `proxy` (the
45
- * MCP Apps sandbox proxy) run theirs where given, and are skipped (with the reason) where not.
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"> & Partial<Pick<ServedConformanceHost, "artifact" | "app" | "proxy">>;
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: (scope: string) => string | Promise<string>;
60
- /** Whether `page` shows the app's own sign-in. */
61
- readonly atSignIn: (page: Page) => Promise<boolean>;
62
- /** On the app's sign-in page: signs in, as a person does. */
63
- readonly completeSignIn: (page: Page) => Promise<void>;
64
- /** Addresses on the content domain that name nothing: each a 404 there (P070). */
65
- readonly unknown?: () => readonly string[] | Promise<readonly string[]>;
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<object, object>, options: HostConformanceOptions): void;
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
- shell: options.instances.shell,
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
- url: given.url,
225
- denied: given.denied,
226
- atSignIn: given.atSignIn,
227
- completeSignIn: given.completeSignIn,
228
- ...(given.unknown === undefined ? {} : { unknown: given.unknown }),
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;`, `<style>#styled { width: 37px }</style><div id="styled"></div><img id="inline" src="${pixel}"><img src="${canary.origin}/outside.png">`),
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
+ }
@@ -58,9 +58,12 @@ export interface MountOptions {
58
58
  /** The height to start at, before the content reports its own. */
59
59
  readonly initialHeightPx?: number;
60
60
  /**
61
- * Fill the container (give it a height) instead of taking the content's height: the content
62
- * scrolls inside its frame (an artifact viewer's page). The content's sizes are still reported
63
- * (`resize`). A url-mode app always fills.
61
+ * Fill the container (give it a height) instead of taking the content's height.
62
+ *
63
+ * @deprecated Say it in the config, `layout: { kind: "fill" }`: every mount then fills, and the
64
+ * manual tells the agent so (a page that scrolls itself, `position: fixed` works). This option
65
+ * sizes only this frame, so the manual keeps saying the height follows the content (P071). A
66
+ * url-mode app always fills.
64
67
  */
65
68
  readonly fill?: boolean;
66
69
  }
@@ -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(`The located URL ${JSON.stringify(location.url)} is not a URL`);
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(`The located URL ${JSON.stringify(location.url)} is not on its origin ${JSON.stringify(location.origin)}`);
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
+ }
@@ -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) and let the content scroll inside, instead of
70
- * growing with the content: an artifact viewer's page. A url-mode app always fills.
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;
@@ -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";
@@ -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";
@@ -0,0 +1,269 @@
1
+ # Adopting Porthole
2
+
3
+ How to put Porthole in an app, from the npm package alone. The package's `examples/` is a whole
4
+ app that does everything below: `examples/app.mjs` is the app, runtime-agnostic;
5
+ `examples/node/server.mjs` and `examples/workers/` run it. DESIGN.md says how it works and
6
+ DECISIONS.md why (the P-numbers the code cites).
7
+
8
+ ## 1. Choose how content is shown
9
+
10
+ | | Opaque | Served |
11
+ | --- | --- | --- |
12
+ | Where it runs | A sandboxed frame in your page, origin `null` | A frame on an origin of its own (`a-<id>.example-usercontent.com`) |
13
+ | Server side | None | The host kit (`createContentHost`) |
14
+ | Storage, clean address, open in a tab | No | Yes |
15
+ | Typical | Widgets in a conversation | Stored pages, artifacts, a viewer |
16
+
17
+ Start opaque if you can; add served pages when content needs storage or an address. A served app
18
+ keeps the opaque config as its fallback for when the content domain is down.
19
+
20
+ The config is the source of truth: `presets.inlineWidget()`, `presets.artifact()`,
21
+ `presets.mcpApp()`, `presets.url()` with your options. The same config object (or the same
22
+ options) must be used by the server (it puts the CSP in headers), the page (`createHost`) and the
23
+ agent's manual (`compile(config).guide()`): give it one home and import it everywhere.
24
+
25
+ ## 2. Opaque displays: the page only
26
+
27
+ ```js
28
+ import { createHost, presets } from "@botiverse/porthole";
29
+
30
+ const config = presets.inlineWidget({ capabilities: { openLink: {} } });
31
+ const host = createHost(config, {
32
+ handlers: { openLink: ({ url }) => window.open(url, "_blank", "noopener") },
33
+ // A gated call asks the person first, with the call's whole effect (here: the link).
34
+ confirm: async (request) => window.confirm(`Open ${JSON.stringify(request.args)}?`),
35
+ });
36
+ const display = host.mount(container, { displayId: "w1", title: "A chart", scheme: "light" });
37
+ display.setContent(agentHtml, { partial: true }); // while it streams: drawn inert
38
+ display.setContent(agentHtml); // once whole: it runs, once
39
+ display.on("contentError", ({ message }) => tellTheAgent(message));
40
+ ```
41
+
42
+ React: wrap the app in `<PortholeProvider>`, then
43
+ `<PortholeFrame config={config} displayId={id} title={title} scheme={scheme} content={html} partial={streaming} />`.
44
+
45
+ ## 3. Served pages: the host kit
46
+
47
+ ### Local development
48
+
49
+ Run the app and the content domain on one server: app `http://localhost:8790`, content domain
50
+ `content.localhost:8790` (pages at `http://a-<id>.content.localhost:8790`). Browsers resolve every
51
+ `*.localhost` name to loopback, and each is a site of its own, so the app and its content never
52
+ share cookies or storage. `http` is allowed only on loopback; everything else is `https`.
53
+
54
+ In production the content domain is a registrable domain your app uses for nothing else
55
+ (`example-usercontent.com`), with wildcard DNS and a wildcard certificate pointing at the same
56
+ app. Porthole refuses one that holds or may share a site with an app origin (`ContentDomainError`).
57
+ Put it on the Public Suffix List when you can, so its labels are sites of their own.
58
+
59
+ ### The server
60
+
61
+ ```js
62
+ import { presets } from "@botiverse/porthole";
63
+ import { createContentHost, prefixedName, memoryTicketStore } from "@botiverse/porthole/server";
64
+
65
+ const APP = "http://localhost:8790";
66
+ export const pageConfig = (source) =>
67
+ presets.artifact({ layout: { kind: "fill" }, isolation: "domain", contentOrigins: [source] });
68
+
69
+ const content = createContentHost({
70
+ domain: "content.localhost:8790", // "" turns content off
71
+ appOrigins: [APP],
72
+ secret: process.env.PORTHOLE_SECRET, // npx porthole secret
73
+ tickets: memoryTicketStore(), // one process; d1TicketStore(env.DB) on Workers
74
+ configs: (source) => ({ artifact: pageConfig(source) }),
75
+ name: prefixedName("a-"), // page "abc" is served on a-abc.<domain>
76
+ instance: (proposal) => myInstance(proposal), // what a frame request asks for, as you mean it
77
+ access: async (instance, viewer) => ((await mayView(viewer, instance)) ? { viewer: viewer.id } : null),
78
+ source: (id, version) => myStore.page(id, version), // { html } | null
79
+ entry: { // clean addresses: a-abc.<domain>/ in a new tab
80
+ authorizeUrl: `${APP}/porthole/authorize`,
81
+ at: (scope, path) => instanceAt(scope, path), // null: nothing there (404)
82
+ signIn: (returnTo) => Response.redirect(`${APP}/login?next=${encodeURIComponent(returnTo)}`, 303),
83
+ },
84
+ });
85
+ ```
86
+
87
+ - **`configs`' keys** are the preset names a stored page names: an artifact page names
88
+ `artifact` unless its `document.preset` says otherwise, so key it `artifact`.
89
+ - **`instance`** gets the client's proposal (`{ scope, document }`) and returns the instance as
90
+ your app means it, or null. Derive the scope (the origin) from what it names: the client never
91
+ chooses an origin.
92
+ - **`access`** returns a grant (`{ viewer }`, or `{ anonymous: true }` for a public page) or null.
93
+ `authorize` (optional) checks again on every request after, for revocation.
94
+ - **`Response.redirect` needs an absolute URL** outside a browser (Node throws on `/login`).
95
+ - **`reserved`** is only for labels your app itself serves on the content domain (previews of a
96
+ dev server, `p-*`). Labels nothing serves need nothing: they are a 404 there.
97
+
98
+ Routes: the content domain first, then your app.
99
+
100
+ ```js
101
+ // Node (node:http)
102
+ import { nodeHost, nodeProbe, toRequest, sendResponse } from "@botiverse/porthole/node";
103
+ const porthole = nodeHost(content, { request: (req, res) => app(toRequest(req, "http")).then((r) => sendResponse(res, r)) });
104
+ http.createServer(porthole.request).on("upgrade", porthole.upgrade).listen(8790, () => content.start());
105
+
106
+ // Any fetch-style runtime (Workers, Hono, Bun, Deno)
107
+ const answer = (await content.fetch(request)) ?? (await app(request));
108
+
109
+ // Your app's routes
110
+ "/api/frames" → content.issue(viewerOf)(request) // POST { instance } → 201 { url, origin }
111
+ "/porthole/authorize" → content.authorize(viewerOf)(request) // GET, for clean addresses
112
+ "/api/meta" → content.meta() // { served, contentSource, health }
113
+ ```
114
+
115
+ `viewerOf(request)` is your app's own: who is signed in, from its cookie, or null.
116
+
117
+ ### The page
118
+
119
+ ```html
120
+ <script type="module" nonce="…">
121
+ // A client module that fails to load shows nothing at all: say so.
122
+ import("@botiverse/porthole").then(async ({ createHost, httpLocator }) => {
123
+ const meta = await (await fetch("/api/meta")).json();
124
+ const host = createHost(meta.served ? servedConfig(meta.contentSource) : opaqueConfig, {
125
+ locator: httpLocator("/api/frames"),
126
+ });
127
+ const display = host.mount(box, {
128
+ displayId: id, title, scheme: "light",
129
+ instance: { scope: id, document: { kind: "artifact", id, version } },
130
+ });
131
+ display.on("outcome", (outcome) => { if (outcome.state !== "loaded") offerNewTab(); });
132
+ }, (error) => showProblem(`Porthole didn't load: ${error.message}`));
133
+ </script>
134
+ ```
135
+
136
+ - `servedOrOpaque(meta, servedConfigs, opaqueConfigs)` picks the configs and says nothing until
137
+ meta is known, so a frame never starts opaque and then restarts served.
138
+ - "Open in a new tab" and "Copy link" use `content.urlOf(scope, path)`, the clean address, never a
139
+ ticket URL. Pass it to the page from the server.
140
+ - `outcome` says how the frame loaded: `blocked` with a `reason` (`cookies`: the browser keeps no
141
+ cookie in a frame, as Safari; `sign-in`; `denied`; `session`) is your cue to offer a new tab.
142
+
143
+ ### The page's CSP
144
+
145
+ - `frame-src`: `content.frameSources` (the content origins, and the authorize route).
146
+ `embedderCsp(configs)` gives the same as a directive, from configs alone.
147
+ - **An opaque display inherits your page's CSP.** Its own policy then narrows it, never widens it.
148
+ If your page sets `default-src`, also allow what agent content uses inline:
149
+ `img-src data: blob:`, `media-src data: blob:`, `font-src data:`, `style-src 'unsafe-inline'`,
150
+ `worker-src blob:`. A nonce-based `script-src` works: give `createHost` the nonce
151
+ (`HostOptions.nonce`) and the shell runs content's scripts under it.
152
+ - **`form-action` holds every redirect of a submission.** If your sign-in page posts a form and
153
+ then redirect entry continues to the content origin, a `form-action 'self'` blocks the last
154
+ hop: leave it out there, or add the content source.
155
+
156
+ ## 4. Cloudflare Workers
157
+
158
+ ```js
159
+ import { d1TicketStore } from "@botiverse/porthole/server";
160
+ let app = null;
161
+ export default {
162
+ async fetch(request, env) {
163
+ app ??= makeApp({ ...settingsFrom(env), tickets: d1TicketStore(env.DB) }); // once per isolate
164
+ return (await app.content.fetch(request)) ?? app.handle(request);
165
+ },
166
+ };
167
+ ```
168
+
169
+ - **Tickets in D1** (never KV, which is eventually consistent):
170
+ `npx porthole d1-schema > migrations/0001_porthole_tickets.sql`, then
171
+ `wrangler d1 migrations apply <db>`.
172
+ - **One secret, `PORTHOLE_SECRET`:** `npx porthole secret`, then `wrangler secret put
173
+ PORTHOLE_SECRET` (`.dev.vars` locally). At least 32 bytes; it signs tickets, cookies and
174
+ entry codes.
175
+ - **Static assets:** set `"assets": { "run_worker_first": true }`. Otherwise Workers serves your
176
+ static files before the Worker runs, on every host, content origins included.
177
+ - No `nodejs_compat` needed. `wrangler dev` passes the Host through, so
178
+ `*.content.localhost:<port>` works locally.
179
+
180
+ ## 5. The agent's side
181
+
182
+ - `compile(config).toolDescription()` is your show tool's description; `compile(config).guide()`
183
+ the manual (topics: `widget`, `interactive`, `chart`, and yours). Set `guide.toolName` and
184
+ `guide.guideToolName` so they name your tools.
185
+ - A tool definition, as an MCP server lists it:
186
+
187
+ ```js
188
+ { name: "show_page", description: compiled.toolDescription(),
189
+ inputSchema: { type: "object", required: ["title", "html"],
190
+ properties: { title: { type: "string" }, html: { type: "string", description: "The whole HTML document" } } } }
191
+ ```
192
+
193
+ - **Fill:** a whole-page viewer says `layout: { kind: "fill" }` in its config. The frame then fills
194
+ its box, and the manual tells the agent so (the page scrolls itself; `position: fixed` works).
195
+ `MountOptions.fill` and `<PortholeFrame fill>` are deprecated: they size the frame but leave the
196
+ manual saying the height follows the content.
197
+ - `errors: "agent"` sends what content throws (and what the sandbox blocks) back to the agent:
198
+ listen for `contentError` and pass it on.
199
+
200
+ ## 6. Conformance: prove your integration
201
+
202
+ `@botiverse/porthole/conformance` runs Porthole's suite (egress and escape probes, the served
203
+ cases, redirect entry) against your app's real page, its CSP and session, in Playwright:
204
+
205
+ ```js
206
+ // playwright.config.mjs
207
+ import { defineConfig, devices } from "@playwright/test";
208
+ import { conformanceProjects } from "@botiverse/porthole/conformance";
209
+ export default defineConfig({ projects: conformanceProjects(devices), webServer: { … } });
210
+
211
+ // porthole.spec.mjs
212
+ import { test } from "@playwright/test";
213
+ import { defineHostConformance } from "@botiverse/porthole/conformance";
214
+ defineHostConformance(test, {
215
+ name: "my-app",
216
+ open: async (page) => { /* sign in, open the page that shows content */ },
217
+ issue: { url: "/api/frames" },
218
+ config: () => pageConfig("http://*.content.localhost:8790"),
219
+ instances: { artifact: (scope, version) => ({ scope, document: { kind: "artifact", id: "conformance", version } }) },
220
+ entry: { url: (scope) => `http://a-t-${scope}.content.localhost:8790/v/1`, unknown: "derive" },
221
+ });
222
+ ```
223
+
224
+ What the runner asks of your app, and what it skips without:
225
+
226
+ | Option | It needs | Without it |
227
+ | --- | --- | --- |
228
+ | `instances.artifact(scope, version)` | versions `"1"` and `"2"` of one stored page on `scope`'s origin, each exactly `conformancePage(version)` | the stored-page case |
229
+ | `instances.shell(scope)` | a served shell | the domain cases run on `artifact(scope, "1")` |
230
+ | `instances.app`, `.proxy` | a url-mode app, the MCP Apps proxy | their cases |
231
+ | `entry.url(scope)` | the clean address of `artifact(scope, "1")` | the redirect entry cases |
232
+ | `entry.denied`, `atSignIn`, `completeSignIn` | a page the viewer may not see; your sign-in page | that case; the sign-in is judged by leaving the content origin, and not completed |
233
+ | `entry.unknown` | addresses that name nothing, or `"derive"` | that case |
234
+
235
+ The suite names its own scopes, so an app serves them through a **test mode**
236
+ (`examples/app.mjs`: `PORTHOLE_CONFORMANCE=1`): the test page under `t-<scope>`, and a private
237
+ page. **Never ship test mode**: with it, anyone signed in can make content origins of their
238
+ choosing. `onDemand(make)` memoizes fixtures made the first time a case asks (a page published
239
+ on demand); `instances` and `entry.url` may be async.
240
+
241
+ The leak probes run opaque displays on your page: where its own CSP closes what a probe needs,
242
+ the probe reports itself inapplicable, saying which directive. Those are facts about your page's
243
+ opaque fallback, not failures.
244
+
245
+ ## 7. Expected, and how to tell
246
+
247
+ - Chromium logs `Unrecognized Content-Security-Policy directive 'webrtc'` for every frame: the
248
+ directive closes WebRTC where an engine knows it, and is ignored where it doesn't.
249
+ - Content's CSP allows `'unsafe-eval'`. Content is the agent's own script already
250
+ (`'unsafe-inline'`), so eval adds no capability, and libraries content uses compile with it
251
+ (Vue's in-browser build, Alpine.js, Vega's expressions, WebAssembly). Egress, the sandbox and the
252
+ origin are what isolate it (P071).
253
+ - On `http` loopback the session cookies are `porthole-<key>`; on `https`, `__Host-porthole-<key>`.
254
+ - A clean address that names nothing (a label the naming never makes, the bare domain, a path
255
+ `entry.at` says has nothing) is a 404 on the content domain: it never reaches your sign-in.
256
+ - Host errors name the content origin and leave out ticket URLs.
257
+
258
+ ## 8. Reference
259
+
260
+ | Import | What |
261
+ | --- | --- |
262
+ | `@botiverse/porthole` | `createHost`, `presets`, `compile`, `embedderCsp`, `httpLocator`, `servedOrOpaque` |
263
+ | `@botiverse/porthole/react` | `PortholeProvider`, `PortholeFrame` |
264
+ | `@botiverse/porthole/server` | `createContentHost`, `prefixedName`, `memoryTicketStore`, `d1TicketStore`, `contentDomain`, `conformancePage`, the callbacks' types |
265
+ | `@botiverse/porthole/node` | `nodeHost`, `nodeProbe`, `toRequest`, `sendResponse` |
266
+ | `@botiverse/porthole/mcp` | the MCP Apps adapter (views, the sandbox proxy) |
267
+ | `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage` |
268
+
269
+ The types' doc comments are the precise reference; DESIGN.md § "The host kit" is the long form.