@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.
Files changed (167) hide show
  1. package/README.md +41 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +208 -13
  4. package/dist/bridge/navigation.d.ts +1 -6
  5. package/dist/bridge/navigation.js +11 -0
  6. package/dist/bridge/refusal.d.ts +5 -1
  7. package/dist/bridge/refusal.js +16 -0
  8. package/dist/bridge/types.d.ts +41 -4
  9. package/dist/check/check.d.ts +19 -3
  10. package/dist/check/check.js +55 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/instrument.d.ts +3 -0
  14. package/dist/check/lint.js +31 -12
  15. package/dist/check/page-source.js +1 -1
  16. package/dist/check/page.js +14 -0
  17. package/dist/check/tools.d.ts +23 -0
  18. package/dist/check/tools.js +27 -3
  19. package/dist/compile/policy.d.ts +34 -0
  20. package/dist/compile/policy.js +74 -0
  21. package/dist/config/capabilities.d.ts +62 -3
  22. package/dist/config/capabilities.js +20 -0
  23. package/dist/config/schema.d.ts +32 -0
  24. package/dist/config/validate.d.ts +1 -1
  25. package/dist/config/validate.js +74 -5
  26. package/dist/conformance/harness-source.js +1 -1
  27. package/dist/conformance/index.d.ts +1 -0
  28. package/dist/conformance/index.js +2 -0
  29. package/dist/conformance/runtime.d.ts +58 -0
  30. package/dist/conformance/runtime.js +314 -0
  31. package/dist/files/paths.d.ts +99 -0
  32. package/dist/files/paths.js +263 -0
  33. package/dist/files/types.d.ts +24 -0
  34. package/dist/files/types.js +83 -0
  35. package/dist/guide/gates.d.ts +3 -0
  36. package/dist/guide/gates.js +19 -0
  37. package/dist/guide/guide.d.ts +2 -0
  38. package/dist/guide/guide.js +44 -32
  39. package/dist/guide/limits.js +4 -4
  40. package/dist/guide/runtime.d.ts +13 -0
  41. package/dist/guide/runtime.js +202 -0
  42. package/dist/host/create-host.js +45 -0
  43. package/dist/host/locate.js +8 -0
  44. package/dist/host/locator.js +7 -0
  45. package/dist/host/types.d.ts +18 -0
  46. package/dist/index.d.ts +13 -4
  47. package/dist/index.js +16 -3
  48. package/dist/isolation/types.d.ts +8 -0
  49. package/dist/presets/presets.d.ts +6 -0
  50. package/dist/presets/presets.js +1 -0
  51. package/dist/protocol/adapter.d.ts +4 -0
  52. package/dist/protocol/mcp-apps.d.ts +6 -0
  53. package/dist/protocol/mcp-apps.js +6 -0
  54. package/dist/protocol/runtime-calls.d.ts +28 -0
  55. package/dist/protocol/runtime-calls.js +113 -0
  56. package/dist/protocol/shell-adapter.js +52 -3
  57. package/dist/react/dialog.js +31 -0
  58. package/dist/react/frame.d.ts +13 -0
  59. package/dist/react/frame.js +6 -0
  60. package/dist/runtime/contract.d.ts +193 -0
  61. package/dist/runtime/contract.js +216 -0
  62. package/dist/runtime/db.d.ts +153 -0
  63. package/dist/runtime/db.js +398 -0
  64. package/dist/runtime/declaration.d.ts +86 -0
  65. package/dist/runtime/declaration.js +266 -0
  66. package/dist/runtime/levels.d.ts +33 -0
  67. package/dist/runtime/levels.js +41 -0
  68. package/dist/runtime/requests.d.ts +125 -0
  69. package/dist/runtime/requests.js +199 -0
  70. package/dist/runtime/segments.d.ts +8 -0
  71. package/dist/runtime/segments.js +14 -0
  72. package/dist/runtime/types.generated.d.ts +1 -0
  73. package/dist/runtime/types.generated.js +19 -0
  74. package/dist/server/files.d.ts +57 -0
  75. package/dist/server/files.js +338 -0
  76. package/dist/server/host.d.ts +44 -2
  77. package/dist/server/host.js +42 -2
  78. package/dist/server/index.d.ts +5 -2
  79. package/dist/server/index.js +5 -1
  80. package/dist/server/keys.d.ts +8 -0
  81. package/dist/server/keys.js +34 -0
  82. package/dist/server/pseudonym.d.ts +9 -0
  83. package/dist/server/pseudonym.js +20 -0
  84. package/dist/server/server.d.ts +0 -5
  85. package/dist/server/server.js +468 -24
  86. package/dist/server/types.d.ts +118 -5
  87. package/dist/shell/document.d.ts +27 -0
  88. package/dist/shell/document.js +46 -2
  89. package/dist/shell/legacy.d.ts +21 -0
  90. package/dist/shell/legacy.js +63 -0
  91. package/dist/shell/plan.d.ts +17 -1
  92. package/dist/shell/plan.js +13 -2
  93. package/dist/shell/runtime.d.ts +2 -1
  94. package/dist/shell/runtime.js +114 -46
  95. package/dist/shell/use.d.ts +15 -0
  96. package/dist/shell/use.js +235 -0
  97. package/docs/ADOPTING.md +142 -5
  98. package/docs/ARCHITECTURE.md +34 -5
  99. package/docs/DECISIONS.md +716 -7
  100. package/docs/DESIGN.md +97 -3
  101. package/package.json +3 -1
  102. package/src/bridge/bridge.ts +281 -17
  103. package/src/bridge/navigation.ts +12 -0
  104. package/src/bridge/refusal.ts +16 -0
  105. package/src/bridge/types.ts +46 -4
  106. package/src/check/check.ts +100 -14
  107. package/src/check/files.ts +384 -0
  108. package/src/check/instrument.ts +3 -0
  109. package/src/check/lint.ts +33 -12
  110. package/src/check/page.ts +14 -0
  111. package/src/check/tools.ts +52 -3
  112. package/src/compile/policy.ts +92 -0
  113. package/src/config/capabilities.ts +49 -2
  114. package/src/config/schema.ts +32 -0
  115. package/src/config/validate.ts +107 -5
  116. package/src/conformance/index.ts +7 -0
  117. package/src/conformance/runtime.ts +573 -0
  118. package/src/files/paths.ts +323 -0
  119. package/src/files/types.ts +101 -0
  120. package/src/guide/gates.ts +25 -0
  121. package/src/guide/guide.ts +78 -52
  122. package/src/guide/limits.ts +4 -4
  123. package/src/guide/runtime.ts +244 -0
  124. package/src/host/create-host.ts +55 -0
  125. package/src/host/locate.ts +10 -0
  126. package/src/host/locator.ts +11 -0
  127. package/src/host/types.ts +18 -0
  128. package/src/index.ts +121 -0
  129. package/src/isolation/types.ts +8 -0
  130. package/src/presets/presets.ts +7 -0
  131. package/src/protocol/adapter.ts +3 -1
  132. package/src/protocol/mcp-apps.ts +7 -0
  133. package/src/protocol/runtime-calls.ts +138 -0
  134. package/src/protocol/shell-adapter.ts +56 -2
  135. package/src/react/dialog.tsx +33 -0
  136. package/src/react/frame.tsx +19 -0
  137. package/src/runtime/contract.ts +305 -0
  138. package/src/runtime/db.ts +530 -0
  139. package/src/runtime/declaration.ts +378 -0
  140. package/src/runtime/levels.ts +69 -0
  141. package/src/runtime/requests.ts +339 -0
  142. package/src/runtime/segments.ts +17 -0
  143. package/src/runtime/types.generated.ts +19 -0
  144. package/src/server/files.ts +425 -0
  145. package/src/server/host.ts +84 -3
  146. package/src/server/index.ts +22 -0
  147. package/src/server/keys.ts +53 -0
  148. package/src/server/pseudonym.ts +21 -0
  149. package/src/server/server.ts +565 -26
  150. package/src/server/types.ts +124 -4
  151. package/src/shell/document.ts +74 -4
  152. package/src/shell/legacy.ts +64 -0
  153. package/src/shell/plan.ts +37 -3
  154. package/src/shell/runtime.ts +114 -46
  155. package/src/shell/use.ts +235 -0
  156. package/types/runtime/v1/artifact.d.ts +50 -0
  157. package/types/runtime/v1/assets.d.ts +43 -0
  158. package/types/runtime/v1/chat.d.ts +13 -0
  159. package/types/runtime/v1/clipboard.d.ts +14 -0
  160. package/types/runtime/v1/comments.d.ts +24 -0
  161. package/types/runtime/v1/context.d.ts +16 -0
  162. package/types/runtime/v1/data.d.ts +29 -0
  163. package/types/runtime/v1/db.d.ts +110 -0
  164. package/types/runtime/v1/downloads.d.ts +22 -0
  165. package/types/runtime/v1/links.d.ts +13 -0
  166. package/types/runtime/v1/porthole.d.ts +44 -0
  167. 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 page by id and version;
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.5.1",
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
  }
@@ -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
- return typeof blocked === "string" && blocked !== "" && blocked.length <= MAX_URL
164
- ? { message: blockedNavigationMessage(blocked, config), navigationBlocked: blocked }
165
- : null;
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<CapabilityName, number[]>();
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: CapabilityName, perMinute: number): boolean => {
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
- const args = (VALIDATORS[capability] as Validator<N>)(raw, config);
272
- if (args === null) {
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
- const gates = effectiveGates(config, capability);
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 === "object" && !withinRate(capability, gate.rateLimit.perMinute)) {
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 context = { displayId: display.id, title: display.title, capability };
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
- if (capability === "subscribeData" && subscription === undefined) {
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 value = await (handler as (args: unknown, context: unknown) => unknown)(
654
+ const answered = await (handler as (args: unknown, context: unknown) => unknown)(
397
655
  args,
398
- capability === "subscribeData" ? { ...context, ...subscription } : context,
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.
@@ -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);
@@ -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. */