@botiverse/porthole 0.3.0 → 0.3.2

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 (56) hide show
  1. package/README.md +3 -2
  2. package/dist/check/check.d.ts +20 -3
  3. package/dist/check/check.js +88 -25
  4. package/dist/check/drivers.d.ts +25 -6
  5. package/dist/check/drivers.js +99 -28
  6. package/dist/check/index.d.ts +2 -2
  7. package/dist/check/index.js +1 -1
  8. package/dist/check/instrument.d.ts +71 -0
  9. package/dist/check/instrument.js +84 -0
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/page.d.ts +2 -40
  12. package/dist/check/page.js +63 -43
  13. package/dist/conformance/harness-source.d.ts +2 -0
  14. package/dist/conformance/harness-source.js +2 -0
  15. package/dist/conformance/host-kit.d.ts +20 -7
  16. package/dist/conformance/host-kit.js +42 -48
  17. package/dist/conformance/index.d.ts +1 -1
  18. package/dist/conformance/reporter.d.ts +14 -0
  19. package/dist/conformance/reporter.js +28 -0
  20. package/dist/host/client.d.ts +33 -15
  21. package/dist/host/client.js +39 -24
  22. package/dist/node/index.d.ts +6 -2
  23. package/dist/node/index.js +53 -8
  24. package/dist/react/frame.d.ts +13 -5
  25. package/dist/react/frame.js +67 -27
  26. package/dist/react/index.d.ts +1 -1
  27. package/dist/react/view.js +6 -1
  28. package/dist/server/host.d.ts +5 -3
  29. package/dist/server/host.js +41 -12
  30. package/docs/ADOPTING.md +115 -26
  31. package/docs/DECISIONS.md +167 -0
  32. package/docs/DESIGN.md +38 -13
  33. package/examples/app.mjs +23 -17
  34. package/examples/conformance/playwright.config.mjs +2 -1
  35. package/examples/conformance/porthole.spec.mjs +2 -1
  36. package/examples/displays.mjs +2 -0
  37. package/examples/node/server.mjs +16 -34
  38. package/examples/workers/worker.mjs +19 -7
  39. package/package.json +9 -3
  40. package/src/check/check.ts +122 -25
  41. package/src/check/drivers.ts +137 -39
  42. package/src/check/index.ts +8 -1
  43. package/src/check/instrument.ts +138 -0
  44. package/src/check/page-source.ts +4 -3
  45. package/src/check/page.ts +94 -68
  46. package/src/conformance/harness-source.ts +23 -0
  47. package/src/conformance/host-kit.ts +69 -46
  48. package/src/conformance/index.ts +1 -0
  49. package/src/conformance/reporter.ts +38 -0
  50. package/src/host/client.ts +65 -34
  51. package/src/node/index.ts +56 -10
  52. package/src/react/frame.tsx +89 -33
  53. package/src/react/index.ts +1 -0
  54. package/src/react/view.tsx +6 -1
  55. package/src/server/host.ts +53 -15
  56. package/dist/conformance/harness.js +0 -1662
