@botiverse/porthole 0.5.0 → 0.6.0

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 (90) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.d.ts +12 -4
  3. package/dist/bridge/bridge.js +62 -27
  4. package/dist/bridge/navigation.d.ts +6 -0
  5. package/dist/bridge/navigation.js +41 -0
  6. package/dist/bridge/refusal.d.ts +53 -0
  7. package/dist/bridge/refusal.js +121 -0
  8. package/dist/bridge/types.d.ts +7 -0
  9. package/dist/check/check.d.ts +12 -3
  10. package/dist/check/check.js +54 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/lint.js +27 -10
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/page.js +5 -0
  16. package/dist/check/tools.d.ts +23 -0
  17. package/dist/check/tools.js +25 -0
  18. package/dist/compile/policy.d.ts +15 -0
  19. package/dist/compile/policy.js +32 -0
  20. package/dist/config/capabilities.d.ts +5 -0
  21. package/dist/config/schema.d.ts +8 -0
  22. package/dist/config/validate.js +8 -1
  23. package/dist/conformance/harness-source.js +1 -1
  24. package/dist/files/paths.d.ts +99 -0
  25. package/dist/files/paths.js +263 -0
  26. package/dist/files/types.d.ts +24 -0
  27. package/dist/files/types.js +83 -0
  28. package/dist/guide/guide.js +25 -5
  29. package/dist/host/create-host.js +36 -4
  30. package/dist/host/types.d.ts +15 -2
  31. package/dist/index.d.ts +7 -3
  32. package/dist/index.js +10 -3
  33. package/dist/mcp/adapter.js +22 -7
  34. package/dist/protocol/adapter.d.ts +4 -0
  35. package/dist/protocol/mcp-apps.d.ts +12 -0
  36. package/dist/protocol/mcp-apps.js +12 -0
  37. package/dist/protocol/shell-adapter.js +18 -2
  38. package/dist/react/frame.d.ts +19 -4
  39. package/dist/react/frame.js +37 -9
  40. package/dist/server/files.d.ts +44 -0
  41. package/dist/server/files.js +244 -0
  42. package/dist/server/host.d.ts +38 -1
  43. package/dist/server/host.js +37 -2
  44. package/dist/server/index.d.ts +4 -2
  45. package/dist/server/index.js +4 -1
  46. package/dist/server/keys.d.ts +8 -0
  47. package/dist/server/keys.js +34 -0
  48. package/dist/server/server.js +287 -22
  49. package/dist/server/types.d.ts +49 -5
  50. package/dist/shell/document.d.ts +19 -0
  51. package/dist/shell/document.js +30 -0
  52. package/dist/shell/runtime.d.ts +2 -1
  53. package/dist/shell/runtime.js +117 -10
  54. package/docs/ADOPTING.md +95 -13
  55. package/docs/ARCHITECTURE.md +13 -3
  56. package/docs/DECISIONS.md +396 -4
  57. package/docs/DESIGN.md +43 -10
  58. package/package.json +1 -1
  59. package/src/bridge/bridge.ts +74 -23
  60. package/src/bridge/navigation.ts +46 -0
  61. package/src/bridge/refusal.ts +151 -0
  62. package/src/bridge/types.ts +12 -1
  63. package/src/check/check.ts +92 -14
  64. package/src/check/files.ts +384 -0
  65. package/src/check/lint.ts +29 -10
  66. package/src/check/page.ts +7 -0
  67. package/src/check/tools.ts +50 -0
  68. package/src/compile/policy.ts +38 -0
  69. package/src/config/capabilities.ts +5 -1
  70. package/src/config/schema.ts +8 -0
  71. package/src/config/validate.ts +8 -1
  72. package/src/files/paths.ts +323 -0
  73. package/src/files/types.ts +101 -0
  74. package/src/guide/guide.ts +38 -4
  75. package/src/host/create-host.ts +37 -4
  76. package/src/host/types.ts +13 -2
  77. package/src/index.ts +41 -0
  78. package/src/mcp/adapter.ts +26 -6
  79. package/src/protocol/adapter.ts +3 -1
  80. package/src/protocol/mcp-apps.ts +14 -0
  81. package/src/protocol/shell-adapter.ts +20 -2
  82. package/src/react/frame.tsx +53 -14
  83. package/src/server/files.ts +312 -0
  84. package/src/server/host.ts +72 -3
  85. package/src/server/index.ts +19 -0
  86. package/src/server/keys.ts +53 -0
  87. package/src/server/server.ts +353 -24
  88. package/src/server/types.ts +56 -4
  89. package/src/shell/document.ts +53 -0
  90. package/src/shell/runtime.ts +117 -10
package/docs/DECISIONS.md CHANGED
@@ -353,7 +353,7 @@ wall.
353
353
  **Revisit when** a gate needs to depend on the call's arguments (then the host's
354
354
  `confirm` decides, as it does for tool calls today).
355
355
 
356
- ## P022 · 2026-10-11 · Every preset starts with egress closed; library CDNs are a one-line opt-in · Accepted
356
+ ## P022 · 2026-10-11 · Every preset starts with egress closed; library CDNs are a one-line opt-in · Accepted; amended by P082
357
357
 
358
358
  **Decision.** Every preset's base egress is empty: nothing loads from outside and
