@botiverse/porthole 0.6.0 → 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 (145) hide show
  1. package/README.md +16 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +200 -8
  4. package/dist/bridge/refusal.d.ts +5 -1
  5. package/dist/bridge/refusal.js +16 -0
  6. package/dist/bridge/types.d.ts +41 -4
  7. package/dist/check/check.d.ts +7 -0
  8. package/dist/check/check.js +1 -0
  9. package/dist/check/instrument.d.ts +3 -0
  10. package/dist/check/lint.js +4 -2
  11. package/dist/check/page-source.js +1 -1
  12. package/dist/check/page.js +14 -0
  13. package/dist/check/tools.js +2 -3
  14. package/dist/compile/policy.d.ts +19 -0
  15. package/dist/compile/policy.js +42 -0
  16. package/dist/config/capabilities.d.ts +62 -3
  17. package/dist/config/capabilities.js +20 -0
  18. package/dist/config/schema.d.ts +24 -0
  19. package/dist/config/validate.d.ts +1 -1
  20. package/dist/config/validate.js +66 -4
  21. package/dist/conformance/harness-source.js +1 -1
  22. package/dist/conformance/index.d.ts +1 -0
  23. package/dist/conformance/index.js +2 -0
  24. package/dist/conformance/runtime.d.ts +58 -0
  25. package/dist/conformance/runtime.js +314 -0
  26. package/dist/guide/gates.d.ts +3 -0
  27. package/dist/guide/gates.js +19 -0
  28. package/dist/guide/guide.d.ts +2 -0
  29. package/dist/guide/guide.js +34 -32
  30. package/dist/guide/limits.js +4 -4
  31. package/dist/guide/runtime.d.ts +13 -0
  32. package/dist/guide/runtime.js +202 -0
  33. package/dist/host/create-host.js +24 -0
  34. package/dist/host/locate.js +8 -0
  35. package/dist/host/locator.js +7 -0
  36. package/dist/host/types.d.ts +18 -0
  37. package/dist/index.d.ts +8 -2
  38. package/dist/index.js +9 -1
  39. package/dist/isolation/types.d.ts +8 -0
  40. package/dist/presets/presets.d.ts +6 -0
  41. package/dist/presets/presets.js +1 -0
  42. package/dist/protocol/runtime-calls.d.ts +28 -0
  43. package/dist/protocol/runtime-calls.js +113 -0
  44. package/dist/protocol/shell-adapter.js +48 -3
  45. package/dist/react/dialog.js +31 -0
  46. package/dist/react/frame.d.ts +13 -0
  47. package/dist/react/frame.js +6 -0
  48. package/dist/runtime/contract.d.ts +193 -0
  49. package/dist/runtime/contract.js +216 -0
  50. package/dist/runtime/db.d.ts +153 -0
  51. package/dist/runtime/db.js +398 -0
  52. package/dist/runtime/declaration.d.ts +86 -0
  53. package/dist/runtime/declaration.js +266 -0
  54. package/dist/runtime/levels.d.ts +33 -0
  55. package/dist/runtime/levels.js +41 -0
  56. package/dist/runtime/requests.d.ts +125 -0
  57. package/dist/runtime/requests.js +199 -0
  58. package/dist/runtime/segments.d.ts +8 -0
  59. package/dist/runtime/segments.js +14 -0
  60. package/dist/runtime/types.generated.d.ts +1 -0
  61. package/dist/runtime/types.generated.js +19 -0
  62. package/dist/server/files.d.ts +14 -1
  63. package/dist/server/files.js +97 -3
  64. package/dist/server/host.d.ts +6 -1
  65. package/dist/server/host.js +5 -0
  66. package/dist/server/index.d.ts +2 -1
  67. package/dist/server/index.js +1 -0
  68. package/dist/server/pseudonym.d.ts +9 -0
  69. package/dist/server/pseudonym.js +20 -0
  70. package/dist/server/server.d.ts +0 -5
  71. package/dist/server/server.js +214 -35
  72. package/dist/server/types.d.ts +69 -0
  73. package/dist/shell/document.d.ts +8 -0
  74. package/dist/shell/document.js +16 -2
  75. package/dist/shell/legacy.d.ts +21 -0
  76. package/dist/shell/legacy.js +63 -0
  77. package/dist/shell/plan.d.ts +17 -1
  78. package/dist/shell/plan.js +13 -2
  79. package/dist/shell/runtime.js +29 -42
  80. package/dist/shell/use.d.ts +15 -0
  81. package/dist/shell/use.js +235 -0
  82. package/docs/ADOPTING.md +91 -6
  83. package/docs/ARCHITECTURE.md +22 -3
  84. package/docs/DECISIONS.md +415 -6
  85. package/docs/DESIGN.md +66 -0
  86. package/package.json +3 -1
  87. package/src/bridge/bridge.ts +273 -12
  88. package/src/bridge/refusal.ts +16 -0
  89. package/src/bridge/types.ts +46 -4
  90. package/src/check/check.ts +8 -0
  91. package/src/check/instrument.ts +3 -0
  92. package/src/check/lint.ts +4 -2
  93. package/src/check/page.ts +14 -0
  94. package/src/check/tools.ts +2 -3
  95. package/src/compile/policy.ts +54 -0
  96. package/src/config/capabilities.ts +49 -2
  97. package/src/config/schema.ts +24 -0
  98. package/src/config/validate.ts +99 -4
  99. package/src/conformance/index.ts +7 -0
  100. package/src/conformance/runtime.ts +573 -0
  101. package/src/guide/gates.ts +25 -0
  102. package/src/guide/guide.ts +59 -53
  103. package/src/guide/limits.ts +4 -4
  104. package/src/guide/runtime.ts +244 -0
  105. package/src/host/create-host.ts +34 -0
  106. package/src/host/locate.ts +10 -0
  107. package/src/host/locator.ts +11 -0
  108. package/src/host/types.ts +18 -0
  109. package/src/index.ts +89 -0
  110. package/src/isolation/types.ts +8 -0
  111. package/src/presets/presets.ts +7 -0
  112. package/src/protocol/runtime-calls.ts +138 -0
  113. package/src/protocol/shell-adapter.ts +52 -3
  114. package/src/react/dialog.tsx +33 -0
  115. package/src/react/frame.tsx +19 -0
  116. package/src/runtime/contract.ts +305 -0
  117. package/src/runtime/db.ts +530 -0
  118. package/src/runtime/declaration.ts +378 -0
  119. package/src/runtime/levels.ts +69 -0
  120. package/src/runtime/requests.ts +339 -0
  121. package/src/runtime/segments.ts +17 -0
  122. package/src/runtime/types.generated.ts +19 -0
  123. package/src/server/files.ts +117 -4
  124. package/src/server/host.ts +12 -0
  125. package/src/server/index.ts +3 -0
  126. package/src/server/pseudonym.ts +21 -0
  127. package/src/server/server.ts +247 -37
  128. package/src/server/types.ts +68 -0
  129. package/src/shell/document.ts +21 -4
  130. package/src/shell/legacy.ts +64 -0
  131. package/src/shell/plan.ts +37 -3
  132. package/src/shell/runtime.ts +29 -42
  133. package/src/shell/use.ts +235 -0
  134. package/types/runtime/v1/artifact.d.ts +50 -0
  135. package/types/runtime/v1/assets.d.ts +43 -0
  136. package/types/runtime/v1/chat.d.ts +13 -0
  137. package/types/runtime/v1/clipboard.d.ts +14 -0
  138. package/types/runtime/v1/comments.d.ts +24 -0
  139. package/types/runtime/v1/context.d.ts +16 -0
  140. package/types/runtime/v1/data.d.ts +29 -0
  141. package/types/runtime/v1/db.d.ts +110 -0
  142. package/types/runtime/v1/downloads.d.ts +22 -0
  143. package/types/runtime/v1/links.d.ts +13 -0
  144. package/types/runtime/v1/porthole.d.ts +44 -0
  145. 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; amended by P082
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
@@ -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
@@ -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).
@@ -2590,7 +2590,7 @@ content needs offline (a service worker of Porthole's own making), the conforman
2590
2590
  content domain joins the public suffix list (then siblings are other sites, and CORP is defense in
2591
2591
  depth only).
2592
2592
 
2593
- ## P082 · 2026-10-18 · A served page with files loads its own version's files, by their path; never `'self'` · Accepted
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
2594
 
2595
2595
  **Decision.** Amends P022 for served pages with files. Their pages and scripts get the frame's CSP
2596
2596
  with one source added to `script-src`, `style-src`, `font-src`, `img-src`, `media-src`,
@@ -2638,7 +2638,7 @@ windows and workers cross it).
2638
2638
  **Revisit when** content needs to load other versions' files (a diff view: through the host), or a
