@botiverse/porthole 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -2
- package/THIRD_PARTY_NOTICES.md +421 -0
- package/dist/bridge/bounded-text.d.ts +34 -0
- package/dist/bridge/bounded-text.js +188 -0
- package/dist/bridge/bridge.d.ts +38 -5
- package/dist/bridge/bridge.js +469 -39
- package/dist/bridge/json-data.d.ts +28 -0
- package/dist/bridge/json-data.js +86 -0
- package/dist/bridge/navigation.d.ts +5 -0
- package/dist/bridge/navigation.js +7 -0
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +17 -0
- package/dist/bridge/types.d.ts +73 -5
- package/dist/check/check.d.ts +7 -0
- package/dist/check/check.js +1 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +4 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +16 -0
- package/dist/check/tools.js +2 -3
- package/dist/compile/compile.d.ts +6 -0
- package/dist/compile/compile.js +3 -1
- package/dist/compile/policy.d.ts +55 -0
- package/dist/compile/policy.js +157 -0
- package/dist/config/capabilities.d.ts +85 -7
- package/dist/config/capabilities.js +32 -2
- package/dist/config/schema.d.ts +35 -0
- package/dist/config/validate.d.ts +9 -3
- package/dist/config/validate.js +92 -8
- package/dist/config/warnings.d.ts +20 -0
- package/dist/config/warnings.js +25 -0
- package/dist/conformance/behavior.js +46 -1
- package/dist/conformance/cookies.d.ts +15 -0
- package/dist/conformance/cookies.js +80 -0
- package/dist/conformance/harness/page.d.ts +1 -0
- package/dist/conformance/harness/page.js +9 -2
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +5 -1
- package/dist/conformance/index.d.ts +11 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/limits.js +38 -1
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +324 -0
- package/dist/conformance/served.d.ts +2 -0
- package/dist/conformance/served.js +737 -4
- package/dist/files/paths.js +4 -0
- package/dist/guide/gates.d.ts +9 -0
- package/dist/guide/gates.js +31 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +35 -33
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +210 -0
- package/dist/host/create-host.js +73 -37
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/pages-of-set.d.ts +43 -0
- package/dist/host/pages-of-set.js +196 -0
- package/dist/host/types.d.ts +26 -1
- package/dist/index.d.ts +11 -4
- package/dist/index.js +11 -2
- package/dist/isolation/types.d.ts +8 -0
- package/dist/mcp/adapter.js +11 -15
- package/dist/node/index.d.ts +36 -4
- package/dist/node/index.js +402 -101
- package/dist/presets/presets.d.ts +22 -8
- package/dist/presets/presets.js +40 -8
- package/dist/protocol/live-data.d.ts +6 -2
- package/dist/protocol/live-data.js +20 -1
- package/dist/protocol/mcp-apps.d.ts +13 -2
- package/dist/protocol/mcp-apps.js +10 -2
- package/dist/protocol/message-text.d.ts +8 -0
- package/dist/protocol/message-text.js +29 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +116 -0
- package/dist/protocol/shell-adapter.js +64 -25
- package/dist/react/context-notice.d.ts +32 -0
- package/dist/react/context-notice.js +28 -0
- package/dist/react/dialog.js +91 -16
- package/dist/react/frame.d.ts +25 -1
- package/dist/react/frame.js +85 -2
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +2 -1
- package/dist/runtime/contract.d.ts +201 -0
- package/dist/runtime/contract.js +245 -0
- package/dist/runtime/db.d.ts +188 -0
- package/dist/runtime/db.js +502 -0
- package/dist/runtime/declaration.d.ts +100 -0
- package/dist/runtime/declaration.js +363 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +215 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +19 -1
- package/dist/server/files.js +115 -6
- package/dist/server/host.d.ts +24 -2
- package/dist/server/host.js +137 -2
- package/dist/server/index.d.ts +3 -2
- package/dist/server/index.js +2 -1
- package/dist/server/peer.d.ts +4 -0
- package/dist/server/peer.js +19 -0
- package/dist/server/proxy.d.ts +6 -0
- package/dist/server/proxy.js +12 -3
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +318 -52
- package/dist/server/types.d.ts +74 -2
- package/dist/shell/document.d.ts +16 -0
- package/dist/shell/document.js +19 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.js +390 -56
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +205 -15
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +1867 -11
- package/docs/DESIGN.md +137 -17
- package/docs/THREAT_MODEL.md +616 -0
- package/package.json +16 -3
- package/src/bridge/bounded-text.ts +240 -0
- package/src/bridge/bridge.ts +601 -51
- package/src/bridge/json-data.ts +95 -0
- package/src/bridge/navigation.ts +10 -0
- package/src/bridge/refusal.ts +17 -0
- package/src/bridge/types.ts +76 -5
- package/src/check/check.ts +8 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +4 -2
- package/src/check/page.ts +16 -0
- package/src/check/tools.ts +2 -3
- package/src/compile/compile.ts +9 -1
- package/src/compile/policy.ts +177 -0
- package/src/config/capabilities.ts +71 -5
- package/src/config/schema.ts +35 -0
- package/src/config/validate.ts +141 -8
- package/src/config/warnings.ts +42 -0
- package/src/conformance/behavior.ts +54 -1
- package/src/conformance/cookies.ts +93 -0
- package/src/conformance/harness/page.ts +11 -2
- package/src/conformance/host-kit.ts +10 -1
- package/src/conformance/index.ts +17 -0
- package/src/conformance/limits.ts +39 -1
- package/src/conformance/runtime.ts +594 -0
- package/src/conformance/served.ts +888 -4
- package/src/files/paths.ts +4 -0
- package/src/guide/gates.ts +37 -0
- package/src/guide/guide.ts +61 -55
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +253 -0
- package/src/host/create-host.ts +88 -36
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/pages-of-set.ts +226 -0
- package/src/host/types.ts +33 -1
- package/src/index.ts +94 -0
- package/src/isolation/types.ts +8 -0
- package/src/mcp/adapter.ts +16 -20
- package/src/node/index.ts +507 -116
- package/src/presets/presets.ts +67 -17
- package/src/protocol/live-data.ts +31 -3
- package/src/protocol/mcp-apps.ts +11 -2
- package/src/protocol/message-text.ts +36 -0
- package/src/protocol/runtime-calls.ts +141 -0
- package/src/protocol/shell-adapter.ts +79 -26
- package/src/react/context-notice.tsx +95 -0
- package/src/react/dialog.tsx +108 -15
- package/src/react/frame.tsx +120 -0
- package/src/react/index.ts +8 -1
- package/src/runtime/contract.ts +339 -0
- package/src/runtime/db.ts +650 -0
- package/src/runtime/declaration.ts +516 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +355 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +138 -7
- package/src/server/host.ts +170 -3
- package/src/server/index.ts +4 -0
- package/src/server/peer.ts +21 -0
- package/src/server/proxy.ts +13 -3
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +370 -57
- package/src/server/types.ts +73 -2
- package/src/shell/document.ts +29 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +390 -56
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +27 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
This describes the layers, their contracts, the flows and trust boundaries, and
|
|
4
4
|
the extension points. It is meant to stay stable while concrete APIs change; the
|
|
5
|
-
phase-1 API lives in [DESIGN.md](DESIGN.md).
|
|
5
|
+
phase-1 API lives in [DESIGN.md](DESIGN.md). What the boundaries protect, from whom,
|
|
6
|
+
and what each use guarantees and leaves to the host is in
|
|
7
|
+
[THREAT_MODEL.md](THREAT_MODEL.md).
|
|
6
8
|
|
|
7
9
|
## The core abstraction
|
|
8
10
|
|
|
@@ -12,10 +14,19 @@ Porthole renders **agent-drawn HTML plus a declared set of host functions.**
|
|
|
12
14
|
- A **host function (capability)** is any power beyond drawing: send a prompt to
|
|
13
15
|
the agent, open a link, read or write state, call a tool, read data, report an
|
|
14
16
|
error. Each is named in the config and carries three facts: its **gate** (needs
|
|
15
|
-
a user gesture, needs a person's confirmation, is
|
|
17
|
+
a user gesture, needs a person's confirmation, is shown to the person first, is
|
|
18
|
+
rate-limited), its **egress
|
|
16
19
|
needs** (origins it must reach), and its **guide entry** (how the manual
|
|
17
20
|
describes it).
|
|
18
21
|
|
|
22
|
+
A page published as an artifact may be an app: under the **capability runtime**, an optional
|
|
23
|
+
layer over the display (THREAT_MODEL.md says what each guarantees), it reaches its
|
|
24
|
+
host through one global, `porthole.use(name)`, for the capabilities it declared and its viewer's
|
|
25
|
+
level allows. The runtime is how content reaches host functions, not new ones: each of its
|
|
26
|
+
methods is served by a host function the config declares, and the bridge alone decides each call
|
|
27
|
+
(the page's declaration, the viewer's level, the gates). The services behind them (a document
|
|
28
|
+
store, an asset library, versions, comments) are the host's.
|
|
29
|
+
|
|
19
30
|
One capability list therefore drives three artifacts: the **bridge** (which
|
|
20
31
|
functions the shell wires and the host handles), the **CSP** (what the sandbox
|
|
21
32
|
may reach), and the **manual** (what the agent is told). This is why the config
|
|
@@ -206,6 +217,9 @@ only the declared content origins.
|
|
|
206
217
|
|
|
207
218
|
## Trust boundaries
|
|
208
219
|
|
|
220
|
+
The attackers each boundary faces, what is out of scope, and the composition rule for
|
|
221
|
+
several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
|
|
222
|
+
|
|
209
223
|
1. **Host ↔ content.** The hard boundary. The content runs on an origin that is
|
|
210
224
|
never the host's, so same-origin policy denies it the host's DOM, storage,
|
|
211
225
|
cookies and credentials. Everything it wants beyond drawing crosses the bridge
|
|
@@ -216,7 +230,8 @@ only the declared content origins.
|
|
|
216
230
|
|
|
217
231
|
2. **Content ↔ the outside network.** Closed by default and opened only to the
|
|
218
232
|
origins the config's capabilities declare (and, for a served page with files,
|
|
219
|
-
its own version's path on its own origin
|
|
233
|
+
its own version's path on its own origin, and its artifact's asset library at `/_blob/`: the
|
|
234
|
+
host's own server, P082, P089). Two
|
|
220
235
|
kinds of attacker matter:
|
|
221
236
|
- *Attacking the host* (steal credentials, read other data, escape the
|
|
222
237
|
sandbox): stopped by origin isolation — the content is a stranger to the
|
|
@@ -228,20 +243,30 @@ only the declared content origins.
|
|
|
228
243
|
realm) reach the network outside a frame's own `connect-src`. These are
|
|
229
244
|
closed by in-shell defenses and by the embedding page's own policy, each
|
|
230
245
|
proven by a leak-suite probe (DESIGN.md lists them).
|
|
246
|
+
- *A served page outside its frame* (a public link, a new tab) has no frame's sandbox and no
|
|
247
|
+
embedding page: its own CSP header carries the frame's sandbox tokens, and the shell closes
|
|
248
|
+
`window.open` and stops it navigating away (P099).
|
|
231
249
|
- *An opaque frame is as closed as its page.* A `srcdoc` frame inherits the
|
|
232
250
|
embedding page's whole policy as well as its own, so on a page with
|
|
233
251
|
`default-src 'none'` and a tight `connect-src`/`img-src` its content is more
|
|
234
252
|
closed than its config says: an origin the config opens stays shut. On such
|
|
235
253
|
a page prefer domain mode, whose frames inherit nothing (P058).
|
|
236
254
|
|
|
237
|
-
3. **
|
|
255
|
+
3. **Host's decision ↔ what a page may do.** Under the capability runtime a page reaches only the
|
|
256
|
+
built-ins and what it declared at publish (stored by the host, given to the mount), and each
|
|
257
|
+
method only for viewers at its level (`view < interact < admin < owner`), which the host's
|
|
258
|
+
access says. The bridge refuses before any handler; the host's own API checks again, since it
|
|
259
|
+
is its data's wall. A person's per-user data is reached by the host's id for them, never the
|
|
260
|
+
content's word.
|
|
261
|
+
|
|
262
|
+
4. **Message boundary.** Every message crossing the frame is validated against a
|
|
238
263
|
schema and checked for sender identity before use; the shell accepts messages
|
|
239
264
|
only from its host, and the host only from its frame. What the frame says about
|
|
240
265
|
itself (its size, its errors, an annotation's anchor and where it is) is the
|
|
241
266
|
content's word even when the shell says it, since they share a realm: the host
|
|
242
267
|
bounds it and uses it as a UI hint, never as a permission (P053).
|
|
243
268
|
|
|
244
|
-
|
|
269
|
+
5. **Host's decision ↔ content domain.** Authentication and authorization
|
|
245
270
|
*policy* are the host's; carrying the host's decision safely onto the content
|
|
246
271
|
domain is Porthole's *mechanism*. The host decides who may open an instance
|
|
247
272
|
before it calls `issue` (a viewer it knows, or a public link), and may decide
|
|
@@ -262,6 +287,10 @@ only the declared content origins.
|
|
|
262
287
|
names are the default vocabulary.
|
|
263
288
|
- **The person's clipboard** is the host's alone: content asks for a copy
|
|
264
289
|
(`copyText`), the host performs it and shows what it copied (P051, P052).
|
|
290
|
+
- **The capability runtime** (`config.runtime`): a contract version's capabilities, each a
|
|
291
|
+
namespace of methods over host functions, with a versioned `.d.ts`; a host offers them through
|
|
292
|
+
its config and serves them through its handlers; an artifact's asset library is served by
|
|
293
|
+
`/server` from the host's store at `/_blob/<id>` on the artifact's origin.
|
|
265
294
|
- **Annotations** (`annotate`): the host drives a select mode and marks anchors in
|
|
266
295
|
the shell; anchors are W3C Web Annotation selectors a host stores with its own
|
|
267
296
|
comments (P053).
|