@botiverse/porthole 0.5.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +41 -0
- package/dist/bridge/bridge.d.ts +13 -0
- package/dist/bridge/bridge.js +208 -13
- package/dist/bridge/navigation.d.ts +1 -6
- package/dist/bridge/navigation.js +11 -0
- 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 +19 -3
- package/dist/check/check.js +55 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +31 -12
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +27 -3
- package/dist/compile/policy.d.ts +34 -0
- package/dist/compile/policy.js +74 -0
- package/dist/config/capabilities.d.ts +62 -3
- package/dist/config/capabilities.js +20 -0
- package/dist/config/schema.d.ts +32 -0
- package/dist/config/validate.d.ts +1 -1
- package/dist/config/validate.js +74 -5
- 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/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -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 +44 -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 +45 -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 +13 -4
- package/dist/index.js +16 -3
- 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/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +113 -0
- package/dist/protocol/shell-adapter.js +52 -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 +57 -0
- package/dist/server/files.js +338 -0
- package/dist/server/host.d.ts +44 -2
- package/dist/server/host.js +42 -2
- package/dist/server/index.d.ts +5 -2
- package/dist/server/index.js +5 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -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 +468 -24
- package/dist/server/types.d.ts +118 -5
- package/dist/shell/document.d.ts +27 -0
- package/dist/shell/document.js +46 -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.d.ts +2 -1
- package/dist/shell/runtime.js +114 -46
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +142 -5
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +716 -7
- package/docs/DESIGN.md +97 -3
- package/package.json +3 -1
- package/src/bridge/bridge.ts +281 -17
- package/src/bridge/navigation.ts +12 -0
- package/src/bridge/refusal.ts +16 -0
- package/src/bridge/types.ts +46 -4
- package/src/check/check.ts +100 -14
- package/src/check/files.ts +384 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +33 -12
- package/src/check/page.ts +14 -0
- package/src/check/tools.ts +52 -3
- package/src/compile/policy.ts +92 -0
- package/src/config/capabilities.ts +49 -2
- package/src/config/schema.ts +32 -0
- package/src/config/validate.ts +107 -5
- package/src/conformance/index.ts +7 -0
- package/src/conformance/runtime.ts +573 -0
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/gates.ts +25 -0
- package/src/guide/guide.ts +78 -52
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +244 -0
- package/src/host/create-host.ts +55 -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 +121 -0
- package/src/isolation/types.ts +8 -0
- package/src/presets/presets.ts +7 -0
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/runtime-calls.ts +138 -0
- package/src/protocol/shell-adapter.ts +56 -2
- 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 +425 -0
- package/src/server/host.ts +84 -3
- package/src/server/index.ts +22 -0
- package/src/server/keys.ts +53 -0
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +565 -26
- package/src/server/types.ts +124 -4
- package/src/shell/document.ts +74 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +114 -46
- 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
|
|
356
|
+
## P022 · 2026-10-11 · Every preset starts with egress closed; library CDNs are a one-line opt-in · Accepted; amended by P082, P089
|
|
357
357
|
|
|
358
358
|
**Decision.** Every preset's base egress is empty: nothing loads from outside and
|
|
359
359
|
every fetch fails. `LIBRARY_CDNS` (cdnjs, jsDelivr, unpkg, esm.sh for scripts,
|
|
@@ -370,7 +370,7 @@ allowlists (break ESM imports and data fetches for no egress gain).
|
|
|
370
370
|
**Revisit when** most hosts open the CDNs anyway (then consider a preset variant,
|
|
371
371
|
by a decision that names the residual supply-chain risk).
|
|
372
372
|
|
|
373
|
-
## P023 · 2026-10-11 · No `readState`/`writeState` capabilities · Accepted
|
|
373
|
+
## P023 · 2026-10-11 · No `readState`/`writeState` capabilities · Accepted; amended by P088
|
|
374
374
|
|
|
375
375
|
**Decision.** The vocabulary drops `readState` and `writeState`. An opaque frame
|
|
376
376
|
keeps an in-memory `localStorage` for its life; content that needs storage that
|
|
@@ -397,7 +397,7 @@ agreement test keeps the shell and the manual on the same name.
|
|
|
397
397
|
**Revisit when** MCP Apps standardizes error reporting or theme-change events for
|
|
398
398
|
views.
|
|
399
399
|
|
|
400
|
-
## P025 · 2026-10-11 · A served document comes with its ticket's answer; the cookie serves what follows · Accepted
|
|
400
|
+
## P025 · 2026-10-11 · A served document comes with its ticket's answer; the cookie serves what follows · Accepted; amended by P083
|
|
401
401
|
|
|
402
402
|
**Decision.** Refines P016's ticket flow. `/server` names each storage scope's origin
|
|
403
403
|
`<label>.<content domain>` (24 base32 characters of an HMAC of the scope, keyed from the
|
|
@@ -568,7 +568,7 @@ Chromium measured no preconnect from a frame here, but harden for the weakest en
|
|
|
568
568
|
**Revisit when** WebKit applies the CSP to preconnect (then the observer suffices), or a
|
|
569
569
|
DOM insertion API is added (wrap it, and add its probe).
|
|
570
570
|
|
|
571
|
-
## P031 · 2026-10-11 · A display whose content navigates its frame is started again, at most three times · Accepted
|
|
571
|
+
## P031 · 2026-10-11 · A display whose content navigates its frame is started again, at most three times · Accepted; amended by P084
|
|
572
572
|
|
|
573
573
|
**Decision.** The web platform counts its frame's loads; any after the first means the
|
|
574
574
|
content navigated the frame. The display is started again from its content (an event
|
|
@@ -979,7 +979,7 @@ location and the rest (a decision each, if ever); delegation in opaque or domain
|
|
|
979
979
|
**Revisit when** WebKit or Firefox enforce the clipboard-write policy feature (then the
|
|
980
980
|
measurement changes), or a host needs another feature.
|
|
981
981
|
|
|
982
|
-
## P050 · 2026-10-11 · The host's check runs on every request; Porthole carries the host's decision and never makes it · Accepted
|
|
982
|
+
## P050 · 2026-10-11 · The host's check runs on every request; Porthole carries the host's decision and never makes it · Accepted; amended by P089
|
|
983
983
|
|
|
984
984
|
**Decision.** `ServerOptions.authorize = { check(request), ttlSeconds? }`. Porthole calls it after
|
|
985
985
|
a ticket or cookie verifies and before anything of the content is served: a document's first
|
|
@@ -2213,7 +2213,7 @@ refused, and reported as a problem, on every engine (`leak/check.spec.ts`).
|
|
|
2213
2213
|
loads (its follow-up) proposes more hosts, such as mirrors reachable from mainland China.
|
|
2214
2214
|
|
|
2215
2215
|
|
|
2216
|
-
## P079 · 2026-10-15 · Live widgets: no network of their own, Porthole's libraries on their origin, the host's data behind the viewer's consent, and frames that never navigate away · Accepted
|
|
2216
|
+
## P079 · 2026-10-15 · Live widgets: no network of their own, Porthole's libraries on their origin, the host's data behind the viewer's consent, and frames that never navigate away · Accepted; amended by P084
|
|
2217
2217
|
|
|
2218
2218
|
**Decision.** Content that shows its host's data, current, read as the person viewing it (a
|
|
2219
2219
|
dashboard tile, a kept widget) gets a preset of its own and the mechanisms it needs. 0.5.0.
|
|
@@ -2342,7 +2342,7 @@ accepts either outcome, as the opaque probes do. The opaque probes `5.*` keep fa
|
|
|
2342
2342
|
Navigation API, a host needs libraries in opaque frames, or agents' live widgets reach for a library
|
|
2343
2343
|
the two don't cover.
|
|
2344
2344
|
|
|
2345
|
-
## P080 · 2026-10-15 · The host hears a navigation the shell stopped; a host may refuse all data without handlers; a refusal tells content why · Accepted
|
|
2345
|
+
## P080 · 2026-10-15 · The host hears a navigation the shell stopped; a host may refuse all data without handlers; a refusal tells content why · Accepted; codes amended by P087
|
|
2346
2346
|
|
|
2347
2347
|
From Ferry's adoption of 0.5.0's live widgets (#12, #13, #14). 0.5.1, additive but for the text of
|
|
2348
2348
|
a refused data call's error (below).
|
|
@@ -2433,3 +2433,712 @@ told why, nothing started again on re-render); `leak/check.spec.ts` (a served wi
|
|
|
2433
2433
|
navigates is told so, without the query). On Chromium, WebKit and Firefox.
|
|
2434
2434
|
**Revisit when** MCP or MCP Apps standardizes error data for refused requests (follow it), or a
|
|
2435
2435
|
host needs the navigation without `reportError`.
|
|
2436
|
+
|
|
2437
|
+
## P081 · 2026-10-18 · A version may be many files: the store's contract, addresses that pin a version, and how each file is served · Accepted
|
|
2438
|
+
|
|
2439
|
+
Task #124: an artifact is what an agent made, as it made it, and that is often a directory (a
|
|
2440
|
+
build's output, a report with its images, a dashboard that reads its data). 0.6.0, additive: a
|
|
2441
|
+
0.5 host's store, `{ html }`, is served as before.
|
|
2442
|
+
|
|
2443
|
+
**Decision.**
|
|
2444
|
+
- **The store.** `ArtifactStore.get(id, version)` answers `{ html }` (one page, as in 0.5) or a
|
|
2445
|
+
`StoredFiles`: `files` (`path → { size, sha256, type? }`), `entry` (default `index.html`), `spa`
|
|
2446
|
+
(default false) and `read(path)` (a `Uint8Array` or a `ReadableStream`, whole; Porthole cuts the
|
|
2447
|
+
range a request asks for). The type a file was published with is the host's to keep (a file list),
|
|
2448
|
+
never served.
|
|
2449
|
+
- **Paths, when a version is published** (`filePathProblem`, `checkFileSet`, a host calls them):
|
|
2450
|
+
relative, `/`-separated, case-sensitive; no empty, `.` or `..` segment; none of `\ % ? #`, a
|
|
2451
|
+
control character or a format character (`Cc`, `Cf`: a right-to-left override or a zero-width
|
|
2452
|
+
space would make a path read as another); Unicode NFC; no segment that starts or ends with a space; at most 512
|
|
2453
|
+
characters and 255 a segment; not under `__porthole/`; no two paths that differ only in case, no
|
|
2454
|
+
path that is both a file and a directory; the entry one of them.
|
|
2455
|
+
- **Paths, when a file is asked for** (`requestFilePath`, `lookupFile`): the path below the
|
|
2456
|
+
version's base, decoded once; a segment that decodes to a separator, an escape, a control
|
|
2457
|
+
character or a dot segment names nothing (the URL parser has resolved the dot segments it
|
|
2458
|
+
sees). Looked up in the manifest only, never a filesystem: `""` is the entry (an entry in a
|
|
2459
|
+
directory: there); `dir/` is `dir/index.html`; `name` is `name`, else `name.html`, else `name/`
|
|
2460
|
+
(307) when `name/index.html` exists. What finds nothing: for a navigation, the entry when the
|
|
2461
|
+
version is a single-page app (`spa`), else the nearest `404.html` (status 404); else a plain 404.
|
|
2462
|
+
- **Limits**, the config's (`limits.maxFiles`, `maxFileBytes`, `maxVersionBytes`; 1,000, 25 MiB,
|
|
2463
|
+
100 MiB by default): the manual states them, and `checkFileSet` and `lintFiles` hold a version
|
|
2464
|
+
to them. The server serves what the host stored.
|
|
2465
|
+
- **Addresses on a tab** (P068). `entry.at` may answer a `FileAddress`, `{ instance, base, file }`:
|
|
2466
|
+
the version's own address (`/v/3/`) and the file the address asks for below it. The session the
|
|
2467
|
+
entry buys serves every path under `base`, and an address that isn't under it (`/`,
|
|
2468
|
+
`/style.css`: the latest) is redeemed to `base` + `file`. A base is a path ending in `/` whose
|
|
2469
|
+
segments are letters, digits and `. _ : ~ -`, never `.` or `..` (it goes into a CSP header as
|
|
2470
|
+
it is); `file` holds no dot segment, backslash, `?`, `#` or control character, and the address
|
|
2471
|
+
it makes must still be under `base`. `pinned: true` says `base` names that version and no
|
|
2472
|
+
other: only then are its files immutable (`/latest/` isn't pinned; its files revalidate). Where
|
|
2473
|
+
sessions' bases nest, the most specific serves. A request on a clean address with no session for
|
|
2474
|
+
it begins an entry only when a page opens (`Sec-Fetch-Mode: navigate`, a document's destination,
|
|
2475
|
+
or a client that sends no fetch metadata): a subresource gets a plain 401, `no-store`, with no
|
|
2476
|
+
nonce cookie. `versionedAddress(path)` reads the convention both first hosts
|
|
2477
|
+
use (`/v/<n>/<file>` pinned, any other path the latest's; a version is never `.` or `..`), and
|
|
2478
|
+
`versionBase(n)` is `/v/<n>/`. Each version is a directory of its origin, as Claude's content
|
|
2479
|
+
origin does it (`/_f/<version id>/`, measured on claude.ai 2026-10-18). `/_blob/`
|
|
2480
|
+
(`ASSET_LIBRARY_PATH`) is kept free outside every version for an asset library that lives
|
|
2481
|
+
across versions (task #124 phase 4, not built): `versionedAddress` names nothing there; it will
|
|
2482
|
+
need a CSP source and an access of its own, decided then. A file set's page answered as a plain
|
|
2483
|
+
instance is served as a frame's is (P083).
|
|
2484
|
+
- **Answers.** Each file is typed by Porthole's table by its extension (`fileTypeOf`); one it
|
|
2485
|
+
doesn't know is `application/octet-stream` with `content-disposition: attachment`; every answer
|
|
2486
|
+
is `nosniff`. Every answer carries its CSP: a page and a script (a worker's policy is its
|
|
2487
|
+
script's) the page's (P082), any other file `default-src 'none'; sandbox` (an SVG or XML file
|
|
2488
|
+
opened on its own runs nothing). A page is `private, no-cache` with an ETag of the bytes served
|
|
2489
|
+
(so the host's check runs on every navigation, P050); any other file `private,
|
|
2490
|
+
max-age=31536000, immutable` with its `sha256` as a strong ETag; `If-None-Match` gets a 304; one
|
|
2491
|
+
`bytes=` range a 206 (a range past the end a 416; several ranges the whole file). Files (not
|
|
2492
|
+
pages) are `Cross-Origin-Resource-Policy: same-origin`. A service worker's script request
|
|
2493
|
+
(`Service-Worker`, `Sec-Fetch-Dest: serviceworker`) is refused.
|
|
2494
|
+
- **Every page of a set is in the shell**, fetched or opened: its hardening, its host functions,
|
|
2495
|
+
its theme (P029: parsed inert, its scripts replayed, a module's relative `src` resolving from
|
|
2496
|
+
the page's address). Each page still writes its own skeleton (`<!doctype html>`, its head), as
|
|
2497
|
+
on Claude, where only the main page is wrapped in a skeleton at publish time: a skeleton is
|
|
2498
|
+
markup, Porthole's shell is the frame's hardening, which a page can't go without.
|
|
2499
|
+
- **The agent's side.** `lintFiles(config, files)` lints each page as `lintContent` does, holds the
|
|
2500
|
+
set to the path rules and limits, and looks every relative reference up in the set (markup,
|
|
2501
|
+
CSS `url()` and `@import`, module imports, `new URL(…, import.meta.url)`, workers, fetches);
|
|
2502
|
+
`admitFiles` refuses what certainly fails (a path or limit the server won't take, no entry, a
|
|
2503
|
+
page `admitContent` would refuse, a page's reference that starts with `/`) and warns on the
|
|
2504
|
+
rest. Its scans run in linear time whatever the text (each pattern bounded and stopped at its
|
|
2505
|
+
own delimiters, a page's markup read tag by tag, line numbers by a search, at most 2,000
|
|
2506
|
+
references of a kind and 2 MiB of a file looked at), and a set over a limit, or a page over its
|
|
2507
|
+
own, is said so and not read further. `checkPage({ files })` serves the whole set from the
|
|
2508
|
+
check's own server and runs its entry; files are named by their path in its report. The manual's widget topic gets a Files
|
|
2509
|
+
section where a config serves them (`servesFiles`: an artifact with domain isolation).
|
|
2510
|
+
|
|
2511
|
+
**Why.**
|
|
2512
|
+
- Packing a directory into one page costs a third more bytes in base64, the agent's tokens to
|
|
2513
|
+
write it, and a whole re-upload for one changed line. Every static host serves a set of files
|
|
2514
|
+
(Netlify, Cloudflare, Vercel, Firebase, GitHub Pages), and so does Claude's own content origin
|
|
2515
|
+
("fetch() of files published alongside the page works with relative URLs").
|
|
2516
|
+
- The serving rules are theirs (task124-industry-practice.md, items 7–11): Cloudflare's slash
|
|
2517
|
+
policy and 404 rules, a server-side type table with `nosniff` (MDN, Go's `ServeContent`), pinned
|
|
2518
|
+
addresses immutable, an ETag on the hash (web.dev's HTTP cache guide).
|
|
2519
|
+
- A page loaded as the latest must not load a newer version's file published while it loads (the
|
|
2520
|
+
chunk-load errors SPAs hit after a deploy; Vercel's Skew Protection exists for them). The
|
|
2521
|
+
address that pins it must be the page's own, not the browser's: a cookie is shared by every tab
|
|
2522
|
+
and replaced when the next version is entered, so the redeem goes to the version's own address
|
|
2523
|
+
before the page loads anything.
|
|
2524
|
+
- Every page in the shell: a page opened without it would run without its in-frame defenses (a
|
|
2525
|
+
nested frame's fresh realm, WebRTC where `webrtc 'block'` isn't honored), and without its host.
|
|
2526
|
+
- `same-origin` resource policy: without the public suffix list (P047, P066) sibling content
|
|
2527
|
+
origins are one site, so on a tab another artifact's page could embed this one's script with the
|
|
2528
|
+
viewer's `Lax` cookie; nothing but the version's own pages needs to load its files (the app
|
|
2529
|
+
frames the page, never a file).
|
|
2530
|
+
|
|
2531
|
+
**Rejected.**
|
|
2532
|
+
- A `<base>` the shell sets on the latest address (`/`, base `/v/3/`): every `#anchor` link then
|
|
2533
|
+
resolves to `/v/3/#anchor`, another document, and `base-uri 'none'` would have to open.
|
|
2534
|
+
- Serving the latest's files at the latest address by the session (`/style.css` from the version the
|
|
2535
|
+
cookie entered): two tabs, or a newer version entered while a page loads, mix versions.
|
|
2536
|
+
- `Cross-Origin-Resource-Policy: cross-origin` for media (task #124's plan): it would let any page
|
|
2537
|
+
embed a version's media, siblings with the viewer's cookie; nothing needs it.
|
|
2538
|
+
- Only the entry in the shell, the other pages as they are (Claude's way): a page the frame opens
|
|
2539
|
+
would run without the frame guard (a nested frame's fresh realm, P006), WebRTC's removal (where
|
|
2540
|
+
`webrtc 'block'` isn't honored), the navigate guard (P079), `document.write`'s and declarative
|
|
2541
|
+
shadow roots' closing (P029) and the clipboard walls (P051), none of which a CSP gives; and
|
|
2542
|
+
without its host functions and theme. Raw HTML to a fetch (`Sec-Fetch-Dest: empty`): a page
|
|
2543
|
+
served without its shell could be replayed as a document (a prefetch cache, a worker's answer).
|
|
2544
|
+
HTML in a set is a page; data that is HTML goes as another type.
|
|
2545
|
+
- `max-age=0` for the latest's files: the latest's address never serves a file, it goes to the
|
|
2546
|
+
version's own.
|
|
2547
|
+
- The uploader's type, or sniffing (a `.txt` holding HTML would run).
|
|
2548
|
+
- Ranges read by the host (`read(path, range)`): one whole-body contract first.
|
|
2549
|
+
- Service workers: one answers its origin's requests with documents it makes, outside the shell
|
|
2550
|
+
and the CSP, and outlives the page.
|
|
2551
|
+
|
|
2552
|
+
**Measured** (Playwright 1.63: Chromium, WebKit, Firefox; `leak/served/files.spec.ts`): a page of
|
|
2553
|
+
many files loads its stylesheet, a classic script, a module and its import, an image, a fetch and
|
|
2554
|
+
a worker (whose own fetch resolves from it) by relative path, framed and on a tab; the committed
|
|
2555
|
+
Vite + React build (`leak/fixtures/vite-react/out`, 143 KB: React 18.3.1, Vite 8.3.4, `base:
|
|
2556
|
+
"./"`) runs as built, its lazy chunk included; a page keeps its own version's data and lazy module
|
|
2557
|
+
when a newer version is published while it runs (framed, and on a tab opened at the latest's
|
|
2558
|
+
address); every spelling of a way out (`..%2f`, `%252e%252e`, `%5c`, `%2f`, a backslash, `%2e%2e`
|
|
2559
|
+
past the base) is a 404 or blocked; an `.html` published as `.txt` is `text/plain`, `nosniff`, and
|
|
2560
|
+
runs nothing opened on its own; another artifact's page loads none of the files (its CSP stops
|
|
2561
|
+
them before any request) and a page elsewhere can't read or run them (no CORS; CORP); no service
|
|
2562
|
+
worker registers. Negative controls (P032): `service-worker` (the harness passes a worker's script
|
|
2563
|
+
request on as a script's) → a service worker registers on a tab on all three engines;
|
|
2564
|
+
`file-corp` (no resource policy) → a page elsewhere runs the set's script on all three.
|
|
2565
|
+
|
|
2566
|
+
**Security review (2026-10-18, of the first cut).** No critical or high finding; the changes above
|
|
2567
|
+
for: format characters in paths, quadratic lint patterns (72 KB of `import a ` took 3.9 s; a
|
|
2568
|
+
megabyte of any adversarial text now takes under 30 ms), a subresource that began an entry (a 302
|
|
2569
|
+
and a nonce cookie for each), and bases (any base was immutable; `; , '` and dot segments passed).
|
|
2570
|
+
The sealed address in reports and its lifetime: P083; a set's pages' notice: P084; versions on a
|
|
2571
|
+
tab: P082.
|
|
2572
|
+
|
|
2573
|
+
**Tested.** `test/files.test.ts` (the path rules, `checkFileSet`, decoding, lookup; the type table;
|
|
2574
|
+
the CSP; framed: the ticket's answer, headers per type, ETag and 304, ranges from bytes and
|
|
2575
|
+
streams, 404s and `404.html`, traversal, service workers, a version's access serves that version,
|
|
2576
|
+
an access is its origin's and ends, the host's check per file, `spa`, a 0.5 page unchanged; on a
|
|
2577
|
+
tab: the latest goes to the version's own, a newer version doesn't reach a page, `versionedAddress`;
|
|
2578
|
+
`lintFiles` and `admitFiles`, the Vite build lints clean; after the review: format characters; the
|
|
2579
|
+
traversal inputs against a decoder that decodes twice (the control: they then reach above the
|
|
2580
|
+
version) and a store that would answer any path (read is asked for manifest paths only); a
|
|
2581
|
+
megabyte of adversarial text linted in under 200 ms, nothing read past a limit; a subresource on a
|
|
2582
|
+
tab refused with no state; immutable only where pinned, the most specific base; bases and files
|
|
2583
|
+
that say something else refused); `test/workers.test.ts` (on workerd:
|
|
2584
|
+
the entry, a streamed file, a range); `test/agreement.test.ts` (the Files section exactly where
|
|
2585
|
+
files are served, with the config's limits); `leak/served/files.spec.ts`; `leak/check.spec.ts`
|
|
2586
|
+
(a set checked whole; a missing script told by its path).
|
|
2587
|
+
**Revisit when** a host stores large media where ranged reads pay (R2: `read(path, range)`),
|
|
2588
|
+
content needs offline (a service worker of Porthole's own making), the conformance runner
|
|
2589
|
+
(`defineHostConformance`) is pointed at an app with file sets (add these cases to it), or the
|
|
2590
|
+
content domain joins the public suffix list (then siblings are other sites, and CORP is defense in
|
|
2591
|
+
depth only).
|
|
2592
|
+
|
|
2593
|
+
## P082 · 2026-10-18 · A served page with files loads its own version's files, by their path; never `'self'` · Accepted; amended by P089
|
|
2594
|
+
|
|
2595
|
+
**Decision.** Amends P022 for served pages with files. Their pages and scripts get the frame's CSP
|
|
2596
|
+
with one source added to `script-src`, `style-src`, `font-src`, `img-src`, `media-src`,
|
|
2597
|
+
`connect-src` and `worker-src` (`fileSetCspDirectives`, `FILE_SET_DIRECTIVES`; `'none'` dropped
|
|
2598
|
+
where it was the only source): the version's own files' path on its origin, `<origin>/v/3/` on a
|
|
2599
|
+
tab (the session's base), `<origin>/__porthole/f/` in a frame (the prefix every sealed path of the
|
|
2600
|
+
scope shares, P083). Nothing else changes: `default-src`, `frame-src`, `object-src`, `base-uri` and
|
|
2601
|
+
`form-action` stay `'none'`, the config's own CSP (`compile(config).csp`) has no such source, and
|
|
2602
|
+
an opaque frame or a page without files keeps P022 whole: never `'self'`.
|
|
2603
|
+
**Threat it re-opens.** Content may now make requests to its own origin, under its version's path:
|
|
2604
|
+
- its requests' paths and queries reach the host's own content server (its logs), which already
|
|
2605
|
+
sees every request the frame makes; nothing reaches another origin;
|
|
2606
|
+
- any file of the version runs as a script or a worker: they are the same author's;
|
|
2607
|
+
- in a frame, a page could load another live sealed path of its scope, if it knew one: it knows
|
|
2608
|
+
only its own, and same-origin frames on one page are one trust domain already (one scope, one
|
|
2609
|
+
storage, each other's DOM through `parent.frames`).
|
|
2610
|
+
Bounded: another version's path, Porthole's own paths (`/__porthole/d/`, `/__porthole/session`)
|
|
2611
|
+
and a url-mode app's stay closed to its loads; the `file-self` control (the harness puts `'self'` where the CSP
|
|
2612
|
+
names the version's path) makes a page on a tab load another version's data and module, and a
|
|
2613
|
+
frame's `%2e%2e` past its base reach the server, on all three engines.
|
|
2614
|
+
**Why.** Relative files are the point of a set, and they live on the page's own origin; the
|
|
2615
|
+
industry's own content origins open it: claudeusercontent.com sends `default-src
|
|
2616
|
+
https://www.claudeusercontent.com` (its own origin, observed), MCP Apps' baseline is `script-src
|
|
2617
|
+
'self'`. Porthole opens less, its version's path: on a tab another version is another path.
|
|
2618
|
+
P022's reason for never `'self'` (an opaque frame's `'self'` may be the embedding page's origin)
|
|
2619
|
+
doesn't hold on an origin of the scope's own, and stays for opaque frames.
|
|
2620
|
+
- Live widgets (P079) are shells, not artifacts: no files, unchanged. Porthole's libraries keep
|
|
2621
|
+
their own source, `<origin>/__porthole/lib/`, under no base. Per-scope labels (P047): the source is
|
|
2622
|
+
the scope's origin, so another scope's files never match.
|
|
2623
|
+
- A CSP ignores a source's path after a redirect: Porthole's redirects under a base stay under it
|
|
2624
|
+
(`dir` → `dir/`), and every other answer on the origin that redirects goes to the app's origin
|
|
2625
|
+
(redirect entry), which no file directive allows.
|
|
2626
|
+
**An artifact's versions are one trust domain** (decided after the review): one origin, one storage,
|
|
2627
|
+
the same writers; a person who may see one version sees its history. The version's path in the CSP
|
|
2628
|
+
keeps a page's loads to its own version, so versions never mix (P081); it is no wall between
|
|
2629
|
+
versions. On a tab (no sandbox there), a page can open another version's address in a window it
|
|
2630
|
+
then scripts (`window.open("/v/1/")`, under that version's CSP) or read the origin's storage another
|
|
2631
|
+
version wrote; a frame can't open windows (no `allow-popups`). Hosts that need versions apart (a
|
|
2632
|
+
version written by someone else, kept from viewers of another) give each its own scope, and so
|
|
2633
|
+
its own origin; Porthole doesn't make popups `noopener`, which would close one path of several.
|
|
2634
|
+
**Rejected.** `'self'` (every version, every Porthole path of the origin); the exact sealed path in
|
|
2635
|
+
a frame's CSP (its length, up to kilobytes with a long scope or subject, in each of seven
|
|
2636
|
+
directives); a wall between versions on one origin (an origin is the browser's unit: storage,
|
|
2637
|
+
windows and workers cross it).
|
|
2638
|
+
**Revisit when** content needs to load other versions' files (a diff view: through the host), or a
|
|
2639
|
+
browser keeps path matching across redirects.
|
|
2640
|
+
|
|
2641
|
+
## P083 · 2026-10-18 · A page with files in a frame carries its access in its files' path, sealed · Accepted; amended by P091
|
|
2642
|
+
|
|
2643
|
+
**Decision.** Amends P025 for served pages with files. The ticket's answer is the version's entry
|
|
2644
|
+
page, in the shell, `no-store`, with no cookie; its plan carries the address of its files,
|
|
2645
|
+
`/__porthole/f/<sealed>/`, and the shell puts it in the frame's history (`history.replaceState`)
|
|
2646
|
+
before anything loads, so the page's relative addresses resolve there and the spent ticket leaves
|
|
2647
|
+
the address. `<sealed>` is the session (the instance, the viewer, the end, the host's subject)
|
|
2648
|
+
sealed with AES-256-GCM (Web Crypto) under a key derived from the server's secret
|
|
2649
|
+
(`porthole/files`), bound to that use; it opens only on the instance's own origin, and the host's
|
|
2650
|
+
check runs on every file (P050). A reload loads the files' address itself.
|
|
2651
|
+
- **Its life is its own** (after the review): an address opens the page's files on its own for an
|
|
2652
|
+
hour at most (its `x`), never past the session's end (its `e`, `sessionSeconds`, up to 30 days).
|
|
2653
|
+
The shell renews it five minutes before then (`<address>__porthole/renew`, which answers only
|
|
2654
|
+
the page itself: same-origin, not a navigation) and moves the page to the new address in place
|
|
2655
|
+
(`history.replaceState`). Past `x` and before `e`, only the running page's own loads
|
|
2656
|
+
(`Sec-Fetch-Site: same-origin`, not a navigation) open: its modules keep the address they loaded
|
|
2657
|
+
from (`import.meta.url`), and their later imports must still load. An address opened on its own
|
|
2658
|
+
(a tab, a history entry, Firefox's "Open Frame in New Tab") ends within the hour.
|
|
2659
|
+
- **Nothing Porthole reports names it** (after the review): the shell says the page's files'
|
|
2660
|
+
address as `./` in every error report, blocked navigation and notice (a stack trace, "Couldn't
|
|
2661
|
+
load", a link to a file that isn't a page), and the host's bridge replaces any sealed address
|
|
2662
|
+
content sends itself (`withoutSealedAddresses`), so neither `contentError` (which a host may give
|
|
2663
|
+
the agent) nor `navigationBlocked` carries it.
|
|
2664
|
+
**Threat it re-opens.** P025 rejected "a token in the document's path (a credential in every URL
|
|
2665
|
+
the content can read and log)". The sealed path is such a credential: whoever has it loads that
|
|
2666
|
+
version's files as that viewer until it ends. Bounded:
|
|
2667
|
+
- it opens one version's files on one origin: not its document path, not `/__porthole/session`,
|
|
2668
|
+
not a url-mode app, not another version;
|
|
2669
|
+
- it is made in the browser's own request, never in the app's API answers or logs (as the
|
|
2670
|
+
ticket's URL is), and every answer sends `Referrer-Policy: no-referrer`;
|
|
2671
|
+
- content that would leak it could send the files' bytes by the same ways; and another page can't
|
|
2672
|
+
embed them with it (`Cross-Origin-Resource-Policy: same-origin`, P081);
|
|
2673
|
+
- the host's check still decides each request, and a revocation ends it (`test/files.test.ts`).
|
|
2674
|
+
**Why.** WebKit keeps no cookie in a cross-site frame (P025, measured): a page whose files needed
|
|
2675
|
+
the cookie would show its entry there and nothing it loads. In the path, every engine loads them.
|
|
2676
|
+
Sealed, not signed: content reads its own address, and a grant's viewer and subject are the host's
|
|
2677
|
+
(never shown to content). In the ticket's own answer rather than behind a redirect: P025's own
|
|
2678
|
+
reason (the document comes with its ticket's answer), one round trip fewer, and Playwright's WebKit
|
|
2679
|
+
can't fulfill a routed redirect ("Cannot fulfill with redirect status: 303", measured with
|
|
2680
|
+
`checkPage`'s driver).
|
|
2681
|
+
**Rejected.** The cookie for files (WebKit); a service worker that adds the access (P025's reasons;
|
|
2682
|
+
and P081 refuses them); a signed token (the viewer and subject readable); a store of sessions (the
|
|
2683
|
+
ticket store takes once, and a new store is a new table for every D1 host); a ticket per file; an
|
|
2684
|
+
hour with no grace for the page's own loads (a single-page app's lazy chunk an hour on would fail).
|
|
2685
|
+
**Residual.** `Sec-Fetch-Site` is a browser's word: someone outside a browser who holds an address
|
|
2686
|
+
(from a log) can claim it, and so load that version's files until the session ends, as before the
|
|
2687
|
+
review; revocation is the host's check (`authorize`).
|
|
2688
|
+
**Cost.** A frame's file addresses are new each session (each seal has a fresh IV), so the browser's
|
|
2689
|
+
cache serves a version's files within a session (its reloads and pages), not across sessions.
|
|
2690
|
+
**Tested** (after the review): `test/files.test.ts` (the address opens on its own for an hour, then
|
|
2691
|
+
only same-origin non-navigation loads until the session's end; renewal only from the page; the
|
|
2692
|
+
host's check and the session's end still hold; sealed addresses taken out of what the host is
|
|
2693
|
+
told); `leak/served/files.spec.ts` (no error report, content error or blocked navigation of a page
|
|
2694
|
+
that throws from a module, fails to load a script, rejects with its own address and is stopped from
|
|
2695
|
+
opening a file names `/__porthole/f/`: each says `./`; the shell renews its address under a clock
|
|
2696
|
+
moved 56 minutes on, and the page goes on loading its files), on Chromium, WebKit and Firefox.
|
|
2697
|
+
**Revisit when** WebKit keeps partitioned cookies in frames (then the cookie, stable addresses and
|
|
2698
|
+
the shared cache), or hosts need a version's files cached across sessions (a seal per day).
|
|
2699
|
+
|
|
2700
|
+
## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted
|
|
2701
|
+
|
|
2702
|
+
**Decision.** Amends P079 (no navigation to another document) and P031 (a navigated frame is
|
|
2703
|
+
started again) for served pages with files. The shell's plan names the version's files' address
|
|
2704
|
+
(`files.base`); its navigate guard lets a navigation go on when its destination is under it and
|
|
2705
|
+
names a page (no extension, `.html`, `.htm`, or a directory), and tells the host first: Porthole's
|
|
2706
|
+
own `porthole/navigating` (`NAVIGATING_METHOD`), which the shell adapter turns into its session's
|
|
2707
|
+
`navigating` event. The host takes the frame's next load as that page: no restart, no `navigated`;
|
|
2708
|
+
the new page's shell says hello again on the same transport. The host takes the notice only from
|
|
2709
|
+
a display whose pages may come with files (`servesFiles`: an artifact with domain isolation), for
|
|
2710
|
+
the next load only, within ten seconds (after the review: any display's content could send it,
|
|
2711
|
+
and the flag lasted, so a load much later skipped P031's restart). A link to such a page opens it in
|
|
2712
|
+
the frame, whatever its target; a link to another file of the set doesn't open, and is reported as
|
|
2713
|
+
a blocked navigation (P080). Every other navigation is stopped, as before.
|
|
2714
|
+
**Threat it re-opens.** A frame that navigates itself carries data out in its URL (P079's reason).
|
|
2715
|
+
Now it may, to its own version's pages, on its own origin: the host's own content server sees the
|
|
2716
|
+
address, as it sees a fetch there (P082). Not to another origin, not to another path of its origin,
|
|
2717
|
+
not to a file that isn't a page (which wouldn't come in the shell). The announcement is the
|
|
2718
|
+
content's word: it only spares a restart, which P031 says is not a wall.
|
|
2719
|
+
**Why.** A set's other pages (Claude's contract names "further HTML pages") are links between
|
|
2720
|
+
pages; a guard that stops them, or a host that starts the display again at its entry on each,
|
|
2721
|
+
breaks every multi-page artifact.
|
|
2722
|
+
**Measured.** Under `navigate-guard` (P079's control), the cases "a link to another page opens it
|
|
2723
|
+
in the frame" (no announcement, so the display starts again) and "a page opens nothing else" (a
|
|
2724
|
+
file that isn't a page, `/`, `/__porthole/d/…` reach the server) fail on Chromium, WebKit and
|
|
2725
|
+
Firefox.
|
|
2726
|
+
**Rejected.** The host opening the page (`openLink`, or a restart at the new address): the frame's
|
|
2727
|
+
history goes, and the sealed address would land in a tab. A new bridge for each page: the host's
|
|
2728
|
+
gates, rates and consent are the display's, across its pages.
|
|
2729
|
+
**Residual.** The host gives annotations (P053) to the display's first page only; live
|
|
2730
|
+
subscriptions a page left keep running until the display ends.
|
|
2731
|
+
**Tested** (after the review): `test/files.test.ts` (the notice spares a restart for a served
|
|
2732
|
+
artifact's display, not one sent eleven seconds before the load, and never for a widget's).
|
|
2733
|
+
**Revisit when** hosts annotate multi-page artifacts (give the marks to each page), or an engine
|
|
2734
|
+
Porthole supports lacks the Navigation API (then `frame-src` is the wall, and a set's pages restart
|
|
2735
|
+
the display).
|
|
2736
|
+
|
|
2737
|
+
## P085 · 2026-10-18 · The capability runtime: one global, `porthole.use(name)`, under a contract pinned per artifact · Accepted; amended by P091
|
|
2738
|
+
|
|
2739
|
+
Task #124 (contract §7): a page published as an artifact is an app, and an app needs more of its host
|
|
2740
|
+
than 0.6's host functions: who is viewing, its comments, a new version of itself, an asset library,
|
|
2741
|
+
shared data. 笑笑's measured study of Claude's artifacts (Notion, 2026-10-18) gives the shape: a page
|
|
2742
|
+
declares `capabilities: { name: config }` at publish, calls `await claude.use(name)` and gets a
|
|
2743
|
+
frozen namespace or null, hears permission problems when it calls, and is pinned to the runtime
|
|
2744
|
+
contract it was written against; each capability's API is a versioned `.d.ts`. 0.7.0.
|
|
2745
|
+
|
|
2746
|
+
**Decision.**
|
|
2747
|
+
- **The switch is the config's** (`PortholeConfig.runtime: "1"`, `presets.*({ runtime })`): inline
|
|
2748
|
+
widgets and artifact pages only (the shell's protocol). Without it a frame, its globals and its
|
|
2749
|
+
manual are 0.6's, byte for byte (`test/agreement.test.ts`, the existing leak suites).
|
|
2750
|
+
- **One global.** The shell defines `porthole`, frozen and fixed, whose only member is `use(name)`
|
|
2751
|
+
(`shell/use.ts`, spliced into the runtime as `__RUNTIME__`). `use` never rejects: it resolves the
|
|
2752
|
+
capability's namespace (frozen, the same object each time) or null, and null says nothing of why
|
|
2753
|
+
(the host doesn't offer it here, the page didn't declare it, no host answered: a preview, a tab).
|
|
2754
|
+
On a tab (`window.parent === window`) it is null at once; in a frame whose host never answers,
|
|
2755
|
+
after the handshake gives up (10 s).
|
|
2756
|
+
- **What is offered** comes in the handshake, in MCP Apps' own extension point:
|
|
2757
|
+
`hostCapabilities.experimental["porthole/runtime"] = { version, capabilities: { name: [methods] } }`,
|
|
2758
|
+
the display's roster (`rosterOf(config, declared)`: the built-ins the config serves, and what the
|
|
2759
|
+
page declared). The same for every viewer: levels refuse at call time (P087).
|
|
2760
|
+
- **Calls** go as `porthole/call { capability, method, args }` (own-prefixed, P002), answered
|
|
2761
|
+
`{ value }` or a JSON-RPC error whose `data` is `{ code, message }` (P080); a watch adds a
|
|
2762
|
+
frame-chosen `watch` id, its updates come as `porthole/event { watch, data }`, and
|
|
2763
|
+
`porthole/unwatch { watch }` (a notification, never gated) ends it; at most 50 a frame.
|
|
2764
|
+
`data.read` and `data.subscribe` ride MCP's own `resources/*` (the cache and subscriptions of
|
|
2765
|
+
P079). The shell's namespace is sugar: the host's bridge decides every call, whichever way it came.
|
|
2766
|
+
- **The contract** (`RUNTIME_CAPABILITIES`, version `"1"`): each capability a namespace of methods,
|
|
2767
|
+
each method served by one of the config's host functions, with a level (P087) and, for a watch,
|
|
2768
|
+
callbacks. The config still declares host functions and their gates (PRINCIPLE 4); the runtime
|
|
2769
|
+
only says how a page reaches them:
|
|
2770
|
+
|
|
2771
|
+
| `use(…)` | methods | host function | built in (P086) |
|
|
2772
|
+
| --- | --- | --- | --- |
|
|
2773
|
+
| `clipboard` | `copy(text)` | `copyText` | yes |
|
|
2774
|
+
| `links` | `open(url)` | `openLink` | yes |
|
|
2775
|
+
| `downloads` | `save({ name, text \| data })` | `downloadFile` (`ui/download-file`) | yes |
|
|
2776
|
+
| `comments` | `open(anchor)` | `comments` (new, P090) | yes |
|
|
2777
|
+
| `user` | `get()` | `user` (new, answered from the viewer, P087) | no |
|
|
2778
|
+
| `chat` | `send(text)` | `sendPrompt` | no |
|
|
2779
|
+
| `data` | `read(uri)`, `subscribe(uri, onData, onError)`, `call(name, args)` | `readData`, `subscribeData`, `callTool` | no |
|
|
2780
|
+
| `context` | `set({ content, structuredContent })` | `setModelContext` | no |
|
|
2781
|
+
| `artifact` | `get()`, `publish(change)` | `artifact` (new, P088) | no |
|
|
2782
|
+
| `assets` | `list()`, `upload(file)`, `delete(id)` | `assets` (new, P089) | no |
|
|
2783
|
+
| `db` | `get`, `query`, `onSnapshot`, `set`, `update`, `delete`, `batch` | `db` (new, P088) | no |
|
|
2784
|
+
|
|
2785
|
+
`resize`, `reportError` and `annotate` stay the shell's own: content never calls them by name.
|
|
2786
|
+
- **Types.** Each capability's API is a `.d.ts` per contract version (`types/runtime/v1/`, shipped
|
|
2787
|
+
in the package, compiled by `pnpm typecheck` with a page-shaped `check.ts`), the call contract in
|
|
2788
|
+
`porthole.d.ts`. `scripts/runtime-types.ts` embeds them in `src/runtime/types.generated.ts` (a
|
|
2789
|
+
module, P075); the manual's new `capabilities` topic teaches the call contract, declaring, levels,
|
|
2790
|
+
where state goes (localStorage for one person's view, `artifact` when the page is the record, `db`
|
|
2791
|
+
for shared data), and each offered capability's types (`test/agreement.test.ts`: exactly the
|
|
2792
|
+
offered ones, as the files hold them).
|
|
2793
|
+
- **The pin.** A declaration carries the contract version it was written against (P086); a mount
|
|
2794
|
+
checks the version is one this Porthole serves (`RUNTIME_VERSIONS`). A new version will be a new
|
|
2795
|
+
directory of types and a new table; a page keeps its own.
|
|
2796
|
+
- **The legacy path** (`shell/legacy.ts`, since 0.7.0): 0.6's globals (`sendPrompt`, `copyText`,
|
|
2797
|
+
`openLink`, `readData`, `subscribeData`) are still defined for what the config declares, under a
|
|
2798
|
+
runtime too, so stored 0.5 and 0.6 pages run unchanged; under a runtime the manual no longer
|
|
2799
|
+
teaches them (`ShellPlan.legacyGlobals`, defined and untaught, asserted by the agreement test),
|
|
2800
|
+
and a page that declared capabilities is held to its declaration on that path as well (P086).
|
|
2801
|
+
Remove it when no host serves a page written before 0.7.
|
|
2802
|
+
|
|
2803
|
+
**Why.**
|
|
2804
|
+
- One entry point keeps the global namespace the content's own, and a namespace per capability
|
|
2805
|
+
lets the manual teach a capability as one block (its declaration, its methods, its types).
|
|
2806
|
+
- Null rather than an error at `use`: a page draws without what isn't there, wherever it is shown
|
|
2807
|
+
(Claude's `ArtifactCheck` preview has no runtime and resolves null too); permission is a property
|
|
2808
|
+
of each call (consent, rate, level), not of the page.
|
|
2809
|
+
- The roster in the handshake: said once, in the field MCP Apps keeps for extensions, without a
|
|
2810
|
+
round trip per `use`.
|
|
2811
|
+
- Pinned contracts: Claude's runtime does the same (`contract` per artifact); old pages keep the
|
|
2812
|
+
API they were written against.
|
|
2813
|
+
|
|
2814
|
+
**Rejected.**
|
|
2815
|
+
- A global per capability (`window.db`): the content's namespace, and a new global per release.
|
|
2816
|
+
- The name `claude`: a vendor's. `porthole` is Porthole's, the same in every host that runs it.
|
|
2817
|
+
- A `porthole/use` request per call to `use`: a round trip for what the handshake can say once.
|
|
2818
|
+
- Refusing at `use` (a page that branches on who views it at load) and rejecting `use`.
|
|
2819
|
+
- Dropping 0.6's globals: every stored page that calls them would break.
|
|
2820
|
+
- Throwing for a capability the config doesn't offer: a page is written once for many hosts.
|
|
2821
|
+
|
|
2822
|
+
**Revisit when** MCP Apps specifies capability negotiation for views (follow it), a second contract
|
|
2823
|
+
version ships (its own types and table; the pins tell which pages need it), or no host serves a
|
|
2824
|
+
page from before 0.7 (remove `shell/legacy.ts`).
|
|
2825
|
+
|
|
2826
|
+
## P086 · 2026-10-18 · A page declares the capabilities it uses; built-ins need no declaring; the bridge holds every path to it · Accepted; amended by P091
|
|
2827
|
+
|
|
2828
|
+
**Decision.**
|
|
2829
|
+
- **The declaration** is `{ capabilities: { name: config }, runtime }` (`PageDeclaration`), stored by
|
|
2830
|
+
the host with the artifact and given to each mount (`MountOptions.declaration`, React's
|
|
2831
|
+
`declaration`), checked against the config there (`checkDeclaration`: a `TypeError` for one that
|
|
2832
|
+
doesn't fit). Configs of their own: `data: { resources?, tools? }` (exact names, or a prefix
|
|
2833
|
+
ending in `*`; absent: all the host serves), `db: { rules? }` (P088), and any capability's
|
|
2834
|
+
`levels` (P087, raise only).
|
|
2835
|
+
- **At publish** (`declareCapabilities({ stored, given, config, runtime? })`, the helper hosts call):
|
|
2836
|
+
`given` omitted carries the stored declaration forward with its pin (none stored: an empty one,
|
|
2837
|
+
pinned to the current contract); `{}` clears it; a non-empty object replaces it whole (anything
|
|
2838
|
+
not restated is revoked); each name checked against the host's offer (`declarationProblems`:
|
|
2839
|
+
known, offered by the config, not built in, of its own shape). The pin moves only when the author
|
|
2840
|
+
asks (`runtime`).
|
|
2841
|
+
- **Built-ins** are reachable by any page whose host offers them, declared or not: `clipboard`,
|
|
2842
|
+
`links`, `downloads`, `comments`, whose every effect is the host's own UI, shown to the person (a
|
|
2843
|
+
copy it shows, a link and a download it confirms, a composer the person writes in). Everything
|
|
2844
|
+
else (`user`, `chat`, `data`, `context`, `artifact`, `assets`, `db`) only a page that declared it.
|
|
2845
|
+
- **The bridge holds a call to it**, whichever way it came (`porthole/call`, or 0.6's requests and
|
|
2846
|
+
globals: `resources/read`, `ui/message`, …), before its arguments are read: a capability the page
|
|
2847
|
+
didn't declare is refused `undeclared` (content: `not_allowed`), as is a resource or tool its
|
|
2848
|
+
`data` doesn't name. A display with no declaration is a 0.6 page: built-ins through `use`, 0.6's
|
|
2849
|
+
globals and requests as before, and none of the runtime's own host functions.
|
|
2850
|
+
- **A page can't change its own declaration**: `artifact.publish` carries none, so a new version
|
|
2851
|
+
made from the page keeps what its author declared.
|
|
2852
|
+
|
|
2853
|
+
**Why.** "What can this page do?" is answered by reading what it declared, checked against what the
|
|
2854
|
+
host offers (PRINCIPLE 4 per page, as the config is per kind). The built-ins are the effects a
|
|
2855
|
+
person sees and answers in the host's UI; declaring them would only add noise to every page with a
|
|
2856
|
+
link.
|
|
2857
|
+
**Rejected.**
|
|
2858
|
+
- Everything declared, links and copy buttons too.
|
|
2859
|
+
- A declaration in the page (a `<meta>`): the content's word, which could grant itself anything.
|
|
2860
|
+
- The declaration in the frame's plan: the shell shares the content's realm; the bridge is the wall.
|
|
2861
|
+
- A page that republishes itself with a new declaration: a page (or what injected it) widening its
|
|
2862
|
+
own reach.
|
|
2863
|
+
**Tested.** `test/runtime.test.ts` (problems, carry/clear/replace and the pin, a mount's check; the
|
|
2864
|
+
bridge refusing an undeclared capability and 0.6's requests from a declared page before any
|
|
2865
|
+
handler; data's names); `leak/served/runtime.spec.ts` ("an undeclared capability: null from use,
|
|
2866
|
+
refused when sent anyway, its handler never asked"; "under the runtime, with no declaration") on
|
|
2867
|
+
Chromium, WebKit and Firefox. Negative control `runtime-declaration` (the bridge's check taken out)
|
|
2868
|
+
→ the first case on all three engines.
|
|
2869
|
+
**Revisit when** a host needs a declaration per version rather than per artifact, or a built-in
|
|
2870
|
+
grows an effect the person doesn't see.
|
|
2871
|
+
|
|
2872
|
+
## P087 · 2026-10-18 · Viewer levels decide each method's audience; the host's access says the level; a refusal is a stable code, at call time · Accepted; amended by P091
|
|
2873
|
+
|
|
2874
|
+
**Decision.**
|
|
2875
|
+
- **Levels** `view < interact < admin < owner` (`VIEWER_LEVELS`): view sees and comments; interact
|
|
2876
|
+
uses what the page does (writes its data, asks the agent); admin publishes versions and manages
|
|
2877
|
+
assets; owner. Each runtime method declares the least level that may call it, and a floor below
|
|
2878
|
+
which a host's config can't set it (`RUNTIME_CAPABILITIES`): reads `view`; `chat.send`,
|
|
2879
|
+
`data.call`, `context.set` and db writes `interact`; `artifact.publish` and `assets.delete`
|
|
2880
|
+
`admin` (floor admin); `assets.upload` `admin` (floor interact). A config may set a host
|
|
2881
|
+
function's methods' levels (`CapabilityConfig.levels`, at or above the floor); a page's
|
|
2882
|
+
declaration may raise them, never lower (`methodLevel`).
|
|
2883
|
+
- **Who says the level**: the host, per request. The host kit's `access(instance, viewer)` returns a
|
|
2884
|
+
`Grant` with `level` (and `user: { id, name }`, the person as a page that declares `user` may know
|
|
2885
|
+
them: the host's public id, not `Grant.viewer`); `/server`'s `issue` answers it as
|
|
2886
|
+
`FrameLocation.viewer`, never in the ticket, the cookie or the page; `httpLocator` and
|
|
2887
|
+
`locateServed` carry it (dropped if it doesn't parse) to the display's bridge. An opaque frame, or
|
|
2888
|
+
a host without the kit, passes `MountOptions.viewer`; the issue's answer wins where both are.
|
|
2889
|
+
- **The bridge checks at call time**, after the declaration (P086) and the arguments, before any
|
|
2890
|
+
gate or handler: below the method's level is `level` (content: `forbidden`). Without a viewer,
|
|
2891
|
+
0.6's host functions run as before (no level is checked: a 0.6 host is unchanged) and the
|
|
2892
|
+
runtime's own (`user`, `comments`, `artifact`, `assets`, `db`) are refused (fail closed). The
|
|
2893
|
+
handler's context carries the viewer (`CallContext.viewer`) and the page's declaration for that
|
|
2894
|
+
capability (`declared`): the app's API checks again, since it is its data's wall
|
|
2895
|
+
(`defineRuntimeConformance` runs its handlers past the bridge to see that it does).
|
|
2896
|
+
- **`user.get()`** answers `{ id, name, level }` from the viewer the host gave, nothing else.
|
|
2897
|
+
- **Codes.** `REFUSAL_CODES` gains `forbidden` (this person may see it but not do this),
|
|
2898
|
+
`conflict` (it moved since it was read, P088) and `too_large` (past a limit); `Refusal` gains
|
|
2899
|
+
`undeclared`, `level`, `too-large`. Content gets the code and Porthole's sentence for it (or the
|
|
2900
|
+
host's `Refused`), never why beyond it. Amends P080's vocabulary; 0.6's data refusals keep their
|
|
2901
|
+
five codes and words.
|
|
2902
|
+
|
|
2903
|
+
**Why.** Claude's runtime decides each capability's audience the same way (view < interact < admin <
|
|
2904
|
+
owner), and the same page runs for every viewer: a level is a property of the person at the call,
|
|
2905
|
+
not of the page. Carried in the issue's answer, the level is decided when the frame is made, by the
|
|
2906
|
+
same policy that decides access, without another request; it never needs to reach the content
|
|
2907
|
+
origin. `forbidden` apart from `not_allowed` lets a page say "ask for access" rather than "not here".
|
|
2908
|
+
**Rejected.** A level refused at `use`; the level in the ticket or cookie (the content server never
|
|
2909
|
+
needs it; less to carry); a level the content says; `not_allowed` for a level.
|
|
2910
|
+
**Tested.** `test/runtime.test.ts` (levels and floors; refused before any handler; no viewer;
|
|
2911
|
+
`user`); `test/assets.test.ts` (a grant's level in the issue's answer and only with one; never in
|
|
2912
|
+
the page; the locator drops what doesn't parse); `leak/served/runtime.spec.ts` ("a method above the
|
|
2913
|
+
viewer's level: forbidden, its handler never asked"). Negative control `runtime-level` (the bridge's
|
|
2914
|
+
level check taken out) → that case on all three engines.
|
|
2915
|
+
**Revisit when** a host needs levels per resource rather than per method (then the host's `Refused`
|
|
2916
|
+
says it, as now), or MCP Apps standardizes a viewer identity for views.
|
|
2917
|
+
|
|
2918
|
+
## P088 · 2026-10-18 · State the host keeps: a page publishes itself (`artifact`), and shares data (`db`); amends P023 · Accepted; amended by P091
|
|
2919
|
+
|
|
2920
|
+
P023 dropped `readState`/`writeState`: domain mode gives a page real `localStorage`. That is one
|
|
2921
|
+
person's, in one browser. Task #124's pages need state that people share and the agent reads: a
|
|
2922
|
+
checklist that is the record, votes, a board. "Revisit when a host needs persisted state for opaque
|
|
2923
|
+
frames": hosts now need it for every frame, shared. The state stays the host's (PRINCIPLE 8:
|
|
2924
|
+
Porthole stores nothing); Porthole defines the protocol, checks what crosses the frame, and gates it.
|
|
2925
|
+
|
|
2926
|
+
**Decision.**
|
|
2927
|
+
- **`artifact`** (artifact mode only): `get()` answers the current version (`{ version, number?,
|
|
2928
|
+
entry, files: [{ path, size, sha256 }] }`), `publish({ base, files, entry?, label?, note? })` a
|
|
2929
|
+
new one: a patch on `base`'s files (text, bytes as base64, `null` removes; the rest kept), at most
|
|
2930
|
+
255 files and the config's file limits (`too_large` past them), paths by `filePathProblem`. Admin
|
|
2931
|
+
and above (floor admin). The host checks `base` is current and refuses with `Refused("conflict")`
|
|
2932
|
+
if it moved; it admits the files as any publish (`admitFiles`). No declaration rides it (P086).
|
|
2933
|
+
- **`db`**: a document store per artifact. Paths are slash-separated, segments of
|
|
2934
|
+
`A-Z a-z 0-9 _ . ~ : @ + -`, a collection odd (1–15), a document even (2–16). Ops: `get`,
|
|
2935
|
+
`set`, `update` (a top-level merge), `delete`, `query` (`where` ≤ 10 of `== != < <= > >= in
|
|
2936
|
+
array-contains`, `orderBy`, `limit` ≤ 500), `batch` (≤ 50 writes, ≤ 1 MiB, all or none),
|
|
2937
|
+
`watch` (`onSnapshot`: a document's snapshot or a collection's `{ docs }`, now and at each
|
|
2938
|
+
change, through the host's `changed`, as `subscribeData`'s). Data is plain JSON, ≤ 1 MiB a
|
|
2939
|
+
document, ≤ 32 deep. Every write to a document that exists names the version it read
|
|
2940
|
+
(`ifVersion`; `0`: must not exist), and `update` needs one that exists; a mismatch is `conflict`.
|
|
2941
|
+
Snapshots: `{ path, id, exists, version, data? }`, `version` counting writes from 1.
|
|
2942
|
+
- **Who reaches what** (`dbAccess`, applied by the bridge and again by the host): `data/users/<id>`
|
|
2943
|
+
is that person's (`me`, resolved by Porthole to the viewer's id from the host); any other path
|
|
2944
|
+
under `data`, or another person's, is refused at every level (`forbidden`); a viewer with no id
|
|
2945
|
+
has none. The page's `db.rules` (by top-level collection or `*`: `{ read?, write? }` levels) raise
|
|
2946
|
+
the defaults (read view, write interact).
|
|
2947
|
+
- Hosts implement both behind their own API (Ferry's server, raft-artifacts' Worker), which the
|
|
2948
|
+
handlers call as the viewer; `defineRuntimeConformance` checks versions, conflicts, batches,
|
|
2949
|
+
watches, the per-user data and the rules, past the bridge too.
|
|
2950
|
+
|
|
2951
|
+
**Why.** Claude's runtime has the same two (`artifact` republishes itself, `db` with `if_version`,
|
|
2952
|
+
`data/users/<id>` and `as_level` rules); an agent reads and writes the same rows through its tools,
|
|
2953
|
+
so the shapes are the platform's, not a page's. Versions on every write make concurrent viewers
|
|
2954
|
+
safe without locks; per-user data resolved by the host's id, never the content's word, keeps one
|
|
2955
|
+
person's prefs from another.
|
|
2956
|
+
**Rejected.** P023's key-value `readState`/`writeState` (no versions, no sharing rules); storage in
|
|
2957
|
+
Porthole; rules evaluated only in the content (its word) or only in the bridge (the app's API is
|
|
2958
|
+
reachable by the viewer directly); a CRDT or a live room (later: `room`, broadcast and presence).
|
|
2959
|
+
**Tested.** `test/runtime.test.ts` (shapes, limits, `me`, another's data, rules, data with no id;
|
|
2960
|
+
the reference services against the conformance cases, and a lax host failing every db case);
|
|
2961
|
+
`leak/served/runtime.spec.ts` (db end to end with a conflict and a watch hearing another person's
|
|
2962
|
+
write; a page publishing itself, a stale base a conflict; "a person's own data is theirs"). Negative
|
|
2963
|
+
control `db-private` (the owner check taken out of `dbAccess`) → that case on all three engines.
|
|
2964
|
+
**Revisit when** a host needs transactions across documents beyond a batch, field-level deletes, or
|
|
2965
|
+
live presence (a `room` capability).
|
|
2966
|
+
|
|
2967
|
+
## P089 · 2026-10-18 · An artifact's asset library at `/_blob/<id>` on its own origin; scripts and styles from it only where uploads are the admins' · Accepted; amended by P091
|
|
2968
|
+
|
|
2969
|
+
Amends P022 and P082 (a page's CSP gains a source on its own origin) and P050 (a running page's own
|
|
2970
|
+
loads of its assets skip the host's per-request check).
|
|
2971
|
+
|
|
2972
|
+
**Decision.**
|
|
2973
|
+
- **The store** is the host's (`ServerOptions.assets`, `createContentHost({ assets })`):
|
|
2974
|
+
`get(id) → { scope, name, size, sha256, read() } | null`. Ids are the host's: 32 lowercase hex
|
|
2975
|
+
characters made at random (`ASSET_ID`). `/server` serves `/_blob/<id>` only on the origin of the
|
|
2976
|
+
asset's own `scope` (another origin: 404), outside every version (P081 kept the path free).
|
|
2977
|
+
- **Who gets it** (as P091 made it): a request carrying an access to the asset's own artifact (a
|
|
2978
|
+
session cookie, or a framed set's sealed files' address as its `Referer`; or the frame's own
|
|
2979
|
+
address for it, `assets.url(id)`), which the host's check then decides. Anything else is a plain
|
|
2980
|
+
401; never an entry (an asset is no address to sign in for). The first cut took a same-origin
|
|
2981
|
+
`Sec-Fetch-Site` alone, which anyone outside a browser can send.
|
|
2982
|
+
- **How it is served**: typed by Porthole's table by its name (never the uploader's type, never
|
|
2983
|
+
sniffed); never as a page (a name typed HTML goes as `application/octet-stream`, a download);
|
|
2984
|
+
`default-src 'none'; sandbox` (an SVG or XML opened on its own runs nothing), `nosniff`,
|
|
2985
|
+
`Cross-Origin-Resource-Policy: same-origin`, `private, max-age=31536000, immutable` (an id never
|
|
2986
|
+
names other bytes), its sha256 the ETag, one range.
|
|
2987
|
+
- **The page's CSP** (`assetCspDirectives`), where its config declares `assets`: `<origin>/_blob/`
|
|
2988
|
+
(the page's own origin, exact) in `img-src`, `media-src`, `font-src` and `connect-src`, always; in
|
|
2989
|
+
`script-src` and `style-src` only where `assets.upload` is admin or above (`assetCodeRuns`):
|
|
2990
|
+
people who may publish the page's code may add code. Never `'self'`.
|
|
2991
|
+
- **The capability** (`assets`, artifact mode, domain isolation): `list()` (view), `upload(file)`
|
|
2992
|
+
(admin; a host may let people who interact, floor interact), `delete(id)` (admin, floor admin).
|
|
2993
|
+
An upload's name must be one Porthole's table types and not a page; at most `maxFileBytes`.
|
|
2994
|
+
`upload` answers `{ id, url: "/_blob/<id>", name, type, size }`.
|
|
2995
|
+
|
|
2996
|
+
**Threats it re-opens, bounded.**
|
|
2997
|
+
- Content loads from its own origin outside its version's path: only `/_blob/`, its artifact's own
|
|
2998
|
+
library, the same trust domain as its versions (P082).
|
|
2999
|
+
- Files someone who interacts uploaded are shown to every viewer: images, media, fonts and data
|
|
3000
|
+
only, never as code (no `script-src`/`style-src` then) and never as a page; an SVG shown as an
|
|
3001
|
+
image runs nothing, opened on its own runs nothing (its CSP).
|
|
3002
|
+
- (The first cut's: a running page's own loads skipped the host's check, and a forged
|
|
3003
|
+
`Sec-Fetch-Site` reached any asset by id. P091 closed it: every load carries an access and gets
|
|
3004
|
+
the host's check, revalidated each time; by id alone only in bearer mode, the host's opt-in.)
|
|
3005
|
+
- `connect-src` lets a page read its assets' bytes: data it could show anyway.
|
|
3006
|
+
|
|
3007
|
+
**Why.** Large or binary media that outlives versions, and that viewers add through the page, needs
|
|
3008
|
+
a stable address any version can use; Claude's content origin serves `/_blob/<id>` outside
|
|
3009
|
+
`/_f/<version>/` the same way (measured, task #124 §1.4). A frame has no cookie (P083), and a stored
|
|
3010
|
+
asset address can't carry a session, so the page's own origin is the credential.
|
|
3011
|
+
**Rejected.** Serving assets under the frame's sealed path (a page stores `/_blob/<id>` in its data
|
|
3012
|
+
and HTML, where a sealed address would be a session leaked into a record); `'self'`; capability
|
|
3013
|
+
URLs with no session for navigations; the uploader's type; HTML assets; scripts from the library
|
|
3014
|
+
whoever uploads.
|
|
3015
|
+
**Measured** (Playwright 1.63, `leak/served/runtime.spec.ts`): an upload from the page is served and
|
|
3016
|
+
loads in its frame, and a file set's page loads the library in its frame, on Chromium, WebKit and
|
|
3017
|
+
Firefox (each sends `Sec-Fetch-Site` for `*.localhost`); a script asset runs where uploads are the
|
|
3018
|
+
admins' and not where people who interact upload; an SVG asset opened on a tab with the artifact's
|
|
3019
|
+
session runs nothing. Negative controls: `blob-script` (the harness opens scripts and styles to the
|
|
3020
|
+
library whoever uploads) → "its scripts run only where uploads are the admins'"; `blob-inert` (the
|
|
3021
|
+
harness drops an asset's CSP) → "an asset opened on its own runs nothing"; on all three engines.
|
|
3022
|
+
**Tested.** `test/assets.test.ts` (served to its own origin's loads, inert, typed, ranges; 404 on
|
|
3023
|
+
another scope's origin or a malformed id; never a page; 401 without a session, never an entry; a
|
|
3024
|
+
tab's session with the host's check; the page's CSP with and without uploads open; nothing without a
|
|
3025
|
+
store); `test/runtime.test.ts` (the CSP sources; upload limits and names).
|
|
3026
|
+
**Revisit when** an engine stops sending Fetch Metadata to a content origin, the content domain joins
|
|
3027
|
+
the public suffix list (CORP becomes defense in depth), or a host needs assets shared across
|
|
3028
|
+
artifacts (`copy_from`: a new id in the destination).
|
|
3029
|
+
|
|
3030
|
+
## P090 · 2026-10-18 · Comments from the page: the host's composer at the page's anchor, write-only · Accepted; amended by P091
|
|
3031
|
+
|
|
3032
|
+
**Decision.** `comments` is a built-in (P086) host function served by a handler: `open({ name,
|
|
3033
|
+
label?, quote? })` (a name the page chose, ≤ 256 characters, `slide-3`, `refs/a.md#L12`; a label ≤
|
|
3034
|
+
200; the quoted text ≤ 2,000), from a click (`user-activation`, 30 a minute), at view level. The
|
|
3035
|
+
host opens its own composer at that anchor (a custom anchor, task #124 §9, beside P053's quote and
|
|
3036
|
+
element anchors) and the person writes and posts there. Content hears whether the composer opened:
|
|
3037
|
+
the bridge answers `true` only for a handler's `true`, whatever else it returned. There is no method
|
|
3038
|
+
that reads a thread.
|
|
3039
|
+
**Why.** Threads hold other people's words: a page that could read them could carry them out (into
|
|
3040
|
+
its data, to the agent) or answer as someone. Reading and replying is the agent's, through the host's
|
|
3041
|
+
tools (Claude's `ArtifactComments`), and the person's, in the host's UI.
|
|
3042
|
+
**Rejected.** A `list` or `on` method; the page posting a comment itself (a comment is a person's
|
|
3043
|
+
word, written by them); comments only through annotations (P053's anchors are the host's to drive).
|
|
3044
|
+
**Tested.** `test/runtime.test.ts` (a handler that answers a thread: content hears `false`; a
|
|
3045
|
+
malformed anchor refused); `leak/served/runtime.spec.ts` ("comments are write-only": the namespace
|
|
3046
|
+
has `open` only, a raw `comments.list` is refused, the composer opens from a click and content hears
|
|
3047
|
+
only that). Negative control `comments-result` (the bridge passes the handler's answer on) → that
|
|
3048
|
+
case on all three engines.
|
|
3049
|
+
**Revisit when** a page needs to show its comment counts (then a count, through the host, never the
|
|
3050
|
+
words).
|
|
3051
|
+
|
|
3052
|
+
## P091 · 2026-10-18 · The security review of 0.7.0's first cut: what each finding changed · Accepted
|
|
3053
|
+
|
|
3054
|
+
Amends P083 (a framed set's pages that may load assets send their own origin a `Referer`), P085,
|
|
3055
|
+
P086, P087, P088, P089 (assets need an access) and P090. No high finding; every one is fixed
|
|
3056
|
+
before the release, each with its regression (`test/runtime-review.test.ts`, `test/assets.test.ts`,
|
|
3057
|
+
`leak/served/runtime.spec.ts`).
|
|
3058
|
+
|
|
3059
|
+
**Decision**, by finding:
|
|
3060
|
+
1. **Assets need an access, then the host's check** (was: a same-origin claim alone, which `curl`
|
|
3061
|
+
can send). `/_blob/<id>` is served for a request that carries an access to an artifact of the
|
|
3062
|
+
origin: a session cookie (tabs; a single page's frame where the engine keeps cookies), or a
|
|
3063
|
+
framed set's sealed files' address (P083) as its `Referer`. A framed set's pages, and its
|
|
3064
|
+
files, now say `Referrer-Policy: same-origin` (header and the shell's `<meta>`) where the
|
|
3065
|
+
config serves assets: the address goes to the page's own origin only, which already sees it in
|
|
3066
|
+
every file request. Measured: WebKit sends a cross-site frame's same-origin requests only the
|
|
3067
|
+
origin, so every page also has `assets.url(id)`, the address that loads an asset in this page
|
|
3068
|
+
now: `<sealed base>__porthole/blob/<id>` in a frame (the access in the path, as P083's files),
|
|
3069
|
+
`/_blob/<id>` elsewhere; never stored (the manual and the `.d.ts` say so). The store is asked
|
|
3070
|
+
with the access (`AssetStore.get(id, access)`), an asset names its artifact
|
|
3071
|
+
(`StoredAsset.artifact`) and is served only to an access for that artifact (a session for B no
|
|
3072
|
+
longer opens A's asset on a shared scope), after the host's check; `private, no-cache` with its
|
|
3073
|
+
sha256 ETag, so a removal or a revocation holds at the next load. By id alone only in bearer
|
|
3074
|
+
mode, an explicit opt-in (`AssetStore.bearer`). Only `/_blob/` and 32 hex characters is an
|
|
3075
|
+
asset; any other path there is a clean address, as in 0.6.
|
|
3076
|
+
2. **db checks are linear and bounded, cheap ones first**: no object reached twice (structured
|
|
3077
|
+
clone keeps shared references: 31 objects were 2^31 nodes), a node budget (100,000 a document,
|
|
3078
|
+
one for a whole batch), a `where` operand's 1,000 nodes and 16 KiB; and for the runtime's own
|
|
3079
|
+
host functions the method's level and the host function's rate come before their arguments are
|
|
3080
|
+
read (`precheck`).
|
|
3081
|
+
3. **Gates per method** (`RuntimeMethod.gates`, `CapabilityConfig.methodGates`, `callGates`): what
|
|
3082
|
+
changes the artifact for everyone, `artifact.publish` and `assets.delete`, needs a gesture and a
|
|
3083
|
+
confirmation by default; `assets.upload` a confirmation where uploaded code may run. The shell
|
|
3084
|
+
refuses those methods without a gesture (`ShellPlan.methodActivation`), the React dialog words
|
|
3085
|
+
them, and the manual says so per method, with "show rows with textContent, never innerHTML".
|
|
3086
|
+
4. **A batch is its writes, a watch its read**: a batch needs the highest level of its writes'
|
|
3087
|
+
methods, a watch that of `get` (a document) or `query` (a collection).
|
|
3088
|
+
5. **db never tells a page the viewer's id**: the bridge says `data/users/me` for every path in the
|
|
3089
|
+
viewer's own tree, in answers and in watches (`withMe`).
|
|
3090
|
+
6. **No viewer is never a way past a level**: under a runtime, a display without a viewer is
|
|
3091
|
+
refused anything above view; a viewer that doesn't parse is the host's error (`locateServed`,
|
|
3092
|
+
`httpLocator`, a mount), never no viewer.
|
|
3093
|
+
7. **Rules are the page's own names**: `Object.hasOwn` in `dbAccess`, and a checked declaration is
|
|
3094
|
+
copied into objects without a prototype (a collection named `constructor` is no rule).
|
|
3095
|
+
8. **A new page follows nothing the last one did**: another page of the set (P084) or a repeat
|
|
3096
|
+
handshake ends the frame's watches and live subscriptions; the shell's watch ids are random.
|
|
3097
|
+
9. **What an upload may become**: where people who interact upload, code-typed names (scripts,
|
|
3098
|
+
stylesheets, WebAssembly) are refused; an upload is `trusted` only when an admin made it where
|
|
3099
|
+
uploaded code may run (the bridge sets it, the store keeps it), and a code-typed asset is
|
|
3100
|
+
served as code only when trusted and the artifact's config still lets uploaded code run;
|
|
3101
|
+
anything else goes as a download, whatever the CSP opens. The manual no longer says "never run".
|
|
3102
|
+
10. **Under a runtime a mount says what its page declared**: `MountOptions.declaration` is
|
|
3103
|
+
required; `null` is the host's word for a page published before 0.7 (0.6's surface). A
|
|
3104
|
+
declaration without a runtime is an error. `checkPage({ declaration })` takes one too.
|
|
3105
|
+
11. **The low ones**: a viewer's id is one db path segment, never `me`; a prefix in `data`'s names
|
|
3106
|
+
vouches for no name with a dot segment, an escape or a backslash; a published `__proto__` path
|
|
3107
|
+
is a path (objects without a prototype); `__proto__`, `constructor` and `prototype` are no
|
|
3108
|
+
document fields; a batch names each path once; a store under `data` folds no case; the
|
|
3109
|
+
reference store holds every write to an existing document to its version, checks a batch in
|
|
3110
|
+
order, caps a collection watch as a query, and checks and admits a merged version.
|
|
3111
|
+
12. **Back compatibility**: `capabilities` is a built-in guide topic only under a runtime (a 0.6
|
|
3112
|
+
config's own topic of that name stays its own).
|
|
3113
|
+
- Also: a version is shown with what it and the artifact both declare
|
|
3114
|
+
(`intersectDeclarations(version's, current)`: hosts store a declaration per version);
|
|
3115
|
+
`porthole.use` resolves null at once where the frame's ancestor isn't one of its hosts, waits for
|
|
3116
|
+
the handshake 3 s at most, and takes a late offer for the calls after it; `pseudonymFor(secret,
|
|
3117
|
+
artifact, person)` gives a person an id per artifact; `defineRuntimeConformance({ api })` runs
|
|
3118
|
+
the past-the-bridge cases against the app's own API with a forged context (a viewer claiming to
|
|
3119
|
+
be the owner, no rules), and the docs say never to trust `context.viewer` or `context.declared`
|
|
3120
|
+
for what data allows.
|
|
3121
|
+
- **Harness**: a control whose text is gone stops the run before anything is served
|
|
3122
|
+
(`checkWeakenings`), the harness's response controls compose, `blob-trusted` is new (an
|
|
3123
|
+
untrusted asset served as the script its name says), and `scripts/controls.ts`
|
|
3124
|
+
(`pnpm --filter @botiverse/porthole test:controls`, a CI job per engine) runs each control and
|
|
3125
|
+
requires it to fail exactly its probes on every engine, and nothing else.
|
|
3126
|
+
|
|
3127
|
+
**Threat it re-opens.** A framed set's pages tell their own origin their sealed address in
|
|
3128
|
+
`Referer` (P083 sent none): only to that origin, the content server that served it (it sees the
|
|
3129
|
+
address in every file request already); nothing goes to another origin (`same-origin`), and pages
|
|
3130
|
+
whose config serves no assets still send none.
|
|
3131
|
+
**Why.** Each finding was a way past a wall the entries above claimed: a forgeable header in place
|
|
3132
|
+
of an access, a validation step that cost exponential time on the host's main thread, levels a
|
|
3133
|
+
batch or a missing viewer skipped, an id leaked through paths, a prototype's names read as rules,
|
|
3134
|
+
a page's updates heard by the next page, code a viewer uploaded made runnable by a later config.
|
|
3135
|
+
**Rejected.**
|
|
3136
|
+
- A partitioned cookie for `/_blob/`: WebKit keeps none in a cross-site frame (P025).
|
|
3137
|
+
- Rewriting `/_blob/` addresses in the page (the shell or the server): CSS, scripts and markup
|
|
3138
|
+
build them in more ways than a rewrite can see; `assets.url` is one call that always works.
|
|
3139
|
+
- Serving assets under the sealed address only: a page's stored HTML and data name `/_blob/<id>`,
|
|
3140
|
+
which tabs and most frames load as they are.
|
|
3141
|
+
- `user-activation` on uploads: a file picker's change event isn't a gesture in every engine.
|
|
3142
|
+
**Revisit when** WebKit sends a cross-site frame's same-origin requests their full `Referer`, or
|
|
3143
|
+
keeps partitioned cookies there (then `/_blob/<id>` loads everywhere and `assets.url` is a
|
|
3144
|
+
convenience); or a host needs per-collection levels beyond a batch's.
|