@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.
- package/README.md +16 -0
- package/dist/bridge/bridge.d.ts +13 -0
- package/dist/bridge/bridge.js +200 -8
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +16 -0
- package/dist/bridge/types.d.ts +41 -4
- package/dist/check/check.d.ts +7 -0
- package/dist/check/check.js +1 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +4 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/check/tools.js +2 -3
- package/dist/compile/policy.d.ts +19 -0
- package/dist/compile/policy.js +42 -0
- package/dist/config/capabilities.d.ts +62 -3
- package/dist/config/capabilities.js +20 -0
- package/dist/config/schema.d.ts +24 -0
- package/dist/config/validate.d.ts +1 -1
- package/dist/config/validate.js +66 -4
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/index.d.ts +1 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +314 -0
- package/dist/guide/gates.d.ts +3 -0
- package/dist/guide/gates.js +19 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +34 -32
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +202 -0
- package/dist/host/create-host.js +24 -0
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/types.d.ts +18 -0
- package/dist/index.d.ts +8 -2
- package/dist/index.js +9 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +1 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +113 -0
- package/dist/protocol/shell-adapter.js +48 -3
- package/dist/react/dialog.js +31 -0
- package/dist/react/frame.d.ts +13 -0
- package/dist/react/frame.js +6 -0
- package/dist/runtime/contract.d.ts +193 -0
- package/dist/runtime/contract.js +216 -0
- package/dist/runtime/db.d.ts +153 -0
- package/dist/runtime/db.js +398 -0
- package/dist/runtime/declaration.d.ts +86 -0
- package/dist/runtime/declaration.js +266 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +199 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +14 -1
- package/dist/server/files.js +97 -3
- package/dist/server/host.d.ts +6 -1
- package/dist/server/host.js +5 -0
- package/dist/server/index.d.ts +2 -1
- package/dist/server/index.js +1 -0
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +214 -35
- package/dist/server/types.d.ts +69 -0
- package/dist/shell/document.d.ts +8 -0
- package/dist/shell/document.js +16 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.js +29 -42
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +91 -6
- package/docs/ARCHITECTURE.md +22 -3
- package/docs/DECISIONS.md +415 -6
- package/docs/DESIGN.md +66 -0
- package/package.json +3 -1
- package/src/bridge/bridge.ts +273 -12
- package/src/bridge/refusal.ts +16 -0
- package/src/bridge/types.ts +46 -4
- package/src/check/check.ts +8 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +4 -2
- package/src/check/page.ts +14 -0
- package/src/check/tools.ts +2 -3
- package/src/compile/policy.ts +54 -0
- package/src/config/capabilities.ts +49 -2
- package/src/config/schema.ts +24 -0
- package/src/config/validate.ts +99 -4
- package/src/conformance/index.ts +7 -0
- package/src/conformance/runtime.ts +573 -0
- package/src/guide/gates.ts +25 -0
- package/src/guide/guide.ts +59 -53
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +244 -0
- package/src/host/create-host.ts +34 -0
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/types.ts +18 -0
- package/src/index.ts +89 -0
- package/src/isolation/types.ts +8 -0
- package/src/presets/presets.ts +7 -0
- package/src/protocol/runtime-calls.ts +138 -0
- package/src/protocol/shell-adapter.ts +52 -3
- package/src/react/dialog.tsx +33 -0
- package/src/react/frame.tsx +19 -0
- package/src/runtime/contract.ts +305 -0
- package/src/runtime/db.ts +530 -0
- package/src/runtime/declaration.ts +378 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +339 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +117 -4
- package/src/server/host.ts +12 -0
- package/src/server/index.ts +3 -0
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +247 -37
- package/src/server/types.ts +68 -0
- package/src/shell/document.ts +21 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +29 -42
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +16 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- 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.
|
|
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
|
}
|