2639
2639
  browser keeps path matching across redirects.
2640
2640
 
2641
- ## P083 · 2026-10-18 · A page with files in a frame carries its access in its files' path, sealed · Accepted
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
2642
 
2643
2643
  **Decision.** Amends P025 for served pages with files. The ticket's answer is the version's entry
2644
2644
  page, in the shell, `no-store`, with no cookie; its plan carries the address of its files,
@@ -2733,3 +2733,412 @@ artifact's display, not one sent eleven seconds before the load, and never for a
2733
2733
  **Revisit when** hosts annotate multi-page artifacts (give the marks to each page), or an engine
2734
2734
  Porthole supports lacks the Navigation API (then `frame-src` is the wall, and a set's pages restart
2735
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.
package/docs/DESIGN.md CHANGED
@@ -114,6 +114,11 @@ no `components` field (P015).
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) |
117
+ | `user` (runtime) | 60/min | viewer (the host's `ViewerInfo`) | `porthole.use("user")` | `porthole/call` (P087) |
118
+ | `comments` (runtime) | user-activation, 30/min | handler (answers a boolean) | `porthole.use("comments")` | `porthole/call` (P090) |
119
+ | `artifact` (runtime, artifact mode) | 10/min | handler (`op: get \| publish`) | `porthole.use("artifact")` | `porthole/call` (P088) |
120
+ | `assets` (runtime, served artifacts) | 30/min | handler (`op: list \| upload \| delete`) | `porthole.use("assets")` | `porthole/call`; `/server` serves `/_blob/<id>` (P089) |
121
+ | `db` (runtime) | 600/min | handler (`op: get \| query \| watch \| set \| update \| delete \| batch`) | `porthole.use("db")` | `porthole/call`, `porthole/event`, `porthole/unwatch` (P088) |
117
122
 
118
123
  Every preset declares only `resize` and `reportError` (they report to the host and
119
124
  carry nothing out); the host declares the rest. Gates are explained in P021: all
@@ -755,6 +760,62 @@ for `localStorage` in an opaque frame, applies the theme variables, and fires th
755
760
  config's theme event after a change. A capability that is not declared is simply
756
761
  absent.
757
762
 
763
+ ## The capability runtime (0.7.0: P085–P090)
764
+
765
+ A config with `runtime: "1"` (inline widgets and artifact pages) gives its frames one global,
766
+ `porthole`, whose only member is `use(name)`:
767
+
768
+ ```js
769
+ const db = await porthole.use("db"); // a frozen namespace, or null (not here: draw without it)
770
+ if (db) {
771
+ try { await db.set("votes/me-1", { choice: "b" }, { ifVersion: 0 }); }
772
+ catch (error) { show(error.message); if (error.code === "conflict") reread(); } // a stable code
773
+ }
774
+ ```
775
+
776
+ - **Contract** (`RUNTIME_CAPABILITIES`, version 1; `types/runtime/v1/*.d.ts`): `clipboard`,
777
+ `links`, `downloads`, `comments` (built in), `user`, `chat`, `data`, `context`, `artifact`,
778
+ `assets`, `db` (declared). Each method is served by one of the config's host functions, gated as
779
+ the config says; the table in P085 maps them.
780
+ - **Declaration** (P086): `{ capabilities: { name: config }, runtime }`, stored by the host,
781
+ resolved at publish by `declareCapabilities` (omitted carries forward, `{}` clears, an object
782
+ replaces), checked against the config, given to `mount({ declaration })`. The bridge refuses an
783
+ undeclared capability on every path (`undeclared` → `not_allowed`). No declaration: a 0.6 page.
784
+ - **Levels** (P087): `view < interact < admin < owner`; each method's least level (config `levels`
785
+ at or above its floor; a page's declaration raises). The host's access says the viewer's level
786
+ (`Grant.level`, `Grant.user` → `FrameLocation.viewer`; or `mount({ viewer })`); below it is
787
+ `forbidden`, before any handler. Without a viewer 0.6's functions run as before; the runtime's own
788
+ are refused.
789
+ - **Order in the bridge**: declared in the config → declared by the page → for the runtime's own,
790
+ the method's level and the host function's rate before the arguments are read → arguments
791
+ (shape, bounded walks, limits: `too_large`) → the call's level (a batch's writes', a watch's
792
+ read's), `data`'s names, `db`'s paths and rules → mute → rates → gesture → consent → confirm
793
+ (the host function's gates and the method's own: `artifact.publish` and `assets.delete` a click
794
+ and a yes, an upload whose code may run a yes) → the handler (context: `viewer`, `declared`,
795
+ `instance`) → `db` answers with `data/users/me` (P091).
796
+ - **Mounts under a runtime** say what the page declared (`declaration`, or `null` for a page from
797
+ before 0.7); an older version is mounted with `intersectDeclarations(version's, current)`. A
798
+ display without a viewer gets nothing above view; a viewer that doesn't parse is an error.
799
+ - **Wire**: the roster in `ui/initialize`'s `hostCapabilities.experimental["porthole/runtime"]`;
800
+ `porthole/call { capability, method, args, watch? }` → `{ value }` or an error with
801
+ `data: { code, message }`; `porthole/event { watch, data }`; `porthole/unwatch { watch }`.
802
+ `data.read`/`data.subscribe` use MCP's `resources/*`.
803
+ - **Services are the host's**: `db` (paths, versions, `ifVersion`, batches, watches, `data/users/<id>`
804
+ private, the page's rules: `dbAccess`, which the host applies again), `artifact` (current version;
805
+ a base-checked patch), `assets` (an `AssetStore` `/server` serves at `/_blob/<id>`), `comments`
806
+ (the host's composer; content hears a boolean). `defineRuntimeConformance` checks an app's real
807
+ handlers, and with `api` its own API past the bridge with a forged context (never trust
808
+ `context.viewer` or `context.declared`); `leak/runtime/memory.ts` is the reference, in memory.
809
+ `pseudonymFor(secret, artifact, person)` gives a person an id per artifact.
810
+ - **Assets on the content origin** (P089, P091): for an access to the asset's artifact (a session
811
+ cookie, a framed set's sealed address as `Referer`, or `assets.url(id)`'s
812
+ `<sealed base>__porthole/blob/<id>`), then the host's check, then `AssetStore.get(id, access)`;
813
+ revalidated (`no-cache`, ETag); code-typed only where trusted and the config lets uploaded code
814
+ run; by id alone only in bearer mode.
815
+ - **The manual**: under a runtime, topic `interactive` lists `porthole.use`'s methods with levels and
816
+ gates, and topic `capabilities` teaches declaring, levels, errors, where state goes, and each
817
+ offered capability's `.d.ts`. 0.6's globals stay defined (`shell/legacy.ts`) and untaught.
818
+
758
819
  ## The modes
