@botiverse/porthole 0.5.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +41 -0
- package/dist/bridge/bridge.d.ts +13 -0
- package/dist/bridge/bridge.js +208 -13
- package/dist/bridge/navigation.d.ts +1 -6
- package/dist/bridge/navigation.js +11 -0
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +16 -0
- package/dist/bridge/types.d.ts +41 -4
- package/dist/check/check.d.ts +19 -3
- package/dist/check/check.js +55 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +31 -12
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +27 -3
- package/dist/compile/policy.d.ts +34 -0
- package/dist/compile/policy.js +74 -0
- package/dist/config/capabilities.d.ts +62 -3
- package/dist/config/capabilities.js +20 -0
- package/dist/config/schema.d.ts +32 -0
- package/dist/config/validate.d.ts +1 -1
- package/dist/config/validate.js +74 -5
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/index.d.ts +1 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +314 -0
- package/dist/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -0
- package/dist/guide/gates.d.ts +3 -0
- package/dist/guide/gates.js +19 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +44 -32
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +202 -0
- package/dist/host/create-host.js +45 -0
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/types.d.ts +18 -0
- package/dist/index.d.ts +13 -4
- package/dist/index.js +16 -3
- package/dist/isolation/types.d.ts +8 -0
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +1 -0
- package/dist/protocol/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +113 -0
- package/dist/protocol/shell-adapter.js +52 -3
- package/dist/react/dialog.js +31 -0
- package/dist/react/frame.d.ts +13 -0
- package/dist/react/frame.js +6 -0
- package/dist/runtime/contract.d.ts +193 -0
- package/dist/runtime/contract.js +216 -0
- package/dist/runtime/db.d.ts +153 -0
- package/dist/runtime/db.js +398 -0
- package/dist/runtime/declaration.d.ts +86 -0
- package/dist/runtime/declaration.js +266 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +199 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +57 -0
- package/dist/server/files.js +338 -0
- package/dist/server/host.d.ts +44 -2
- package/dist/server/host.js +42 -2
- package/dist/server/index.d.ts +5 -2
- package/dist/server/index.js +5 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -0
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +468 -24
- package/dist/server/types.d.ts +118 -5
- package/dist/shell/document.d.ts +27 -0
- package/dist/shell/document.js +46 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.d.ts +2 -1
- package/dist/shell/runtime.js +114 -46
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +142 -5
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +716 -7
- package/docs/DESIGN.md +97 -3
- package/package.json +3 -1
- package/src/bridge/bridge.ts +281 -17
- package/src/bridge/navigation.ts +12 -0
- package/src/bridge/refusal.ts +16 -0
- package/src/bridge/types.ts +46 -4
- package/src/check/check.ts +100 -14
- package/src/check/files.ts +384 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +33 -12
- package/src/check/page.ts +14 -0
- package/src/check/tools.ts +52 -3
- package/src/compile/policy.ts +92 -0
- package/src/config/capabilities.ts +49 -2
- package/src/config/schema.ts +32 -0
- package/src/config/validate.ts +107 -5
- package/src/conformance/index.ts +7 -0
- package/src/conformance/runtime.ts +573 -0
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/gates.ts +25 -0
- package/src/guide/guide.ts +78 -52
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +244 -0
- package/src/host/create-host.ts +55 -0
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/types.ts +18 -0
- package/src/index.ts +121 -0
- package/src/isolation/types.ts +8 -0
- package/src/presets/presets.ts +7 -0
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/runtime-calls.ts +138 -0
- package/src/protocol/shell-adapter.ts +56 -2
- package/src/react/dialog.tsx +33 -0
- package/src/react/frame.tsx +19 -0
- package/src/runtime/contract.ts +305 -0
- package/src/runtime/db.ts +530 -0
- package/src/runtime/declaration.ts +378 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +339 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +425 -0
- package/src/server/host.ts +84 -3
- package/src/server/index.ts +22 -0
- package/src/server/keys.ts +53 -0
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +565 -26
- package/src/server/types.ts +124 -4
- package/src/shell/document.ts +74 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +114 -46
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +16 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
package/docs/DESIGN.md
CHANGED
|
@@ -114,6 +114,11 @@ no `components` field (P015).
|
|
|
114
114
|
| `resize` | none | event | (automatic) | `ui/notifications/size-changed` |
|
|
115
115
|
| `copyText` | user-activation, 30/min | handler | `copyText(text)` | `porthole/copy-text` (none in the standard) |
|
|
116
116
|
| `annotate` | 120/min (the frame's reports) | event | — | `porthole/annotate.*` (the host drives it, P053) |
|
|
117
|
+
| `user` (runtime) | 60/min | viewer (the host's `ViewerInfo`) | `porthole.use("user")` | `porthole/call` (P087) |
|
|
118
|
+
| `comments` (runtime) | user-activation, 30/min | handler (answers a boolean) | `porthole.use("comments")` | `porthole/call` (P090) |
|
|
119
|
+
| `artifact` (runtime, artifact mode) | 10/min | handler (`op: get \| publish`) | `porthole.use("artifact")` | `porthole/call` (P088) |
|
|
120
|
+
| `assets` (runtime, served artifacts) | 30/min | handler (`op: list \| upload \| delete`) | `porthole.use("assets")` | `porthole/call`; `/server` serves `/_blob/<id>` (P089) |
|
|
121
|
+
| `db` (runtime) | 600/min | handler (`op: get \| query \| watch \| set \| update \| delete \| batch`) | `porthole.use("db")` | `porthole/call`, `porthole/event`, `porthole/unwatch` (P088) |
|
|
117
122
|
|
|
118
123
|
Every preset declares only `resize` and `reportError` (they report to the host and
|
|
119
124
|
carry nothing out); the host declares the rest. Gates are explained in P021: all
|
|
@@ -184,6 +189,7 @@ functions not built yet throw `NotBuiltYet` naming their milestone.
|
|
|
184
189
|
| React: `PortholeProvider`, `PortholeFrame`, `ConfirmDialog`, `admitFrame` | `src/react/` | core (M4, built) | first host |
|
|
185
190
|
| Conformance: `ConformanceHost`, `LaunchSpec`, `LaunchedDisplay`, `defineLeakSuite`, `PROBES`, the oracles; `defineServedSuite`, `ServedConformanceHost` | `src/conformance/` | core (M2, built); served modes (done) | any host |
|
|
186
191
|
| Server: `createServer`, `PortholeServer`, `TicketStore`, `ArtifactStore`, `ContentDomain`, `Grant`, `Access`, `Upstream`, `proxyTo`, `memoryTicketStore` | `src/server/` | served modes (done) | host backends |
|
|
192
|
+
| Files (P081): `checkFileSet`, `filePathProblem`, `fileLimits`, `requestFilePath`, `lookupFile`, `fileTypeOf`, `servesFiles`; `StoredFiles`, `FileAddress`, `versionedAddress`; `lintFiles`, `admitFiles` | `src/files/`, `src/server/files.ts`, `src/check/files.ts` | 0.6 (done) | host backends, publish tools |
|
|
187
193
|
|
|
188
194
|
### Host API
|
|
189
195
|
|
|
@@ -241,6 +247,20 @@ and calls `PortholeServer.issue`.
|
|
|
241
247
|
- **What a served frame loads** is a `ServedDocument`: the shell (content then
|
|
242
248
|
arrives over the transport, as for opaque frames), a stored artifact version, the
|
|
243
249
|
MCP Apps sandbox proxy, or an external app (url mode).
|
|
250
|
+
- **A version made of files** (P081–P084). The store answers a manifest (`files`: path →
|
|
251
|
+
`{ size, sha256, type? }`, an `entry`, `spa`) and `read(path)`; `{ html }` stays one page. Every
|
|
252
|
+
file is looked up in the manifest only, by the path below the version's base, decoded once
|
|
253
|
+
(`requestFilePath`, `lookupFile`: `dir/` is its `index.html`, `name` is `name.html`, the nearest
|
|
254
|
+
`404.html`, the entry for a single-page app's navigations). Its answer is typed by Porthole's
|
|
255
|
+
table (`fileTypeOf`; unknown: a download), `nosniff`, with its CSP (a page's and a script's: the
|
|
256
|
+
frame's plus the version's own path, P082; anything else `default-src 'none'; sandbox`), a
|
|
257
|
+
strong ETag and 304, ranges, `Cross-Origin-Resource-Policy: same-origin` (files), and the cache
|
|
258
|
+
rule of its address (files immutable, pages revalidated); a service worker's script is refused.
|
|
259
|
+
Every page is in the shell. Its address: in a frame, `/__porthole/f/<sealed access>/<path>` (the
|
|
260
|
+
ticket's answer is the entry, whose shell moves to that address first, P083); on a tab, the
|
|
261
|
+
version's own clean address, `entry.at`'s `base` (`/v/3/`), where an address that means the
|
|
262
|
+
latest (`/`, `/style.css`) is redeemed (P081). So a page never mixes versions: its relative
|
|
263
|
+
addresses are its version's. A set's pages open each other in the frame (P084).
|
|
244
264
|
- **Tickets** are minted by `issue` (one-time, short-lived, bound to an instance and
|
|
245
265
|
a viewer, stored as their hash), carried once in the frame's URL, and taken by the
|
|
246
266
|
content origin. A served document (at `/__porthole/d/<instance key>`) comes back in
|
|
@@ -363,8 +383,9 @@ with redirect entry):
|
|
|
363
383
|
- `instance`: the instance an issue request proposes, as the app means it;
|
|
364
384
|
- `access`: may this viewer see it, and with what grant;
|
|
365
385
|
- `authorize`: may this cookie still see it, on each request (P050);
|
|
366
|
-
- `source`: a stored
|
|
367
|
-
- `entry.at`: the instance a clean address's path names (redirect entry)
|
|
386
|
+
- `source`: a stored version by id and version: one page (`{ html }`), or a set of files (P081);
|
|
387
|
+
- `entry.at`: the instance a clean address's path names (redirect entry), or, for a set of files,
|
|
388
|
+
the instance with its version's own address (`{ instance, base, file }`, P081).
|
|
368
389
|
|
|
369
390
|
**An adopter's whole wiring** (the package's `examples/app.mjs` is this, runnable on Node and
|
|
370
391
|
Workers; docs/ADOPTING.md walks through it):
|
|
@@ -381,7 +402,7 @@ const content = createContentHost<Viewer>({
|
|
|
381
402
|
access: async (instance, viewer) =>
|
|
382
403
|
viewer !== null && (await canSee(viewer, instance)) ? { viewer: viewer.id, subject: viewer.id } : null,
|
|
383
404
|
authorize: ({ subject }) => (revoked(subject) ? { allow: false, code: "revoked" } : { allow: true }),
|
|
384
|
-
source: (id, version) => store.page(id, version), // { html } | null
|
|
405
|
+
source: (id, version) => store.page(id, version), // { html } | { files, read } | null
|
|
385
406
|
entry: {
|
|
386
407
|
authorizeUrl: `${env.APP_ORIGIN}/porthole/authorize`,
|
|
387
408
|
at: (scope, path) => pageAt(scope, path), // "/" → latest, "/v/3" → version 3
|
|
@@ -577,6 +598,14 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
|
|
|
577
598
|
- **`admitContent(config, content, { refuseOn })`**: the show tool's gate. It refuses errors by
|
|
578
599
|
default with a text that says what to change; otherwise it shows the content (a widget's
|
|
579
600
|
document taken as its body) and returns the warnings as a note.
|
|
601
|
+
- **A page with files** (P081): `lintFiles(config, files)` lints each page as `lintContent` does
|
|
602
|
+
(findings name their `path`), holds the set to `checkFileSet`'s rules and the config's limits,
|
|
603
|
+
and looks each relative reference up in the set (markup, CSS, module imports, workers,
|
|
604
|
+
fetches): a page's reference that starts with `/` is an error (it names the address's root, not
|
|
605
|
+
the version: a Vite build without `base: "./"`), one that isn't in the set a warning.
|
|
606
|
+
`admitFiles` is the publish tool's gate, as `admitContent` is the show tool's. `checkPage({
|
|
607
|
+
config, files, driver })` serves the whole set and runs its entry (a served artifact config and
|
|
608
|
+
a driver that serves).
|
|
580
609
|
- **`checkPage({ config, content, driver })`** (`/check`): the content in the real sandbox at each
|
|
581
610
|
width and scheme (defaults: the manual's phone and desktop widths, light and dark unless
|
|
582
611
|
unthemed). The check page (`src/check/page.ts`, bundled and shipped as `/check/page`, a module
|
|
@@ -731,6 +760,62 @@ for `localStorage` in an opaque frame, applies the theme variables, and fires th
|
|
|
731
760
|
config's theme event after a change. A capability that is not declared is simply
|
|
732
761
|
absent.
|
|
733
762
|
|
|
763
|
+
## The capability runtime (0.7.0: P085–P090)
|
|
764
|
+
|
|
765
|
+
A config with `runtime: "1"` (inline widgets and artifact pages) gives its frames one global,
|
|
766
|
+
`porthole`, whose only member is `use(name)`:
|
|
767
|
+
|
|
768
|
+
```js
|
|
769
|
+
const db = await porthole.use("db"); // a frozen namespace, or null (not here: draw without it)
|
|
770
|
+
if (db) {
|
|
771
|
+
try { await db.set("votes/me-1", { choice: "b" }, { ifVersion: 0 }); }
|
|
772
|
+
catch (error) { show(error.message); if (error.code === "conflict") reread(); } // a stable code
|
|
773
|
+
}
|
|
774
|
+
```
|
|
775
|
+
|
|
776
|
+
- **Contract** (`RUNTIME_CAPABILITIES`, version 1; `types/runtime/v1/*.d.ts`): `clipboard`,
|
|
777
|
+
`links`, `downloads`, `comments` (built in), `user`, `chat`, `data`, `context`, `artifact`,
|
|
778
|
+
`assets`, `db` (declared). Each method is served by one of the config's host functions, gated as
|
|
779
|
+
the config says; the table in P085 maps them.
|
|
780
|
+
- **Declaration** (P086): `{ capabilities: { name: config }, runtime }`, stored by the host,
|
|
781
|
+
resolved at publish by `declareCapabilities` (omitted carries forward, `{}` clears, an object
|
|
782
|
+
replaces), checked against the config, given to `mount({ declaration })`. The bridge refuses an
|
|
783
|
+
undeclared capability on every path (`undeclared` → `not_allowed`). No declaration: a 0.6 page.
|
|
784
|
+
- **Levels** (P087): `view < interact < admin < owner`; each method's least level (config `levels`
|
|
785
|
+
at or above its floor; a page's declaration raises). The host's access says the viewer's level
|
|
786
|
+
(`Grant.level`, `Grant.user` → `FrameLocation.viewer`; or `mount({ viewer })`); below it is
|
|
787
|
+
`forbidden`, before any handler. Without a viewer 0.6's functions run as before; the runtime's own
|
|
788
|
+
are refused.
|
|
789
|
+
- **Order in the bridge**: declared in the config → declared by the page → for the runtime's own,
|
|
790
|
+
the method's level and the host function's rate before the arguments are read → arguments
|
|
791
|
+
(shape, bounded walks, limits: `too_large`) → the call's level (a batch's writes', a watch's
|
|
792
|
+
read's), `data`'s names, `db`'s paths and rules → mute → rates → gesture → consent → confirm
|
|
793
|
+
(the host function's gates and the method's own: `artifact.publish` and `assets.delete` a click
|
|
794
|
+
and a yes, an upload whose code may run a yes) → the handler (context: `viewer`, `declared`,
|
|
795
|
+
`instance`) → `db` answers with `data/users/me` (P091).
|
|
796
|
+
- **Mounts under a runtime** say what the page declared (`declaration`, or `null` for a page from
|
|
797
|
+
before 0.7); an older version is mounted with `intersectDeclarations(version's, current)`. A
|
|
798
|
+
display without a viewer gets nothing above view; a viewer that doesn't parse is an error.
|
|
799
|
+
- **Wire**: the roster in `ui/initialize`'s `hostCapabilities.experimental["porthole/runtime"]`;
|
|
800
|
+
`porthole/call { capability, method, args, watch? }` → `{ value }` or an error with
|
|
801
|
+
`data: { code, message }`; `porthole/event { watch, data }`; `porthole/unwatch { watch }`.
|
|
802
|
+
`data.read`/`data.subscribe` use MCP's `resources/*`.
|
|
803
|
+
- **Services are the host's**: `db` (paths, versions, `ifVersion`, batches, watches, `data/users/<id>`
|
|
804
|
+
private, the page's rules: `dbAccess`, which the host applies again), `artifact` (current version;
|
|
805
|
+
a base-checked patch), `assets` (an `AssetStore` `/server` serves at `/_blob/<id>`), `comments`
|
|
806
|
+
(the host's composer; content hears a boolean). `defineRuntimeConformance` checks an app's real
|
|
807
|
+
handlers, and with `api` its own API past the bridge with a forged context (never trust
|
|
808
|
+
`context.viewer` or `context.declared`); `leak/runtime/memory.ts` is the reference, in memory.
|
|
809
|
+
`pseudonymFor(secret, artifact, person)` gives a person an id per artifact.
|
|
810
|
+
- **Assets on the content origin** (P089, P091): for an access to the asset's artifact (a session
|
|
811
|
+
cookie, a framed set's sealed address as `Referer`, or `assets.url(id)`'s
|
|
812
|
+
`<sealed base>__porthole/blob/<id>`), then the host's check, then `AssetStore.get(id, access)`;
|
|
813
|
+
revalidated (`no-cache`, ETag); code-typed only where trusted and the config lets uploaded code
|
|
814
|
+
run; by id alone only in bearer mode.
|
|
815
|
+
- **The manual**: under a runtime, topic `interactive` lists `porthole.use`'s methods with levels and
|
|
816
|
+
gates, and topic `capabilities` teaches declaring, levels, errors, where state goes, and each
|
|
817
|
+
offered capability's `.d.ts`. 0.6's globals stay defined (`shell/legacy.ts`) and untaught.
|
|
818
|
+
|
|
734
819
|
## The modes
|
|
735
820
|
|
|
736
821
|
- **Inline widget** (`presets.inlineWidget`). The host has the HTML (the agent
|
|
@@ -841,6 +926,15 @@ for that to lapse and click with raw input.
|
|
|
841
926
|
| 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) |
|
|
842
927
|
| 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) |
|
|
843
928
|
| 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) |
|
|
929
|
+
| 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) |
|
|
930
|
+
| Files: the version's own path in the CSP (P082) | `fileSetCspDirectives`: `<origin><base>` (tab) or `<origin>/__porthole/f/` (frame) in the seven loading directives; never `'self'` | `leak/served/files.spec.ts`: a page loads no other version's files; a way out past the base is blocked | `file-self` → those two cases (another version's data and module load; `%2e%2e` past the base reaches the server; all three) |
|
|
931
|
+
| Files in a frame: access in the path (P083) | the ticket's answer is the entry; `/__porthole/f/<AES-GCM sealed session>/`; `history.replaceState` before anything loads; the host's check per file; an address opens on its own for an hour (then only the running page's own same-origin loads, till the session ends), renewed by the shell; reported as `./`, never whole | `test/files.test.ts` (sealed: no viewer or subject in it; another origin, a tampered or ended one: 401; revoked: 403; its hour, the page's own loads after it, renewal; redaction); `test/workers.test.ts` (workerd); every framed case of `leak/served/files.spec.ts` on WebKit (no cookie in frames), its reports never naming the address, its renewal under a moved clock | — |
|
|
932
|
+
| Files: pages navigate within the set (P084) | the guard lets a navigation to a page under `files.base` go, after `porthole/navigating`; the host takes the next load as that page | `leak/served/files.spec.ts`: a link opens another page in the frame, the display goes on; a non-page file, `/`, `/__porthole/d/…` never open | `navigate-guard` → both cases (all three) |
|
|
933
|
+
| The runtime: a page's declaration (P086) | the bridge refuses a capability the page didn't declare (`undeclared`), on `porthole/call` and 0.6's requests alike, before any handler | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "an undeclared capability: null from use, refused when sent anyway, its handler never asked" | `runtime-declaration` → that case (all three) |
|
|
934
|
+
| The runtime: levels (P087) | each method's least level against the host's viewer, before any handler | `test/runtime.test.ts`, `test/assets.test.ts` (the grant's level to the bridge); `leak/served/runtime.spec.ts`: "a method above the viewer's level: forbidden, its handler never asked" | `runtime-level` → that case (all three) |
|
|
935
|
+
| The runtime: per-user data (P088) | `dbAccess`: `me` is the host's id; another's `data/users/<id>`, or anything else under `data`, refused at every level, in the bridge and the host | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "a person's own data is theirs" | `db-private` → that case (all three) |
|
|
936
|
+
| The runtime: comments write-only (P090) | the bridge answers `comments` with `true` only for a handler's `true`; no read method | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "comments are write-only" | `comments-result` → that case (all three) |
|
|
937
|
+
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run, inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
844
938
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
845
939
|
|
|
846
940
|
### The clipboard, and copy buttons
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"bin": {
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
"files": [
|
|
10
10
|
"src",
|
|
11
11
|
"dist",
|
|
12
|
+
"types/runtime/**/*.d.ts",
|
|
12
13
|
"docs",
|
|
13
14
|
"examples",
|
|
14
15
|
"README.md"
|
|
@@ -85,6 +86,7 @@
|
|
|
85
86
|
"scripts": {
|
|
86
87
|
"build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node scripts/build-harness.ts && node scripts/copy-docs.ts",
|
|
87
88
|
"test:leak": "playwright test -c leak/playwright.config.ts",
|
|
89
|
+
"test:controls": "node scripts/controls.ts",
|
|
88
90
|
"test:bundle": "node scripts/bundle-test.ts"
|
|
89
91
|
}
|
|
90
92
|
}
|
package/src/bridge/bridge.ts
CHANGED
|
@@ -8,8 +8,31 @@ import {
|
|
|
8
8
|
import type { AnnotationReport } from "../annotate/types.ts";
|
|
9
9
|
import { parseReport } from "../annotate/validate.ts";
|
|
10
10
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
11
|
-
import { effectiveGates } from "../compile/policy.ts";
|
|
12
|
-
import { blockedNavigationMessage } from "./navigation.ts";
|
|
11
|
+
import { callGates, effectiveGates } from "../compile/policy.ts";
|
|
12
|
+
import { blockedNavigationMessage, withoutSealedAddresses } from "./navigation.ts";
|
|
13
|
+
import {
|
|
14
|
+
RUNTIME_HOST_FUNCTIONS,
|
|
15
|
+
familyOf,
|
|
16
|
+
methodLevel,
|
|
17
|
+
methodOf,
|
|
18
|
+
assetCodeRuns,
|
|
19
|
+
rosterOf,
|
|
20
|
+
runtimeCapability,
|
|
21
|
+
type RuntimeCapabilityName,
|
|
22
|
+
} from "../runtime/contract.ts";
|
|
23
|
+
import {
|
|
24
|
+
declaredMatch,
|
|
25
|
+
type DeclaredCapability,
|
|
26
|
+
type PageDeclaration,
|
|
27
|
+
} from "../runtime/declaration.ts";
|
|
28
|
+
import { dbAccess, parseDbRequest, withMe, type DbRequest } from "../runtime/db.ts";
|
|
29
|
+
import { atLeast, higher, type ViewerInfo, type ViewerLevel } from "../runtime/levels.ts";
|
|
30
|
+
import {
|
|
31
|
+
isCodeAsset,
|
|
32
|
+
parseArtifactRequest,
|
|
33
|
+
parseAssetRequest,
|
|
34
|
+
parseCommentRequest,
|
|
35
|
+
} from "../runtime/requests.ts";
|
|
13
36
|
import {
|
|
14
37
|
defaultReason,
|
|
15
38
|
isRefused,
|
|
@@ -67,6 +90,17 @@ export interface BridgeOptions {
|
|
|
67
90
|
readonly onEvent: (event: BridgeEvent) => void;
|
|
68
91
|
/** The clock, in milliseconds (tests pass their own). */
|
|
69
92
|
readonly now?: () => number;
|
|
93
|
+
/**
|
|
94
|
+
* Who is viewing (P087), as the host said: each runtime method's level is checked against it,
|
|
95
|
+
* and the runtime's own host functions need it. Absent: 0.6's functions run unchecked, as before.
|
|
96
|
+
*/
|
|
97
|
+
readonly viewer?: ViewerInfo;
|
|
98
|
+
/**
|
|
99
|
+
* What the display's page declared (P086), checked against the config (`checkDeclaration`).
|
|
100
|
+
* Absent: a page without one (0.6's): built-ins only through the runtime, and 0.6's globals and
|
|
101
|
+
* requests as before.
|
|
102
|
+
*/
|
|
103
|
+
readonly declaration?: PageDeclaration | null;
|
|
70
104
|
}
|
|
71
105
|
|
|
72
106
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
@@ -101,10 +135,11 @@ function resourceUri(args: unknown): { uri: string } | null {
|
|
|
101
135
|
return typeof uri === "string" && uri !== "" && uri.length <= MAX_URL ? { uri } : null;
|
|
102
136
|
}
|
|
103
137
|
|
|
138
|
+
/** A call's arguments checked: the capability's, or null (malformed), or "too_large". */
|
|
104
139
|
type Validator<N extends CapabilityName> = (
|
|
105
140
|
args: unknown,
|
|
106
141
|
config: PortholeConfig,
|
|
107
|
-
) => CapabilityArgs[N] | null;
|
|
142
|
+
) => CapabilityArgs[N] | "too_large" | null;
|
|
108
143
|
|
|
109
144
|
const VALIDATORS: { readonly [N in CapabilityName]: Validator<N> } = {
|
|
110
145
|
sendPrompt: (args, config) => {
|
|
@@ -158,15 +193,18 @@ const VALIDATORS: { readonly [N in CapabilityName]: Validator<N> } = {
|
|
|
158
193
|
reportError: (args, config) => {
|
|
159
194
|
// A navigation the shell cancelled (P080): Porthole words it, naming the address without its
|
|
160
195
|
// query; the address itself goes to the host whole.
|
|
196
|
+
// A frame's sealed files' address never reaches the host from here (P083): `./` instead.
|
|
161
197
|
const blocked = isRecord(args) ? args.navigationBlocked : undefined;
|
|
162
198
|
if (blocked !== undefined) {
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
199
|
+
if (typeof blocked !== "string" || blocked === "" || blocked.length > MAX_URL) {
|
|
200
|
+
return null;
|
|
201
|
+
}
|
|
202
|
+
const url = withoutSealedAddresses(blocked);
|
|
203
|
+
return { message: blockedNavigationMessage(url, config), navigationBlocked: url };
|
|
166
204
|
}
|
|
167
205
|
const message = isRecord(args) ? args.message : undefined;
|
|
168
206
|
return typeof message === "string" && message !== ""
|
|
169
|
-
? { message: message.slice(0, 2_000) }
|
|
207
|
+
? { message: withoutSealedAddresses(message).slice(0, 2_000) }
|
|
170
208
|
: null;
|
|
171
209
|
},
|
|
172
210
|
copyText: (args) => {
|
|
@@ -176,6 +214,13 @@ const VALIDATORS: { readonly [N in CapabilityName]: Validator<N> } = {
|
|
|
176
214
|
: null;
|
|
177
215
|
},
|
|
178
216
|
annotate: (args) => parseReport(args),
|
|
217
|
+
// The runtime's own (P088-P090): their shapes and limits, before any gate.
|
|
218
|
+
user: (args) => (args === undefined || isRecord(args) ? {} : null),
|
|
219
|
+
comments: (args) => parseCommentRequest(args),
|
|
220
|
+
artifact: (args, config) => parseArtifactRequest(args, config.limits),
|
|
221
|
+
// Code-typed names only where uploaded code may run (P089, after the review).
|
|
222
|
+
assets: (args, config) => parseAssetRequest(args, config.limits, assetCodeRuns(config)),
|
|
223
|
+
db: (args) => parseDbRequest(args),
|
|
179
224
|
resize: (args) => {
|
|
180
225
|
if (
|
|
181
226
|
!isRecord(args) ||
|
|
@@ -222,10 +267,23 @@ export function onceConsent(consent: Consent): Consent {
|
|
|
222
267
|
};
|
|
223
268
|
}
|
|
224
269
|
|
|
270
|
+
/** What the page declared for one runtime capability, if it declared it. */
|
|
271
|
+
function declaredOf(
|
|
272
|
+
declaration: PageDeclaration | undefined,
|
|
273
|
+
family: RuntimeCapabilityName,
|
|
274
|
+
): DeclaredCapability | undefined {
|
|
275
|
+
const capabilities = declaration?.capabilities as
|
|
276
|
+
| Readonly<Record<string, DeclaredCapability>>
|
|
277
|
+
| undefined;
|
|
278
|
+
return capabilities !== undefined && Object.hasOwn(capabilities, family)
|
|
279
|
+
? capabilities[family]
|
|
280
|
+
: undefined;
|
|
281
|
+
}
|
|
282
|
+
|
|
225
283
|
export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
226
284
|
const { config, display, handlers, onEvent } = options;
|
|
227
285
|
const now = options.now ?? (() => Date.now());
|
|
228
|
-
const calls = new Map<
|
|
286
|
+
const calls = new Map<string, number[]>();
|
|
229
287
|
let declines = 0;
|
|
230
288
|
let muted = false;
|
|
231
289
|
|
|
@@ -244,7 +302,7 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
|
244
302
|
};
|
|
245
303
|
};
|
|
246
304
|
|
|
247
|
-
const withinRate = (capability:
|
|
305
|
+
const withinRate = (capability: string, perMinute: number): boolean => {
|
|
248
306
|
const at = now();
|
|
249
307
|
const recent = (calls.get(capability) ?? []).filter((time) => at - time < 60_000);
|
|
250
308
|
if (recent.length >= perMinute) {
|
|
@@ -256,9 +314,132 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
|
256
314
|
return true;
|
|
257
315
|
};
|
|
258
316
|
|
|
317
|
+
/** The least level a call needs: its method's, and a db batch's writes' or a watch's read's. */
|
|
318
|
+
function levelOf(
|
|
319
|
+
capability: CapabilityName,
|
|
320
|
+
family: RuntimeCapabilityName,
|
|
321
|
+
method: string,
|
|
322
|
+
args: unknown,
|
|
323
|
+
): ViewerLevel | null {
|
|
324
|
+
const declared = declaredOf(options.declaration ?? undefined, family);
|
|
325
|
+
const own = methodLevel(config, family, method, declared);
|
|
326
|
+
if (capability !== "db" || own === null) {
|
|
327
|
+
return own;
|
|
328
|
+
}
|
|
329
|
+
// A batch is each of its writes; a watch is a read (after the review: neither escapes the
|
|
330
|
+
// levels of what it does).
|
|
331
|
+
const request = args as DbRequest;
|
|
332
|
+
const inner =
|
|
333
|
+
request.op === "batch"
|
|
334
|
+
? request.writes.map((write) => write.op)
|
|
335
|
+
: request.op === "watch"
|
|
336
|
+
? [request.path.split("/").length % 2 === 0 ? "get" : "query"]
|
|
337
|
+
: [];
|
|
338
|
+
return inner.reduce<ViewerLevel>(
|
|
339
|
+
(most, op) => higher(most, methodLevel(config, family, op, declared) ?? most),
|
|
340
|
+
own,
|
|
341
|
+
);
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/**
|
|
345
|
+
* Whether this viewer may make this call (P087), and the call as the handler gets it: the
|
|
346
|
+
* call's level (the contract's, the host's, the page's; a batch's writes', a watch's read's),
|
|
347
|
+
* the resources and tools a page's `data` names, and a `db` call's paths (another person's data
|
|
348
|
+
* refused, `me` resolved, the page's rules). Without a viewer: the runtime's own are refused,
|
|
349
|
+
* and under a runtime anything above view; a 0.6 config's functions run as before.
|
|
350
|
+
*/
|
|
351
|
+
function checkAudience<N extends CapabilityName>(
|
|
352
|
+
capability: N,
|
|
353
|
+
family: RuntimeCapabilityName,
|
|
354
|
+
args: CapabilityArgs[N],
|
|
355
|
+
): CapabilityArgs[N] | "undeclared" | "level" {
|
|
356
|
+
const { viewer } = options;
|
|
357
|
+
const declaration = options.declaration ?? undefined;
|
|
358
|
+
const method = methodOf(capability, args);
|
|
359
|
+
if (method === null) {
|
|
360
|
+
return args;
|
|
361
|
+
}
|
|
362
|
+
const needed = levelOf(capability, family, method, args);
|
|
363
|
+
if (viewer === undefined) {
|
|
364
|
+
if (RUNTIME_HOST_FUNCTIONS.includes(capability)) {
|
|
365
|
+
return "level";
|
|
366
|
+
}
|
|
367
|
+
// Under a runtime, a level the host set is never skipped for want of a viewer.
|
|
368
|
+
return config.runtime !== undefined && needed !== null && needed !== "view" ? "level" : args;
|
|
369
|
+
}
|
|
370
|
+
if (needed !== null && !atLeast(viewer.level, needed)) {
|
|
371
|
+
return "level";
|
|
372
|
+
}
|
|
373
|
+
if (family === "data" && declaration !== undefined) {
|
|
374
|
+
const data = declaration.capabilities.data;
|
|
375
|
+
const named =
|
|
376
|
+
capability === "callTool"
|
|
377
|
+
? declaredMatch(data?.tools, (args as CapabilityArgs["callTool"]).name)
|
|
378
|
+
: declaredMatch(data?.resources, (args as CapabilityArgs["readData"]).uri);
|
|
379
|
+
if (!named) {
|
|
380
|
+
return "undeclared";
|
|
381
|
+
}
|
|
382
|
+
}
|
|
383
|
+
if (capability === "db") {
|
|
384
|
+
const rules = declaration?.capabilities.db?.rules;
|
|
385
|
+
const access = dbAccess(args as DbRequest, viewer, rules);
|
|
386
|
+
return access.ok ? (access.request as CapabilityArgs[N]) : "level";
|
|
387
|
+
}
|
|
388
|
+
if (capability === "assets" && (args as CapabilityArgs["assets"]).op === "upload") {
|
|
389
|
+
// What an upload may become (P089): code only an admin added where uploaded code may run.
|
|
390
|
+
const upload = args as CapabilityArgs["assets"] & { readonly op: "upload" };
|
|
391
|
+
return {
|
|
392
|
+
...upload,
|
|
393
|
+
trusted:
|
|
394
|
+
isCodeAsset(upload.name) && assetCodeRuns(config) && atLeast(viewer.level, "admin"),
|
|
395
|
+
} as CapabilityArgs[N];
|
|
396
|
+
}
|
|
397
|
+
return args;
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
/**
|
|
401
|
+
* The cheap checks for the runtime's own, before their arguments are read (after the review: a
|
|
402
|
+
* malformed call costs nothing but its rate): a method by its `op`, a viewer at its level, its
|
|
403
|
+
* host function's rate.
|
|
404
|
+
*/
|
|
405
|
+
function precheck(capability: CapabilityName, raw: unknown): Refusal | null {
|
|
406
|
+
if (!RUNTIME_HOST_FUNCTIONS.includes(capability)) {
|
|
407
|
+
return null;
|
|
408
|
+
}
|
|
409
|
+
const family = familyOf(capability);
|
|
410
|
+
const method = methodOf(capability, raw);
|
|
411
|
+
if (family === null || method === null) {
|
|
412
|
+
return "invalid";
|
|
413
|
+
}
|
|
414
|
+
const viewer = options.viewer;
|
|
415
|
+
const needed = methodLevel(
|
|
416
|
+
config,
|
|
417
|
+
family.name,
|
|
418
|
+
method,
|
|
419
|
+
declaredOf(options.declaration ?? undefined, family.name),
|
|
420
|
+
);
|
|
421
|
+
if (viewer === undefined || (needed !== null && !atLeast(viewer.level, needed))) {
|
|
422
|
+
return "level";
|
|
423
|
+
}
|
|
424
|
+
for (const gate of effectiveGates(config, capability)) {
|
|
425
|
+
if (typeof gate === "object" && !withinRate(capability, gate.rateLimit.perMinute)) {
|
|
426
|
+
return "rate-limited";
|
|
427
|
+
}
|
|
428
|
+
}
|
|
429
|
+
return null;
|
|
430
|
+
}
|
|
431
|
+
|
|
259
432
|
return {
|
|
260
433
|
declared: (capability) => config.capabilities[capability] !== undefined,
|
|
261
434
|
|
|
435
|
+
roster: () =>
|
|
436
|
+
rosterOf(
|
|
437
|
+
config,
|
|
438
|
+
options.declaration === undefined || options.declaration === null
|
|
439
|
+
? []
|
|
440
|
+
: Object.keys(options.declaration.capabilities),
|
|
441
|
+
),
|
|
442
|
+
|
|
262
443
|
async call<N extends CapabilityName>(
|
|
263
444
|
capability: N,
|
|
264
445
|
raw: unknown,
|
|
@@ -268,17 +449,56 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
|
268
449
|
if (config.capabilities[capability] === undefined) {
|
|
269
450
|
return refuse<Result>(capability, "not-declared");
|
|
270
451
|
}
|
|
271
|
-
|
|
272
|
-
|
|
452
|
+
// The page's declaration (P086): a built-in needs none; any other runtime capability only
|
|
453
|
+
// a page that declared it reaches; a page with no declaration, none of the runtime's own.
|
|
454
|
+
const family = familyOf(capability);
|
|
455
|
+
// No declaration, or the host's explicit null for a page from before 0.7 (P086).
|
|
456
|
+
const declaration = options.declaration ?? undefined;
|
|
457
|
+
if (
|
|
458
|
+
family !== null &&
|
|
459
|
+
!runtimeCapability(family.name).builtIn &&
|
|
460
|
+
(declaration === undefined
|
|
461
|
+
? RUNTIME_HOST_FUNCTIONS.includes(capability)
|
|
462
|
+
: !Object.hasOwn(declaration.capabilities, family.name))
|
|
463
|
+
) {
|
|
464
|
+
return refuse<Result>(capability, "undeclared");
|
|
465
|
+
}
|
|
466
|
+
const early = precheck(capability, raw);
|
|
467
|
+
if (early !== null) {
|
|
468
|
+
return refuse<Result>(capability, early);
|
|
469
|
+
}
|
|
470
|
+
const parsed = (VALIDATORS[capability] as Validator<N>)(raw, config);
|
|
471
|
+
if (parsed === null) {
|
|
273
472
|
return refuse<Result>(capability, "invalid");
|
|
274
473
|
}
|
|
275
|
-
|
|
474
|
+
if (parsed === "too_large") {
|
|
475
|
+
return refuse<Result>(capability, "too-large");
|
|
476
|
+
}
|
|
477
|
+
let args: CapabilityArgs[N] = parsed;
|
|
478
|
+
// Who may (P087): the method's level against the viewer's, the page's own narrowing.
|
|
479
|
+
if (family !== null) {
|
|
480
|
+
const audience = checkAudience(capability, family.name, args);
|
|
481
|
+
if (audience === "undeclared" || audience === "level") {
|
|
482
|
+
return refuse<Result>(capability, audience as Refusal);
|
|
483
|
+
}
|
|
484
|
+
args = audience;
|
|
485
|
+
}
|
|
486
|
+
// Its host function's gates, and its method's own (after the review): all apply.
|
|
487
|
+
const gates = callGates(config, capability, args);
|
|
488
|
+
const own = new Set(effectiveGates(config, capability));
|
|
276
489
|
const confirms = gates.includes("confirm");
|
|
277
490
|
if (confirms && muted) {
|
|
278
491
|
return refuse<Result>(capability, "muted");
|
|
279
492
|
}
|
|
493
|
+
const method = family === null ? null : methodOf(capability, args);
|
|
280
494
|
for (const gate of gates) {
|
|
281
|
-
if (typeof gate
|
|
495
|
+
if (typeof gate !== "object") {
|
|
496
|
+
continue;
|
|
497
|
+
}
|
|
498
|
+
// The runtime's own were counted before their arguments were read (`precheck`).
|
|
499
|
+
const counted = own.has(gate) && RUNTIME_HOST_FUNCTIONS.includes(capability);
|
|
500
|
+
const key = own.has(gate) ? capability : `${capability}.${method ?? ""}`;
|
|
501
|
+
if (!counted && !withinRate(key, gate.rateLimit.perMinute)) {
|
|
282
502
|
return refuse<Result>(capability, "rate-limited");
|
|
283
503
|
}
|
|
284
504
|
}
|
|
@@ -371,11 +591,36 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
|
371
591
|
}
|
|
372
592
|
return { ok: true, value: undefined as Result };
|
|
373
593
|
}
|
|
594
|
+
if (capabilitySpec(capability).served === "viewer") {
|
|
595
|
+
// `user` (P087): the viewer the host gave the display, and nothing else.
|
|
596
|
+
const viewer = options.viewer;
|
|
597
|
+
if (viewer === undefined) {
|
|
598
|
+
return refuse<Result>(capability, "level");
|
|
599
|
+
}
|
|
600
|
+
return {
|
|
601
|
+
ok: true,
|
|
602
|
+
value: {
|
|
603
|
+
id: viewer.id ?? null,
|
|
604
|
+
name: viewer.name ?? null,
|
|
605
|
+
level: viewer.level,
|
|
606
|
+
} as Result,
|
|
607
|
+
};
|
|
608
|
+
}
|
|
374
609
|
const handler = (handlers as Record<string, CapabilityHandler<N> | undefined>)[capability];
|
|
375
610
|
if (handler === undefined) {
|
|
376
611
|
return refuse<Result>(capability, "not-declared");
|
|
377
612
|
}
|
|
378
|
-
const
|
|
613
|
+
const family = familyOf(capability);
|
|
614
|
+
const declared =
|
|
615
|
+
family === null ? undefined : declaredOf(options.declaration ?? undefined, family.name);
|
|
616
|
+
const context = {
|
|
617
|
+
displayId: display.id,
|
|
618
|
+
title: display.title,
|
|
619
|
+
capability,
|
|
620
|
+
...(display.instance === undefined ? {} : { instance: display.instance }),
|
|
621
|
+
...(options.viewer === undefined ? {} : { viewer: options.viewer }),
|
|
622
|
+
...(declared === undefined ? {} : { declared }),
|
|
623
|
+
};
|
|
379
624
|
// A read the content subscribes to may be answered from the host's cache, marked stale; the
|
|
380
625
|
// fresh one follows as an update (the adapter asks for it). A cache that fails is no answer.
|
|
381
626
|
if (capability === "readData" && callOptions?.stale === true && options.cached) {
|
|
@@ -389,14 +634,33 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
|
389
634
|
}
|
|
390
635
|
}
|
|
391
636
|
const subscription = callOptions?.subscription;
|
|
392
|
-
|
|
637
|
+
// A subscription (`subscribeData`, a `db` watch) needs its channel back.
|
|
638
|
+
const watches =
|
|
639
|
+
capability === "subscribeData" ||
|
|
640
|
+
(capability === "db" && (args as CapabilityArgs["db"]).op === "watch");
|
|
641
|
+
if (watches && subscription === undefined) {
|
|
393
642
|
return refuse<Result>(capability, "invalid");
|
|
394
643
|
}
|
|
644
|
+
// A db answer names the viewer's own tree `me`, never their id (after the review, P088).
|
|
645
|
+
const viewer = options.viewer;
|
|
646
|
+
const channel =
|
|
647
|
+
watches && subscription !== undefined && capability === "db"
|
|
648
|
+
? {
|
|
649
|
+
changed: (state?: unknown) => subscription.changed(withMe(state, viewer)),
|
|
650
|
+
signal: subscription.signal,
|
|
651
|
+
}
|
|
652
|
+
: subscription;
|
|
395
653
|
try {
|
|
396
|
-
const
|
|
654
|
+
const answered = await (handler as (args: unknown, context: unknown) => unknown)(
|
|
397
655
|
args,
|
|
398
|
-
|
|
656
|
+
watches ? { ...context, ...channel } : context,
|
|
399
657
|
);
|
|
658
|
+
const value = capability === "db" ? withMe(answered, viewer) : answered;
|
|
659
|
+
// Comments are write-only (P090): content hears whether the composer opened, never what
|
|
660
|
+
// the host answered beyond that (a thread, its text).
|
|
661
|
+
if (capability === "comments") {
|
|
662
|
+
return { ok: true, value: (value === true) as Result };
|
|
663
|
+
}
|
|
400
664
|
return { ok: true, value: value as Result };
|
|
401
665
|
} catch (error) {
|
|
402
666
|
// A host's Refused tells content its reason (P080); any other error stays the host's.
|
package/src/bridge/navigation.ts
CHANGED
|
@@ -7,8 +7,20 @@ import type { PortholeConfig } from "../config/schema.ts";
|
|
|
7
7
|
* its query or fragment, where a viewer's data would be.
|
|
8
8
|
*/
|
|
9
9
|
|
|
10
|
+
/**
|
|
11
|
+
* A frame's sealed files' address (P083) is its access: whatever content says, the host is told
|
|
12
|
+
* it as `./`, the page's own files (the shell says it so already; content may not).
|
|
13
|
+
*/
|
|
14
|
+
const SEALED = /(?:https?:\/\/[^\s"'<>/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//gu;
|
|
15
|
+
export const withoutSealedAddresses = (text: string): string => text.replace(SEALED, "./");
|
|
16
|
+
|
|
10
17
|
/** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
|
|
11
18
|
export function addressWithoutQuery(url: string): string {
|
|
19
|
+
// A page's own file (P084), as the shell names it: its path, without query or fragment.
|
|
20
|
+
if (url.startsWith("./")) {
|
|
21
|
+
const path = url.split(/[?#]/u)[0] ?? "./";
|
|
22
|
+
return path === url ? path : `${path}?…`;
|
|
23
|
+
}
|
|
12
24
|
let parsed: URL;
|
|
13
25
|
try {
|
|
14
26
|
parsed = new URL(url);
|
package/src/bridge/refusal.ts
CHANGED
|
@@ -12,6 +12,10 @@ import type { Refusal } from "./types.ts";
|
|
|
12
12
|
* - `not_allowed`: the host doesn't let this content have it, here or at all (a URI it doesn't
|
|
13
13
|
* serve, a page where data never runs).
|
|
14
14
|
* - `failed`: the host tried and couldn't.
|
|
15
|
+
* - `forbidden` (P087): the person viewing it may see the content but not do this (their level).
|
|
16
|
+
* - `conflict` (P088): what it changes moved since it was read (a document's version, the
|
|
17
|
+
* artifact's base): read it again, then write.
|
|
18
|
+
* - `too_large` (P088): more than a limit (a document, a batch, an upload, a publish).
|
|
15
19
|
*/
|
|
16
20
|
export const REFUSAL_CODES = [
|
|
17
21
|
"consent_required",
|
|
@@ -19,6 +23,9 @@ export const REFUSAL_CODES = [
|
|
|
19
23
|
"rate_limited",
|
|
20
24
|
"not_allowed",
|
|
21
25
|
"failed",
|
|
26
|
+
"forbidden",
|
|
27
|
+
"conflict",
|
|
28
|
+
"too_large",
|
|
22
29
|
] as const;
|
|
23
30
|
|
|
24
31
|
export type RefusalCode = (typeof REFUSAL_CODES)[number];
|
|
@@ -89,6 +96,9 @@ const DEFAULT_MESSAGES: { readonly [Code in RefusalCode]: string } = {
|
|
|
89
96
|
rate_limited: "Too many requests: try again in a minute.",
|
|
90
97
|
not_allowed: "This isn't available here.",
|
|
91
98
|
failed: "The app couldn't do this.",
|
|
99
|
+
forbidden: "You don't have permission to do this here.",
|
|
100
|
+
conflict: "This changed since it was read: read it again, then try again.",
|
|
101
|
+
too_large: "This is too large.",
|
|
92
102
|
};
|
|
93
103
|
|
|
94
104
|
/** Where a data capability's words differ: they name the data. */
|
|
@@ -98,6 +108,9 @@ const DATA_MESSAGES: { readonly [Code in RefusalCode]: string } = {
|
|
|
98
108
|
rate_limited: "Too many data requests: try again in a minute.",
|
|
99
109
|
not_allowed: "This data isn't available here.",
|
|
100
110
|
failed: "The app couldn't get this data.",
|
|
111
|
+
forbidden: "You don't have permission to read this data.",
|
|
112
|
+
conflict: DEFAULT_MESSAGES.conflict,
|
|
113
|
+
too_large: DEFAULT_MESSAGES.too_large,
|
|
101
114
|
};
|
|
102
115
|
|
|
103
116
|
/** Each refusal's code, as content is told it. */
|
|
@@ -113,6 +126,9 @@ const CODES: { readonly [R in Refusal]: RefusalCode } = {
|
|
|
113
126
|
denied: "denied",
|
|
114
127
|
"rate-limited": "rate_limited",
|
|
115
128
|
failed: "failed",
|
|
129
|
+
undeclared: "not_allowed",
|
|
130
|
+
level: "forbidden",
|
|
131
|
+
"too-large": "too_large",
|
|
116
132
|
};
|
|
117
133
|
|
|
118
134
|
/** Refusals whose own words say more than their code's. */
|