@botiverse/porthole 0.5.1 → 0.7.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 (167) hide show
  1. package/README.md +41 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +208 -13
  4. package/dist/bridge/navigation.d.ts +1 -6
  5. package/dist/bridge/navigation.js +11 -0
  6. package/dist/bridge/refusal.d.ts +5 -1
  7. package/dist/bridge/refusal.js +16 -0
  8. package/dist/bridge/types.d.ts +41 -4
  9. package/dist/check/check.d.ts +19 -3
  10. package/dist/check/check.js +55 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/instrument.d.ts +3 -0
  14. package/dist/check/lint.js +31 -12
  15. package/dist/check/page-source.js +1 -1
  16. package/dist/check/page.js +14 -0
  17. package/dist/check/tools.d.ts +23 -0
  18. package/dist/check/tools.js +27 -3
  19. package/dist/compile/policy.d.ts +34 -0
  20. package/dist/compile/policy.js +74 -0
  21. package/dist/config/capabilities.d.ts +62 -3
  22. package/dist/config/capabilities.js +20 -0
  23. package/dist/config/schema.d.ts +32 -0
  24. package/dist/config/validate.d.ts +1 -1
  25. package/dist/config/validate.js +74 -5
  26. package/dist/conformance/harness-source.js +1 -1
  27. package/dist/conformance/index.d.ts +1 -0
  28. package/dist/conformance/index.js +2 -0
  29. package/dist/conformance/runtime.d.ts +58 -0
  30. package/dist/conformance/runtime.js +314 -0
  31. package/dist/files/paths.d.ts +99 -0
  32. package/dist/files/paths.js +263 -0
  33. package/dist/files/types.d.ts +24 -0
  34. package/dist/files/types.js +83 -0
  35. package/dist/guide/gates.d.ts +3 -0
  36. package/dist/guide/gates.js +19 -0
  37. package/dist/guide/guide.d.ts +2 -0
  38. package/dist/guide/guide.js +44 -32
  39. package/dist/guide/limits.js +4 -4
  40. package/dist/guide/runtime.d.ts +13 -0
  41. package/dist/guide/runtime.js +202 -0
  42. package/dist/host/create-host.js +45 -0
  43. package/dist/host/locate.js +8 -0
  44. package/dist/host/locator.js +7 -0
  45. package/dist/host/types.d.ts +18 -0
  46. package/dist/index.d.ts +13 -4
  47. package/dist/index.js +16 -3
  48. package/dist/isolation/types.d.ts +8 -0
  49. package/dist/presets/presets.d.ts +6 -0
  50. package/dist/presets/presets.js +1 -0
  51. package/dist/protocol/adapter.d.ts +4 -0
  52. package/dist/protocol/mcp-apps.d.ts +6 -0
  53. package/dist/protocol/mcp-apps.js +6 -0
  54. package/dist/protocol/runtime-calls.d.ts +28 -0
  55. package/dist/protocol/runtime-calls.js +113 -0
  56. package/dist/protocol/shell-adapter.js +52 -3
  57. package/dist/react/dialog.js +31 -0
  58. package/dist/react/frame.d.ts +13 -0
  59. package/dist/react/frame.js +6 -0
  60. package/dist/runtime/contract.d.ts +193 -0
  61. package/dist/runtime/contract.js +216 -0
  62. package/dist/runtime/db.d.ts +153 -0
  63. package/dist/runtime/db.js +398 -0
  64. package/dist/runtime/declaration.d.ts +86 -0
  65. package/dist/runtime/declaration.js +266 -0
  66. package/dist/runtime/levels.d.ts +33 -0
  67. package/dist/runtime/levels.js +41 -0
  68. package/dist/runtime/requests.d.ts +125 -0
  69. package/dist/runtime/requests.js +199 -0
  70. package/dist/runtime/segments.d.ts +8 -0
  71. package/dist/runtime/segments.js +14 -0
  72. package/dist/runtime/types.generated.d.ts +1 -0
  73. package/dist/runtime/types.generated.js +19 -0
  74. package/dist/server/files.d.ts +57 -0
  75. package/dist/server/files.js +338 -0
  76. package/dist/server/host.d.ts +44 -2
  77. package/dist/server/host.js +42 -2
  78. package/dist/server/index.d.ts +5 -2
  79. package/dist/server/index.js +5 -1
  80. package/dist/server/keys.d.ts +8 -0
  81. package/dist/server/keys.js +34 -0
  82. package/dist/server/pseudonym.d.ts +9 -0
  83. package/dist/server/pseudonym.js +20 -0
  84. package/dist/server/server.d.ts +0 -5
  85. package/dist/server/server.js +468 -24
  86. package/dist/server/types.d.ts +118 -5
  87. package/dist/shell/document.d.ts +27 -0
  88. package/dist/shell/document.js +46 -2
  89. package/dist/shell/legacy.d.ts +21 -0
  90. package/dist/shell/legacy.js +63 -0
  91. package/dist/shell/plan.d.ts +17 -1
  92. package/dist/shell/plan.js +13 -2
  93. package/dist/shell/runtime.d.ts +2 -1
  94. package/dist/shell/runtime.js +114 -46
  95. package/dist/shell/use.d.ts +15 -0
  96. package/dist/shell/use.js +235 -0
  97. package/docs/ADOPTING.md +142 -5
  98. package/docs/ARCHITECTURE.md +34 -5
  99. package/docs/DECISIONS.md +716 -7
  100. package/docs/DESIGN.md +97 -3
  101. package/package.json +3 -1
  102. package/src/bridge/bridge.ts +281 -17
  103. package/src/bridge/navigation.ts +12 -0
  104. package/src/bridge/refusal.ts +16 -0
  105. package/src/bridge/types.ts +46 -4
  106. package/src/check/check.ts +100 -14
  107. package/src/check/files.ts +384 -0
  108. package/src/check/instrument.ts +3 -0
  109. package/src/check/lint.ts +33 -12
  110. package/src/check/page.ts +14 -0
  111. package/src/check/tools.ts +52 -3
  112. package/src/compile/policy.ts +92 -0
  113. package/src/config/capabilities.ts +49 -2
  114. package/src/config/schema.ts +32 -0
  115. package/src/config/validate.ts +107 -5
  116. package/src/conformance/index.ts +7 -0
  117. package/src/conformance/runtime.ts +573 -0
  118. package/src/files/paths.ts +323 -0
  119. package/src/files/types.ts +101 -0
  120. package/src/guide/gates.ts +25 -0
  121. package/src/guide/guide.ts +78 -52
  122. package/src/guide/limits.ts +4 -4
  123. package/src/guide/runtime.ts +244 -0
  124. package/src/host/create-host.ts +55 -0
  125. package/src/host/locate.ts +10 -0
  126. package/src/host/locator.ts +11 -0
  127. package/src/host/types.ts +18 -0
  128. package/src/index.ts +121 -0
  129. package/src/isolation/types.ts +8 -0
  130. package/src/presets/presets.ts +7 -0
  131. package/src/protocol/adapter.ts +3 -1
  132. package/src/protocol/mcp-apps.ts +7 -0
  133. package/src/protocol/runtime-calls.ts +138 -0
  134. package/src/protocol/shell-adapter.ts +56 -2
  135. package/src/react/dialog.tsx +33 -0
  136. package/src/react/frame.tsx +19 -0
  137. package/src/runtime/contract.ts +305 -0
  138. package/src/runtime/db.ts +530 -0
  139. package/src/runtime/declaration.ts +378 -0
  140. package/src/runtime/levels.ts +69 -0
  141. package/src/runtime/requests.ts +339 -0
  142. package/src/runtime/segments.ts +17 -0
  143. package/src/runtime/types.generated.ts +19 -0
  144. package/src/server/files.ts +425 -0
  145. package/src/server/host.ts +84 -3
  146. package/src/server/index.ts +22 -0
  147. package/src/server/keys.ts +53 -0
  148. package/src/server/pseudonym.ts +21 -0
  149. package/src/server/server.ts +565 -26
  150. package/src/server/types.ts +124 -4
  151. package/src/shell/document.ts +74 -4
  152. package/src/shell/legacy.ts +64 -0
  153. package/src/shell/plan.ts +37 -3
  154. package/src/shell/runtime.ts +114 -46
  155. package/src/shell/use.ts +235 -0
  156. package/types/runtime/v1/artifact.d.ts +50 -0
  157. package/types/runtime/v1/assets.d.ts +43 -0
  158. package/types/runtime/v1/chat.d.ts +13 -0
  159. package/types/runtime/v1/clipboard.d.ts +14 -0
  160. package/types/runtime/v1/comments.d.ts +24 -0
  161. package/types/runtime/v1/context.d.ts +16 -0
  162. package/types/runtime/v1/data.d.ts +29 -0
  163. package/types/runtime/v1/db.d.ts +110 -0
  164. package/types/runtime/v1/downloads.d.ts +22 -0
  165. package/types/runtime/v1/links.d.ts +13 -0
  166. package/types/runtime/v1/porthole.d.ts +44 -0
  167. package/types/runtime/v1/user.d.ts +19 -0
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, P089
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,
@@ -370,7 +370,7 @@ allowlists (break ESM imports and data fetches for no egress gain).
370
370
  **Revisit when** most hosts open the CDNs anyway (then consider a preset variant,
371
371
  by a decision that names the residual supply-chain risk).