759
820
 
760
821
  - **Inline widget** (`presets.inlineWidget`). The host has the HTML (the agent
@@ -869,6 +930,11 @@ for that to lapse and click with raw input.
869
930
  | 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
931
  | 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
932
  | 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) |
933
+ | The runtime: a page's declaration (P086) | the bridge refuses a capability the page didn't declare (`undeclared`), on `porthole/call` and 0.6's requests alike, before any handler | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "an undeclared capability: null from use, refused when sent anyway, its handler never asked" | `runtime-declaration` → that case (all three) |
934
+ | The runtime: levels (P087) | each method's least level against the host's viewer, before any handler | `test/runtime.test.ts`, `test/assets.test.ts` (the grant's level to the bridge); `leak/served/runtime.spec.ts`: "a method above the viewer's level: forbidden, its handler never asked" | `runtime-level` → that case (all three) |
935
+ | The runtime: per-user data (P088) | `dbAccess`: `me` is the host's id; another's `data/users/<id>`, or anything else under `data`, refused at every level, in the bridge and the host | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "a person's own data is theirs" | `db-private` → that case (all three) |
936
+ | The runtime: comments write-only (P090) | the bridge answers `comments` with `true` only for a handler's `true`; no read method | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "comments are write-only" | `comments-result` → that case (all three) |
937
+ | The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run, inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
872
938
  | 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) | — |
873
939
 
874
940
  ### The clipboard, and copy buttons
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.6.0",
3
+ "version": "0.7.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": {
@@ -9,6 +9,7 @@
9
9
  "files": [
10
10
  "src",
11
11
  "dist",
12
+ "types/runtime/**/*.d.ts",
12
13
  "docs",
13
14
  "examples",
14
15
  "README.md"
@@ -85,6 +86,7 @@
85
86
  "scripts": {
86
87
  "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node scripts/build-harness.ts && node scripts/copy-docs.ts",
87
88
  "test:leak": "playwright test -c leak/playwright.config.ts",
89
+ "test:controls": "node scripts/controls.ts",
88
90
  "test:bundle": "node scripts/bundle-test.ts"
89
91
  }
90
92
  }