@botiverse/porthole 0.6.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 +25 -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 +38 -5
- package/dist/bridge/bridge.js +469 -39
- 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.d.ts +5 -1
- package/dist/bridge/refusal.js +17 -0
- package/dist/bridge/types.d.ts +73 -5
- package/dist/check/check.d.ts +7 -0
- package/dist/check/check.js +1 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +4 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +16 -0
- package/dist/check/tools.js +2 -3
- package/dist/compile/compile.d.ts +6 -0
- package/dist/compile/compile.js +3 -1
- package/dist/compile/policy.d.ts +55 -0
- package/dist/compile/policy.js +157 -0
- package/dist/config/capabilities.d.ts +85 -7
- package/dist/config/capabilities.js +32 -2
- package/dist/config/schema.d.ts +35 -0
- package/dist/config/validate.d.ts +9 -3
- package/dist/config/validate.js +92 -8
- 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 +11 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/limits.js +38 -1
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +324 -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 +9 -0
- package/dist/guide/gates.js +31 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +35 -33
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +210 -0
- package/dist/host/create-host.js +73 -37
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- 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 +26 -1
- package/dist/index.d.ts +11 -4
- package/dist/index.js +11 -2
- package/dist/isolation/types.d.ts +8 -0
- 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 +22 -8
- package/dist/presets/presets.js +40 -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.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +116 -0
- package/dist/protocol/shell-adapter.js +64 -25
- package/dist/react/context-notice.d.ts +32 -0
- package/dist/react/context-notice.js +28 -0
- package/dist/react/dialog.js +91 -16
- package/dist/react/frame.d.ts +25 -1
- package/dist/react/frame.js +85 -2
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +2 -1
- package/dist/runtime/contract.d.ts +201 -0
- package/dist/runtime/contract.js +245 -0
- package/dist/runtime/db.d.ts +188 -0
- package/dist/runtime/db.js +502 -0
- package/dist/runtime/declaration.d.ts +100 -0
- package/dist/runtime/declaration.js +363 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +215 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +19 -1
- package/dist/server/files.js +115 -6
- package/dist/server/host.d.ts +24 -2
- package/dist/server/host.js +137 -2
- package/dist/server/index.d.ts +3 -2
- package/dist/server/index.js +2 -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/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +318 -52
- package/dist/server/types.d.ts +74 -2
- package/dist/shell/document.d.ts +16 -0
- package/dist/shell/document.js +19 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.js +390 -56
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +205 -15
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +1867 -11
- package/docs/DESIGN.md +137 -17
- package/docs/THREAT_MODEL.md +616 -0
- package/package.json +16 -3
- package/src/bridge/bounded-text.ts +240 -0
- package/src/bridge/bridge.ts +601 -51
- package/src/bridge/json-data.ts +95 -0
- package/src/bridge/navigation.ts +10 -0
- package/src/bridge/refusal.ts +17 -0
- package/src/bridge/types.ts +76 -5
- package/src/check/check.ts +8 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +4 -2
- package/src/check/page.ts +16 -0
- package/src/check/tools.ts +2 -3
- package/src/compile/compile.ts +9 -1
- package/src/compile/policy.ts +177 -0
- package/src/config/capabilities.ts +71 -5
- package/src/config/schema.ts +35 -0
- package/src/config/validate.ts +141 -8
- 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 +17 -0
- package/src/conformance/limits.ts +39 -1
- package/src/conformance/runtime.ts +594 -0
- package/src/conformance/served.ts +888 -4
- package/src/files/paths.ts +4 -0
- package/src/guide/gates.ts +37 -0
- package/src/guide/guide.ts +61 -55
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +253 -0
- package/src/host/create-host.ts +88 -36
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/pages-of-set.ts +226 -0
- package/src/host/types.ts +33 -1
- package/src/index.ts +94 -0
- package/src/isolation/types.ts +8 -0
- package/src/mcp/adapter.ts +16 -20
- package/src/node/index.ts +507 -116
- package/src/presets/presets.ts +67 -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 +141 -0
- package/src/protocol/shell-adapter.ts +79 -26
- package/src/react/context-notice.tsx +95 -0
- package/src/react/dialog.tsx +108 -15
- package/src/react/frame.tsx +120 -0
- package/src/react/index.ts +8 -1
- package/src/runtime/contract.ts +339 -0
- package/src/runtime/db.ts +650 -0
- package/src/runtime/declaration.ts +516 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +355 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +138 -7
- package/src/server/host.ts +170 -3
- package/src/server/index.ts +4 -0
- package/src/server/peer.ts +21 -0
- package/src/server/proxy.ts +13 -3
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +370 -57
- package/src/server/types.ts +73 -2
- package/src/shell/document.ts +29 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +390 -56
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +27 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
package/docs/DESIGN.md
CHANGED
|
@@ -9,7 +9,9 @@ below like `leak/…` and `ops/…` are Porthole's own repository, not the packa
|
|
|
9
9
|
|
|
10
10
|
## Threat model
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
The whole of it, use by use (who attacks, what is out of scope, what each scenario
|
|
13
|
+
guarantees and leaves to the host), is [THREAT_MODEL.md](THREAT_MODEL.md). In short:
|
|
14
|
+
two classes of attacker, handled by different layers (ARCHITECTURE § Trust
|
|
13
15
|
boundaries):
|
|
14
16
|
|
|
15
17
|
1. **Attacking the host** — steal the host's credentials or data, act as the
|
|
@@ -81,6 +83,7 @@ interface PortholeConfig {
|
|
|
81
83
|
isolation: "opaque" | "domain" | "external"; // external ⇔ url mode
|
|
82
84
|
capabilities: { [name in CapabilityName]?: {
|
|
83
85
|
gates?: Gate[]; // all must pass; omitted = the vocabulary's defaults
|
|
86
|
+
withoutShow?: true; // gates leave the default show out on purpose (P100)
|
|
84
87
|
connect?: string[]; resource?: string[]; // extra origins it needs
|
|
85
88
|
guide?: string; // replaces the generated manual entry
|
|
86
89
|
} };
|
|
@@ -93,7 +96,7 @@ interface PortholeConfig {
|
|
|
93
96
|
contentOrigins: string[]; // domain/external: where content is served from
|
|
94
97
|
embedder: { frameSrc?: string[] }; // extra frames the embedding page shows
|
|
95
98
|
}
|
|
96
|
-
type Gate = "user-activation" | "confirm" | "consent" | { rateLimit: { perMinute: number } };
|
|
99
|
+
type Gate = "user-activation" | "confirm" | "consent" | "show" | { rateLimit: { perMinute: number } };
|
|
97
100
|
```
|
|
98
101
|
|
|
99
102
|
`mode` and `isolation` select the mechanism; everything else is policy. There is
|
|
@@ -106,14 +109,19 @@ no `components` field (P015).
|
|
|
106
109
|
| `sendPrompt` | user-activation, confirm | handler | `sendPrompt(text)` | `ui/message` (`app.sendMessage`) |
|
|
107
110
|
| `openLink` | user-activation, confirm | handler | `openLink(url)` | `ui/open-link` (`app.openLink`) |
|
|
108
111
|
| `downloadFile` | user-activation, confirm | handler | — | `ui/download-file` (`app.downloadFile`) |
|
|
109
|
-
| `callTool` | confirm | handler | — | `tools/call` (`app.callServerTool`) |
|
|
112
|
+
| `callTool` | confirm, 30/min (P103) | handler | — | `tools/call` (`app.callServerTool`) |
|
|
110
113
|
| `readData` | 120/min | handler | `readData(uri)` | `resources/read` (`app.readServerResource`) |
|
|
111
114
|
| `subscribeData` | 60/min (needs `readData`) | handler (`changed`, `signal`) | `subscribeData(uri, onData, onError)` | `resources/subscribe`, `resources/unsubscribe`; the host's `notifications/resources/updated` (MCP's own; none in MCP Apps, P079) |
|
|
112
|
-
| `setModelContext` | 30/min | handler | — | `ui/update-model-context` (`app.updateModelContext`) |
|
|
115
|
+
| `setModelContext` | 30/min, show (P100) | handler (text blocks and plain-JSON structured content, at most `MAX_CONTEXT_CHARS` together; both adapters offer `{ text, structuredContent }`) | — | `ui/update-model-context` (`app.updateModelContext`) |
|
|
113
116
|
| `reportError` | 10/min | event | (automatic) | `notifications/message`, level `error`; `porthole/navigation-blocked` `{ url }`, a navigation the shell stopped (P080) |
|
|
114
117
|
| `resize` | none | event | (automatic) | `ui/notifications/size-changed` |
|
|
115
118
|
| `copyText` | user-activation, 30/min | handler | `copyText(text)` | `porthole/copy-text` (none in the standard) |
|
|
116
119
|
| `annotate` | 120/min (the frame's reports) | event | — | `porthole/annotate.*` (the host drives it, P053) |
|
|
120
|
+
| `user` (runtime) | 60/min | viewer (the host's `ViewerInfo`) | `porthole.use("user")` | `porthole/call` (P087) |
|
|
121
|
+
| `comments` (runtime) | user-activation, 30/min | handler (answers a boolean) | `porthole.use("comments")` | `porthole/call` (P090) |
|
|
122
|
+
| `artifact` (runtime, artifact mode) | 10/min | handler (`op: get \| publish`) | `porthole.use("artifact")` | `porthole/call` (P088) |
|
|
123
|
+
| `assets` (runtime, served artifacts) | 30/min | handler (`op: list \| upload \| delete`) | `porthole.use("assets")` | `porthole/call`; `/server` serves `/_blob/<id>` (P089) |
|
|
124
|
+
| `db` (runtime) | 600/min | handler (`op: get \| query \| watch \| set \| update \| delete \| batch`) | `porthole.use("db")` | `porthole/call`, `porthole/event`, `porthole/unwatch` (P088) |
|
|
117
125
|
|
|
118
126
|
Every preset declares only `resize` and `reportError` (they report to the host and
|
|
119
127
|
carry nothing out); the host declares the rest. Gates are explained in P021: all
|
|
@@ -122,11 +130,16 @@ one; `user-activation` is checked by the shell (advisory: it shares the content'
|
|
|
122
130
|
realm) and by the host where the engine passes the gesture up; `consent` asks the
|
|
123
131
|
host's `consent` function once per display, before its first consent-gated call,
|
|
124
132
|
and fails closed without one (P079); a `Refused` given as `consent` refuses them all,
|
|
125
|
-
asking nothing, and their capabilities need no handler (P080)
|
|
133
|
+
asking nothing, and their capabilities need no handler (P080); `show` calls the host's
|
|
134
|
+
`show` function with the call's whole effect before the handler runs, asking nothing, and
|
|
135
|
+
fails closed without one, or when it throws (P100: by default every model context update,
|
|
136
|
+
which the person sees outside the frame before the agent's next turn; the React binding's
|
|
137
|
+
`ContextNotice` is the default surface). A refused request's
|
|
126
138
|
error carries why, `data: { code, message }` (`consent_required`, `denied`,
|
|
127
139
|
`rate_limited`, `not_allowed`, `failed`; the host's `Refused` words its own, P080). `presets.liveWidget` declares `readData` and
|
|
128
140
|
`subscribeData` with `consent` and its rate, and keeps egress closed (no option opens
|
|
129
|
-
it
|
|
141
|
+
it: it refuses `egress` and a capability's own `connect` or `resource`, P103); served, it loads
|
|
142
|
+
Porthole's libraries from its origin (`egress.libraries`).
|
|
130
143
|
|
|
131
144
|
## What the compiler derives
|
|
132
145
|
|
|
@@ -242,6 +255,18 @@ and calls `PortholeServer.issue`.
|
|
|
242
255
|
- **What a served frame loads** is a `ServedDocument`: the shell (content then
|
|
243
256
|
arrives over the transport, as for opaque frames), a stored artifact version, the
|
|
244
257
|
MCP Apps sandbox proxy, or an external app (url mode).
|
|
258
|
+
- **A served page carries its frame's sandbox** (P099). Every page `/server` serves (a shell, an
|
|
259
|
+
artifact page, a set's page, the sandbox proxy; not a url-mode app's own documents) sends
|
|
260
|
+
`sandbox allow-scripts allow-same-origin` in its CSP header (`servedSandboxDirective`: the
|
|
261
|
+
frame's own tokens). In a frame it repeats the attribute; on a tab of its own (a public link, a
|
|
262
|
+
new tab, a frame's address opened outside it) it is the only sandbox: no popups, forms,
|
|
263
|
+
downloads, modals or navigation of another window. Its `Permissions-Policy` header denies what
|
|
264
|
+
the frame's `allow` doesn't grant (`servedPermissionsPolicy`: camera, microphone, location, full
|
|
265
|
+
screen and the rest of `FRAME_DENIED_FEATURES`), changing nothing in a frame. On a tab the shell
|
|
266
|
+
also answers `window.open` with null (but `_self`), refuses picture-in-picture windows, devices,
|
|
267
|
+
location and full screen (for engines that don't read the header), and its navigation guard
|
|
268
|
+
stops the page navigating itself away (an engine without the Navigation API has no wall for
|
|
269
|
+
that on a tab: P099's accepted limit).
|
|
245
270
|
- **A version made of files** (P081–P084). The store answers a manifest (`files`: path →
|
|
246
271
|
`{ size, sha256, type? }`, an `entry`, `spa`) and `read(path)`; `{ html }` stays one page. Every
|
|
247
272
|
file is looked up in the manifest only, by the path below the version's base, decoded once
|
|
@@ -429,7 +454,12 @@ Workers, Deno, Bun).** It gives:
|
|
|
429
454
|
else (404). App ids travel in the document's fields. **The client never chooses an origin**:
|
|
430
455
|
the scope the server maps to does. Then `access` (401 without a viewer, 403 refused), a ticket,
|
|
431
456
|
and `201 FrameLocation`. `503 not-served` while content isn't served; `409` when `/server`
|
|
432
|
-
refuses the instance; an optional per-viewer rate limit (429)
|
|
457
|
+
refuses the instance; an optional per-viewer rate limit (429), an anonymous viewer keyed by an
|
|
458
|
+
address the host trusts (the socket's peer, `CF-Connecting-IP` on Workers, or behind
|
|
459
|
+
`trustedProxies` the `X-Forwarded-For` entry they appended; never what a client says, P092).
|
|
460
|
+
The body is read to at most
|
|
461
|
+
`ISSUE_BODY_BYTES` (64 KiB), counted as it arrives: past it the read stops and the answer is
|
|
462
|
+
`413 too-large`; a Content-Length over it is refused before the viewer is asked (P092).
|
|
433
463
|
- **`authorize(viewerOf)` and `urlOf(scope, path)`: redirect entry** (below).
|
|
434
464
|
- **`meta()`** `{ served, contentSource, health }` for the app's page; **`frameSources`** for
|
|
435
465
|
its CSP (`frame-src`), the authorize route's path included.
|
|
@@ -490,7 +520,16 @@ returns a request listener and an upgrade listener for `http.createServer`: cont
|
|
|
490
520
|
`toRequest`/`sendResponse` convert (P070): the request carries a signal aborted when the client
|
|
491
521
|
goes away (`proxyTo` passes it on, so a proxied event stream ends with its page); the body is
|
|
492
522
|
written as the socket drains and cancelled when the client leaves; an error mid-body destroys
|
|
493
|
-
the response rather than end it looking whole.
|
|
523
|
+
the response rather than end it looking whole. Nothing a request does throws out of the
|
|
524
|
+
listeners or ends the process (P092): a request fetch can't take is 405 (`CONNECT`, `TRACE`,
|
|
525
|
+
`TRACK`) or 400 (a Host or a target that is no URL); a handler or an app listener that throws or
|
|
526
|
+
rejects, or an answer Node can't write, is 500, and `onError` hears it (by default a process
|
|
527
|
+
warning); an upgrade's socket closes on its own errors. A HEAD gets the head, its body cancelled;
|
|
528
|
+
a client gone before the answer cancels it too. The request body is read only as it is pulled
|
|
529
|
+
(a reserved label's request reaches the app whole); once the answer is out, what no one read is
|
|
530
|
+
dropped (at most 1 MiB and 5 s) before the connection closes, so a client still sending reads
|
|
531
|
+
its answer. `nodeListener(app, { scheme, onError })` is a fetch-style app's listener with the
|
|
532
|
+
same guarantees (it is `nodeServer`'s `app`). `nodeProbe()` is the health probe (`*.localhost`
|
|
494
533
|
resolved to loopback, no redirects, 4 KB read). `/server` stays free of Node.
|
|
495
534
|
|
|
496
535
|
**Client** (core). `httpLocator(url, { headers, credentials, onNotServed })` POSTs
|
|
@@ -664,10 +703,19 @@ it (`leak/mcp/`), in an opaque frame and behind the sandbox proxy.
|
|
|
664
703
|
|
|
665
704
|
### The host-function bridge
|
|
666
705
|
|
|
667
|
-
`bridge.call(capability, args)` checks, in order:
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
706
|
+
`bridge.call(capability, args)` checks, in order: the display's run not stopped (a restart or
|
|
707
|
+
its end closes its bridge, P095) → declared by the config → declared by the page, where it has
|
|
708
|
+
a declaration (P086) → before the arguments are read: for the runtime's own host functions, a
|
|
709
|
+
method by its `op` and the viewer's level for it, then for every capability its host function's
|
|
710
|
+
own rate (P091, P095: a malformed call costs its rate) → arguments valid and within their
|
|
711
|
+
limits (`openLink` http(s) only and without credentials in the URL; a prompt
|
|
712
|
+
1..`maxPromptChars` characters; a tool's arguments, model context and a download's contents
|
|
713
|
+
plain, bounded JSON, P095) → who may (P087: the level of each method the call runs for the
|
|
714
|
+
viewer, the data a page named with or without a viewer (P094), db's rules) → muted, if
|
|
715
|
+
confirm-gated → the own rate of each method it runs (`methodGates`; P094: a batch's writes count
|
|
716
|
+
each) → user activation → the viewer's `consent` → `confirm` (at most 10 waiting a display, P095)
|
|
717
|
+
→ the host's handler (or, for a read, a result the host already gave for it (P094), or for a read
|
|
718
|
+
allowed stale, the host's cache). Each refusal is a
|
|
671
719
|
`Refusal` and a `refused` display event; the frame gets an error result. After
|
|
672
720
|
`declinesBeforeMute` declines a display stops asking (`muted`) until it runs again.
|
|
673
721
|
|
|
@@ -755,6 +803,66 @@ for `localStorage` in an opaque frame, applies the theme variables, and fires th
|
|
|
755
803
|
config's theme event after a change. A capability that is not declared is simply
|
|
756
804
|
absent.
|
|
757
805
|
|
|
806
|
+
## The capability runtime (0.7.0: P085–P090)
|
|
807
|
+
|
|
808
|
+
A config with `runtime: "1"` (inline widgets and artifact pages) gives its frames one global,
|
|
809
|
+
`porthole`, whose only member is `use(name)`:
|
|
810
|
+
|
|
811
|
+
```js
|
|
812
|
+
const db = await porthole.use("db"); // a frozen namespace, or null (not here: draw without it)
|
|
813
|
+
if (db) {
|
|
814
|
+
try { await db.set("votes/me-1", { choice: "b" }, { ifVersion: 0 }); }
|
|
815
|
+
catch (error) { show(error.message); if (error.code === "conflict") reread(); } // a stable code
|
|
816
|
+
}
|
|
817
|
+
```
|
|
818
|
+
|
|
819
|
+
- **Contract** (`RUNTIME_CAPABILITIES`, version 1; `types/runtime/v1/*.d.ts`): `clipboard`,
|
|
820
|
+
`links`, `downloads`, `comments` (built in), `user`, `chat`, `data`, `context`, `artifact`,
|
|
821
|
+
`assets`, `db` (declared). Each method is served by one of the config's host functions, gated as
|
|
822
|
+
the config says; the table in P085 maps them.
|
|
823
|
+
- **Declaration** (P086): `{ capabilities: { name: config }, runtime }`, stored by the host,
|
|
824
|
+
resolved at publish by `declareCapabilities` (omitted carries forward, `{}` clears, an object
|
|
825
|
+
replaces), checked against the config, given to `mount({ declaration })`. The bridge refuses an
|
|
826
|
+
undeclared capability on every path (`undeclared` → `not_allowed`). No declaration: a 0.6 page.
|
|
827
|
+
- **Levels** (P087): `view < interact < admin < owner`; each method's least level (config `levels`
|
|
828
|
+
at or above its floor; a page's declaration raises). The host's access says the viewer's level
|
|
829
|
+
(`Grant.level`, `Grant.user` → `FrameLocation.viewer`; or `mount({ viewer })`); below it is
|
|
830
|
+
`forbidden`, before any handler. Without a viewer 0.6's functions run as before; the runtime's own
|
|
831
|
+
are refused.
|
|
832
|
+
- **Order in the bridge**: declared in the config → declared by the page → for the runtime's own,
|
|
833
|
+
the method's level and the host function's rate before the arguments are read → arguments
|
|
834
|
+
(shape, bounded walks, limits: `too_large`) → the call's level (a batch's writes', a watch's
|
|
835
|
+
read's), `data`'s names (with a viewer or without one, P094), `db`'s paths and rules → mute →
|
|
836
|
+
rates → gesture → consent → confirm (the host function's gates and the own gates of each method
|
|
837
|
+
the call runs: `artifact.publish` and `assets.delete` a click and a yes, an upload whose code
|
|
838
|
+
may run a yes; a db batch its writes', confirmed once whole, a rate counting each write; a watch
|
|
839
|
+
its read's, P094) → the handler, or for a read a result the host already gave for it (P094)
|
|
840
|
+
(context: `viewer`, `declared`, `instance`) → `db` answers with `data/users/me` (P091).
|
|
841
|
+
- **Mounts under a runtime** say what the page declared (`declaration`, or `null` for a page from
|
|
842
|
+
before 0.7); an older version is mounted with `intersectDeclarations(version's, current)`, which
|
|
843
|
+
allows exactly what both allow (each side's `db` rules read as `dbAccess` reads them, P093). A
|
|
844
|
+
display without a viewer gets nothing above view; a viewer that doesn't parse is an error.
|
|
845
|
+
- **Wire**: the roster in `ui/initialize`'s `hostCapabilities.experimental["porthole/runtime"]`;
|
|
846
|
+
`porthole/call { capability, method, args, watch? }` → `{ value }` or an error with
|
|
847
|
+
`data: { code, message }`; `porthole/event { watch, data }`; `porthole/unwatch { watch }`.
|
|
848
|
+
`data.read`/`data.subscribe` use MCP's `resources/*`.
|
|
849
|
+
- **Services are the host's**: `db` (paths, versions, `ifVersion`, batches, watches, `data/users/<id>`
|
|
850
|
+
private, the page's rules: `dbAccess`, which the host applies again), `artifact` (current version;
|
|
851
|
+
a base-checked patch), `assets` (an `AssetStore` `/server` serves at `/_blob/<id>`), `comments`
|
|
852
|
+
(the host's composer; content hears a boolean). `defineRuntimeConformance` checks an app's real
|
|
853
|
+
handlers, and with `api` its own API past the bridge with a forged context (never trust
|
|
854
|
+
`context.viewer` or `context.declared`); `leak/runtime/memory.ts` is the reference, in memory.
|
|
855
|
+
`pseudonymFor(secret, artifact, person)` gives a person an id per artifact.
|
|
856
|
+
- **Assets on the content origin** (P089, P091): for an access to the asset's artifact (a session
|
|
857
|
+
cookie, a framed set's sealed address as `Referer`, or `assets.url(id)`'s
|
|
858
|
+
`<sealed base>__porthole/blob/<id>`), then the host's check, then `AssetStore.get(id, access)`;
|
|
859
|
+
revalidated (`no-cache`, ETag); code-typed only where trusted and the config lets uploaded code
|
|
860
|
+
run, asked at each load (in bearer mode, every artifact config must, P103); by id alone only in
|
|
861
|
+
bearer mode.
|
|
862
|
+
- **The manual**: under a runtime, topic `interactive` lists `porthole.use`'s methods with levels and
|
|
863
|
+
gates, and topic `capabilities` teaches declaring, levels, errors, where state goes, and each
|
|
864
|
+
offered capability's `.d.ts`. 0.6's globals stay defined (`shell/legacy.ts`) and untaught.
|
|
865
|
+
|
|
758
866
|
## The modes
|
|
759
867
|
|
|
760
868
|
- **Inline widget** (`presets.inlineWidget`). The host has the HTML (the agent
|
|
@@ -762,8 +870,9 @@ absent.
|
|
|
762
870
|
The phase-1 workhorse.
|
|
763
871
|
- **Live widget** (`presets.liveWidget`, P079). An inline widget that shows the
|
|
764
872
|
host's data, current, as the viewer may see it: `readData` and `subscribeData`
|
|
765
|
-
behind the viewer's consent, no network of its own
|
|
766
|
-
Chart.js and D3
|
|
873
|
+
behind the viewer's consent, no network of its own (no option opens it, a
|
|
874
|
+
capability's own origins included, P103), and, served, Porthole's Chart.js and D3
|
|
875
|
+
from its own origin.
|
|
767
876
|
- **Artifact page** (`presets.artifact`). A whole document: written into an opaque
|
|
768
877
|
frame by the shell where the host has it (the first host's "show an HTML file"),
|
|
769
878
|
or served on its own origin (domain isolation), CSP in headers, versioned. It
|
|
@@ -826,7 +935,7 @@ closed like a strict host's (`leak/inherited-policy.spec.ts`).
|
|
|
826
935
|
| 2 | images, CSS images, SVG `<image>`/`<use>`, media and posters, `input type=image`, stylesheets, `@import`, fonts, scripts, `import()`, workers, manifests, icons | CSP `img/media/font/style/script-src` = the allowlist only; `worker-src blob:` | `2.resources` (an allowed image as positive control) | — (the same CSP as item 1) |
|
|
827
936
|
| 3 | WebRTC (ICE gathering reaches the network outside `connect-src`) | CSP `webrtc 'block'` **and** the shell removes every `RTC*`/`webkitRTC*` constructor, fixed in place, before content runs | `3.webrtc` (an unsandboxed peer connection as positive control: it sends STUN on both engines) | `webrtc` → `3.webrtc` (all three; Firefox's positive control needs `media.peerconnection.ice.loopback`, set in the suite's Firefox project, P035) |
|
|
828
937
|
| 4 | a nested frame: a fresh realm where item 3's removal never happened | the shell drops frame-like elements (`iframe, frame, frameset, object, embed, portal, fencedframe`) synchronously wherever content connects a node (P030), and an observer removes any that arrive another way, in the document and every shadow root (`attachShadow` is wrapped so closed ones are reached too); documents are rendered inert and imported, never written; `document.open/write` throw; declarative shadow roots can't be built (P029); CSP `frame-src 'none'` | `4.light-dom`, `.sync-realm`, `.open-shadow`, `.closed-shadow`, `.shadow-nested`, `.declarative-shadow`, `.parse-html-unsafe`, `.domparser`, `.document-write`, `.plugins`, `.foreign-object`, `.template-clone`, `.static` (each: the child never runs, no STUN, no frame left) | `frame-guard,sync-guard` → light-dom, sync-realm, plugins, foreign-object, template-clone; `attach-shadow,sync-guard` → closed-shadow, shadow-nested; `declarative-shadow` → declarative-shadow; `parser-entry-points` → document-write (each on all three engines). Either guard alone is covered by the other. |
|
|
829
|
-
| 5 | self-navigation out, with data in the URL (`location`, `replace`, `open(…, "_self")`, meta refresh, a link clicked past the shell, an SVG link), to the host's own origin, or to a `blob:`/`data:` document of its own (a fresh realm) | the **embedding page's** `frame-src` (`embedderCsp`: `'none'` for opaque content, P033; frames only, so the host's own workers are untouched, P038): a frame's own CSP cannot stop its own navigation; the shell sends link clicks out through `openLink` and drops refreshes (P030); a display whose frame navigates is started again, at most three times (P031). A served frame's page must let it reach the content origins, so there the shell cancels every navigation the frame starts to another document (the Navigation API's `navigate` event; reloads and same-document ones go on, P079), and tells the host (`navigationBlocked`, P080); an opaque frame gets no navigate events | `5.location`, `.replace`, `.open-self`, `.refresh`, `.anchor`, `.svg-link`, `.host-origin`, `.blob`, `.data` (no request reaches the canary or the host; a navigated document never runs: a witness origin hears nothing); served: `leak/served/live.spec.ts` (`location`, `replace`, `open(…, "_self")`, `navigation.navigate` to another content origin and to an outside site: no request reaches either, the document stays, the host is told the sibling's address) | `embedder-csp` → location, replace, open-self, anchor, svg-link, blob, data, `6.remote-download` (all three; `.refresh` holds: the synchronous guard drops the refresh; Firefox also holds `.data` by itself, P035; the navigation guard has no events in these opaque frames); `embedder-self` → `5.host-origin`; `navigate-guard` → the four served navigation cases (each reaches another content origin) |
|
|
938
|
+
| 5 | self-navigation out, with data in the URL (`location`, `replace`, `open(…, "_self")`, meta refresh, a link clicked past the shell, an SVG link), to the host's own origin, or to a `blob:`/`data:` document of its own (a fresh realm) | the **embedding page's** `frame-src` (`embedderCsp`: `'none'` for opaque content, P033; frames only, so the host's own workers are untouched, P038): a frame's own CSP cannot stop its own navigation; the shell sends link clicks out through `openLink` and drops refreshes (P030); a display whose frame navigates is started again, at most three times (P031). A served frame's page must let it reach the content origins, so there the shell cancels every navigation the frame starts to another document (the Navigation API's `navigate` event; reloads and same-document ones go on, P079), and tells the host (`navigationBlocked`, P080); an opaque frame gets no navigate events | `5.location`, `.replace`, `.open-self`, `.refresh`, `.anchor`, `.svg-link`, `.host-origin`, `.blob`, `.data` (no request reaches the canary or the host; a navigated document never runs: a witness origin hears nothing); served: `leak/served/live.spec.ts` (`location`, `replace`, `open(…, "_self")`, `navigation.navigate` to another content origin and to an outside site: no request reaches either, the document stays, the host is told the sibling's address), and the served conformance case `served.domain.self-navigation` (a click sends the frame to another content origin, then an outside site: the document stays, no request reaches the canary; on a tab of its own, `served.domain.tab-navigation`, P099) | `embedder-csp` → location, replace, open-self, anchor, svg-link, blob, data, `6.remote-download` (all three; `.refresh` holds: the synchronous guard drops the refresh; Firefox also holds `.data` by itself, P035; the navigation guard has no events in these opaque frames); `embedder-self` → `5.host-origin`; `navigate-guard` → the four served navigation cases (each reaches another content origin), `served.domain.self-navigation` and `served.domain.tab-navigation` (all three) |
|
|
830
939
|
| 6 | forms, popups, downloads, top and parent navigation | `sandbox="allow-scripts"` only; CSP `form-action 'none'` | `6.submit`, `.request-submit`, `.blank-form`, `.open`, `.blank-link`, `.download`, `.remote-download`, `.top`, `.top-link`, `.parent` | `sandbox` → open, blank-link, top, top-link, parent (all three), download (Chromium; WebKit and Firefox started no download either way). Form submits still fail: `form-action` is a second wall |
|
|
831
940
|
| 7 | `<base>` hijack, plugins | CSP `base-uri 'none'`, `object-src 'none'`; plugins removed as frames | `7.base-plugins` | `base-uri` → `7.base-plugins` (all three); `frame-guard,sync-guard` too (plugins left in place) |
|
|
832
941
|
| 8 | resource hints and speculation rules | CSP for those an engine governs (`prefetch`, `preload`, `modulepreload`); for the rest the shell drops `dns-prefetch`, `preconnect`, `prefetch`, `prerender` links, speculation rules, refreshes and `x-dns-prefetch-control` metas synchronously, and refuses changes that would make a connected link one (P030); `x-dns-prefetch-control: off` | `8.preconnect`, `.dns-prefetch`, `.prefetch`, `.prerender`, `.preload`, `.modulepreload`, `.speculation-rules` (each in markup, inserted, and switched on by attribute change; no request, no connection) | `sync-guard` → `8.preconnect` (WebKit: it preconnects synchronously, outside CSP). Measured: Chromium and Firefox opened no preconnect even unsandboxed. `dns-prefetch` has no out-of-band oracle here (DNS isn't observed); the element is refused before it connects |
|
|
@@ -850,6 +959,8 @@ official App SDK connects under the inline, artifact and MCP Apps presets
|
|
|
850
959
|
| 12 | `sendPrompt` | the shell refuses a call without a gesture; the host refuses one without its page's user activation, then asks `confirm` with the whole text; declines count toward a mute | `12.prompt-gesture-confirm` (a call on load is refused; a click asks; a no sends nothing; a yes reaches the handler), `12.raw-message` (a raw `ui/message` around the shell, no click: refused by the host), `12.mute`, `12.no-confirm` | `confirm-gate` → prompt-gesture-confirm, link, mute, no-confirm; `shell-gesture` → prompt-gesture-confirm, mute; `host-gesture` → raw-message |
|
|
851
960
|
| 12 | live data (`readData`, `subscribeData`, P079) | MCP `resources/read`, `resources/subscribe`/`unsubscribe`, `notifications/resources/updated`; the `consent` gate asks the host once per display before the first data call (a no refuses them all; none refuses, fail closed), then the rate; a subscribed read may be answered from the host's cache, marked stale, the fresh one following as an update; a refusal tells content why (`data: { code, message }`, P080) | `test/live-data.test.ts`, `test/refusals.test.ts`; `leak/served/live.spec.ts` (read and followed, consent asked once; cached then fresh; a viewer's no refuses both, no handler runs, `denied` with its sentence; a host refusing all without handlers; a handler's `Refused`) | — |
|
|
852
961
|
| 12 | `openLink` | link clicks go out through `openLink`; the bridge takes http(s) only, without credentials in the URL; confirmed | `12.link` (a web link asks and opens; `javascript:` links and `openLink("javascript:…")` do nothing and are refused) | `link-scheme` → `12.link` |
|
|
962
|
+
| 14 | error reports (`reportError`, S05, P095) | the adapters hand the bridge what content logged as it came; the bridge counts reportError's rate before reading it, then makes bounded text of it (`boundedText`: each object once, `[Circular]`/`[Repeated]`; 1,000 values, 16 levels, 8,000 characters; a BigInt as `"5n"`), scrubs sealed addresses and cuts to 2,000; nothing a log holds throws out of an adapter | `14.error-shapes` (a cycle, a BigInt and a 20-level shared graph from an inline widget and from an MCP Apps view, each reported as bounded text); `test/log-bounds.test.ts` (undeclared or past its rate: nothing of it read) | `report-unbounded` → `14.error-shapes` |
|
|
963
|
+
| 12 | model context (`setModelContext`, S5, P100) | the `show` gate by default: the bridge hands the host's `show` the whole update (text blocks rebuilt, structured content P095's JSON data, at most `MAX_CONTEXT_CHARS`, no character the person can't see: format characters, variation selectors, private use, lone surrogates, controls but `\n` and `\t`, save the selectors and joiners of real emoji and the joiners that shape Arabic, Indic and Myanmar letters) after every other gate and before the handler; no `show`, or one that throws, refuses it (`no-show`, `not_allowed`), and `close` ends its wait; the manual calls it the content's unconfirmed text, never instructions, and says what is refused; the React provider's default `show` draws `ContextNotice`, whole, and lets a call go once its own update is on the page (one replaced before it was drawn is refused); named gates without `show` and without `withoutShow: true` earn a `ConfigWarning` | `12.model-context` (a raw `ui/update-model-context`: shown whole, then handled; a host without `show`: refused, no handler); `test/model-context.test.ts` (both adapters, the order, the shapes, the size, each invisible character in text, values and keys, the warning); `leak/react.spec.ts` (the default notice is drawn before the handler runs, with its size; two updates in one task: only the drawn one goes; stacked displays all reachable; no provider: refused) | `model-context-show` → `12.model-context` (all three, `scripts/controls.ts`; the kit's harness is built unweakened), and both React cases (measured on Chromium) |
|
|
853
964
|
|
|
854
965
|
Measured: a click in the frame gives the host page user activation (it propagates to
|
|
855
966
|
ancestors) on Chromium, WebKit and Firefox, so the host-side gesture check holds for real
|
|
@@ -863,12 +974,21 @@ for that to lapse and click with raw input.
|
|
|
863
974
|
|------|-----------|-------|------------------|
|
|
864
975
|
| The host's check (P050) | `authorize.check` after a ticket or cookie verifies, before anything is served; a deny is a 403 page saying `denied` and the host's code, and the display's `outcome` says so even after `loaded` | `leak/served/authorize.spec.ts`: a revoked subject's ticket (a page, an app); a framed app's next request and reload mid-session (Chromium, Firefox: WebKit keeps no framed cookie, P025); a framed page's next load; an app and a page in a tab | `authorize` → every case but WebKit's framed page (`session` either way) |
|
|
865
976
|
| Url-mode delegation (P049) | `allow` from `permissions`, `""` by default | `leak/served/permissions.spec.ts`: full screen follows it on all three; clipboard writes on Chromium only (WebKit and Firefox let any frame write in a click) | `url-permissions` → the default case (all three) |
|
|
977
|
+
| Siblings on the content domain (P101) | over https only `__Host-porthole-` names are read (a sibling sets any other name for the whole domain, never a `__Host-` one), names trimmed of spaces and tabs only; the entered mark is its label's and path's, read from a nonce cookie only; a url-mode app's request rides its cookie only from its own origin (`Origin`; `Sec-Fetch-Site` `same-origin` or `none`) or as a GET/HEAD navigation, else a 403 before the upstream and the host's check; a socket (`access`, `nodeHost`'s `appSocket`, a Worker's upgrade path) from its own origin only | `test/siblings.test.ts` (planted names, the mark on another label, every kind of request and socket, `nodeHost` over a real socket); `test/workers.test.ts` (workerd: a sibling's POST and socket refused, the app's own open); `served.url.siblings`: another app's frame (Chromium, Firefox: WebKit keeps no framed cookie, P025) or tab loading the app's script is refused, its own loads; `leak/kit.spec.ts`: the app's own WebSocket opens through `nodeHost`, a same-site sibling's doesn't; prod shape: a session copied under an unprefixed name and planted with `Domain=` opens nothing, and the socket case over wss | `url-origin` → `served.url.siblings` on the reference serving (Chromium, Firefox; its labels are cross-site on `*.localhost`, so only the framed half rides a cookie) |
|
|
866
978
|
| Porthole's libraries (P079) | `egress.libraries` (domain isolation; on in `presets.liveWidget`): `script-src <content origin>/__porthole/lib/`; `/server` serves Chart.js 4.5.1 and D3 7.9.0, npm's bytes, on every content origin, without a ticket, immutable | `test/libraries.test.ts` (npm's bytes, pinned, licenses; headers; nothing else under the path); `leak/served/live.spec.ts` (both load and draw in a live widget whose every other load and fetch reaches no oracle) | — (rows 1–2) |
|
|
867
979
|
| Library CDNs for artifacts (P048, P078) | `egress: LIBRARY_CDNS` in the host's artifact config; closed by default (P022); Tailwind's, jQuery's and Plotly's own CDNs for scripts only | `leak/cdn.spec.ts`: opaque and served, a CDN library loads only when opened; another origin never; a stylesheet, an image and a fetch never reach the libraries' own CDNs | — (the CSP of rows 1–2) |
|
|
868
980
|
| Files: serving (P081) | `StoredFiles`; the manifest only, decoded once; Porthole's type table, `nosniff`, a CSP on every answer, ETag/304, ranges, CORP `same-origin`, service workers refused; every page in the shell | `test/files.test.ts`; `leak/served/files.spec.ts`: many files by relative path (framed, on a tab), the Vite + React build, a newer version never reaches a running page, traversal 404s, `.html` as `.txt` is text, another origin reads nothing, no service worker | `service-worker` → "no service worker ever registers" (all three); `file-corp` → "another origin reads none of the files" (a page elsewhere runs the script, all three) |
|
|
869
981
|
| Files: the version's own path in the CSP (P082) | `fileSetCspDirectives`: `<origin><base>` (tab) or `<origin>/__porthole/f/` (frame) in the seven loading directives; never `'self'` | `leak/served/files.spec.ts`: a page loads no other version's files; a way out past the base is blocked | `file-self` → those two cases (another version's data and module load; `%2e%2e` past the base reaches the server; all three) |
|
|
870
982
|
| Files in a frame: access in the path (P083) | the ticket's answer is the entry; `/__porthole/f/<AES-GCM sealed session>/`; `history.replaceState` before anything loads; the host's check per file; an address opens on its own for an hour (then only the running page's own same-origin loads, till the session ends), renewed by the shell; reported as `./`, never whole | `test/files.test.ts` (sealed: no viewer or subject in it; another origin, a tampered or ended one: 401; revoked: 403; its hour, the page's own loads after it, renewal; redaction); `test/workers.test.ts` (workerd); every framed case of `leak/served/files.spec.ts` on WebKit (no cookie in frames), its reports never naming the address, its renewal under a moved clock | — |
|
|
871
|
-
| Files: pages navigate within the set (P084) | the guard lets a navigation to a page under `files.base` go, after `porthole/navigating
|
|
983
|
+
| Files: pages navigate within the set (P084, P098) | the guard lets a navigation to a page under `files.base` go, after `porthole/navigating`, and the page it opened says so as it arrives, each naming its version; the host takes the next load as that page, or the load the notice came after: a load no notice for the mounted version explained waits `LATE_NOTICE_MS` holding the frame (nothing it says reaches the display), then starts it again | `leak/served/files.spec.ts`: a link opens another page in the frame, the display goes on, also with the leaving page's notice dropped or every notice late; a non-page file, `/`, `/__porthole/d/…` never open; `test/pages-of-set.test.ts`: another version's notice or a hello first restarts at once, nothing is answered during the wait | `navigate-guard` → the three link cases, "opens nothing else" and the sealed-address reports case (all three; the last measured failing before P098 too) |
|
|
984
|
+
| A page on a tab of its own (P099) | every served page's CSP header carries the frame's sandbox (`sandbox allow-scripts allow-same-origin`, `servedSandboxDirective`) and its `Permissions-Policy` denies what the frame's `allow` doesn't grant (`servedPermissionsPolicy`); on a tab the shell answers `window.open` with null (but `_self`), refuses picture-in-picture windows, devices, location, full screen, passkeys, the share sheet, payments (Apple Pay too) and a video's full screen; its navigation guard (P079) stops the page navigating itself, and `navigation.navigate()` and a tab's `open(…, "_self")` ask its rule before they start (the address read once, through the platform's own functions); a tab's links are followed by the shell as clicked (cancelled in its first listener, found through the composed path, closed shadow roots made open to it), never by the browser; a lock that can't take says so (`data-porthole-unfixed`, a report to the host) | `test/server.test.ts`, `test/files.test.ts`, `test/policy.test.ts`, `test/agreement.test.ts` (every served page, in a frame, on a tab, without fetch metadata; never a script, a url-mode app or Porthole's own pages; the header held to the frame's `allow`); served conformance `served.domain.tab-window-open`, `.tab-escapes` (a target=_blank link clicked past the shell, forms, a blob download, `prompt`), `.tab-opener` (its opener sent elsewhere), `.tab-navigation` (a `blob:` document of its own and an outside site, each from a fresh tab by `location`, `assign`, `replace`, a link past the shell, `navigation.navigate()` and `open(…, "_self")`, the last two given a two-faced address too, a link and `navigate()` with the built-ins lying), `.tab-links` (a link's `href`, `target` or `download` changed after the shell read it, a link in an open or closed shadow root; a fragment link still jumps, a cancelled one goes nowhere), `.tab-devices` (location, camera and microphone granted by the browser, full screen after a click), `.tab-prompts` (a passkey, a payment to a canary method, a share, a video's full screen: each refused at once); `test/permissions-policy.test.ts` (the denied list against Chromium's, checked in); `leak/served/tab.spec.ts`: those five, a file set's page on a tab (its module, fetch and links to its own pages work; nothing else opens), a frame's sealed address opened on a tab | `tab-sandbox` → tab-escapes, tab-opener, the file set's and the sealed address's cases (all three); `tab-sandbox,window-open` → those and tab-window-open (all three; picture-in-picture opens on Chromium and Firefox, absent on WebKit); `permissions-policy,device-locks` → tab-devices (all three), tab-prompts (Chromium, Firefox; WebKit refused each at once here either way); `device-locks` alone → tab-devices on WebKit and Firefox (they don't apply the header; Chromium holds), tab-prompts on Firefox; `window-open` or `permissions-policy` alone → none; `navigate-guard` → tab-navigation (all three); `navigate-ask` (the rule asked first, alone) → tab-navigation and tab-links on WebKit (Chromium and Firefox hold by the event); `link-rule` (the browser follows links again) → tab-links and tab-navigation on WebKit; `scripts/controls.ts` |
|
|
985
|
+
| The runtime: a page's declaration (P086) | the bridge refuses a capability the page didn't declare (`undeclared`), on `porthole/call` and 0.6's requests alike, before any handler | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "an undeclared capability: null from use, refused when sent anyway, its handler never asked" | `runtime-declaration` → that case (all three) |
|
|
986
|
+
| The runtime: levels (P087) | each method's least level against the host's viewer, before any handler | `test/runtime.test.ts`, `test/assets.test.ts` (the grant's level to the bridge); `leak/served/runtime.spec.ts`: "a method above the viewer's level: forbidden, its handler never asked" | `runtime-level` → that case, and P094's "a read above the viewer's level: a result the host pushed is refused as a cold read is", whose reads stand on it (all three) |
|
|
987
|
+
| The runtime: a page's data names (P086, P094) | the bridge refuses a resource or tool the page's `data` doesn't name (`undeclared`), with a viewer and without one, before any handler | `test/audit-gates.test.ts`, `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "a resource outside the page's data names: refused with a viewer and without one, its handler never asked" | `runtime-data-names` → that case (all three) |
|
|
988
|
+
| Live data: a kept result is a read (P094) | a result the host pushed (`changed(result)`), or read after a stale answer, answers the frame's next read only past every gate a read has (level, names, rate, gesture, consent, confirm), with no new upstream call | `test/audit-gates.test.ts`; `leak/served/runtime.spec.ts`: "a read above the viewer's level: a result the host pushed is refused as a cold read is" | `live-held-read` → that case (all three) |
|
|
989
|
+
| The runtime: per-user data (P088) | `dbAccess`: `me` is the host's id; another's `data/users/<id>`, or anything else under `data`, refused at every level, in the bridge and the host | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "a person's own data is theirs" | `db-private` → that case (all three) |
|
|
990
|
+
| The runtime: comments write-only (P090) | the bridge answers `comments` with `true` only for a handler's `true`; no read method | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "comments are write-only" | `comments-result` → that case (all three) |
|
|
991
|
+
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
872
992
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
873
993
|
|
|
874
994
|
### The clipboard, and copy buttons
|
|
@@ -1043,7 +1163,7 @@ Three more limits sit outside the list:
|
|
|
1043
1163
|
- `theme` (where it runs): the person's theme, a page that declares it, or
|
|
1044
1164
|
`theme.documents: "never"`, always light. Checks: `11.theme-flip`, `11.document-theme`,
|
|
1045
1165
|
`14.theme-never`.
|
|
1046
|
-
- `errors` (interactive): `errors: "agent" | "host" | "none"`.
|
|
1166
|
+
- `errors` (interactive): `errors: "agent" | "host" | "none"`. Checks: `14.errors`, `14.error-shapes`.
|
|
1047
1167
|
|
|
1048
1168
|
They are config facts a whole-page viewer needed (P065):
|
|
1049
1169
|
- `layout.kind: "fill"` makes every mount fill its container (`MountOptions.fill`, React
|