359
359
  every fetch fails. `LIBRARY_CDNS` (cdnjs, jsDelivr, unpkg, esm.sh for scripts,
@@ -397,7 +397,7 @@ agreement test keeps the shell and the manual on the same name.
397
397
  **Revisit when** MCP Apps standardizes error reporting or theme-change events for
398
398
  views.
399
399
 
400
- ## P025 · 2026-10-11 · A served document comes with its ticket's answer; the cookie serves what follows · Accepted
400
+ ## P025 · 2026-10-11 · A served document comes with its ticket's answer; the cookie serves what follows · Accepted; amended by P083
401
401
 
402
402
  **Decision.** Refines P016's ticket flow. `/server` names each storage scope's origin
403
403
  `<label>.<content domain>` (24 base32 characters of an HMAC of the scope, keyed from the
@@ -568,7 +568,7 @@ Chromium measured no preconnect from a frame here, but harden for the weakest en
568
568
  **Revisit when** WebKit applies the CSP to preconnect (then the observer suffices), or a
569
569
  DOM insertion API is added (wrap it, and add its probe).
570
570
 
571
- ## P031 · 2026-10-11 · A display whose content navigates its frame is started again, at most three times · Accepted
571
+ ## P031 · 2026-10-11 · A display whose content navigates its frame is started again, at most three times · Accepted; amended by P084
572
572
 
573
573
  **Decision.** The web platform counts its frame's loads; any after the first means the
574
574
  content navigated the frame. The display is started again from its content (an event
@@ -2213,7 +2213,7 @@ refused, and reported as a problem, on every engine (`leak/check.spec.ts`).
2213
2213
  loads (its follow-up) proposes more hosts, such as mirrors reachable from mainland China.
2214
2214
 
2215
2215
 
2216
- ## P079 · 2026-10-15 · Live widgets: no network of their own, Porthole's libraries on their origin, the host's data behind the viewer's consent, and frames that never navigate away · Accepted
2216
+ ## P079 · 2026-10-15 · Live widgets: no network of their own, Porthole's libraries on their origin, the host's data behind the viewer's consent, and frames that never navigate away · Accepted; amended by P084
2217
2217
 
2218
2218
  **Decision.** Content that shows its host's data, current, read as the person viewing it (a
2219
2219
  dashboard tile, a kept widget) gets a preset of its own and the mechanisms it needs. 0.5.0.
@@ -2341,3 +2341,395 @@ accepts either outcome, as the opaque probes do. The opaque probes `5.*` keep fa
2341
2341
  **Revisit when** MCP Apps specifies subscriptions (follow it), an engine Porthole supports lacks the
2342
2342
  Navigation API, a host needs libraries in opaque frames, or agents' live widgets reach for a library
2343
2343
  the two don't cover.
2344
+
2345
+ ## P080 · 2026-10-15 · The host hears a navigation the shell stopped; a host may refuse all data without handlers; a refusal tells content why · Accepted
2346
+
2347
+ From Ferry's adoption of 0.5.0's live widgets (#12, #13, #14). 0.5.1, additive but for the text of
2348
+ a refused data call's error (below).
2349
+
2350
+ **Decision.**
2351
+ - **A navigation the shell stopped is an error report (#12).** When the navigate guard (P079)
2352
+ cancels a navigation, the shell sends Porthole's own notification `porthole/navigation-blocked`
2353
+ with `{ url }` (`NAVIGATION_BLOCKED_METHOD`), where the config declares `reportError` and within
2354
+ its reports (`limits.maxErrorReports` a run, the capability's rate). Both adapters carry it into
2355
+ `reportError`; the shell sends it even where the content speaks for itself (an MCP Apps view).
2356
+ The host gets `navigationBlocked: { url }` (React `onNavigationBlocked`), the address whole, and a
2357
+ `contentError` (so `errors: "agent"` hosts pass it on as they do every content error) that
2358
+ Porthole words and that names the address without its query or fragment: "It tried to navigate
2359
+ its frame to https://x.example/path?…, and was stopped: content never leaves its page.", with
2360
+ where links go when `openLink` is declared. `checkPage` reports it as an error.
2361
+ - **A host may refuse every data call without handlers (#13).** `HostOptions.consent` (React's
2362
+ `consent` on the provider and the frame) takes a `Refused` in place of the function: every
2363
+ `consent`-gated call is refused with it, nothing is asked, the host's cache isn't read, and those
2364
+ capabilities need no handler at mount. Any other declared capability still needs one, and so does
2365
+ one whose gates the host stripped of `consent`. React compares the `Refused` by value (its code and
2366
+ message), so one written inline restarts nothing; a change between a `Refused` and a function makes
2367
+ the display again, since its handlers differ.
2368
+ - **A refusal tells content why (#14).** A refused request's JSON-RPC error carries
2369
+ `data: { code, message }` (`RefusalReason`): `code` is one of `REFUSAL_CODES`,
2370
+ `consent_required` (no answer yet: the host's consent function failed, and the next call asks
2371
+ again), `denied` (the viewer said no, or the person asked to confirm declined), `rate_limited`,
2372
+ `not_allowed` (no consent function, an undeclared or malformed call, a `consent` given as a
2373
+ `Refused` with that code: not here) or `failed` (the handler threw); `message` is a sentence for
2374
+ the person viewing it. A host words its own by throwing `new Refused(code, message)` from a
2375
+ handler (a URI it doesn't serve) or from a consent function (kept as the display's answer, as
2376
+ `false` is), or by passing one as `consent`; otherwise Porthole's sentence for the code (naming
2377
+ the data for `readData` and `subscribeData`). Anything else a handler throws is `failed` in
2378
+ Porthole's words: the error's own message stays the host's (`CallOutcome.message`). The shell's
2379
+ `readData` and `subscribeData`'s `onError` reject with an `Error` whose `message` is that sentence
2380
+ and whose `code` is the code; the manual teaches the codes and to show the sentence. The JSON-RPC
2381
+ error's own `message` is unchanged (`Refused (denied)`). A host's `refused` event still names the
2382
+ bridge's `Refusal` (a handler's `Refused` is `failed` there, a consent's `denied`).
2383
+
2384
+ **Why.**
2385
+ - 0.5.0's guard was silent: a host that learned of navigations from the frame reloading (Ferry's
2386
+ display tests; its agents hearing that their widget left its page) heard nothing, so an agent
2387
+ never learned its widget's link or form was dead. A blocked navigation is something the sandbox
2388
+ blocked, which `reportError` already reports ("Blocked by the sandbox: …"), so it rides the same
2389
+ capability, bound and rate, and no frame says anything to a host whose config says errors go
2390
+ nowhere (PRINCIPLE 4). The address is the content's word either way; the host gets it whole (it
2391
+ holds the viewer's data already), while the sentence that may reach the agent drops the query and
2392
+ fragment, where a widget that read the viewer's data would have put it.
2393
+ - A page where live data must not run (Ferry: a transcript beside a preview that reaches the
2394
+ network, P079's residual) passed handlers that threw, only to satisfy the mount's check, and a
2395
+ consent that said no. The check exists so a manual never teaches a function nobody serves; with
2396
+ every call refused before any handler, the function is taught and answered, with a reason. A
2397
+ value rather than a flag: the policy is the consent's answer, known before any call, and the same
2398
+ `Refused` words the reason (PRINCIPLE 8: one option, no knob).
2399
+ - "Refused (denied)" told a widget nothing it could show. The reasons are the five a widget draws
2400
+ differently (wait for permission, show it isn't allowed, back off, say it isn't available here,
2401
+ show an error), in the error's `data`, which JSON-RPC leaves to the implementation: no new
2402
+ method, and an App SDK view reads them from the error it already gets (PRINCIPLE 2).
2403
+
2404
+ **Rejected.**
2405
+ - A `navigationBlocked` event for every config, without `reportError`: content would speak to a
2406
+ host that declared no channel for it.
2407
+ - `consent: false` for refuse-all: indistinguishable at a glance from an absent consent (also a
2408
+ refusal, but one that keeps the handler check), and it carries no words.
2409
+ - Passing a handler's error message to content: hosts' errors carry internals (a database
2410
+ address); content gets them only through a `Refused`.
2411
+ - New `Refusal` members for the consent cases: the host-facing union stays as it was; the code
2412
+ content gets is a separate, smaller vocabulary.
2413
+
2414
+ **Residual.** Opaque frames get no navigate events (P079): the guard can't see their navigations,
2415
+ so nothing is reported; a navigation the page's `frame-src` blocks replaces the frame's document,
2416
+ which the host hears as `navigated` (P031), without the address. WebKit fires no navigate event for
2417
+ `navigation.navigate()` to a site the page's `frame-src` blocks (P079): `navigated` there too.
2418
+ Content can send `porthole/navigation-blocked` itself, with any address: it is its word, bound like
2419
+ any error report.
2420
+
2421
+ **Tested.** `test/refusals.test.ts` (on `createHost` over a stand-in platform: each code over the
2422
+ wire, the consent's `Refused` kept, a failing consent asked again, a handler's `Refused` and a plain
2423
+ throw that keeps the host's words; `consent` as a `Refused` mounts without data handlers, refuses
2424
+ both, never reads the cache, and still needs any other handler; `navigationBlocked` whole and the
2425
+ content error without the query, a non-http address by its scheme, nothing without `reportError`,
2426
+ the rate, malformed reports dropped); `test/mcp.test.ts` (the `/mcp` adapter carries both);
2427
+ `test/agreement.test.ts` (the codes taught exactly where `readData` is); `leak/served/live.spec.ts`
2428
+ (each served navigation case tells the host the sibling's address, and its content error omits
2429
+ the secret; a viewer's no reaches the content as `denied` and the sentence; a host refusing all,
2430
+ with no handlers, as `not_allowed` and its sentence; a handler's `Refused` for one URI);
2431
+ `leak/react.spec.ts` (a `Refused` on the frame and on the provider: no data handlers, the content
2432
+ told why, nothing started again on re-render); `leak/check.spec.ts` (a served widget that
2433
+ navigates is told so, without the query). On Chromium, WebKit and Firefox.
2434
+ **Revisit when** MCP or MCP Apps standardizes error data for refused requests (follow it), or a
2435
+ host needs the navigation without `reportError`.
2436
+
2437
+ ## P081 · 2026-10-18 · A version may be many files: the store's contract, addresses that pin a version, and how each file is served · Accepted
2438
+
2439
+ Task #124: an artifact is what an agent made, as it made it, and that is often a directory (a
2440
+ build's output, a report with its images, a dashboard that reads its data). 0.6.0, additive: a
2441
+ 0.5 host's store, `{ html }`, is served as before.
2442
+
2443
+ **Decision.**
2444
+ - **The store.** `ArtifactStore.get(id, version)` answers `{ html }` (one page, as in 0.5) or a
2445
+ `StoredFiles`: `files` (`path → { size, sha256, type? }`), `entry` (default `index.html`), `spa`
2446
+ (default false) and `read(path)` (a `Uint8Array` or a `ReadableStream`, whole; Porthole cuts the
2447
+ range a request asks for). The type a file was published with is the host's to keep (a file list),
2448
+ never served.
2449
+ - **Paths, when a version is published** (`filePathProblem`, `checkFileSet`, a host calls them):
2450
+ relative, `/`-separated, case-sensitive; no empty, `.` or `..` segment; none of `\ % ? #`, a
2451
+ control character or a format character (`Cc`, `Cf`: a right-to-left override or a zero-width
2452
+ space would make a path read as another); Unicode NFC; no segment that starts or ends with a space; at most 512
2453
+ characters and 255 a segment; not under `__porthole/`; no two paths that differ only in case, no
2454
+ path that is both a file and a directory; the entry one of them.
2455
+ - **Paths, when a file is asked for** (`requestFilePath`, `lookupFile`): the path below the
2456
+ version's base, decoded once; a segment that decodes to a separator, an escape, a control
2457
+ character or a dot segment names nothing (the URL parser has resolved the dot segments it
2458
+ sees). Looked up in the manifest only, never a filesystem: `""` is the entry (an entry in a
2459
+ directory: there); `dir/` is `dir/index.html`; `name` is `name`, else `name.html`, else `name/`
2460
+ (307) when `name/index.html` exists. What finds nothing: for a navigation, the entry when the
2461
+ version is a single-page app (`spa`), else the nearest `404.html` (status 404); else a plain 404.
2462
+ - **Limits**, the config's (`limits.maxFiles`, `maxFileBytes`, `maxVersionBytes`; 1,000, 25 MiB,
2463
+ 100 MiB by default): the manual states them, and `checkFileSet` and `lintFiles` hold a version
2464
+ to them. The server serves what the host stored.
2465
+ - **Addresses on a tab** (P068). `entry.at` may answer a `FileAddress`, `{ instance, base, file }`:
2466
+ the version's own address (`/v/3/`) and the file the address asks for below it. The session the
2467
+ entry buys serves every path under `base`, and an address that isn't under it (`/`,
2468
+ `/style.css`: the latest) is redeemed to `base` + `file`. A base is a path ending in `/` whose
2469
+ segments are letters, digits and `. _ : ~ -`, never `.` or `..` (it goes into a CSP header as
2470
+ it is); `file` holds no dot segment, backslash, `?`, `#` or control character, and the address
2471
+ it makes must still be under `base`. `pinned: true` says `base` names that version and no
2472
+ other: only then are its files immutable (`/latest/` isn't pinned; its files revalidate). Where
2473
+ sessions' bases nest, the most specific serves. A request on a clean address with no session for
2474
+ it begins an entry only when a page opens (`Sec-Fetch-Mode: navigate`, a document's destination,
2475
+ or a client that sends no fetch metadata): a subresource gets a plain 401, `no-store`, with no
2476
+ nonce cookie. `versionedAddress(path)` reads the convention both first hosts
2477
+ use (`/v/<n>/<file>` pinned, any other path the latest's; a version is never `.` or `..`), and
2478
+ `versionBase(n)` is `/v/<n>/`. Each version is a directory of its origin, as Claude's content
2479
+ origin does it (`/_f/<version id>/`, measured on claude.ai 2026-10-18). `/_blob/`
2480
+ (`ASSET_LIBRARY_PATH`) is kept free outside every version for an asset library that lives
2481
+ across versions (task #124 phase 4, not built): `versionedAddress` names nothing there; it will
2482
+ need a CSP source and an access of its own, decided then. A file set's page answered as a plain
2483
+ instance is served as a frame's is (P083).
2484
+ - **Answers.** Each file is typed by Porthole's table by its extension (`fileTypeOf`); one it
2485
+ doesn't know is `application/octet-stream` with `content-disposition: attachment`; every answer
2486
+ is `nosniff`. Every answer carries its CSP: a page and a script (a worker's policy is its
2487
+ script's) the page's (P082), any other file `default-src 'none'; sandbox` (an SVG or XML file
2488
+ opened on its own runs nothing). A page is `private, no-cache` with an ETag of the bytes served
2489
+ (so the host's check runs on every navigation, P050); any other file `private,
2490
+ max-age=31536000, immutable` with its `sha256` as a strong ETag; `If-None-Match` gets a 304; one
2491
+ `bytes=` range a 206 (a range past the end a 416; several ranges the whole file). Files (not
2492
+ pages) are `Cross-Origin-Resource-Policy: same-origin`. A service worker's script request
2493
+ (`Service-Worker`, `Sec-Fetch-Dest: serviceworker`) is refused.
2494
+ - **Every page of a set is in the shell**, fetched or opened: its hardening, its host functions,
2495
+ its theme (P029: parsed inert, its scripts replayed, a module's relative `src` resolving from
2496
+ the page's address). Each page still writes its own skeleton (`<!doctype html>`, its head), as
2497
+ on Claude, where only the main page is wrapped in a skeleton at publish time: a skeleton is
2498
+ markup, Porthole's shell is the frame's hardening, which a page can't go without.
2499
+ - **The agent's side.** `lintFiles(config, files)` lints each page as `lintContent` does, holds the
2500
+ set to the path rules and limits, and looks every relative reference up in the set (markup,
2501
+ CSS `url()` and `@import`, module imports, `new URL(…, import.meta.url)`, workers, fetches);
2502
+ `admitFiles` refuses what certainly fails (a path or limit the server won't take, no entry, a
2503
+ page `admitContent` would refuse, a page's reference that starts with `/`) and warns on the
2504
+ rest. Its scans run in linear time whatever the text (each pattern bounded and stopped at its
2505
+ own delimiters, a page's markup read tag by tag, line numbers by a search, at most 2,000
2506
+ references of a kind and 2 MiB of a file looked at), and a set over a limit, or a page over its
2507
+ own, is said so and not read further. `checkPage({ files })` serves the whole set from the
2508
+ check's own server and runs its entry; files are named by their path in its report. The manual's widget topic gets a Files
2509
+ section where a config serves them (`servesFiles`: an artifact with domain isolation).
2510
+
2511
+ **Why.**
2512
+ - Packing a directory into one page costs a third more bytes in base64, the agent's tokens to
2513
+ write it, and a whole re-upload for one changed line. Every static host serves a set of files
2514
+ (Netlify, Cloudflare, Vercel, Firebase, GitHub Pages), and so does Claude's own content origin
2515
+ ("fetch() of files published alongside the page works with relative URLs").
2516
+ - The serving rules are theirs (task124-industry-practice.md, items 7–11): Cloudflare's slash
2517
+ policy and 404 rules, a server-side type table with `nosniff` (MDN, Go's `ServeContent`), pinned
2518
+ addresses immutable, an ETag on the hash (web.dev's HTTP cache guide).
2519
+ - A page loaded as the latest must not load a newer version's file published while it loads (the
2520
+ chunk-load errors SPAs hit after a deploy; Vercel's Skew Protection exists for them). The
2521
+ address that pins it must be the page's own, not the browser's: a cookie is shared by every tab
2522
+ and replaced when the next version is entered, so the redeem goes to the version's own address
2523
+ before the page loads anything.
2524
+ - Every page in the shell: a page opened without it would run without its in-frame defenses (a
2525
+ nested frame's fresh realm, WebRTC where `webrtc 'block'` isn't honored), and without its host.
2526
+ - `same-origin` resource policy: without the public suffix list (P047, P066) sibling content
2527
+ origins are one site, so on a tab another artifact's page could embed this one's script with the
2528
+ viewer's `Lax` cookie; nothing but the version's own pages needs to load its files (the app
2529
+ frames the page, never a file).
2530
+
2531
+ **Rejected.**
2532
+ - A `<base>` the shell sets on the latest address (`/`, base `/v/3/`): every `#anchor` link then
2533
+ resolves to `/v/3/#anchor`, another document, and `base-uri 'none'` would have to open.
2534
+ - Serving the latest's files at the latest address by the session (`/style.css` from the version the
2535
+ cookie entered): two tabs, or a newer version entered while a page loads, mix versions.
2536
+ - `Cross-Origin-Resource-Policy: cross-origin` for media (task #124's plan): it would let any page
2537
+ embed a version's media, siblings with the viewer's cookie; nothing needs it.
2538
+ - Only the entry in the shell, the other pages as they are (Claude's way): a page the frame opens
2539
+ would run without the frame guard (a nested frame's fresh realm, P006), WebRTC's removal (where
2540
+ `webrtc 'block'` isn't honored), the navigate guard (P079), `document.write`'s and declarative
2541
+ shadow roots' closing (P029) and the clipboard walls (P051), none of which a CSP gives; and
2542
+ without its host functions and theme. Raw HTML to a fetch (`Sec-Fetch-Dest: empty`): a page
2543
+ served without its shell could be replayed as a document (a prefetch cache, a worker's answer).
2544
+ HTML in a set is a page; data that is HTML goes as another type.
2545
+ - `max-age=0` for the latest's files: the latest's address never serves a file, it goes to the
2546
+ version's own.
2547
+ - The uploader's type, or sniffing (a `.txt` holding HTML would run).
2548
+ - Ranges read by the host (`read(path, range)`): one whole-body contract first.
2549
+ - Service workers: one answers its origin's requests with documents it makes, outside the shell
2550
+ and the CSP, and outlives the page.
2551
+
2552
+ **Measured** (Playwright 1.63: Chromium, WebKit, Firefox; `leak/served/files.spec.ts`): a page of
2553
+ many files loads its stylesheet, a classic script, a module and its import, an image, a fetch and
2554
+ a worker (whose own fetch resolves from it) by relative path, framed and on a tab; the committed
2555
+ Vite + React build (`leak/fixtures/vite-react/out`, 143 KB: React 18.3.1, Vite 8.3.4, `base:
2556
+ "./"`) runs as built, its lazy chunk included; a page keeps its own version's data and lazy module
2557
+ when a newer version is published while it runs (framed, and on a tab opened at the latest's
2558
+ address); every spelling of a way out (`..%2f`, `%252e%252e`, `%5c`, `%2f`, a backslash, `%2e%2e`
2559
+ past the base) is a 404 or blocked; an `.html` published as `.txt` is `text/plain`, `nosniff`, and
2560
+ runs nothing opened on its own; another artifact's page loads none of the files (its CSP stops
2561
+ them before any request) and a page elsewhere can't read or run them (no CORS; CORP); no service
2562
+ worker registers. Negative controls (P032): `service-worker` (the harness passes a worker's script
2563
+ request on as a script's) → a service worker registers on a tab on all three engines;
2564
+ `file-corp` (no resource policy) → a page elsewhere runs the set's script on all three.
2565
+
2566
+ **Security review (2026-10-18, of the first cut).** No critical or high finding; the changes above
2567
+ for: format characters in paths, quadratic lint patterns (72 KB of `import a ` took 3.9 s; a
2568
+ megabyte of any adversarial text now takes under 30 ms), a subresource that began an entry (a 302
2569
+ and a nonce cookie for each), and bases (any base was immutable; `; , '` and dot segments passed).
2570
+ The sealed address in reports and its lifetime: P083; a set's pages' notice: P084; versions on a
2571
+ tab: P082.
2572
+
2573
+ **Tested.** `test/files.test.ts` (the path rules, `checkFileSet`, decoding, lookup; the type table;
2574
+ the CSP; framed: the ticket's answer, headers per type, ETag and 304, ranges from bytes and
2575
+ streams, 404s and `404.html`, traversal, service workers, a version's access serves that version,
2576
+ an access is its origin's and ends, the host's check per file, `spa`, a 0.5 page unchanged; on a
2577
+ tab: the latest goes to the version's own, a newer version doesn't reach a page, `versionedAddress`;
2578
+ `lintFiles` and `admitFiles`, the Vite build lints clean; after the review: format characters; the
2579
+ traversal inputs against a decoder that decodes twice (the control: they then reach above the
2580
+ version) and a store that would answer any path (read is asked for manifest paths only); a
2581
+ megabyte of adversarial text linted in under 200 ms, nothing read past a limit; a subresource on a
2582
+ tab refused with no state; immutable only where pinned, the most specific base; bases and files
2583
+ that say something else refused); `test/workers.test.ts` (on workerd:
2584
+ the entry, a streamed file, a range); `test/agreement.test.ts` (the Files section exactly where
2585
+ files are served, with the config's limits); `leak/served/files.spec.ts`; `leak/check.spec.ts`
2586
+ (a set checked whole; a missing script told by its path).
2587
+ **Revisit when** a host stores large media where ranged reads pay (R2: `read(path, range)`),
2588
+ content needs offline (a service worker of Porthole's own making), the conformance runner
2589
+ (`defineHostConformance`) is pointed at an app with file sets (add these cases to it), or the
2590
+ content domain joins the public suffix list (then siblings are other sites, and CORP is defense in
2591
+ depth only).
2592
+
2593
+ ## P082 · 2026-10-18 · A served page with files loads its own version's files, by their path; never `'self'` · Accepted
2594
+
2595
+ **Decision.** Amends P022 for served pages with files. Their pages and scripts get the frame's CSP
2596
+ with one source added to `script-src`, `style-src`, `font-src`, `img-src`, `media-src`,
2597
+ `connect-src` and `worker-src` (`fileSetCspDirectives`, `FILE_SET_DIRECTIVES`; `'none'` dropped
2598
+ where it was the only source): the version's own files' path on its origin, `<origin>/v/3/` on a
2599
+ tab (the session's base), `<origin>/__porthole/f/` in a frame (the prefix every sealed path of the
2600
+ scope shares, P083). Nothing else changes: `default-src`, `frame-src`, `object-src`, `base-uri` and
2601
+ `form-action` stay `'none'`, the config's own CSP (`compile(config).csp`) has no such source, and
2602
+ an opaque frame or a page without files keeps P022 whole: never `'self'`.
2603
+ **Threat it re-opens.** Content may now make requests to its own origin, under its version's path:
2604
+ - its requests' paths and queries reach the host's own content server (its logs), which already
2605
+ sees every request the frame makes; nothing reaches another origin;
2606
+ - any file of the version runs as a script or a worker: they are the same author's;
2607
+ - in a frame, a page could load another live sealed path of its scope, if it knew one: it knows
2608
+ only its own, and same-origin frames on one page are one trust domain already (one scope, one
2609
+ storage, each other's DOM through `parent.frames`).
2610
+ Bounded: another version's path, Porthole's own paths (`/__porthole/d/`, `/__porthole/session`)
2611
+ and a url-mode app's stay closed to its loads; the `file-self` control (the harness puts `'self'` where the CSP
2612
+ names the version's path) makes a page on a tab load another version's data and module, and a
2613
+ frame's `%2e%2e` past its base reach the server, on all three engines.
2614
+ **Why.** Relative files are the point of a set, and they live on the page's own origin; the
2615
+ industry's own content origins open it: claudeusercontent.com sends `default-src
2616
+ https://www.claudeusercontent.com` (its own origin, observed), MCP Apps' baseline is `script-src
2617
+ 'self'`. Porthole opens less, its version's path: on a tab another version is another path.
2618
+ P022's reason for never `'self'` (an opaque frame's `'self'` may be the embedding page's origin)
2619
+ doesn't hold on an origin of the scope's own, and stays for opaque frames.
2620
+ - Live widgets (P079) are shells, not artifacts: no files, unchanged. Porthole's libraries keep
2621
+ their own source, `<origin>/__porthole/lib/`, under no base. Per-scope labels (P047): the source is
2622
+ the scope's origin, so another scope's files never match.
2623
+ - A CSP ignores a source's path after a redirect: Porthole's redirects under a base stay under it
2624
+ (`dir` → `dir/`), and every other answer on the origin that redirects goes to the app's origin
2625
+ (redirect entry), which no file directive allows.
2626
+ **An artifact's versions are one trust domain** (decided after the review): one origin, one storage,
2627
+ the same writers; a person who may see one version sees its history. The version's path in the CSP
2628
+ keeps a page's loads to its own version, so versions never mix (P081); it is no wall between
2629
+ versions. On a tab (no sandbox there), a page can open another version's address in a window it
2630
+ then scripts (`window.open("/v/1/")`, under that version's CSP) or read the origin's storage another
2631
+ version wrote; a frame can't open windows (no `allow-popups`). Hosts that need versions apart (a
2632
+ version written by someone else, kept from viewers of another) give each its own scope, and so
2633
+ its own origin; Porthole doesn't make popups `noopener`, which would close one path of several.
2634
+ **Rejected.** `'self'` (every version, every Porthole path of the origin); the exact sealed path in
2635
+ a frame's CSP (its length, up to kilobytes with a long scope or subject, in each of seven
2636
+ directives); a wall between versions on one origin (an origin is the browser's unit: storage,
2637
+ windows and workers cross it).
2638
+ **Revisit when** content needs to load other versions' files (a diff view: through the host), or a
2639
+ browser keeps path matching across redirects.
2640
+
2641
+ ## P083 · 2026-10-18 · A page with files in a frame carries its access in its files' path, sealed · Accepted
2642
+
2643
+ **Decision.** Amends P025 for served pages with files. The ticket's answer is the version's entry
2644
+ page, in the shell, `no-store`, with no cookie; its plan carries the address of its files,
2645
+ `/__porthole/f/<sealed>/`, and the shell puts it in the frame's history (`history.replaceState`)
2646
+ before anything loads, so the page's relative addresses resolve there and the spent ticket leaves
2647
+ the address. `<sealed>` is the session (the instance, the viewer, the end, the host's subject)
2648
+ sealed with AES-256-GCM (Web Crypto) under a key derived from the server's secret
2649
+ (`porthole/files`), bound to that use; it opens only on the instance's own origin, and the host's
2650
+ check runs on every file (P050). A reload loads the files' address itself.
2651
+ - **Its life is its own** (after the review): an address opens the page's files on its own for an
2652
+ hour at most (its `x`), never past the session's end (its `e`, `sessionSeconds`, up to 30 days).
2653
+ The shell renews it five minutes before then (`<address>__porthole/renew`, which answers only
2654
+ the page itself: same-origin, not a navigation) and moves the page to the new address in place
2655
+ (`history.replaceState`). Past `x` and before `e`, only the running page's own loads
2656
+ (`Sec-Fetch-Site: same-origin`, not a navigation) open: its modules keep the address they loaded
2657
+ from (`import.meta.url`), and their later imports must still load. An address opened on its own
2658
+ (a tab, a history entry, Firefox's "Open Frame in New Tab") ends within the hour.
2659
+ - **Nothing Porthole reports names it** (after the review): the shell says the page's files'
2660
+ address as `./` in every error report, blocked navigation and notice (a stack trace, "Couldn't
2661
+ load", a link to a file that isn't a page), and the host's bridge replaces any sealed address
2662
+ content sends itself (`withoutSealedAddresses`), so neither `contentError` (which a host may give
2663
+ the agent) nor `navigationBlocked` carries it.
2664
+ **Threat it re-opens.** P025 rejected "a token in the document's path (a credential in every URL
2665
+ the content can read and log)". The sealed path is such a credential: whoever has it loads that
2666
+ version's files as that viewer until it ends. Bounded:
2667
+ - it opens one version's files on one origin: not its document path, not `/__porthole/session`,
2668
+ not a url-mode app, not another version;
2669
+ - it is made in the browser's own request, never in the app's API answers or logs (as the
2670
+ ticket's URL is), and every answer sends `Referrer-Policy: no-referrer`;
2671
+ - content that would leak it could send the files' bytes by the same ways; and another page can't
2672
+ embed them with it (`Cross-Origin-Resource-Policy: same-origin`, P081);
2673
+ - the host's check still decides each request, and a revocation ends it (`test/files.test.ts`).
2674
+ **Why.** WebKit keeps no cookie in a cross-site frame (P025, measured): a page whose files needed
2675
+ the cookie would show its entry there and nothing it loads. In the path, every engine loads them.
2676
+ Sealed, not signed: content reads its own address, and a grant's viewer and subject are the host's
2677
+ (never shown to content). In the ticket's own answer rather than behind a redirect: P025's own
2678
+ reason (the document comes with its ticket's answer), one round trip fewer, and Playwright's WebKit
2679
+ can't fulfill a routed redirect ("Cannot fulfill with redirect status: 303", measured with
2680
+ `checkPage`'s driver).
2681
+ **Rejected.** The cookie for files (WebKit); a service worker that adds the access (P025's reasons;
2682
+ and P081 refuses them); a signed token (the viewer and subject readable); a store of sessions (the
2683
+ ticket store takes once, and a new store is a new table for every D1 host); a ticket per file; an
2684
+ hour with no grace for the page's own loads (a single-page app's lazy chunk an hour on would fail).
2685
+ **Residual.** `Sec-Fetch-Site` is a browser's word: someone outside a browser who holds an address
2686
+ (from a log) can claim it, and so load that version's files until the session ends, as before the
2687
+ review; revocation is the host's check (`authorize`).
2688
+ **Cost.** A frame's file addresses are new each session (each seal has a fresh IV), so the browser's
2689
+ cache serves a version's files within a session (its reloads and pages), not across sessions.
2690
+ **Tested** (after the review): `test/files.test.ts` (the address opens on its own for an hour, then
2691
+ only same-origin non-navigation loads until the session's end; renewal only from the page; the
2692
+ host's check and the session's end still hold; sealed addresses taken out of what the host is
2693
+ told); `leak/served/files.spec.ts` (no error report, content error or blocked navigation of a page
2694
+ that throws from a module, fails to load a script, rejects with its own address and is stopped from
2695
+ opening a file names `/__porthole/f/`: each says `./`; the shell renews its address under a clock
2696
+ moved 56 minutes on, and the page goes on loading its files), on Chromium, WebKit and Firefox.
2697
+ **Revisit when** WebKit keeps partitioned cookies in frames (then the cookie, stable addresses and
2698
+ the shared cache), or hosts need a version's files cached across sessions (a seal per day).
2699
+
2700
+ ## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted
2701
+
2702
+ **Decision.** Amends P079 (no navigation to another document) and P031 (a navigated frame is
2703
+ started again) for served pages with files. The shell's plan names the version's files' address
2704
+ (`files.base`); its navigate guard lets a navigation go on when its destination is under it and
2705
+ names a page (no extension, `.html`, `.htm`, or a directory), and tells the host first: Porthole's
2706
+ own `porthole/navigating` (`NAVIGATING_METHOD`), which the shell adapter turns into its session's
2707
+ `navigating` event. The host takes the frame's next load as that page: no restart, no `navigated`;
2708
+ the new page's shell says hello again on the same transport. The host takes the notice only from
2709
+ a display whose pages may come with files (`servesFiles`: an artifact with domain isolation), for
2710
+ the next load only, within ten seconds (after the review: any display's content could send it,
2711
+ and the flag lasted, so a load much later skipped P031's restart). A link to such a page opens it in
2712
+ the frame, whatever its target; a link to another file of the set doesn't open, and is reported as
2713
+ a blocked navigation (P080). Every other navigation is stopped, as before.
2714
+ **Threat it re-opens.** A frame that navigates itself carries data out in its URL (P079's reason).
2715
+ Now it may, to its own version's pages, on its own origin: the host's own content server sees the
2716
+ address, as it sees a fetch there (P082). Not to another origin, not to another path of its origin,
2717
+ not to a file that isn't a page (which wouldn't come in the shell). The announcement is the
2718
+ content's word: it only spares a restart, which P031 says is not a wall.
2719
+ **Why.** A set's other pages (Claude's contract names "further HTML pages") are links between
2720
+ pages; a guard that stops them, or a host that starts the display again at its entry on each,
2721
+ breaks every multi-page artifact.
2722
+ **Measured.** Under `navigate-guard` (P079's control), the cases "a link to another page opens it
2723
+ in the frame" (no announcement, so the display starts again) and "a page opens nothing else" (a
2724
+ file that isn't a page, `/`, `/__porthole/d/…` reach the server) fail on Chromium, WebKit and
2725
+ Firefox.
2726
+ **Rejected.** The host opening the page (`openLink`, or a restart at the new address): the frame's
2727
+ history goes, and the sealed address would land in a tab. A new bridge for each page: the host's
2728
+ gates, rates and consent are the display's, across its pages.
2729
+ **Residual.** The host gives annotations (P053) to the display's first page only; live
2730
+ subscriptions a page left keep running until the display ends.
2731
+ **Tested** (after the review): `test/files.test.ts` (the notice spares a restart for a served
2732
+ artifact's display, not one sent eleven seconds before the load, and never for a widget's).
2733
+ **Revisit when** hosts annotate multi-page artifacts (give the marks to each page), or an engine
2734
+ Porthole supports lacks the Navigation API (then `frame-src` is the wall, and a set's pages restart
2735
+ the display).
package/docs/DESIGN.md CHANGED
@@ -110,7 +110,7 @@ no `components` field (P015).
110
110
  | `readData` | 120/min | handler | `readData(uri)` | `resources/read` (`app.readServerResource`) |
111
111
  | `subscribeData` | 60/min (needs `readData`) | handler (`changed`, `signal`) | `subscribeData(uri, onData, onError)` | `resources/subscribe`, `resources/unsubscribe`; the host's `notifications/resources/updated` (MCP's own; none in MCP Apps, P079) |
112
112
  | `setModelContext` | 30/min | handler | — | `ui/update-model-context` (`app.updateModelContext`) |
113
- | `reportError` | 10/min | event | (automatic) | `notifications/message`, level `error` |
113
+ | `reportError` | 10/min | event | (automatic) | `notifications/message`, level `error`; `porthole/navigation-blocked` `{ url }`, a navigation the shell stopped (P080) |
114
114
  | `resize` | none | event | (automatic) | `ui/notifications/size-changed` |
115
115
  | `copyText` | user-activation, 30/min | handler | `copyText(text)` | `porthole/copy-text` (none in the standard) |
116
116
  | `annotate` | 120/min (the frame's reports) | event | — | `porthole/annotate.*` (the host drives it, P053) |
@@ -121,7 +121,10 @@ must pass; `confirm` calls the host's `confirm` function and fails closed withou
121
121
  one; `user-activation` is checked by the shell (advisory: it shares the content's
122
122
  realm) and by the host where the engine passes the gesture up; `consent` asks the
123
123
  host's `consent` function once per display, before its first consent-gated call,
124
- and fails closed without one (P079). `presets.liveWidget` declares `readData` and
124
+ and fails closed without one (P079); a `Refused` given as `consent` refuses them all,
125
+ asking nothing, and their capabilities need no handler (P080). A refused request's
126
+ error carries why, `data: { code, message }` (`consent_required`, `denied`,
127
+ `rate_limited`, `not_allowed`, `failed`; the host's `Refused` words its own, P080). `presets.liveWidget` declares `readData` and
125
128
  `subscribeData` with `consent` and its rate, and keeps egress closed (no option opens
126
129
  it); served, it loads Porthole's libraries from its origin (`egress.libraries`).
127
130
 
@@ -181,6 +184,7 @@ functions not built yet throw `NotBuiltYet` naming their milestone.
181
184
  | React: `PortholeProvider`, `PortholeFrame`, `ConfirmDialog`, `admitFrame` | `src/react/` | core (M4, built) | first host |
182
185
  | Conformance: `ConformanceHost`, `LaunchSpec`, `LaunchedDisplay`, `defineLeakSuite`, `PROBES`, the oracles; `defineServedSuite`, `ServedConformanceHost` | `src/conformance/` | core (M2, built); served modes (done) | any host |
183
186
  | Server: `createServer`, `PortholeServer`, `TicketStore`, `ArtifactStore`, `ContentDomain`, `Grant`, `Access`, `Upstream`, `proxyTo`, `memoryTicketStore` | `src/server/` | served modes (done) | host backends |
187
+ | Files (P081): `checkFileSet`, `filePathProblem`, `fileLimits`, `requestFilePath`, `lookupFile`, `fileTypeOf`, `servesFiles`; `StoredFiles`, `FileAddress`, `versionedAddress`; `lintFiles`, `admitFiles` | `src/files/`, `src/server/files.ts`, `src/check/files.ts` | 0.6 (done) | host backends, publish tools |
184
188
 
185
189
  ### Host API
186
190
 
@@ -238,6 +242,20 @@ and calls `PortholeServer.issue`.
238
242
  - **What a served frame loads** is a `ServedDocument`: the shell (content then
239
243
  arrives over the transport, as for opaque frames), a stored artifact version, the
240
244
  MCP Apps sandbox proxy, or an external app (url mode).
245
+ - **A version made of files** (P081–P084). The store answers a manifest (`files`: path →
246
+ `{ size, sha256, type? }`, an `entry`, `spa`) and `read(path)`; `{ html }` stays one page. Every
247
+ file is looked up in the manifest only, by the path below the version's base, decoded once
248
+ (`requestFilePath`, `lookupFile`: `dir/` is its `index.html`, `name` is `name.html`, the nearest
249
+ `404.html`, the entry for a single-page app's navigations). Its answer is typed by Porthole's
250
+ table (`fileTypeOf`; unknown: a download), `nosniff`, with its CSP (a page's and a script's: the
251
+ frame's plus the version's own path, P082; anything else `default-src 'none'; sandbox`), a
252
+ strong ETag and 304, ranges, `Cross-Origin-Resource-Policy: same-origin` (files), and the cache
253
+ rule of its address (files immutable, pages revalidated); a service worker's script is refused.
254
+ Every page is in the shell. Its address: in a frame, `/__porthole/f/<sealed access>/<path>` (the
255
+ ticket's answer is the entry, whose shell moves to that address first, P083); on a tab, the
256
+ version's own clean address, `entry.at`'s `base` (`/v/3/`), where an address that means the
257
+ latest (`/`, `/style.css`) is redeemed (P081). So a page never mixes versions: its relative
258
+ addresses are its version's. A set's pages open each other in the frame (P084).
241
259
  - **Tickets** are minted by `issue` (one-time, short-lived, bound to an instance and
242
260
  a viewer, stored as their hash), carried once in the frame's URL, and taken by the
243
261
  content origin. A served document (at `/__porthole/d/<instance key>`) comes back in
@@ -360,8 +378,9 @@ with redirect entry):
360
378
  - `instance`: the instance an issue request proposes, as the app means it;
361
379
  - `access`: may this viewer see it, and with what grant;
362
380
  - `authorize`: may this cookie still see it, on each request (P050);
363
- - `source`: a stored page by id and version;
364
- - `entry.at`: the instance a clean address's path names (redirect entry).
381
+ - `source`: a stored version by id and version: one page (`{ html }`), or a set of files (P081);
382
+ - `entry.at`: the instance a clean address's path names (redirect entry), or, for a set of files,
383
+ the instance with its version's own address (`{ instance, base, file }`, P081).
365
384
 
366
385
  **An adopter's whole wiring** (the package's `examples/app.mjs` is this, runnable on Node and
367
386
  Workers; docs/ADOPTING.md walks through it):
@@ -378,7 +397,7 @@ const content = createContentHost<Viewer>({
378
397
  access: async (instance, viewer) =>
379
398
  viewer !== null && (await canSee(viewer, instance)) ? { viewer: viewer.id, subject: viewer.id } : null,
380
399
  authorize: ({ subject }) => (revoked(subject) ? { allow: false, code: "revoked" } : { allow: true }),
381
- source: (id, version) => store.page(id, version), // { html } | null
400
+ source: (id, version) => store.page(id, version), // { html } | { files, read } | null
382
401
  entry: {
383
402
  authorizeUrl: `${env.APP_ORIGIN}/porthole/authorize`,
384
403
  at: (scope, path) => pageAt(scope, path), // "/" → latest, "/v/3" → version 3
@@ -574,6 +593,14 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
574
593
  - **`admitContent(config, content, { refuseOn })`**: the show tool's gate. It refuses errors by
575
594
  default with a text that says what to change; otherwise it shows the content (a widget's
576
595
  document taken as its body) and returns the warnings as a note.
596
+ - **A page with files** (P081): `lintFiles(config, files)` lints each page as `lintContent` does
597
+ (findings name their `path`), holds the set to `checkFileSet`'s rules and the config's limits,
598
+ and looks each relative reference up in the set (markup, CSS, module imports, workers,
599
+ fetches): a page's reference that starts with `/` is an error (it names the address's root, not
600
+ the version: a Vite build without `base: "./"`), one that isn't in the set a warning.
601
+ `admitFiles` is the publish tool's gate, as `admitContent` is the show tool's. `checkPage({
602
+ config, files, driver })` serves the whole set and runs its entry (a served artifact config and
603
+ a driver that serves).
577
604
  - **`checkPage({ config, content, driver })`** (`/check`): the content in the real sandbox at each
578
605
  width and scheme (defaults: the manual's phone and desktop widths, light and dark unless
579
606
  unthemed). The check page (`src/check/page.ts`, bundled and shipped as `/check/page`, a module
@@ -660,7 +687,8 @@ binding is mounting and lifecycle (P034).
660
687
  handlers={{ sendPrompt, openLink }} // one per declared capability; latest are called
661
688
  theme={(scheme) => tokens} // live values for the config's variable names
662
689
  generation={n} // bump to run again from the start
663
- onContentError onHostError onResize onNavigated onRefused onMuted onInitialized onOutcome
690
+ onContentError onHostError onResize onNavigated onNavigationBlocked onRefused onMuted
691
+ onInitialized onOutcome
664
692
  fill? // fill the box and scroll inside, not grow with the content
665
693
  annotating? annotations? focusedAnnotation? onAnnotation? // where annotate is declared
666
694
  aliases? themeKey? renderPlaceholder? eager? confirm? document? instance?
@@ -699,8 +727,9 @@ binding is mounting and lifecycle (P034).
699
727
  view; `{ id, key }` with a new key focuses the same one again); `onAnnotation` gets
700
728
  what the frame reported. A frame that mounts again gets them all.
701
729
  - **Errors** (P055): `onContentError` gets what the content did wrong (what it
702
- threw, what the sandbox blocked, that it kept navigating away): the agent's to
703
- hear. `onHostError` gets what failed on the host's side (`locate`, `mount`,
730
+ threw, what the sandbox blocked, a navigation the shell stopped, that it kept
731
+ navigating away): the agent's to hear. `onNavigationBlocked` gets a stopped
732
+ navigation's address whole (P080). `onHostError` gets what failed on the host's side (`locate`, `mount`,
704
733
  `annotations`): never the agent's. `onError(message, source)` gets both.
705
734
  - **Identity** (P057): `config`, `instance`, `annotations` and the provider's
706
735
  `hostInfo` are compared by value, and the provider's `locator` and `confirm` are
@@ -797,7 +826,7 @@ closed like a strict host's (`leak/inherited-policy.spec.ts`).
797
826
  | 2 | images, CSS images, SVG `<image>`/`<use>`, media and posters, `input type=image`, stylesheets, `@import`, fonts, scripts, `import()`, workers, manifests, icons | CSP `img/media/font/style/script-src` = the allowlist only; `worker-src blob:` | `2.resources` (an allowed image as positive control) | — (the same CSP as item 1) |
798
827
  | 3 | WebRTC (ICE gathering reaches the network outside `connect-src`) | CSP `webrtc 'block'` **and** the shell removes every `RTC*`/`webkitRTC*` constructor, fixed in place, before content runs | `3.webrtc` (an unsandboxed peer connection as positive control: it sends STUN on both engines) | `webrtc` → `3.webrtc` (all three; Firefox's positive control needs `media.peerconnection.ice.loopback`, set in the suite's Firefox project, P035) |
799
828
  | 4 | a nested frame: a fresh realm where item 3's removal never happened | the shell drops frame-like elements (`iframe, frame, frameset, object, embed, portal, fencedframe`) synchronously wherever content connects a node (P030), and an observer removes any that arrive another way, in the document and every shadow root (`attachShadow` is wrapped so closed ones are reached too); documents are rendered inert and imported, never written; `document.open/write` throw; declarative shadow roots can't be built (P029); CSP `frame-src 'none'` | `4.light-dom`, `.sync-realm`, `.open-shadow`, `.closed-shadow`, `.shadow-nested`, `.declarative-shadow`, `.parse-html-unsafe`, `.domparser`, `.document-write`, `.plugins`, `.foreign-object`, `.template-clone`, `.static` (each: the child never runs, no STUN, no frame left) | `frame-guard,sync-guard` → light-dom, sync-realm, plugins, foreign-object, template-clone; `attach-shadow,sync-guard` → closed-shadow, shadow-nested; `declarative-shadow` → declarative-shadow; `parser-entry-points` → document-write (each on all three engines). Either guard alone is covered by the other. |
800
- | 5 | self-navigation out, with data in the URL (`location`, `replace`, `open(…, "_self")`, meta refresh, a link clicked past the shell, an SVG link), to the host's own origin, or to a `blob:`/`data:` document of its own (a fresh realm) | the **embedding page's** `frame-src` (`embedderCsp`: `'none'` for opaque content, P033; frames only, so the host's own workers are untouched, P038): a frame's own CSP cannot stop its own navigation; the shell sends link clicks out through `openLink` and drops refreshes (P030); a display whose frame navigates is started again, at most three times (P031). A served frame's page must let it reach the content origins, so there the shell cancels every navigation the frame starts to another document (the Navigation API's `navigate` event; reloads and same-document ones go on, P079); an opaque frame gets no navigate events | `5.location`, `.replace`, `.open-self`, `.refresh`, `.anchor`, `.svg-link`, `.host-origin`, `.blob`, `.data` (no request reaches the canary or the host; a navigated document never runs: a witness origin hears nothing); served: `leak/served/live.spec.ts` (`location`, `replace`, `open(…, "_self")`, `navigation.navigate` to another content origin and to an outside site: no request reaches either, the document stays) | `embedder-csp` → location, replace, open-self, anchor, svg-link, blob, data, `6.remote-download` (all three; `.refresh` holds: the synchronous guard drops the refresh; Firefox also holds `.data` by itself, P035; the navigation guard has no events in these opaque frames); `embedder-self` → `5.host-origin`; `navigate-guard` → the four served navigation cases (each reaches another content origin) |
829
+ | 5 | self-navigation out, with data in the URL (`location`, `replace`, `open(…, "_self")`, meta refresh, a link clicked past the shell, an SVG link), to the host's own origin, or to a `blob:`/`data:` document of its own (a fresh realm) | the **embedding page's** `frame-src` (`embedderCsp`: `'none'` for opaque content, P033; frames only, so the host's own workers are untouched, P038): a frame's own CSP cannot stop its own navigation; the shell sends link clicks out through `openLink` and drops refreshes (P030); a display whose frame navigates is started again, at most three times (P031). A served frame's page must let it reach the content origins, so there the shell cancels every navigation the frame starts to another document (the Navigation API's `navigate` event; reloads and same-document ones go on, P079), and tells the host (`navigationBlocked`, P080); an opaque frame gets no navigate events | `5.location`, `.replace`, `.open-self`, `.refresh`, `.anchor`, `.svg-link`, `.host-origin`, `.blob`, `.data` (no request reaches the canary or the host; a navigated document never runs: a witness origin hears nothing); served: `leak/served/live.spec.ts` (`location`, `replace`, `open(…, "_self")`, `navigation.navigate` to another content origin and to an outside site: no request reaches either, the document stays, the host is told the sibling's address) | `embedder-csp` → location, replace, open-self, anchor, svg-link, blob, data, `6.remote-download` (all three; `.refresh` holds: the synchronous guard drops the refresh; Firefox also holds `.data` by itself, P035; the navigation guard has no events in these opaque frames); `embedder-self` → `5.host-origin`; `navigate-guard` → the four served navigation cases (each reaches another content origin) |
801
830
  | 6 | forms, popups, downloads, top and parent navigation | `sandbox="allow-scripts"` only; CSP `form-action 'none'` | `6.submit`, `.request-submit`, `.blank-form`, `.open`, `.blank-link`, `.download`, `.remote-download`, `.top`, `.top-link`, `.parent` | `sandbox` → open, blank-link, top, top-link, parent (all three), download (Chromium; WebKit and Firefox started no download either way). Form submits still fail: `form-action` is a second wall |
802
831
  | 7 | `<base>` hijack, plugins | CSP `base-uri 'none'`, `object-src 'none'`; plugins removed as frames | `7.base-plugins` | `base-uri` → `7.base-plugins` (all three); `frame-guard,sync-guard` too (plugins left in place) |
803
832
  | 8 | resource hints and speculation rules | CSP for those an engine governs (`prefetch`, `preload`, `modulepreload`); for the rest the shell drops `dns-prefetch`, `preconnect`, `prefetch`, `prerender` links, speculation rules, refreshes and `x-dns-prefetch-control` metas synchronously, and refuses changes that would make a connected link one (P030); `x-dns-prefetch-control: off` | `8.preconnect`, `.dns-prefetch`, `.prefetch`, `.prerender`, `.preload`, `.modulepreload`, `.speculation-rules` (each in markup, inserted, and switched on by attribute change; no request, no connection) | `sync-guard` → `8.preconnect` (WebKit: it preconnects synchronously, outside CSP). Measured: Chromium and Firefox opened no preconnect even unsandboxed. `dns-prefetch` has no out-of-band oracle here (DNS isn't observed); the element is refused before it connects |
@@ -819,7 +848,7 @@ official App SDK connects under the inline, artifact and MCP Apps presets
819
848
  | 11 | theming | `setTheme(scheme)`: the host sends the resolved variables (the host's live values over the defaults, P028), the shell sets them in place, with `data-theme` and `color-scheme`, then fires the config's theme event once, only when the scheme or a value changed (never at mount, never for a host re-sending what the content has, P061); the frame element's `color-scheme` follows | `11.theme-flip` (no event at mount or for the same scheme; in place: content state kept, the event fired once per flip, back and forth), `11.theme-host-values` (live values for standard and own names; undeclared names dropped) | — |
820
849
  | 11 | base styles | plain CSS at zero specificity (`:where`): native buttons, inputs, selects and text areas take the theme's borders, radius, colors and focus ring, 44 px tall (the manual's touch size); the manual says so for inline widgets | `11.base-styles` (themed; content's own CSS overrides them) | — |
821
850
  | 12 | `sendPrompt` | the shell refuses a call without a gesture; the host refuses one without its page's user activation, then asks `confirm` with the whole text; declines count toward a mute | `12.prompt-gesture-confirm` (a call on load is refused; a click asks; a no sends nothing; a yes reaches the handler), `12.raw-message` (a raw `ui/message` around the shell, no click: refused by the host), `12.mute`, `12.no-confirm` | `confirm-gate` → prompt-gesture-confirm, link, mute, no-confirm; `shell-gesture` → prompt-gesture-confirm, mute; `host-gesture` → raw-message |
822
- | 12 | live data (`readData`, `subscribeData`, P079) | MCP `resources/read`, `resources/subscribe`/`unsubscribe`, `notifications/resources/updated`; the `consent` gate asks the host once per display before the first data call (a no refuses them all; none refuses, fail closed), then the rate; a subscribed read may be answered from the host's cache, marked stale, the fresh one following as an update | `test/live-data.test.ts`; `leak/served/live.spec.ts` (read and followed, consent asked once; cached then fresh; a viewer's no refuses both, no handler runs) | — |
851
+ | 12 | live data (`readData`, `subscribeData`, P079) | MCP `resources/read`, `resources/subscribe`/`unsubscribe`, `notifications/resources/updated`; the `consent` gate asks the host once per display before the first data call (a no refuses them all; none refuses, fail closed), then the rate; a subscribed read may be answered from the host's cache, marked stale, the fresh one following as an update; a refusal tells content why (`data: { code, message }`, P080) | `test/live-data.test.ts`, `test/refusals.test.ts`; `leak/served/live.spec.ts` (read and followed, consent asked once; cached then fresh; a viewer's no refuses both, no handler runs, `denied` with its sentence; a host refusing all without handlers; a handler's `Refused`) | — |
823
852
  | 12 | `openLink` | link clicks go out through `openLink`; the bridge takes http(s) only, without credentials in the URL; confirmed | `12.link` (a web link asks and opens; `javascript:` links and `openLink("javascript:…")` do nothing and are refused) | `link-scheme` → `12.link` |
824
853
 
825
854
  Measured: a click in the frame gives the host page user activation (it propagates to
@@ -836,6 +865,10 @@ for that to lapse and click with raw input.
836
865
  | Url-mode delegation (P049) | `allow` from `permissions`, `""` by default | `leak/served/permissions.spec.ts`: full screen follows it on all three; clipboard writes on Chromium only (WebKit and Firefox let any frame write in a click) | `url-permissions` → the default case (all three) |
837
866
  | Porthole's libraries (P079) | `egress.libraries` (domain isolation; on in `presets.liveWidget`): `script-src <content origin>/__porthole/lib/`; `/server` serves Chart.js 4.5.1 and D3 7.9.0, npm's bytes, on every content origin, without a ticket, immutable | `test/libraries.test.ts` (npm's bytes, pinned, licenses; headers; nothing else under the path); `leak/served/live.spec.ts` (both load and draw in a live widget whose every other load and fetch reaches no oracle) | — (rows 1–2) |
838
867
  | Library CDNs for artifacts (P048, P078) | `egress: LIBRARY_CDNS` in the host's artifact config; closed by default (P022); Tailwind's, jQuery's and Plotly's own CDNs for scripts only | `leak/cdn.spec.ts`: opaque and served, a CDN library loads only when opened; another origin never; a stylesheet, an image and a fetch never reach the libraries' own CDNs | — (the CSP of rows 1–2) |
868
+ | Files: serving (P081) | `StoredFiles`; the manifest only, decoded once; Porthole's type table, `nosniff`, a CSP on every answer, ETag/304, ranges, CORP `same-origin`, service workers refused; every page in the shell | `test/files.test.ts`; `leak/served/files.spec.ts`: many files by relative path (framed, on a tab), the Vite + React build, a newer version never reaches a running page, traversal 404s, `.html` as `.txt` is text, another origin reads nothing, no service worker | `service-worker` → "no service worker ever registers" (all three); `file-corp` → "another origin reads none of the files" (a page elsewhere runs the script, all three) |
869
+ | Files: the version's own path in the CSP (P082) | `fileSetCspDirectives`: `<origin><base>` (tab) or `<origin>/__porthole/f/` (frame) in the seven loading directives; never `'self'` | `leak/served/files.spec.ts`: a page loads no other version's files; a way out past the base is blocked | `file-self` → those two cases (another version's data and module load; `%2e%2e` past the base reaches the server; all three) |
870
+ | Files in a frame: access in the path (P083) | the ticket's answer is the entry; `/__porthole/f/<AES-GCM sealed session>/`; `history.replaceState` before anything loads; the host's check per file; an address opens on its own for an hour (then only the running page's own same-origin loads, till the session ends), renewed by the shell; reported as `./`, never whole | `test/files.test.ts` (sealed: no viewer or subject in it; another origin, a tampered or ended one: 401; revoked: 403; its hour, the page's own loads after it, renewal; redaction); `test/workers.test.ts` (workerd); every framed case of `leak/served/files.spec.ts` on WebKit (no cookie in frames), its reports never naming the address, its renewal under a moved clock | — |
871
+ | Files: pages navigate within the set (P084) | the guard lets a navigation to a page under `files.base` go, after `porthole/navigating`; the host takes the next load as that page | `leak/served/files.spec.ts`: a link opens another page in the frame, the display goes on; a non-page file, `/`, `/__porthole/d/…` never open | `navigate-guard` → both cases (all three) |
839
872
  | Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
840
873
 
841
874
  ### The clipboard, and copy buttons
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "license": "Apache-2.0",
6
6
  "bin": {