@@ -90,10 +90,17 @@ export function createContentHost(options) {
90
90
  if (options.configs === undefined && options.displays === undefined) {
91
91
  throw new TypeError("createContentHost needs configs or displays");
92
92
  }
93
- const secret = typeof options.secret === "string" ? utf8(options.secret.trim()) : options.secret;
93
+ // The secret as given (an unset environment variable: none), checked with the domain below.
94
+ const secret = typeof options.secret === "string"
95
+ ? utf8(options.secret.trim())
96
+ : options.secret instanceof Uint8Array
97
+ ? options.secret
98
+ : null;
94
99
  const healthLabel = gate?.label ?? DEFAULT_HEALTH_LABEL;
95
100
  // The id Porthole's health check answers with: keyed, so another deployment's answer fails.
96
- const healthId = base64url(hmacSha256(secret, utf8("porthole/health"))).slice(0, 22);
101
+ const healthId = secret === null || secret.byteLength < 32
102
+ ? ""
103
+ : base64url(hmacSha256(secret, utf8("porthole/health"))).slice(0, 22);
97
104
  const appReserved = reservedLabels(options.reserved);
98
105
  let domain = null;
99
106
  let server = null;
@@ -105,6 +112,13 @@ export function createContentHost(options) {
105
112
  ? options.domain
106
113
  : contentDomain(options.domain, { appOrigins: options.appOrigins });
107
114
  if (domain !== null) {
115
+ // Said plainly where it's missing, as where it's short (P074).
116
+ if (secret === null) {
117
+ throw new TypeError("createContentHost needs a secret: at least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)");
118
+ }
119
+ if (secret.byteLength < 32) {
120
+ throw new TypeError("The secret must be at least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)");
121
+ }
108
122
  if (options.entry !== undefined && options.name?.scopeOf === undefined) {
109
123
  throw new TypeError("Redirect entry needs a naming that says which scope a label names (prefixedName)");
110
124
  }
@@ -302,7 +316,8 @@ export function createContentHost(options) {
302
316
  };
303
317
  // The viewer handoff (P072): a key Porthole signs, naming the app's viewer until a time, in a
304
318
  // cookie only the prefix's routes get. Never the app's own credential.
305
- const handoffKey = hmacSha256(secret, utf8("porthole/handoff"));
319
+ // None where the secret can't sign (then nothing is served, and no handoff made or taken).
320
+ const handoffKey = secret === null || secret.byteLength < 32 ? null : hmacSha256(secret, utf8("porthole/handoff"));
306
321
  const secureApp = (options.appOrigins[0] ?? "").startsWith("https:");
307
322
  const handoffName = secureApp ? "__Secure-porthole-handoff" : "porthole-handoff";
308
323
  const handoffCookie = (value, maxAge) => [
@@ -313,14 +328,14 @@ export function createContentHost(options) {
313
328
  `Max-Age=${maxAge}`,
314
329
  ...(secureApp ? ["Secure"] : []),
315
330
  ].join("; ");
316
- const signHandoff = (id, until) => {
331
+ const signHandoff = (key, id, until) => {
317
332
  const payload = base64url(utf8(JSON.stringify({ h: 1, v: id, x: until })));
318
- return `${payload}.${base64url(hmacSha256(handoffKey, utf8(payload)))}`;
333
+ return `${payload}.${base64url(hmacSha256(key, utf8(payload)))}`;
319
334
  };
320
335
  /** The viewer a request's handoff cookie names, if it is good. */
321
336
  const handedOver = async (request) => {
322
337
  const handoff = options.entry?.handoff;
323
- if (handoff === undefined) {
338
+ if (handoff === undefined || handoffKey === null) {
324
339
  return null;
325
340
  }
326
341
  for (const part of (request.headers.get("cookie") ?? "").split(";")) {
@@ -356,14 +371,25 @@ export function createContentHost(options) {
356
371
  }
357
372
  return null;
358
373
  };
374
+ /**
375
+ * Where the person comes back after signing in: the authorize route as the app is reached
376
+ * (`authorizeUrl`'s origin and path), with this request's query (its state). Never the request's
377
+ * own URL, whose origin behind a TLS edge or a dev proxy isn't the app's (P074).
378
+ */
379
+ const returnOf = (request) => {
380
+ const back = new URL(authorizeUrl);
381
+ back.search = new URL(request.url).search;
382
+ return back.href;
383
+ };
359
384
  /** The app's sign-in: its own `signIn`, or its single-page route with `next`. */
360
385
  const signInWith = async (entry, request, context) => {
386
+ const returnTo = returnOf(request);
361
387
  if (entry.signIn !== undefined) {
362
- return entry.signIn(request.url, request, context);
388
+ return entry.signIn(returnTo, request, context);
363
389
  }
364
390
  const route = entry.spa?.route ?? "/";
365
- const to = new URL(route, options.appOrigins[0]);
366
- to.searchParams.set("next", request.url);
391
+ const to = new URL(route, new URL(authorizeUrl).origin);
392
+ to.searchParams.set("next", returnTo);
367
393
  return new Response(null, {
368
394
  status: 303,
369
395
  headers: { location: to.href, "cache-control": "no-store", "referrer-policy": "no-referrer" },
@@ -456,10 +482,10 @@ export function createContentHost(options) {
456
482
  catch (error) {
457
483
  return refusal(409, "refused", error instanceof Error ? error.message : String(error));
458
484
  }
459
- // The clean address, where the app says the instance's path (P072).
460
- const path = options.entry?.pathOf?.(instance) ?? null;
485
+ // The clean address, where the app says the instance's path (P072, P074).
461
486
  let link = null;
462
487
  try {
488
+ const path = (await options.entry?.pathOf?.(instance, request)) ?? null;
463
489
  link = path === null ? null : server.urlOf(instance.scope, path);
464
490
  }
465
491
  catch {
@@ -555,7 +581,10 @@ export function createContentHost(options) {
555
581
  if (typeof id !== "string" || id.length === 0 || id.length > 512) {
556
582
  return refusal(500, "failed", "entry.handoff.id gave no id (1 to 512 characters)");
557
583
  }
558
- const key = signHandoff(id, Date.now() + HANDOFF_SECONDS * 1_000);
584
+ if (handoffKey === null) {
585
+ return refusal(503, "unavailable", "The content domain isn't served");
586
+ }
587
+ const key = signHandoff(handoffKey, id, Date.now() + HANDOFF_SECONDS * 1_000);
559
588
  return new Response(null, {
560
589
  status: 204,
561
590
  headers: {
package/docs/ADOPTING.md CHANGED
@@ -2,7 +2,8 @@
2
2
 
3
3
  How to put Porthole in an app, from the npm package alone. The package's `examples/` is a whole
4
4
  app that does everything below: `examples/app.mjs` is the app, runtime-agnostic;
5
- `examples/node/server.mjs` and `examples/workers/` run it; `examples/mcp/server.mjs` gives the
5
+ `examples/node/server.mjs` (`nodeServer`) and `examples/workers/` (`contentHostFor`) run it, as
6
+ §4 and §5 recommend; `examples/mcp/server.mjs` gives the
6
7
  agent its tools. DESIGN.md says how it works and DECISIONS.md why (the P-numbers the code cites).
7
8
 
8
9
  ## 1. Choose how content is shown
@@ -61,8 +62,10 @@ React: `<PortholeProvider>` near the root; `<PortholeFrame config displayId titl
61
62
  per display. The provider takes what every frame shares: `scheme`, `theme` (and `themeKey`;
62
63
  `cssVariableTheme(tokens)` reads the values from your page's CSS variables), `nonce` (`"auto"`
63
64
  reads the page's), `handlers`, `openLink` (default: a new tab), `notify` (your own toast for what
64
- a copy button copied), and `renderConfirm` (your own dialog: Porthole keeps the queue, runs your
65
- yes inside its click, and counts declines). `useRunAgain()` gives a "run again" button.
65
+ a copy button copied), and `renderConfirm` (your own dialog, given `accept`, `decline` and
66
+ `redirect`: Porthole keeps the queue, runs `accept` inside its click, and counts declines toward
67
+ muting the display; `redirect`, for "edit it first", answers the call `"redirected"` and neither
68
+ counts nor resets the count). `useRunAgain()` gives a "run again" button.
66
69
 
67
70
  ## 4. Served pages: the host kit
68
71
 
@@ -82,6 +85,7 @@ Put it on the Public Suffix List when you can, so its labels are sites of their
82
85
 
83
86
  ```js
84
87
  import { createContentHost, prefixedName, memoryTicketStore } from "@botiverse/porthole/server";
88
+ import { nodeServer } from "@botiverse/porthole/node";
85
89
  import { displays } from "./displays.mjs";
86
90
 
87
91
  const APP = "http://localhost:8790";
@@ -97,15 +101,15 @@ const content = createContentHost({
97
101
  source: (id, version) => myStore.page(id, version), // { html } | null
98
102
  entry: { // clean addresses: a-abc.<domain>/ in a new tab
99
103
  at: (scope, path) => instanceAt(scope, path), // null: nothing there (a 404 on the content domain)
100
- pathOf: (instance) => pathOf(instance), // the reverse: frames come with their link
104
+ pathOf: async (instance) => pathOf(instance), // the reverse (may look it up): frames come with their link
101
105
  signIn: (returnTo) => Response.redirect(`${APP}/login?next=${encodeURIComponent(returnTo)}`, 303),
102
106
  },
103
107
  });
104
108
 
105
109
  // One mount, under /porthole: POST frames, GET authorize, GET meta, POST/DELETE handoff.
106
110
  const routes = content.routes(viewerOf);
107
- // Every request: the content domain first, then Porthole's routes, then your app.
108
- const answer = (await content.fetch(request)) ?? (await routes(request)) ?? (await app(request));
111
+ // The whole server: the content domain to Porthole, then Porthole's routes, then your app.
112
+ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(request) }).listen(8790);
109
113
  ```
110
114
 
111
115
  - **`instance`** gets the client's proposal (`{ scope, document }`) and returns the instance as
@@ -117,10 +121,21 @@ const answer = (await content.fetch(request)) ?? (await routes(request)) ?? (awa
117
121
  - **`Response.redirect` needs an absolute URL** outside a browser (Node throws on `/login`).
118
122
  - **`reserved`** is only for labels your app itself serves on the content domain (previews of a
119
123
  dev server, `p-*`). Labels nothing serves need nothing: they are a 404 there.
120
- - **Node:** `nodeServer({ content, app: (request) => answer(request) }).listen(8790)` is the whole
121
- server, WebSockets included, the health gate started on listen. **Workers:**
122
- `contentHostFor((env) => options)` makes one host per `env`, and answers a plain 503 naming the
123
- problem when the settings can't be served.
124
+ - **No content domain** (self-hosted without one): still make the host, with `domain: null` (or
125
+ `""`). That is the supported setup: no secret is needed, `GET /porthole/meta` answers
126
+ `{ served: false }`, and pages show every kind opaque (a url kind, its fallback) instead of
127
+ waiting for a meta that never comes. Without a host, `portholeClient` stays pending.
128
+ - **`secret`** is at least 32 random bytes (`npx porthole secret`), from the environment
129
+ (`PORTHOLE_SECRET`). A missing or short one throws at `createContentHost`, saying so (with
130
+ `health`, frames stay opaque and the meta says why).
131
+ - **`nodeServer`** is the whole Node server: the content domain to Porthole, WebSockets included,
132
+ every other request to `app` (fetch-style: Hono's `app.fetch`) or `request` (a Node listener:
133
+ Express), the health gate started on listen and stopped on close. Behind a TLS edge, add
134
+ `scheme: "https"`. A host that needs the port first (`listen(0)`) can come later: `content:
135
+ () => host` (null until made); requests go to the app until it gives one.
136
+ - **`nodeHost(content, { request })`** is for an app that keeps its own `node:http` server (or a
137
+ framework that owns one): put its `request` and `upgrade` listeners on your server, call
138
+ `content.start()` once it listens and `content.close()` when it stops.
124
139
  - **Health:** `health: { probe: nodeProbe(), onServedChange: (served) => … }` checks the content
125
140
  domain over the real network and falls back to opaque frames while it doesn't answer.
126
141
 
@@ -144,10 +159,26 @@ openButton.onclick = () => porthole.openInTab(instance); // the clean
144
159
 
145
160
  `porthole.config(kind)` is the served config while frames are served, the opaque one while they
146
161
  aren't, and null until the meta is known, so a frame never starts opaque and then restarts
147
- served. A client module that fails to load shows nothing at all: catch its import and say so
162
+ served. The client's functions take no `this`: pass them bare
163
+ (`useSyncExternalStore(porthole.subscribe, porthole.meta)`). A client module that fails to load shows nothing at all: catch its import and say so
148
164
  (`examples/app.mjs` does).
149
165
 
150
- React: give the provider the client, and show a kind:
166
+ **Without a bundler**, the page gets Porthole's browser modules from your server, in three parts
167
+ (`examples/app.mjs` has all three):
168
+
169
+ 1. Serve the package's `dist/` at a path of your app's (`/porthole-client/`, `.js` files only).
170
+ On Workers it is the static assets directory (`assets.directory`, with `run_worker_first`).
171
+ 2. Map the bare name in an import map that carries the page's nonce:
172
+ `<script type="importmap" nonce="…">{"imports":{"@botiverse/porthole":"/porthole-client/index.js"}}</script>`.
173
+ 3. Serve the page its display kinds as a module, made from the same plain object the server's
174
+ `defineDisplays` gets, so they never disagree:
175
+ `` `import { defineDisplays } from "@botiverse/porthole";\nexport const displays = defineDisplays(${JSON.stringify(kinds)});` ``
176
+ at `/porthole-client/displays.mjs`, imported from there.
177
+
178
+ With a bundler, import `@botiverse/porthole` and your `displays.mjs` as usual.
179
+
180
+ React: give the provider the client, and show a kind. Flipping the provider's `scheme`, or a new
181
+ `themeKey`, re-themes running frames in place: they keep their state.
151
182
 
152
183
  ```jsx
153
184
  <PortholeProvider client={porthole} scheme={mode} theme={cssVariableTheme(TOKENS)} nonce="auto">
@@ -157,6 +188,10 @@ React: give the provider the client, and show a kind:
157
188
  // const { link, open, copy } = usePortholeLink(instance); "Open in a new tab", "Copy link"
158
189
  ```
159
190
 
191
+ Rendered on a server, `PortholeView` draws what the client's meta says: give `portholeClient` the
192
+ meta it starts with (`meta`, from your page's data), and the server's HTML has the frame's
193
+ placeholder or the fallback, which the page then hydrates. Without it, `pending`.
194
+
160
195
  ### The page's CSP
161
196
 
162
197
  - `frame-src`: `content.frameSources` (the content origins, and the authorize route), also in
@@ -169,9 +204,15 @@ React: give the provider the client, and show a kind:
169
204
 
170
205
  ### Sign-in
171
206
 
172
- - Your sign-in page gets the authorize URL as `next`, and goes back to it when signed in. Check
173
- it with `entryTarget(next, authorizeUrl)` (or `porthole.entryTarget(next)`): only your own
174
- authorize route, never another site.
207
+ - Your sign-in page gets the authorize URL as `next` (`signIn`'s `returnTo`), and goes back to it
208
+ when signed in. The authorize URL is `<first app origin>/porthole/authorize` unless
209
+ `entry.authorizeUrl` names another, and `next` is built from it with the entry's state: never
210
+ from the address the request arrived at, which behind a TLS edge or a dev proxy isn't your app's.
211
+ - Check `next` with `entryTarget(next, authorizeUrl, { app: true })` (in the page,
212
+ `porthole.entryTarget(next, { app: true })`): the authorize route or any page on your app's
213
+ origin, as an absolute URL, and null for anything else (another site, `//host`, `/\host`,
214
+ `javascript:`), so one check serves sign-ins that go back to a page and those that go back to
215
+ a frame's content. Without `{ app: true }` it takes only the authorize route.
175
216
  - **Warning: no `form-action 'self'` on a sign-in page that posts a form.** `form-action` holds
176
217
  every redirect of a submission, and redirect entry continues from your sign-in through the
177
218
  content origin, so the browser blocks the last hop and the person stays on your sign-in. Leave
@@ -211,6 +252,13 @@ export default {
211
252
  };
212
253
  ```
213
254
 
255
+ - **`contentHostFor`** makes one content host per `env`, the first time a request needs it. While
256
+ the settings can't be served (no `PORTHOLE_SECRET`, a content domain that shares a site with the
257
+ app), every request gets a plain 503 naming the problem, logged once (`{ log }`), instead of a
258
+ stack trace. `porthole.host(env)` is the host itself (`frameSources` for your CSP) once `fetch`
259
+ has answered null. Settings fixed at build time (no `env`) can make one `createContentHost` at
260
+ module scope instead; a bad setting then fails the Worker as it starts.
261
+
214
262
  - **Tickets in D1** (never KV, which is eventually consistent):
215
263
  `npx porthole d1-schema > migrations/0001_porthole_tickets.sql`, then
216
264
  `wrangler d1 migrations apply <db>`.
@@ -236,8 +284,10 @@ const tools = [showTool(config), guideTool(config), checkTool(config)]; // { nam
236
284
  // guide: answerGuide(config, args) // { text } or { error }
237
285
  ```
238
286
 
239
- Names come from the config (`guide.toolName`, `guide.guideToolName`); the descriptions are the
240
- manual's own words. `examples/mcp/server.mjs` wires all three as an MCP server.
287
+ Names come from the config (`guide.toolName`, `guide.guideToolName`), else `show_<noun>`,
288
+ `<noun>_guide` and `check_<noun>` (`show_page`, `page_guide`, `check_page` for a page; naming them
289
+ in the config also has the manual name them). The descriptions are the manual's own words.
290
+ `examples/mcp/server.mjs` wires all three as an MCP server.
241
291
 
242
292
  - **`admitContent`** runs `lintContent` and refuses (by default, `refuseOn: "error"`) only what
243
293
  would certainly fail or be cut: over the size limit, a document with no body where a fragment
@@ -254,7 +304,20 @@ manual's own words. `examples/mcp/server.mjs` wires all three as an MCP server.
254
304
  `checkPage` (`@botiverse/porthole/check`) runs the content in the real sandbox at the manual's
255
305
  phone and desktop widths, in light and dark, and answers a report whose `text` is a few lines for
256
306
  the agent: what it threw, what the sandbox blocked, what failed to load, `console.error`, overflow
257
- and a cut height, each problem once with where it happened (at most 8; the rest counted).
307
+ and a cut height, each problem once with where it happened (at most 8; the rest counted). Lines
308
+ are the content's own, as the agent wrote it (a script's error and a lint finding name the same
309
+ line).
310
+
311
+ A served config is checked served: its content runs on an origin of its own under Porthole's
312
+ server, with the served CSP, shell, storage and cookies, as people's browsers run it (both drivers
313
+ answer a reserved content domain themselves; nothing goes to your server). An opaque config, or
314
+ an MCP Apps view, runs opaque.
315
+
316
+ The host functions the config declares are answered as a host that declines would: a person
317
+ asked to confirm says no, and a handler answers no (no prompt sent, a tool call refused). Each
318
+ call is in the report (`run.calls`): one hosts refuse whatever the person says (no click, bad
319
+ arguments) is a problem; one a person may decline is a note, so the agent makes sure the page
320
+ still works then.
258
321
 
259
322
  ```js
260
323
  import { checkPage, playwrightDriver } from "@botiverse/porthole/check";
@@ -263,7 +326,7 @@ report.ok; report.text;
263
326
  ```
264
327
 
265
328
  It needs a browser somewhere: Chromium is best (WebKit mutes a thrown error's message in an
266
- opaque frame, so the agent reads only "Script error."). Where:
329
+ opaque frame, so the agent reads only "Script error.", and names no line in a served one). Where:
267
330
 
268
331
  - **A server with Chromium** (Node): `playwrightDriver(await chromium.launch())`.
269
332
  - **An agent on a person's machine, maybe without Chromium** (Ferry's daemon): run
@@ -275,13 +338,19 @@ opaque frame, so the agent reads only "Script error."). Where:
275
338
  ```js
276
339
  import puppeteer from "@cloudflare/puppeteer";
277
340
  import { cdpDriver, checkPage } from "@botiverse/porthole/check";
278
- import page from "@botiverse/porthole/check/page"; // the check page's script, bundled
279
341
  const browser = await puppeteer.launch(env.BROWSER);
280
342
  const tab = await browser.newPage();
281
- const report = await checkPage({ config, content, page, driver: cdpDriver(() => tab.createCDPSession()) });
343
+ const report = await checkPage({ config, content, driver: cdpDriver(() => tab.createCDPSession()) }); // no cast
282
344
  await browser.close();
283
345
  ```
284
346
 
347
+ **Bundling:** every entry point bundles whole (a Worker, a single executable): `/check` imports
348
+ its check page's script as a module, and `/conformance` its harness, so nothing is looked up
349
+ beside a module at run time. Each release is bundled with rolldown and esbuild and checked for
350
+ that before it is published (`test:bundle`). `/conformance`, which runs under Playwright, still
351
+ looks for the optional MCP Apps App SDK where it runs; without it, the App SDK probes say so and
352
+ don't run.
353
+
285
354
  ## 7. Conformance: prove your integration
286
355
 
287
356
  `@botiverse/porthole/conformance` runs Porthole's suite (egress and escape probes, the served
@@ -291,7 +360,16 @@ cases, redirect entry) against your app's real page, its CSP and session, in Pla
291
360
  // playwright.config.mjs
292
361
  import { defineConfig, devices } from "@playwright/test";
293
362
  import { conformanceProjects } from "@botiverse/porthole/conformance";
294
- export default defineConfig({ projects: conformanceProjects(devices), webServer: { … } });
363
+ export default defineConfig({
364
+ fullyParallel: true, // else one spec file is one worker: minutes longer
365
+ // The list, then why each skipped case was skipped (the list alone shows a bare "-").
366
+ reporter: [["list"], ["@botiverse/porthole/conformance/reporter"]],
367
+ projects: conformanceProjects(devices, {
368
+ engines: ["chromium", "webkit", "firefox"], // the default
369
+ // launchOptions: { chromium: { executablePath: "/usr/bin/chromium" } }, a system browser
370
+ }),
371
+ webServer: { … },
372
+ });
295
373
 
296
374
  // porthole.spec.mjs
297
375
  import { test } from "@playwright/test";
@@ -300,7 +378,7 @@ defineHostConformance(test, {
300
378
  name: "my-app",
301
379
  open: async (page) => { /* sign in, open the page that shows content */ },
302
380
  issue: { url: "/porthole/frames" },
303
- displays, contentSource: "http://*.content.localhost:8790",
381
+ displays, contentSource: () => `http://*.content.localhost:${port}`, // asked per case: a port known later
304
382
  instances: { artifact: (scope, version) => ({ scope, document: { kind: "artifact", id: "conformance", version } }) },
305
383
  entry: { url: (scope) => `http://a-t-${scope}.content.localhost:8790/v/1`, unknown: "derive" },
306
384
  });
@@ -324,9 +402,16 @@ choosing. `onDemand(make)` memoizes fixtures made the first time a case asks (a
324
402
  on demand); `instances` and `entry.url` may be async. The tests are located at your
325
403
  `defineHostConformance` call, so `playwright test porthole.spec.mjs` selects them.
326
404
 
405
+ Each engine needs its browser (`npx playwright install chromium webkit firefox`); a subset is
406
+ `engines: ["chromium"]`. Where Playwright has no build of one (arm64 Linux's Chromium), point at
407
+ the system's: `launchOptions: { chromium: { executablePath, args } }`, merged with Porthole's own
408
+ (`use` adds to every project's).
409
+
327
410
  The leak probes run opaque displays on your page: where its own CSP closes what a probe needs,
328
411
  the probe reports itself inapplicable, saying which directive. Those are facts about your page's
329
- opaque fallback, not failures.
412
+ opaque fallback, not failures: a page with a `default-src` sees `[1.connect]` and
413
+ `[2.resources]` skipped, its `connect-src` already closing what they probe. The reporter above
414
+ prints each reason at the end; so does `--reporter=json`.
330
415
 
331
416
  ## 8. Expected, and how to tell
332
417
 
@@ -337,6 +422,10 @@ opaque fallback, not failures.
337
422
  (Vue's in-browser build, Alpine.js, Vega's expressions, WebAssembly). Egress, the sandbox and the
338
423
  origin are what isolate it (P071).
339
424
  - On `http` loopback the session cookies are `porthole-<key>`; on `https`, `__Host-porthole-<key>`.
425
+ A frame's are `Secure; SameSite=None; Partitioned` on loopback too: browsers keep `Secure`
426
+ cookies on `localhost`.
427
+ - A served frame is one iframe on the content's own origin (no frame inside it), first loaded at
428
+ `/__porthole/d/<key>?ticket=…`: in a test, `page.frameLocator('iframe[src*="/__porthole/d/"]')`.
340
429
  - A clean address that names nothing (a label the naming never makes, the bare domain, a path
341
430
  `entry.at` says has nothing) is a 404 on the content domain: it never reaches your sign-in.
342
431
  - Host errors name the content origin and leave out ticket URLs.
@@ -349,8 +438,8 @@ opaque fallback, not failures.
349
438
  | `@botiverse/porthole/react` | `PortholeProvider`, `PortholeFrame`, `PortholeView`, `usePortholeLink`, `cssVariableTheme`, `useRunAgain` |
350
439
  | `@botiverse/porthole/server` | `createContentHost` (`routes`, `forget`), `contentHostFor`, `prefixedName`, `memoryTicketStore`, `d1TicketStore`, `upstreamHeaders`, `statusPage`, `conformancePage`, the callbacks' types |
351
440
  | `@botiverse/porthole/node` | `nodeServer`, `nodeHost`, `nodeProbe`, `toRequest`, `sendResponse` |
352
- | `@botiverse/porthole/check` | `checkPage`, `playwrightDriver`, `cdpDriver`; `/check/page`, the check page's script |
441
+ | `@botiverse/porthole/check` | `checkPage`, `playwrightDriver`, `cdpDriver` (`CHECK_ORIGIN`, `CHECK_CONTENT_DOMAIN`: the names a driver of your own answers); `/check/page`, the check page's script (`checkPage` has it already) |
353
442
  | `@botiverse/porthole/mcp` | the MCP Apps adapter (views, the sandbox proxy) |
354
- | `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage` |
443
+ | `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage`; `/conformance/reporter`, skip reasons |
355
444
 
356
445
  The types' doc comments are the precise reference; DESIGN.md § "The host kit" is the long form.
package/docs/DECISIONS.md CHANGED
@@ -1955,3 +1955,170 @@ document's width to the page by `postMessage`. Height comes from the display's o
1955
1955
  and MCP Apps presets at the manual's widths in light and dark, on three engines
1956
1956
  (`leak/check.spec.ts`); a broken widget is told each problem once; the CDP driver runs on
1957
1957
  Chromium.
1958
+
1959
+ ## P074 · 2026-10-12 · 0.3.1: sign-in behind a proxy, pages checked as they run, and what 0.3.0's adopters had to guess · Accepted
1960
+
1961
+ **Decision.** 0.3.1 fixes what Ferry's and Raft Artifacts' adoptions of 0.3.0 and a second cold
1962
+ adoption (from the package alone) hit. Additions only.
1963
+ 1. **Sign-in comes back to the app as it is reached.** `signIn`'s `returnTo` and `entry.spa`'s
1964
+ `next` are `authorizeUrl` (by default `<first app origin>/porthole/authorize`) with the
1965
+ request's query, its state. Before, they were the request's own URL, which behind a TLS edge
1966
+ (`http://`) or a dev proxy (`localhost:5173`, a rewritten Host) names an origin that isn't the
1967
+ app's, so `entryTarget` refused it and the person stayed on the sign-in.
1968
+ 2. **`renderConfirm` gets `redirect()`** beside `accept` and `decline`: the call answers
1969
+ `"redirected"` (the core's existing answer for "the person took it elsewhere": edited the
1970
+ prompt first). It doesn't go, and neither counts toward muting the display nor resets the
1971
+ count. `ConfirmActions` is exported.
1972
+ 3. **`nodeServer`'s `content` may be a function** giving the host once it exists (null until
1973
+ then): a host whose content domain names the port `listen(0)` chose. Until it gives one, every
1974
+ request and upgrade is the app's; the host is started once, when first given while listening,
1975
+ and closed with the server.
1976
+ 4. **A served config is checked served.** `checkPage` ran every config opaque, so for a served
1977
+ page it reported what people never see (`document.cookie` throwing in an opaque frame) and
1978
+ missed what they do (the CSP block the throw stopped short of). Now, where the driver can serve
1979
+ (`CheckSession.serve`, both shipped drivers), the check runs Porthole's own `createServer`
1980
+ in process (a random secret; the check page, `https://porthole-check.invalid`, its only host
1981
+ origin), and the driver answers a reserved content domain (`*.porthole-check-content.invalid`)
1982
+ from it, so the content gets an origin of its own, the served CSP in headers, the shell,
1983
+ storage and cookies; each run a new origin. Nothing reaches the app's server or the network
1984
+ for those names. Opaque configs, MCP Apps views and drivers without `serve` run opaque as
1985
+ before. **One numbering:** each inline script is named (`//# sourceURL=porthole-script-<n>`)
1986
+ and its first line recorded, so a runtime error's line is the content's own line, as lint
1987
+ numbers it (it was the line within the script).
1988
+ 5. **Conformance says why it skipped:** `@botiverse/porthole/conformance/reporter`, beside the
1989
+ list reporter, prints each skipped case's reason after the run (an inapplicable probe names the
1990
+ page's directive). The example config uses it; ADOPTING's snippet has it and `fullyParallel`.
1991
+ 6. **A missing secret is named:** `createContentHost` without one throws "needs a secret: at
1992
+ least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)" (it threw a
1993
+ `TypeError` from inside the HMAC); a short one says the same. Like any setting it refuses, it
1994
+ is a lasting "misconfigured" instead under the health gate's fallback (P066), and
1995
+ `contentHostFor` answers its 503 with the text. Content off (`domain: ""`) needs no secret.
1996
+ 7. **The examples follow the recommended path:** Node on `nodeServer`, Workers on
1997
+ `contentHostFor`; `examples/app.mjs` gives the host's options and a handler that takes the
1998
+ host. ADOPTING says when the other path is right: `nodeHost` for an app that keeps its own
1999
+ server, `createContentHost` at module scope for settings fixed at build time.
2000
+ 8. **ADOPTING says how a page without a bundler loads Porthole:** the package's `dist/` served at
2001
+ a path, an import map with the page's nonce, and the display kinds served as a module made
2002
+ from the same object the server's `defineDisplays` gets.
2003
+ 9. **`entryTarget(next, authorizeUrl, { app: true })`** also takes a path or address on the app's
2004
+ own origin (one leading slash, no backslash, `http(s)` only, the origin checked once resolved),
2005
+ returned absolute: one open-redirect guard for a sign-in that goes back to a page or to a
2006
+ frame's content. Without the option it is the authorize route only, as before. ADOPTING and
2007
+ the doc comment state the default authorize URL.
2008
+
2009
+ 10. **Configs that declare host functions can be checked (#8).** The check page mounted with no
2010
+ handlers, so `mount` threw "No handler for the declared capabilities" before content ran,
2011
+ and `checkTool` on a widget config with `sendPrompt` couldn't run at all. Now the check page
2012
+ answers every declared host function as a host that declines (its `confirm` says no; each
2013
+ handler answers no: `false`, nothing, or a refused tool call or read) and reports each call
2014
+ the host sees (`run.calls`): one a host's gates refuse whatever the person says (no click, bad
2015
+ arguments, not offered, too often) is a problem; one a person or host may decline is a note.
2016
+ A global the shell refuses itself (`sendPrompt` with no click) rejects in the content, which
2017
+ the check reports as the error it is. The manual's examples are now checked under presets
2018
+ that declare every host function too, opaque, served and MCP Apps.
2019
+
2020
+ From Raft Artifacts' adoption of 0.3.0 (its workarounds grew from 14 lines to 34 for these):
2021
+
2022
+ 11. **`entry.pathOf` may be async** (`Awaitable`, given the request too): a clean path that needs a
2023
+ lookup (`/` for a page's current version) comes from the database. Where it fails, the frame
2024
+ is issued without a link rather than refused. `link`, `usePortholeLink` and `openInTab` were
2025
+ async already.
2026
+ 12. **The runner's `contentSource` may be a function**, asked when a case needs a config: the
2027
+ test server's port isn't known when the spec file loads.
2028
+ 13. **`conformanceProjects(devices, { use, launchOptions })`**: `use` adds to every project's;
2029
+ `launchOptions` per engine (a system Chromium's `executablePath` and `args`, where Playwright
2030
+ has no build: arm64 Linux) merges with Porthole's own, Firefox's preferences with the ones its
2031
+ probes need.
2032
+ 14. **`PortholeView` renders on the server** what the client's meta says: the frame's placeholder
2033
+ or the fallback, from `portholeClient({ meta })`. Its server snapshot was null, so an SSR'd
2034
+ page (and its tests) had nothing until hydration.
2035
+ 15. **`CdpSession` is documented as the least the driver uses**, and a type test holds that
2036
+ Playwright's `CDPSession` and Puppeteer's (as it declares itself, generic over the protocol)
2037
+ are taken with no cast. Checked against Raft's own `@cloudflare/puppeteer` and TypeScript
2038
+ 5.9 settings, 0.3.0's type took both already: its cast can simply go.
2039
+
2040
+ From Ferry, after 0.3.0:
2041
+
2042
+ 16. **`portholeClient`'s functions are declared `this: void`**, so they pass bare
2043
+ (`useSyncExternalStore(porthole.subscribe, porthole.meta)`) under type-aware lint's
2044
+ `unbound-method`, and none reads `this` (`openInTab` called `this.link`). Method syntax with
2045
+ `this: void` rather than function properties keeps `PortholeClient<"a" | "b">` assignable to
2046
+ `PortholeClient` (the provider's), as methods' parameters are.
2047
+ 17. **No content domain is a host with `domain: null`**, the supported setup for a self-hosted app
2048
+ without one: no secret needed, and `/porthole/meta` answers `{ served: false }`, so pages show
2049
+ opaque rather than pending. ADOPTING says so.
2050
+ 18. **A provider's scheme flip or new `themeKey` re-themes its frames in place (#9).** The
2051
+ provider's context value is renewed with its scheme, theme and themeKey, and two effects were
2052
+ keyed on it: `PortholeFrame`'s registry effect (whose cleanup let the frame go, so it was made
2053
+ again) and the mount effect. Every display was destroyed and made again: widgets lost their
2054
+ state, url-mode previews reloaded. Both now depend only on the provider's stable parts (the
2055
+ registry, heights, handlers, confirm, locator, nonce, hostInfo by value), and read the scheme
2056
+ and theme when used; flips go through `setTheme`, a new themeKey through `refreshTheme`, and a
2057
+ new theme function (tokens passed inline) through `refreshTheme` where its values changed.
2058
+
2059
+ **Risks.**
2060
+ - Item 9 widens what a guard accepts, on request. Bounded by `test/kit03.test.ts`: `//host`,
2061
+ `/\host`, a tab inside the slashes, `\\host`, another scheme, a look-alike host, `javascript:`
2062
+ and `data:` are all null.
2063
+ - Item 3 sends every request to the app until the host exists, the content domain's included.
2064
+ Nothing names that domain before the host does (its port is the one just chosen); an app whose
2065
+ DNS already points the content domain at it makes the host before it listens.
2066
+ - Item 1 trusts `authorizeUrl`, which the app sets (or its first app origin); the request can no
2067
+ longer choose where sign-in comes back to, which is narrower than before.
2068
+
2069
+ **Why.** Each item was a workaround or a wrong guess: Ferry's sign-in stayed put behind its dev
2070
+ proxy and a TLS edge; an app's own dialog couldn't answer "edit first" without a decline that
2071
+ counts; an app that makes its host after its server starts had to drop to `nodeHost`; an agent told
2072
+ to fix line 6 of a served page's runtime error edited the wrong line, for an error people never see;
2073
+ `[1.connect]` showed as a bare "-"; a forgotten secret crashed inside the HMAC; Ferry's widget
2074
+ config couldn't be checked at all (#8); the cold adopter had to choose between the guide's path and
2075
+ the examples', read `examples/app.mjs` to load the browser modules, and read `client.js` to learn
2076
+ `entryTarget` refused `/`; Raft Artifacts' workarounds for items 11 to 15 had grown to 34 lines;
2077
+ Ferry's type-aware lint refused the client's functions passed bare, it made no host at all without a
2078
+ content domain, leaving displays pending, and every theme flip made its displays again (#9).
2079
+ **Measured.** `test/kit03.test.ts` (a proxied authorize request, the SPA `next`, the lazy
2080
+ `nodeServer`, the secret, `entryTarget`, an async `pathOf`, the client's functions taken bare and
2081
+ linted, no content domain); the prod-shape profile signs in through its TLS edge with the kit app
2082
+ reached as `http` behind it (failing before item 1); `leak/react.spec.ts` (four redirects, never
2083
+ muted, no prompt sent); `leak/check.spec.ts` (a served page: no cookie error, the connect block
2084
+ reported, errors on their file lines, on both drivers; every host function declared: the manual's
2085
+ examples pass, and a widget's calls on load are answered and reported, opaque and served);
2086
+ `test/check.test.ts` (the calls' words, the CDP session types); `test/conformance-options.test.ts`;
2087
+ `test/react-ssr.test.ts` (failing before item 14); `leak/react.spec.ts`'s flips of the provider's
2088
+ scheme and themeKey keep each frame element, its window and its page, opaque, served and url
2089
+ (failing before item 18); the examples' unit tests and their conformance run on three engines.
2090
+ **Revisit when** a driver that can't intercept requests needs served checks (it would need a
2091
+ real content domain).
2092
+
2093
+ ## P075 · 2026-10-12 · Every entry point bundles whole: no file looked up beside a module · Accepted
2094
+
2095
+ **Decision.** `/check` loaded its check page's script at run time from a path computed beside its
2096
+ module (`new URL("./page-source.js", import.meta.url)`, then `import()` of it), and `/conformance`
2097
+ read its harness the same way (`readFile(new URL("./harness.js", import.meta.url))`, falling back
2098
+ to `import("esbuild")`). A bundle has no files beside its modules: Ferry's CLI, one executable
2099
+ built by rolldown for Node SEA, refuses such loads at build time, and its 0.1.85 release failed
2100
+ on `/check`; a Worker's bundle would fail where the path runs. 0.3.2:
2101
+ 1. **Both scripts are modules imported statically**: `check/page-source` and
2102
+ `conformance/harness-source`, which from the sources build the script with esbuild (Porthole's
2103
+ own development dependency), and which the build replaces with a module exporting the built
2104
+ script as a string and nothing else. `checkPage`'s `page` option stays, and is no longer
2105
+ needed anywhere.
2106
+ 2. **`test:bundle`** bundles every published entry point from the build, with rolldown (for Node,
2107
+ one file, dynamic imports inlined) and with esbuild for Workers, lists every load left for run
2108
+ time as Ferry's build does (an `import()` of anything but a literal builtin, `require`,
2109
+ `createRequire`, the module's own location), and fails on any not reviewed in the script; then
2110
+ it imports each bundle from a directory with nothing else in it, and checks a page in Chromium
2111
+ from the `/check` bundle with no `page` given. CI and the release workflow run it after the
2112
+ build: a package that fails it is never published. Run on 0.3.1's build it fails, naming
2113
+ `/check`'s and `/conformance`'s loads.
2114
+ 3. **The one reviewed load:** `/conformance`'s MCP probes look for the optional official App SDK
2115
+ where the suite runs (`createRequire(import.meta.url).resolve(...)`), inside a `try`: without it
2116
+ they say so and don't run. The runner runs under Playwright, from `node_modules`.
2117
+ 4. The build empties `dist/` first, so no file of an earlier build ships.
2118
+
2119
+ **Cost.** Importing `/check` loads the check page's script (about 145 KB) with it; importing
2120
+ `/conformance` its harness (about 140 KB). Both were loaded on first use before.
2121
+ **Why.** An entry point that works only beside its own files isn't a library a bundler can take,
2122
+ and the failure shows only where the path runs.
2123
+ **Revisit when** a bundler needs code split into chunks of its own (none does yet).
2124
+