@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.
Files changed (38) 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/DECISIONS.md +37 -0
  20. package/docs/DESIGN.md +13 -6
  21. package/examples/app.mjs +234 -0
  22. package/examples/conformance/playwright.config.mjs +28 -0
  23. package/examples/conformance/porthole.spec.mjs +36 -0
  24. package/examples/node/server.mjs +75 -0
  25. package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
  26. package/examples/workers/worker.mjs +33 -0
  27. package/examples/workers/wrangler.jsonc +19 -0
  28. package/package.json +7 -2
  29. package/src/cli.ts +54 -0
  30. package/src/conformance/entry.ts +33 -11
  31. package/src/conformance/host-kit.ts +127 -21
  32. package/src/conformance/index.ts +4 -0
  33. package/src/conformance/limits.ts +21 -4
  34. package/src/conformance/page.ts +8 -0
  35. package/src/host/types.ts +6 -3
  36. package/src/isolation/served.ts +12 -2
  37. package/src/react/frame.tsx +5 -2
  38. 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";
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) plus `blob:` and the script origins; each other
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 kit reference app, `packages/porthole/leak/kit/app.ts`, is
355
- this, runnable):
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.CONTENT_SECRET, tickets: d1TicketStore(env.DB),
362
- configs: (source) => ({ page: presets.artifact({ isolation: "domain", contentOrigins: [source] }) }),
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
- signIn: (returnTo) => Response.redirect(`/login?next=${encodeURIComponent(returnTo)}`, 303),
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
  });