372
372
 
373
- ## P023 · 2026-10-11 · No `readState`/`writeState` capabilities · Accepted
373
+ ## P023 · 2026-10-11 · No `readState`/`writeState` capabilities · Accepted; amended by P088
374
374
 
375
375
  **Decision.** The vocabulary drops `readState` and `writeState`. An opaque frame
376
376
  keeps an in-memory `localStorage` for its life; content that needs storage that
@@ -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
@@ -979,7 +979,7 @@ location and the rest (a decision each, if ever); delegation in opaque or domain
979
979
  **Revisit when** WebKit or Firefox enforce the clipboard-write policy feature (then the
980
980
  measurement changes), or a host needs another feature.
981
981
 
982
- ## P050 · 2026-10-11 · The host's check runs on every request; Porthole carries the host's decision and never makes it · Accepted
982
+ ## P050 · 2026-10-11 · The host's check runs on every request; Porthole carries the host's decision and never makes it · Accepted; amended by P089
983
983
 
984
984
  **Decision.** `ServerOptions.authorize = { check(request), ttlSeconds? }`. Porthole calls it after
985
985
  a ticket or cookie verifies and before anything of the content is served: a document's first
@@ -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.
@@ -2342,7 +2342,7 @@ accepts either outcome, as the opaque probes do. The opaque probes `5.*` keep fa
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
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
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; codes amended by P087
2346
2346
 
2347
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
2348
  a refused data call's error (below).
@@ -2433,3 +2433,712 @@ told why, nothing started again on re-render); `leak/check.spec.ts` (a served wi
2433
2433
  navigates is told so, without the query). On Chromium, WebKit and Firefox.
2434
2434
  **Revisit when** MCP or MCP Apps standardizes error data for refused requests (follow it), or a
2435
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; amended by P089
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; amended by P091
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).
2736
+
2737
+ ## P085 · 2026-10-18 · The capability runtime: one global, `porthole.use(name)`, under a contract pinned per artifact · Accepted; amended by P091
2738
+
2739
+ Task #124 (contract §7): a page published as an artifact is an app, and an app needs more of its host
2740
+ than 0.6's host functions: who is viewing, its comments, a new version of itself, an asset library,
2741
+ shared data. 笑笑's measured study of Claude's artifacts (Notion, 2026-10-18) gives the shape: a page
2742
+ declares `capabilities: { name: config }` at publish, calls `await claude.use(name)` and gets a
2743
+ frozen namespace or null, hears permission problems when it calls, and is pinned to the runtime
2744
+ contract it was written against; each capability's API is a versioned `.d.ts`. 0.7.0.
2745
+
2746
+ **Decision.**
2747
+ - **The switch is the config's** (`PortholeConfig.runtime: "1"`, `presets.*({ runtime })`): inline
2748
+ widgets and artifact pages only (the shell's protocol). Without it a frame, its globals and its
2749
+ manual are 0.6's, byte for byte (`test/agreement.test.ts`, the existing leak suites).
2750
+ - **One global.** The shell defines `porthole`, frozen and fixed, whose only member is `use(name)`
2751
+ (`shell/use.ts`, spliced into the runtime as `__RUNTIME__`). `use` never rejects: it resolves the
2752
+ capability's namespace (frozen, the same object each time) or null, and null says nothing of why
2753
+ (the host doesn't offer it here, the page didn't declare it, no host answered: a preview, a tab).
2754
+ On a tab (`window.parent === window`) it is null at once; in a frame whose host never answers,
2755
+ after the handshake gives up (10 s).
2756
+ - **What is offered** comes in the handshake, in MCP Apps' own extension point:
2757
+ `hostCapabilities.experimental["porthole/runtime"] = { version, capabilities: { name: [methods] } }`,
2758
+ the display's roster (`rosterOf(config, declared)`: the built-ins the config serves, and what the
2759
+ page declared). The same for every viewer: levels refuse at call time (P087).
2760
+ - **Calls** go as `porthole/call { capability, method, args }` (own-prefixed, P002), answered
2761
+ `{ value }` or a JSON-RPC error whose `data` is `{ code, message }` (P080); a watch adds a
2762
+ frame-chosen `watch` id, its updates come as `porthole/event { watch, data }`, and
2763
+ `porthole/unwatch { watch }` (a notification, never gated) ends it; at most 50 a frame.
2764
+ `data.read` and `data.subscribe` ride MCP's own `resources/*` (the cache and subscriptions of
2765
+ P079). The shell's namespace is sugar: the host's bridge decides every call, whichever way it came.
2766
+ - **The contract** (`RUNTIME_CAPABILITIES`, version `"1"`): each capability a namespace of methods,
2767
+ each method served by one of the config's host functions, with a level (P087) and, for a watch,
2768
+ callbacks. The config still declares host functions and their gates (PRINCIPLE 4); the runtime
2769
+ only says how a page reaches them:
2770
+
2771
+ | `use(…)` | methods | host function | built in (P086) |
2772
+ | --- | --- | --- | --- |
2773
+ | `clipboard` | `copy(text)` | `copyText` | yes |
2774
+ | `links` | `open(url)` | `openLink` | yes |
2775
+ | `downloads` | `save({ name, text \| data })` | `downloadFile` (`ui/download-file`) | yes |
2776
+ | `comments` | `open(anchor)` | `comments` (new, P090) | yes |
2777
+ | `user` | `get()` | `user` (new, answered from the viewer, P087) | no |
2778
+ | `chat` | `send(text)` | `sendPrompt` | no |
2779
+ | `data` | `read(uri)`, `subscribe(uri, onData, onError)`, `call(name, args)` | `readData`, `subscribeData`, `callTool` | no |
2780
+ | `context` | `set({ content, structuredContent })` | `setModelContext` | no |
2781
+ | `artifact` | `get()`, `publish(change)` | `artifact` (new, P088) | no |
2782
+ | `assets` | `list()`, `upload(file)`, `delete(id)` | `assets` (new, P089) | no |
2783
+ | `db` | `get`, `query`, `onSnapshot`, `set`, `update`, `delete`, `batch` | `db` (new, P088) | no |
2784
+
2785
+ `resize`, `reportError` and `annotate` stay the shell's own: content never calls them by name.
2786
+ - **Types.** Each capability's API is a `.d.ts` per contract version (`types/runtime/v1/`, shipped
2787
+ in the package, compiled by `pnpm typecheck` with a page-shaped `check.ts`), the call contract in
2788
+ `porthole.d.ts`. `scripts/runtime-types.ts` embeds them in `src/runtime/types.generated.ts` (a
2789
+ module, P075); the manual's new `capabilities` topic teaches the call contract, declaring, levels,
2790
+ where state goes (localStorage for one person's view, `artifact` when the page is the record, `db`
2791
+ for shared data), and each offered capability's types (`test/agreement.test.ts`: exactly the
2792
+ offered ones, as the files hold them).
2793
+ - **The pin.** A declaration carries the contract version it was written against (P086); a mount
2794
+ checks the version is one this Porthole serves (`RUNTIME_VERSIONS`). A new version will be a new
2795
+ directory of types and a new table; a page keeps its own.
2796
+ - **The legacy path** (`shell/legacy.ts`, since 0.7.0): 0.6's globals (`sendPrompt`, `copyText`,
2797
+ `openLink`, `readData`, `subscribeData`) are still defined for what the config declares, under a
2798
+ runtime too, so stored 0.5 and 0.6 pages run unchanged; under a runtime the manual no longer
2799
+ teaches them (`ShellPlan.legacyGlobals`, defined and untaught, asserted by the agreement test),
2800
+ and a page that declared capabilities is held to its declaration on that path as well (P086).
2801
+ Remove it when no host serves a page written before 0.7.
2802
+
2803
+ **Why.**
2804
+ - One entry point keeps the global namespace the content's own, and a namespace per capability
2805
+ lets the manual teach a capability as one block (its declaration, its methods, its types).
2806
+ - Null rather than an error at `use`: a page draws without what isn't there, wherever it is shown
2807
+ (Claude's `ArtifactCheck` preview has no runtime and resolves null too); permission is a property
2808
+ of each call (consent, rate, level), not of the page.
2809
+ - The roster in the handshake: said once, in the field MCP Apps keeps for extensions, without a
2810
+ round trip per `use`.
2811
+ - Pinned contracts: Claude's runtime does the same (`contract` per artifact); old pages keep the
2812
+ API they were written against.
2813
+
2814
+ **Rejected.**
2815
+ - A global per capability (`window.db`): the content's namespace, and a new global per release.
2816
+ - The name `claude`: a vendor's. `porthole` is Porthole's, the same in every host that runs it.
2817
+ - A `porthole/use` request per call to `use`: a round trip for what the handshake can say once.
2818
+ - Refusing at `use` (a page that branches on who views it at load) and rejecting `use`.
2819
+ - Dropping 0.6's globals: every stored page that calls them would break.
2820
+ - Throwing for a capability the config doesn't offer: a page is written once for many hosts.
2821
+
2822
+ **Revisit when** MCP Apps specifies capability negotiation for views (follow it), a second contract
2823
+ version ships (its own types and table; the pins tell which pages need it), or no host serves a
2824
+ page from before 0.7 (remove `shell/legacy.ts`).
2825
+
2826
+ ## P086 · 2026-10-18 · A page declares the capabilities it uses; built-ins need no declaring; the bridge holds every path to it · Accepted; amended by P091
2827
+
2828
+ **Decision.**
2829
+ - **The declaration** is `{ capabilities: { name: config }, runtime }` (`PageDeclaration`), stored by
2830
+ the host with the artifact and given to each mount (`MountOptions.declaration`, React's
2831
+ `declaration`), checked against the config there (`checkDeclaration`: a `TypeError` for one that
2832
+ doesn't fit). Configs of their own: `data: { resources?, tools? }` (exact names, or a prefix
2833
+ ending in `*`; absent: all the host serves), `db: { rules? }` (P088), and any capability's
2834
+ `levels` (P087, raise only).
2835
+ - **At publish** (`declareCapabilities({ stored, given, config, runtime? })`, the helper hosts call):
2836
+ `given` omitted carries the stored declaration forward with its pin (none stored: an empty one,
2837
+ pinned to the current contract); `{}` clears it; a non-empty object replaces it whole (anything
2838
+ not restated is revoked); each name checked against the host's offer (`declarationProblems`:
2839
+ known, offered by the config, not built in, of its own shape). The pin moves only when the author
2840
+ asks (`runtime`).
2841
+ - **Built-ins** are reachable by any page whose host offers them, declared or not: `clipboard`,
2842
+ `links`, `downloads`, `comments`, whose every effect is the host's own UI, shown to the person (a
2843
+ copy it shows, a link and a download it confirms, a composer the person writes in). Everything
2844
+ else (`user`, `chat`, `data`, `context`, `artifact`, `assets`, `db`) only a page that declared it.
2845
+ - **The bridge holds a call to it**, whichever way it came (`porthole/call`, or 0.6's requests and
2846
+ globals: `resources/read`, `ui/message`, …), before its arguments are read: a capability the page
2847
+ didn't declare is refused `undeclared` (content: `not_allowed`), as is a resource or tool its
2848
+ `data` doesn't name. A display with no declaration is a 0.6 page: built-ins through `use`, 0.6's
2849
+ globals and requests as before, and none of the runtime's own host functions.
2850
+ - **A page can't change its own declaration**: `artifact.publish` carries none, so a new version
2851
+ made from the page keeps what its author declared.
2852
+
2853
+ **Why.** "What can this page do?" is answered by reading what it declared, checked against what the
2854
+ host offers (PRINCIPLE 4 per page, as the config is per kind). The built-ins are the effects a
2855
+ person sees and answers in the host's UI; declaring them would only add noise to every page with a
2856
+ link.
2857
+ **Rejected.**
2858
+ - Everything declared, links and copy buttons too.
2859
+ - A declaration in the page (a `<meta>`): the content's word, which could grant itself anything.
2860
+ - The declaration in the frame's plan: the shell shares the content's realm; the bridge is the wall.
2861
+ - A page that republishes itself with a new declaration: a page (or what injected it) widening its
2862
+ own reach.
2863
+ **Tested.** `test/runtime.test.ts` (problems, carry/clear/replace and the pin, a mount's check; the
2864
+ bridge refusing an undeclared capability and 0.6's requests from a declared page before any
2865
+ handler; data's names); `leak/served/runtime.spec.ts` ("an undeclared capability: null from use,
2866
+ refused when sent anyway, its handler never asked"; "under the runtime, with no declaration") on
2867
+ Chromium, WebKit and Firefox. Negative control `runtime-declaration` (the bridge's check taken out)
2868
+ → the first case on all three engines.
2869
+ **Revisit when** a host needs a declaration per version rather than per artifact, or a built-in
2870
+ grows an effect the person doesn't see.
2871
+
2872
+ ## P087 · 2026-10-18 · Viewer levels decide each method's audience; the host's access says the level; a refusal is a stable code, at call time · Accepted; amended by P091
2873
+
2874
+ **Decision.**
2875
+ - **Levels** `view < interact < admin < owner` (`VIEWER_LEVELS`): view sees and comments; interact
2876
+ uses what the page does (writes its data, asks the agent); admin publishes versions and manages
2877
+ assets; owner. Each runtime method declares the least level that may call it, and a floor below
2878
+ which a host's config can't set it (`RUNTIME_CAPABILITIES`): reads `view`; `chat.send`,
2879
+ `data.call`, `context.set` and db writes `interact`; `artifact.publish` and `assets.delete`
2880
+ `admin` (floor admin); `assets.upload` `admin` (floor interact). A config may set a host
2881
+ function's methods' levels (`CapabilityConfig.levels`, at or above the floor); a page's
2882
+ declaration may raise them, never lower (`methodLevel`).
2883
+ - **Who says the level**: the host, per request. The host kit's `access(instance, viewer)` returns a
2884
+ `Grant` with `level` (and `user: { id, name }`, the person as a page that declares `user` may know
2885
+ them: the host's public id, not `Grant.viewer`); `/server`'s `issue` answers it as
2886
+ `FrameLocation.viewer`, never in the ticket, the cookie or the page; `httpLocator` and
2887
+ `locateServed` carry it (dropped if it doesn't parse) to the display's bridge. An opaque frame, or
2888
+ a host without the kit, passes `MountOptions.viewer`; the issue's answer wins where both are.
2889
+ - **The bridge checks at call time**, after the declaration (P086) and the arguments, before any
2890
+ gate or handler: below the method's level is `level` (content: `forbidden`). Without a viewer,
2891
+ 0.6's host functions run as before (no level is checked: a 0.6 host is unchanged) and the
2892
+ runtime's own (`user`, `comments`, `artifact`, `assets`, `db`) are refused (fail closed). The
2893
+ handler's context carries the viewer (`CallContext.viewer`) and the page's declaration for that
2894
+ capability (`declared`): the app's API checks again, since it is its data's wall
2895
+ (`defineRuntimeConformance` runs its handlers past the bridge to see that it does).
2896
+ - **`user.get()`** answers `{ id, name, level }` from the viewer the host gave, nothing else.
2897
+ - **Codes.** `REFUSAL_CODES` gains `forbidden` (this person may see it but not do this),
2898
+ `conflict` (it moved since it was read, P088) and `too_large` (past a limit); `Refusal` gains
2899
+ `undeclared`, `level`, `too-large`. Content gets the code and Porthole's sentence for it (or the
2900
+ host's `Refused`), never why beyond it. Amends P080's vocabulary; 0.6's data refusals keep their
2901
+ five codes and words.
2902
+
2903
+ **Why.** Claude's runtime decides each capability's audience the same way (view < interact < admin <
2904
+ owner), and the same page runs for every viewer: a level is a property of the person at the call,
2905
+ not of the page. Carried in the issue's answer, the level is decided when the frame is made, by the
2906
+ same policy that decides access, without another request; it never needs to reach the content
2907
+ origin. `forbidden` apart from `not_allowed` lets a page say "ask for access" rather than "not here".
2908
+ **Rejected.** A level refused at `use`; the level in the ticket or cookie (the content server never
2909
+ needs it; less to carry); a level the content says; `not_allowed` for a level.
2910
+ **Tested.** `test/runtime.test.ts` (levels and floors; refused before any handler; no viewer;
2911
+ `user`); `test/assets.test.ts` (a grant's level in the issue's answer and only with one; never in
2912
+ the page; the locator drops what doesn't parse); `leak/served/runtime.spec.ts` ("a method above the
2913
+ viewer's level: forbidden, its handler never asked"). Negative control `runtime-level` (the bridge's
2914
+ level check taken out) → that case on all three engines.
2915
+ **Revisit when** a host needs levels per resource rather than per method (then the host's `Refused`
2916
+ says it, as now), or MCP Apps standardizes a viewer identity for views.
2917
+
2918
+ ## P088 · 2026-10-18 · State the host keeps: a page publishes itself (`artifact`), and shares data (`db`); amends P023 · Accepted; amended by P091
2919
+
2920
+ P023 dropped `readState`/`writeState`: domain mode gives a page real `localStorage`. That is one
2921
+ person's, in one browser. Task #124's pages need state that people share and the agent reads: a
2922
+ checklist that is the record, votes, a board. "Revisit when a host needs persisted state for opaque
2923
+ frames": hosts now need it for every frame, shared. The state stays the host's (PRINCIPLE 8:
2924
+ Porthole stores nothing); Porthole defines the protocol, checks what crosses the frame, and gates it.
2925
+
2926
+ **Decision.**
2927
+ - **`artifact`** (artifact mode only): `get()` answers the current version (`{ version, number?,
2928
+ entry, files: [{ path, size, sha256 }] }`), `publish({ base, files, entry?, label?, note? })` a
2929
+ new one: a patch on `base`'s files (text, bytes as base64, `null` removes; the rest kept), at most
2930
+ 255 files and the config's file limits (`too_large` past them), paths by `filePathProblem`. Admin
2931
+ and above (floor admin). The host checks `base` is current and refuses with `Refused("conflict")`
2932
+ if it moved; it admits the files as any publish (`admitFiles`). No declaration rides it (P086).
2933
+ - **`db`**: a document store per artifact. Paths are slash-separated, segments of
2934
+ `A-Z a-z 0-9 _ . ~ : @ + -`, a collection odd (1–15), a document even (2–16). Ops: `get`,
2935
+ `set`, `update` (a top-level merge), `delete`, `query` (`where` ≤ 10 of `== != < <= > >= in
2936
+ array-contains`, `orderBy`, `limit` ≤ 500), `batch` (≤ 50 writes, ≤ 1 MiB, all or none),
2937
+ `watch` (`onSnapshot`: a document's snapshot or a collection's `{ docs }`, now and at each
2938
+ change, through the host's `changed`, as `subscribeData`'s). Data is plain JSON, ≤ 1 MiB a
2939
+ document, ≤ 32 deep. Every write to a document that exists names the version it read
2940
+ (`ifVersion`; `0`: must not exist), and `update` needs one that exists; a mismatch is `conflict`.
2941
+ Snapshots: `{ path, id, exists, version, data? }`, `version` counting writes from 1.
2942
+ - **Who reaches what** (`dbAccess`, applied by the bridge and again by the host): `data/users/<id>`
2943
+ is that person's (`me`, resolved by Porthole to the viewer's id from the host); any other path
2944
+ under `data`, or another person's, is refused at every level (`forbidden`); a viewer with no id
2945
+ has none. The page's `db.rules` (by top-level collection or `*`: `{ read?, write? }` levels) raise
2946
+ the defaults (read view, write interact).
2947
+ - Hosts implement both behind their own API (Ferry's server, raft-artifacts' Worker), which the
2948
+ handlers call as the viewer; `defineRuntimeConformance` checks versions, conflicts, batches,
2949
+ watches, the per-user data and the rules, past the bridge too.
2950
+
2951
+ **Why.** Claude's runtime has the same two (`artifact` republishes itself, `db` with `if_version`,
2952
+ `data/users/<id>` and `as_level` rules); an agent reads and writes the same rows through its tools,
2953
+ so the shapes are the platform's, not a page's. Versions on every write make concurrent viewers
2954
+ safe without locks; per-user data resolved by the host's id, never the content's word, keeps one
2955
+ person's prefs from another.
2956
+ **Rejected.** P023's key-value `readState`/`writeState` (no versions, no sharing rules); storage in
2957
+ Porthole; rules evaluated only in the content (its word) or only in the bridge (the app's API is
2958
+ reachable by the viewer directly); a CRDT or a live room (later: `room`, broadcast and presence).
2959
+ **Tested.** `test/runtime.test.ts` (shapes, limits, `me`, another's data, rules, data with no id;
2960
+ the reference services against the conformance cases, and a lax host failing every db case);
2961
+ `leak/served/runtime.spec.ts` (db end to end with a conflict and a watch hearing another person's
2962
+ write; a page publishing itself, a stale base a conflict; "a person's own data is theirs"). Negative
2963
+ control `db-private` (the owner check taken out of `dbAccess`) → that case on all three engines.
2964
+ **Revisit when** a host needs transactions across documents beyond a batch, field-level deletes, or
2965
+ live presence (a `room` capability).
2966
+
2967
+ ## P089 · 2026-10-18 · An artifact's asset library at `/_blob/<id>` on its own origin; scripts and styles from it only where uploads are the admins' · Accepted; amended by P091
2968
+
2969
+ Amends P022 and P082 (a page's CSP gains a source on its own origin) and P050 (a running page's own
2970
+ loads of its assets skip the host's per-request check).
2971
+
2972
+ **Decision.**
2973
+ - **The store** is the host's (`ServerOptions.assets`, `createContentHost({ assets })`):
2974
+ `get(id) → { scope, name, size, sha256, read() } | null`. Ids are the host's: 32 lowercase hex
2975
+ characters made at random (`ASSET_ID`). `/server` serves `/_blob/<id>` only on the origin of the
2976
+ asset's own `scope` (another origin: 404), outside every version (P081 kept the path free).
2977
+ - **Who gets it** (as P091 made it): a request carrying an access to the asset's own artifact (a
2978
+ session cookie, or a framed set's sealed files' address as its `Referer`; or the frame's own
2979
+ address for it, `assets.url(id)`), which the host's check then decides. Anything else is a plain
2980
+ 401; never an entry (an asset is no address to sign in for). The first cut took a same-origin
2981
+ `Sec-Fetch-Site` alone, which anyone outside a browser can send.
2982
+ - **How it is served**: typed by Porthole's table by its name (never the uploader's type, never
2983
+ sniffed); never as a page (a name typed HTML goes as `application/octet-stream`, a download);
2984
+ `default-src 'none'; sandbox` (an SVG or XML opened on its own runs nothing), `nosniff`,
2985
+ `Cross-Origin-Resource-Policy: same-origin`, `private, max-age=31536000, immutable` (an id never
2986
+ names other bytes), its sha256 the ETag, one range.
2987
+ - **The page's CSP** (`assetCspDirectives`), where its config declares `assets`: `<origin>/_blob/`
2988
+ (the page's own origin, exact) in `img-src`, `media-src`, `font-src` and `connect-src`, always; in
2989
+ `script-src` and `style-src` only where `assets.upload` is admin or above (`assetCodeRuns`):
2990
+ people who may publish the page's code may add code. Never `'self'`.
2991
+ - **The capability** (`assets`, artifact mode, domain isolation): `list()` (view), `upload(file)`
2992
+ (admin; a host may let people who interact, floor interact), `delete(id)` (admin, floor admin).
2993
+ An upload's name must be one Porthole's table types and not a page; at most `maxFileBytes`.
2994
+ `upload` answers `{ id, url: "/_blob/<id>", name, type, size }`.
2995
+
2996
+ **Threats it re-opens, bounded.**
2997
+ - Content loads from its own origin outside its version's path: only `/_blob/`, its artifact's own
2998
+ library, the same trust domain as its versions (P082).
2999
+ - Files someone who interacts uploaded are shown to every viewer: images, media, fonts and data
3000
+ only, never as code (no `script-src`/`style-src` then) and never as a page; an SVG shown as an
3001
+ image runs nothing, opened on its own runs nothing (its CSP).
3002
+ - (The first cut's: a running page's own loads skipped the host's check, and a forged
3003
+ `Sec-Fetch-Site` reached any asset by id. P091 closed it: every load carries an access and gets
3004
+ the host's check, revalidated each time; by id alone only in bearer mode, the host's opt-in.)
3005
+ - `connect-src` lets a page read its assets' bytes: data it could show anyway.
3006
+
3007
+ **Why.** Large or binary media that outlives versions, and that viewers add through the page, needs
3008
+ a stable address any version can use; Claude's content origin serves `/_blob/<id>` outside
3009
+ `/_f/<version>/` the same way (measured, task #124 §1.4). A frame has no cookie (P083), and a stored
3010
+ asset address can't carry a session, so the page's own origin is the credential.
3011
+ **Rejected.** Serving assets under the frame's sealed path (a page stores `/_blob/<id>` in its data
3012
+ and HTML, where a sealed address would be a session leaked into a record); `'self'`; capability
3013
+ URLs with no session for navigations; the uploader's type; HTML assets; scripts from the library
3014
+ whoever uploads.
3015
+ **Measured** (Playwright 1.63, `leak/served/runtime.spec.ts`): an upload from the page is served and
3016
+ loads in its frame, and a file set's page loads the library in its frame, on Chromium, WebKit and
3017
+ Firefox (each sends `Sec-Fetch-Site` for `*.localhost`); a script asset runs where uploads are the
3018
+ admins' and not where people who interact upload; an SVG asset opened on a tab with the artifact's
3019
+ session runs nothing. Negative controls: `blob-script` (the harness opens scripts and styles to the
3020
+ library whoever uploads) → "its scripts run only where uploads are the admins'"; `blob-inert` (the
3021
+ harness drops an asset's CSP) → "an asset opened on its own runs nothing"; on all three engines.
3022
+ **Tested.** `test/assets.test.ts` (served to its own origin's loads, inert, typed, ranges; 404 on
3023
+ another scope's origin or a malformed id; never a page; 401 without a session, never an entry; a
3024
+ tab's session with the host's check; the page's CSP with and without uploads open; nothing without a
3025
+ store); `test/runtime.test.ts` (the CSP sources; upload limits and names).
3026
+ **Revisit when** an engine stops sending Fetch Metadata to a content origin, the content domain joins
3027
+ the public suffix list (CORP becomes defense in depth), or a host needs assets shared across
3028
+ artifacts (`copy_from`: a new id in the destination).
3029
+
3030
+ ## P090 · 2026-10-18 · Comments from the page: the host's composer at the page's anchor, write-only · Accepted; amended by P091
3031
+
3032
+ **Decision.** `comments` is a built-in (P086) host function served by a handler: `open({ name,
3033
+ label?, quote? })` (a name the page chose, ≤ 256 characters, `slide-3`, `refs/a.md#L12`; a label ≤
3034
+ 200; the quoted text ≤ 2,000), from a click (`user-activation`, 30 a minute), at view level. The
3035
+ host opens its own composer at that anchor (a custom anchor, task #124 §9, beside P053's quote and
3036
+ element anchors) and the person writes and posts there. Content hears whether the composer opened:
3037
+ the bridge answers `true` only for a handler's `true`, whatever else it returned. There is no method
3038
+ that reads a thread.
3039
+ **Why.** Threads hold other people's words: a page that could read them could carry them out (into
3040
+ its data, to the agent) or answer as someone. Reading and replying is the agent's, through the host's
3041
+ tools (Claude's `ArtifactComments`), and the person's, in the host's UI.
3042
+ **Rejected.** A `list` or `on` method; the page posting a comment itself (a comment is a person's
3043
+ word, written by them); comments only through annotations (P053's anchors are the host's to drive).
3044
+ **Tested.** `test/runtime.test.ts` (a handler that answers a thread: content hears `false`; a
3045
+ malformed anchor refused); `leak/served/runtime.spec.ts` ("comments are write-only": the namespace
3046
+ has `open` only, a raw `comments.list` is refused, the composer opens from a click and content hears
3047
+ only that). Negative control `comments-result` (the bridge passes the handler's answer on) → that
3048
+ case on all three engines.
3049
+ **Revisit when** a page needs to show its comment counts (then a count, through the host, never the
3050
+ words).
3051
+
3052
+ ## P091 · 2026-10-18 · The security review of 0.7.0's first cut: what each finding changed · Accepted
3053
+
3054
+ Amends P083 (a framed set's pages that may load assets send their own origin a `Referer`), P085,
3055
+ P086, P087, P088, P089 (assets need an access) and P090. No high finding; every one is fixed
3056
+ before the release, each with its regression (`test/runtime-review.test.ts`, `test/assets.test.ts`,
3057
+ `leak/served/runtime.spec.ts`).
3058
+
3059
+ **Decision**, by finding:
3060
+ 1. **Assets need an access, then the host's check** (was: a same-origin claim alone, which `curl`
3061
+ can send). `/_blob/<id>` is served for a request that carries an access to an artifact of the
3062
+ origin: a session cookie (tabs; a single page's frame where the engine keeps cookies), or a
3063
+ framed set's sealed files' address (P083) as its `Referer`. A framed set's pages, and its
3064
+ files, now say `Referrer-Policy: same-origin` (header and the shell's `<meta>`) where the
3065
+ config serves assets: the address goes to the page's own origin only, which already sees it in
3066
+ every file request. Measured: WebKit sends a cross-site frame's same-origin requests only the
3067
+ origin, so every page also has `assets.url(id)`, the address that loads an asset in this page
3068
+ now: `<sealed base>__porthole/blob/<id>` in a frame (the access in the path, as P083's files),
3069
+ `/_blob/<id>` elsewhere; never stored (the manual and the `.d.ts` say so). The store is asked
3070
+ with the access (`AssetStore.get(id, access)`), an asset names its artifact
3071
+ (`StoredAsset.artifact`) and is served only to an access for that artifact (a session for B no
3072
+ longer opens A's asset on a shared scope), after the host's check; `private, no-cache` with its
3073
+ sha256 ETag, so a removal or a revocation holds at the next load. By id alone only in bearer
3074
+ mode, an explicit opt-in (`AssetStore.bearer`). Only `/_blob/` and 32 hex characters is an
3075
+ asset; any other path there is a clean address, as in 0.6.
3076
+ 2. **db checks are linear and bounded, cheap ones first**: no object reached twice (structured
3077
+ clone keeps shared references: 31 objects were 2^31 nodes), a node budget (100,000 a document,
3078
+ one for a whole batch), a `where` operand's 1,000 nodes and 16 KiB; and for the runtime's own
3079
+ host functions the method's level and the host function's rate come before their arguments are
3080
+ read (`precheck`).
3081
+ 3. **Gates per method** (`RuntimeMethod.gates`, `CapabilityConfig.methodGates`, `callGates`): what
3082
+ changes the artifact for everyone, `artifact.publish` and `assets.delete`, needs a gesture and a
3083
+ confirmation by default; `assets.upload` a confirmation where uploaded code may run. The shell
3084
+ refuses those methods without a gesture (`ShellPlan.methodActivation`), the React dialog words
3085
+ them, and the manual says so per method, with "show rows with textContent, never innerHTML".
3086
+ 4. **A batch is its writes, a watch its read**: a batch needs the highest level of its writes'
3087
+ methods, a watch that of `get` (a document) or `query` (a collection).
3088
+ 5. **db never tells a page the viewer's id**: the bridge says `data/users/me` for every path in the
3089
+ viewer's own tree, in answers and in watches (`withMe`).
3090
+ 6. **No viewer is never a way past a level**: under a runtime, a display without a viewer is
3091
+ refused anything above view; a viewer that doesn't parse is the host's error (`locateServed`,
3092
+ `httpLocator`, a mount), never no viewer.
3093
+ 7. **Rules are the page's own names**: `Object.hasOwn` in `dbAccess`, and a checked declaration is
3094
+ copied into objects without a prototype (a collection named `constructor` is no rule).
3095
+ 8. **A new page follows nothing the last one did**: another page of the set (P084) or a repeat
3096
+ handshake ends the frame's watches and live subscriptions; the shell's watch ids are random.
3097
+ 9. **What an upload may become**: where people who interact upload, code-typed names (scripts,
3098
+ stylesheets, WebAssembly) are refused; an upload is `trusted` only when an admin made it where
3099
+ uploaded code may run (the bridge sets it, the store keeps it), and a code-typed asset is
3100
+ served as code only when trusted and the artifact's config still lets uploaded code run;
3101
+ anything else goes as a download, whatever the CSP opens. The manual no longer says "never run".
3102
+ 10. **Under a runtime a mount says what its page declared**: `MountOptions.declaration` is
3103
+ required; `null` is the host's word for a page published before 0.7 (0.6's surface). A
3104
+ declaration without a runtime is an error. `checkPage({ declaration })` takes one too.
3105
+ 11. **The low ones**: a viewer's id is one db path segment, never `me`; a prefix in `data`'s names
3106
+ vouches for no name with a dot segment, an escape or a backslash; a published `__proto__` path
3107
+ is a path (objects without a prototype); `__proto__`, `constructor` and `prototype` are no
3108
+ document fields; a batch names each path once; a store under `data` folds no case; the
3109
+ reference store holds every write to an existing document to its version, checks a batch in
3110
+ order, caps a collection watch as a query, and checks and admits a merged version.
3111
+ 12. **Back compatibility**: `capabilities` is a built-in guide topic only under a runtime (a 0.6
3112
+ config's own topic of that name stays its own).
3113
+ - Also: a version is shown with what it and the artifact both declare
3114
+ (`intersectDeclarations(version's, current)`: hosts store a declaration per version);
3115
+ `porthole.use` resolves null at once where the frame's ancestor isn't one of its hosts, waits for
3116
+ the handshake 3 s at most, and takes a late offer for the calls after it; `pseudonymFor(secret,
3117
+ artifact, person)` gives a person an id per artifact; `defineRuntimeConformance({ api })` runs
3118
+ the past-the-bridge cases against the app's own API with a forged context (a viewer claiming to
3119
+ be the owner, no rules), and the docs say never to trust `context.viewer` or `context.declared`
3120
+ for what data allows.
3121
+ - **Harness**: a control whose text is gone stops the run before anything is served
3122
+ (`checkWeakenings`), the harness's response controls compose, `blob-trusted` is new (an
3123
+ untrusted asset served as the script its name says), and `scripts/controls.ts`
3124
+ (`pnpm --filter @botiverse/porthole test:controls`, a CI job per engine) runs each control and
3125
+ requires it to fail exactly its probes on every engine, and nothing else.
3126
+
3127
+ **Threat it re-opens.** A framed set's pages tell their own origin their sealed address in
3128
+ `Referer` (P083 sent none): only to that origin, the content server that served it (it sees the
3129
+ address in every file request already); nothing goes to another origin (`same-origin`), and pages
3130
+ whose config serves no assets still send none.
3131
+ **Why.** Each finding was a way past a wall the entries above claimed: a forgeable header in place
3132
+ of an access, a validation step that cost exponential time on the host's main thread, levels a
3133
+ batch or a missing viewer skipped, an id leaked through paths, a prototype's names read as rules,
3134
+ a page's updates heard by the next page, code a viewer uploaded made runnable by a later config.
3135
+ **Rejected.**
3136
+ - A partitioned cookie for `/_blob/`: WebKit keeps none in a cross-site frame (P025).
3137
+ - Rewriting `/_blob/` addresses in the page (the shell or the server): CSS, scripts and markup
3138
+ build them in more ways than a rewrite can see; `assets.url` is one call that always works.
3139
+ - Serving assets under the sealed address only: a page's stored HTML and data name `/_blob/<id>`,
3140
+ which tabs and most frames load as they are.
3141
+ - `user-activation` on uploads: a file picker's change event isn't a gesture in every engine.
3142
+ **Revisit when** WebKit sends a cross-site frame's same-origin requests their full `Referer`, or
3143
+ keeps partitioned cookies there (then `/_blob/<id>` loads everywhere and `assets.url` is a
3144
+ convenience); or a host needs per-collection levels beyond a batch's.