@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/dist/check/page.js
CHANGED
|
@@ -22,6 +22,16 @@ const DECLINED = {
|
|
|
22
22
|
subscribeData: () => {
|
|
23
23
|
throw new Error("The host declined the subscription");
|
|
24
24
|
},
|
|
25
|
+
comments: () => false,
|
|
26
|
+
artifact: () => {
|
|
27
|
+
throw new Error("The host declined the artifact call");
|
|
28
|
+
},
|
|
29
|
+
assets: () => {
|
|
30
|
+
throw new Error("The host declined the asset call");
|
|
31
|
+
},
|
|
32
|
+
db: () => {
|
|
33
|
+
throw new Error("The host declined the db call");
|
|
34
|
+
},
|
|
25
35
|
};
|
|
26
36
|
/**
|
|
27
37
|
* The web platform, with no person on the page: no call comes from a click (P078). The driver's
|
|
@@ -116,6 +126,8 @@ const check = {
|
|
|
116
126
|
confirm: () => Promise.resolve("declined"),
|
|
117
127
|
// A viewer who doesn't allow a live widget their data (P079): its calls are refused.
|
|
118
128
|
consent: () => false,
|
|
129
|
+
// Model context goes to a surface nobody reads here (P100): the check has no person.
|
|
130
|
+
show: () => { },
|
|
119
131
|
// A served config's instance, issued by the check's own server on this page's origin.
|
|
120
132
|
locator: {
|
|
121
133
|
locate: async (instance) => (await (await fetch("/issue", { method: "POST", body: JSON.stringify({ instance }) })).json()),
|
|
@@ -125,6 +137,10 @@ const check = {
|
|
|
125
137
|
title: "Check",
|
|
126
138
|
scheme: spec.scheme,
|
|
127
139
|
...(spec.instance === undefined ? {} : { instance: spec.instance }),
|
|
140
|
+
// Under a runtime: the page's declaration (none by default), a viewer who only views.
|
|
141
|
+
...(spec.config.runtime === undefined
|
|
142
|
+
? {}
|
|
143
|
+
: { declaration: spec.declaration ?? null, viewer: { level: "view" } }),
|
|
128
144
|
});
|
|
129
145
|
const run = {
|
|
130
146
|
display,
|
package/dist/check/tools.js
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { generateGuide, generateToolDescription } from "../guide/guide.js";
|
|
1
|
+
import { builtInTopics, generateGuide, generateToolDescription } from "../guide/guide.js";
|
|
3
2
|
import { fragmentOf, lintContent } from "./lint.js";
|
|
4
3
|
import { lintFiles, whereOf } from "./files.js";
|
|
5
4
|
const noun = (config) => config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
|
|
@@ -9,7 +8,7 @@ const showName = (config) => config.guide.toolName ?? `show_${noun(config)}`;
|
|
|
9
8
|
const guideName = (config) => config.guide.guideToolName ?? `${noun(config)}_guide`;
|
|
10
9
|
/** The topics the manual has: the built-in ones and the config's own. */
|
|
11
10
|
export function guideTopics(config) {
|
|
12
|
-
return [...
|
|
11
|
+
return [...builtInTopics(config), ...Object.keys(config.guide.topics ?? {})];
|
|
13
12
|
}
|
|
14
13
|
/** The tool that shows content: `{ title, html }`. */
|
|
15
14
|
export function showTool(config, options = {}) {
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import type { ConfigWarning } from "../config/warnings.ts";
|
|
2
3
|
import { type GuideTopic } from "../guide/guide.ts";
|
|
3
4
|
import { type ShellDocumentOptions } from "../shell/document.ts";
|
|
4
5
|
import { type ShellPlan } from "../shell/plan.ts";
|
|
@@ -10,6 +11,11 @@ import { type CspDirective } from "./policy.ts";
|
|
|
10
11
|
*/
|
|
11
12
|
export interface CompiledConfig {
|
|
12
13
|
readonly config: PortholeConfig;
|
|
14
|
+
/**
|
|
15
|
+
* What the config says that its host likely didn't mean (`configWarnings`): log them at startup.
|
|
16
|
+
* Empty for a config without any.
|
|
17
|
+
*/
|
|
18
|
+
readonly warnings: readonly ConfigWarning[];
|
|
13
19
|
/** The frame's CSP, directive by directive; empty in url mode (the app sends its own). */
|
|
14
20
|
readonly cspDirectives: readonly CspDirective[];
|
|
15
21
|
/** The frame's CSP: in the shell's `<meta>`, or a served document's header. */
|
package/dist/compile/compile.js
CHANGED
|
@@ -5,12 +5,14 @@ import { shellPlan } from "../shell/plan.js";
|
|
|
5
5
|
import { allowAttribute, embedderFrameSources, frameCspDirectives, sandboxTokens, serializeCsp, } from "./policy.js";
|
|
6
6
|
/** Validates `config` and derives everything from it. Throws a `ConfigError` on a bad config. */
|
|
7
7
|
export function compile(config) {
|
|
8
|
-
|
|
8
|
+
const warnings = [];
|
|
9
|
+
validateConfig(config, { onWarning: (warning) => warnings.push(warning) });
|
|
9
10
|
const cspDirectives = frameCspDirectives(config);
|
|
10
11
|
const csp = serializeCsp(cspDirectives);
|
|
11
12
|
const shell = shellPlan(config);
|
|
12
13
|
return {
|
|
13
14
|
config,
|
|
15
|
+
warnings,
|
|
14
16
|
cspDirectives,
|
|
15
17
|
csp,
|
|
16
18
|
sandbox: sandboxTokens(config).join(" "),
|
package/dist/compile/policy.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type CapabilityName, type Gate } from "../config/capabilities.ts";
|
|
2
2
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
3
|
+
import { assetCodeRuns } from "../runtime/contract.ts";
|
|
3
4
|
/**
|
|
4
5
|
* The frame's policies, derived from the config: its CSP (in the shell's `<meta>` for opaque
|
|
5
6
|
* frames, in headers for served ones), its `sandbox` and `allow` attributes, and the `frame-src`
|
|
@@ -14,6 +15,12 @@ export declare function anyHttps(config: PortholeConfig, kind: EgressKind): bool
|
|
|
14
15
|
export declare function declaredCapabilities(config: PortholeConfig): CapabilityName[];
|
|
15
16
|
/** The gates a declared capability runs under: its own, else the vocabulary's defaults. */
|
|
16
17
|
export declare function effectiveGates(config: PortholeConfig, name: CapabilityName): readonly Gate[];
|
|
18
|
+
/**
|
|
19
|
+
* The gates one call runs under: its host function's, and the own gates of each runtime method it
|
|
20
|
+
* runs (after the review: `artifact.publish`, `assets.delete`, an upload whose code may run; P094:
|
|
21
|
+
* a db batch's writes' and a watch's read's too, `methodsOfCall`), every one applying.
|
|
22
|
+
*/
|
|
23
|
+
export declare function callGates(config: PortholeConfig, name: CapabilityName, args: unknown): readonly Gate[];
|
|
17
24
|
/** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
|
|
18
25
|
export declare function egressOrigins(config: PortholeConfig, kind: EgressKind): string[];
|
|
19
26
|
/** Every origin content may reach, of any kind. */
|
|
@@ -41,6 +48,19 @@ export declare const FILE_SET_DIRECTIVES: readonly ["script-src", "style-src", "
|
|
|
41
48
|
* `'none'`. Opaque frames have no files, and keep P022's rule whole.
|
|
42
49
|
*/
|
|
43
50
|
export declare function fileSetCspDirectives(directives: readonly CspDirective[], source: string): CspDirective[];
|
|
51
|
+
/**
|
|
52
|
+
* The directives a page opens its artifact's asset library to (P089), at `/_blob/` on its own
|
|
53
|
+
* origin: what loads without running, always; what runs (scripts, styles) only where uploads are
|
|
54
|
+
* the admins' alone, who publish the page's code anyway.
|
|
55
|
+
*/
|
|
56
|
+
export declare const ASSET_DIRECTIVES: readonly ["img-src", "media-src", "font-src", "connect-src"];
|
|
57
|
+
export declare const ASSET_CODE_DIRECTIVES: readonly ["script-src", "style-src"];
|
|
58
|
+
export { assetCodeRuns };
|
|
59
|
+
/**
|
|
60
|
+
* A served page's CSP with its asset library opened (P089), on `origin` (the page's own, exact:
|
|
61
|
+
* never a sibling's): only where the config declares `assets`. Never `'self'`.
|
|
62
|
+
*/
|
|
63
|
+
export declare function assetCspDirectives(config: PortholeConfig, directives: readonly CspDirective[], origin: string): CspDirective[];
|
|
44
64
|
/**
|
|
45
65
|
* The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
|
|
46
66
|
* and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
|
|
@@ -54,6 +74,41 @@ export declare function serializeCsp(directives: readonly CspDirective[]): strin
|
|
|
54
74
|
* isn't). External (url mode): what a running web app needs to work on its own origin.
|
|
55
75
|
*/
|
|
56
76
|
export declare function sandboxTokens(config: PortholeConfig): string[];
|
|
77
|
+
/**
|
|
78
|
+
* The `sandbox` a served document's CSP header carries (P099): the frame's own tokens, so a page
|
|
79
|
+
* opened on a tab of its own (a public link, a new tab, a bookmark, a frame's address opened
|
|
80
|
+
* outside it) holds no power it lacks in its frame: scripts on its own origin, and no popups,
|
|
81
|
+
* forms, downloads, modals, or navigation of another window (its opener's included). In a frame
|
|
82
|
+
* it repeats the frame's attribute, so it changes nothing there; it is sent on every served page,
|
|
83
|
+
* not only on a `Sec-Fetch-Dest: document` request, so a client that sends no fetch metadata is
|
|
84
|
+
* sandboxed too and one address needs no `Vary`. Domain isolation only: url mode serves the app's
|
|
85
|
+
* own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
|
|
86
|
+
*/
|
|
87
|
+
export declare function servedSandboxDirective(config: PortholeConfig): CspDirective | null;
|
|
88
|
+
/** A served page's CSP header: the page's directives, then its sandbox (P099). */
|
|
89
|
+
export declare function servedDocumentCsp(config: PortholeConfig, directives: readonly CspDirective[]): string;
|
|
90
|
+
/**
|
|
91
|
+
* The features a cross-origin frame never has unless its `allow` names them (each one's default
|
|
92
|
+
* allowlist is `'self'`), and a served page denies itself (P099): devices, location, full screen,
|
|
93
|
+
* the clipboard, payments, credentials, sharing, the built-in AI models, WebMCP's `tools`, the
|
|
94
|
+
* local network, autofill. Every such feature Chromium lists for web pages
|
|
95
|
+
* (`test/reference/permissions-policy-features.json`), but client hints, `cross-origin-isolated`
|
|
96
|
+
* and Chromium's sample (`test/permissions-policy.test.ts` says why). Features whose default is
|
|
97
|
+
* `*` (a video's picture-in-picture, gamepads) are left out: a frame has them, so denying them on
|
|
98
|
+
* a tab would change the frame too. An engine that doesn't know a name ignores it.
|
|
99
|
+
*/
|
|
100
|
+
export declare const FRAME_DENIED_FEATURES: readonly ["accelerometer", "ambient-light-sensor", "autofill", "autoplay", "bluetooth", "camera", "captured-surface-control", "clipboard-read", "clipboard-write", "compute-pressure", "deferred-fetch", "device-attributes", "digital-credentials-create", "digital-credentials-get", "display-capture", "encrypted-media", "fullscreen", "geolocation", "gyroscope", "haptics", "hid", "identity-credentials-get", "idle-detection", "keyboard-map", "language-detector", "language-model", "local-fonts", "local-network", "local-network-access", "loopback-network", "magnetometer", "manual-text", "microphone", "midi", "on-device-speech-recognition", "otp-credentials", "payment", "publickey-credentials-create", "publickey-credentials-get", "publickey-credentials-remote-client-data-json", "rewriter", "screen-wake-lock", "serial", "speaker-selection", "summarizer", "tools", "translator", "unbounded-element", "usb", "web-app-installation", "web-share", "webnn", "window-management", "writer", "xr-spatial-tracking"];
|
|
101
|
+
/** The features a frame's `allow` attribute grants (`allowAttribute`): none but url mode's. */
|
|
102
|
+
export declare function delegatedFeatures(config: PortholeConfig): string[];
|
|
103
|
+
/**
|
|
104
|
+
* The `Permissions-Policy` header of a served page (P099): every feature of
|
|
105
|
+
* `FRAME_DENIED_FEATURES` its frame's `allow` doesn't grant, denied (`camera=()`), so a page on
|
|
106
|
+
* a tab of its own (no `allow` there) can't ask for the camera, the microphone, location or full
|
|
107
|
+
* screen under the content origin's name. In a frame it changes nothing: the frame's `allow`
|
|
108
|
+
* grants none of them, and a frame's features are the intersection of the two. Domain isolation
|
|
109
|
+
* only, as `servedSandboxDirective`.
|
|
110
|
+
*/
|
|
111
|
+
export declare function servedPermissionsPolicy(config: PortholeConfig): string | null;
|
|
57
112
|
/**
|
|
58
113
|
* The frame's `allow` attribute (Permissions Policy). No camera, microphone, geolocation,
|
|
59
114
|
* fullscreen or other powerful feature is delegated to the frame, and the clipboard is denied by
|
package/dist/compile/policy.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { CAPABILITIES } from "../config/capabilities.js";
|
|
2
2
|
import { LIBRARY_PATH } from "../libraries/libraries.js";
|
|
3
|
+
import { assetCodeRuns, familyOf, methodGates, methodsOfCall } from "../runtime/contract.js";
|
|
4
|
+
import { ASSET_PATH } from "../runtime/requests.js";
|
|
3
5
|
/** Whether `kind` loads from any https site (`EgressConfig.anyHttps`, P059): passive kinds only. */
|
|
4
6
|
export function anyHttps(config, kind) {
|
|
5
7
|
return (config.egress.anyHttps ?? []).some((each) => each === kind);
|
|
@@ -12,6 +14,26 @@ export function declaredCapabilities(config) {
|
|
|
12
14
|
export function effectiveGates(config, name) {
|
|
13
15
|
return config.capabilities[name]?.gates ?? CAPABILITIES[name].defaultGates;
|
|
14
16
|
}
|
|
17
|
+
/**
|
|
18
|
+
* The gates one call runs under: its host function's, and the own gates of each runtime method it
|
|
19
|
+
* runs (after the review: `artifact.publish`, `assets.delete`, an upload whose code may run; P094:
|
|
20
|
+
* a db batch's writes' and a watch's read's too, `methodsOfCall`), every one applying.
|
|
21
|
+
*/
|
|
22
|
+
export function callGates(config, name, args) {
|
|
23
|
+
const gates = [...effectiveGates(config, name)];
|
|
24
|
+
const family = familyOf(name);
|
|
25
|
+
if (family === null) {
|
|
26
|
+
return gates;
|
|
27
|
+
}
|
|
28
|
+
for (const method of new Set(methodsOfCall(name, args))) {
|
|
29
|
+
for (const gate of methodGates(config, family.name, method)) {
|
|
30
|
+
if (!gates.includes(gate)) {
|
|
31
|
+
gates.push(gate);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
return gates;
|
|
36
|
+
}
|
|
15
37
|
const unique = (values) => [...new Set(values)];
|
|
16
38
|
/** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
|
|
17
39
|
export function egressOrigins(config, kind) {
|
|
@@ -103,6 +125,35 @@ export function fileSetCspDirectives(directives, source) {
|
|
|
103
125
|
return [name, ...kept, source];
|
|
104
126
|
});
|
|
105
127
|
}
|
|
128
|
+
/**
|
|
129
|
+
* The directives a page opens its artifact's asset library to (P089), at `/_blob/` on its own
|
|
130
|
+
* origin: what loads without running, always; what runs (scripts, styles) only where uploads are
|
|
131
|
+
* the admins' alone, who publish the page's code anyway.
|
|
132
|
+
*/
|
|
133
|
+
export const ASSET_DIRECTIVES = ["img-src", "media-src", "font-src", "connect-src"];
|
|
134
|
+
export const ASSET_CODE_DIRECTIVES = ["script-src", "style-src"];
|
|
135
|
+
export { assetCodeRuns };
|
|
136
|
+
/**
|
|
137
|
+
* A served page's CSP with its asset library opened (P089), on `origin` (the page's own, exact:
|
|
138
|
+
* never a sibling's): only where the config declares `assets`. Never `'self'`.
|
|
139
|
+
*/
|
|
140
|
+
export function assetCspDirectives(config, directives, origin) {
|
|
141
|
+
if (config.capabilities.assets === undefined || config.isolation !== "domain") {
|
|
142
|
+
return [...directives];
|
|
143
|
+
}
|
|
144
|
+
const source = `${origin}${ASSET_PATH}`;
|
|
145
|
+
const opened = new Set([
|
|
146
|
+
...ASSET_DIRECTIVES,
|
|
147
|
+
...(assetCodeRuns(config) ? ASSET_CODE_DIRECTIVES : []),
|
|
148
|
+
]);
|
|
149
|
+
return directives.map(([name, ...sources]) => {
|
|
150
|
+
if (!opened.has(name)) {
|
|
151
|
+
return [name, ...sources];
|
|
152
|
+
}
|
|
153
|
+
const kept = sources.filter((each) => each !== "'none'");
|
|
154
|
+
return [name, ...kept, source];
|
|
155
|
+
});
|
|
156
|
+
}
|
|
106
157
|
/**
|
|
107
158
|
* The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
|
|
108
159
|
* and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
|
|
@@ -128,6 +179,112 @@ export function sandboxTokens(config) {
|
|
|
128
179
|
return ["allow-scripts", "allow-same-origin", "allow-forms", ...(config.sandbox ?? [])];
|
|
129
180
|
}
|
|
130
181
|
}
|
|
182
|
+
/**
|
|
183
|
+
* The `sandbox` a served document's CSP header carries (P099): the frame's own tokens, so a page
|
|
184
|
+
* opened on a tab of its own (a public link, a new tab, a bookmark, a frame's address opened
|
|
185
|
+
* outside it) holds no power it lacks in its frame: scripts on its own origin, and no popups,
|
|
186
|
+
* forms, downloads, modals, or navigation of another window (its opener's included). In a frame
|
|
187
|
+
* it repeats the frame's attribute, so it changes nothing there; it is sent on every served page,
|
|
188
|
+
* not only on a `Sec-Fetch-Dest: document` request, so a client that sends no fetch metadata is
|
|
189
|
+
* sandboxed too and one address needs no `Vary`. Domain isolation only: url mode serves the app's
|
|
190
|
+
* own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
|
|
191
|
+
*/
|
|
192
|
+
export function servedSandboxDirective(config) {
|
|
193
|
+
return config.isolation === "domain" ? ["sandbox", ...sandboxTokens(config)] : null;
|
|
194
|
+
}
|
|
195
|
+
/** A served page's CSP header: the page's directives, then its sandbox (P099). */
|
|
196
|
+
export function servedDocumentCsp(config, directives) {
|
|
197
|
+
const sandbox = servedSandboxDirective(config);
|
|
198
|
+
return serializeCsp(sandbox === null ? directives : [...directives, sandbox]);
|
|
199
|
+
}
|
|
200
|
+
/**
|
|
201
|
+
* The features a cross-origin frame never has unless its `allow` names them (each one's default
|
|
202
|
+
* allowlist is `'self'`), and a served page denies itself (P099): devices, location, full screen,
|
|
203
|
+
* the clipboard, payments, credentials, sharing, the built-in AI models, WebMCP's `tools`, the
|
|
204
|
+
* local network, autofill. Every such feature Chromium lists for web pages
|
|
205
|
+
* (`test/reference/permissions-policy-features.json`), but client hints, `cross-origin-isolated`
|
|
206
|
+
* and Chromium's sample (`test/permissions-policy.test.ts` says why). Features whose default is
|
|
207
|
+
* `*` (a video's picture-in-picture, gamepads) are left out: a frame has them, so denying them on
|
|
208
|
+
* a tab would change the frame too. An engine that doesn't know a name ignores it.
|
|
209
|
+
*/
|
|
210
|
+
export const FRAME_DENIED_FEATURES = [
|
|
211
|
+
"accelerometer",
|
|
212
|
+
"ambient-light-sensor",
|
|
213
|
+
"autofill",
|
|
214
|
+
"autoplay",
|
|
215
|
+
"bluetooth",
|
|
216
|
+
"camera",
|
|
217
|
+
"captured-surface-control",
|
|
218
|
+
"clipboard-read",
|
|
219
|
+
"clipboard-write",
|
|
220
|
+
"compute-pressure",
|
|
221
|
+
"deferred-fetch",
|
|
222
|
+
"device-attributes",
|
|
223
|
+
"digital-credentials-create",
|
|
224
|
+
"digital-credentials-get",
|
|
225
|
+
"display-capture",
|
|
226
|
+
"encrypted-media",
|
|
227
|
+
"fullscreen",
|
|
228
|
+
"geolocation",
|
|
229
|
+
"gyroscope",
|
|
230
|
+
"haptics",
|
|
231
|
+
"hid",
|
|
232
|
+
"identity-credentials-get",
|
|
233
|
+
"idle-detection",
|
|
234
|
+
"keyboard-map",
|
|
235
|
+
"language-detector",
|
|
236
|
+
"language-model",
|
|
237
|
+
"local-fonts",
|
|
238
|
+
"local-network",
|
|
239
|
+
"local-network-access",
|
|
240
|
+
"loopback-network",
|
|
241
|
+
"magnetometer",
|
|
242
|
+
"manual-text",
|
|
243
|
+
"microphone",
|
|
244
|
+
"midi",
|
|
245
|
+
"on-device-speech-recognition",
|
|
246
|
+
"otp-credentials",
|
|
247
|
+
"payment",
|
|
248
|
+
"publickey-credentials-create",
|
|
249
|
+
"publickey-credentials-get",
|
|
250
|
+
"publickey-credentials-remote-client-data-json",
|
|
251
|
+
"rewriter",
|
|
252
|
+
"screen-wake-lock",
|
|
253
|
+
"serial",
|
|
254
|
+
"speaker-selection",
|
|
255
|
+
"summarizer",
|
|
256
|
+
"tools",
|
|
257
|
+
"translator",
|
|
258
|
+
"unbounded-element",
|
|
259
|
+
"usb",
|
|
260
|
+
"web-app-installation",
|
|
261
|
+
"web-share",
|
|
262
|
+
"webnn",
|
|
263
|
+
"window-management",
|
|
264
|
+
"writer",
|
|
265
|
+
"xr-spatial-tracking",
|
|
266
|
+
];
|
|
267
|
+
/** The features a frame's `allow` attribute grants (`allowAttribute`): none but url mode's. */
|
|
268
|
+
export function delegatedFeatures(config) {
|
|
269
|
+
return config.mode === "url" ? [...(config.permissions ?? [])] : [];
|
|
270
|
+
}
|
|
271
|
+
/**
|
|
272
|
+
* The `Permissions-Policy` header of a served page (P099): every feature of
|
|
273
|
+
* `FRAME_DENIED_FEATURES` its frame's `allow` doesn't grant, denied (`camera=()`), so a page on
|
|
274
|
+
* a tab of its own (no `allow` there) can't ask for the camera, the microphone, location or full
|
|
275
|
+
* screen under the content origin's name. In a frame it changes nothing: the frame's `allow`
|
|
276
|
+
* grants none of them, and a frame's features are the intersection of the two. Domain isolation
|
|
277
|
+
* only, as `servedSandboxDirective`.
|
|
278
|
+
*/
|
|
279
|
+
export function servedPermissionsPolicy(config) {
|
|
280
|
+
if (config.isolation !== "domain") {
|
|
281
|
+
return null;
|
|
282
|
+
}
|
|
283
|
+
const granted = new Set(delegatedFeatures(config));
|
|
284
|
+
return FRAME_DENIED_FEATURES.filter((feature) => !granted.has(feature))
|
|
285
|
+
.map((feature) => `${feature}=()`)
|
|
286
|
+
.join(", ");
|
|
287
|
+
}
|
|
131
288
|
/**
|
|
132
289
|
* The frame's `allow` attribute (Permissions Policy). No camera, microphone, geolocation,
|
|
133
290
|
* fullscreen or other powerful feature is delegated to the frame, and the clipboard is denied by
|
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
import type { AnnotationReport } from "../annotate/types.ts";
|
|
2
|
+
import type { DbRequest, DbResult } from "../runtime/db.ts";
|
|
3
|
+
import type { ArtifactInfo, ArtifactRequest, AssetInfo, AssetRequest, CommentRequest, PublishedVersion, UserInfo } from "../runtime/requests.ts";
|
|
2
4
|
/**
|
|
3
5
|
* The capability vocabulary (PRINCIPLE 4): every power content has beyond drawing is one of these
|
|
4
6
|
* host functions, named in the config. A capability the config doesn't declare is not wired into
|
|
@@ -8,7 +10,7 @@ import type { AnnotationReport } from "../annotate/types.ts";
|
|
|
8
10
|
* are on by default), and is served either by a handler the host passes or as an event the
|
|
9
11
|
* framework emits.
|
|
10
12
|
*/
|
|
11
|
-
export declare const CAPABILITY_NAMES: readonly ["sendPrompt", "openLink", "downloadFile", "callTool", "readData", "subscribeData", "setModelContext", "reportError", "resize", "copyText", "annotate"];
|
|
13
|
+
export declare const CAPABILITY_NAMES: readonly ["sendPrompt", "openLink", "downloadFile", "callTool", "readData", "subscribeData", "setModelContext", "reportError", "resize", "copyText", "annotate", "user", "comments", "artifact", "assets", "db"];
|
|
12
14
|
export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
13
15
|
/**
|
|
14
16
|
* What must hold before a call reaches the host's handler. A capability's gates all apply.
|
|
@@ -23,8 +25,11 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
|
23
25
|
* call of any of its consent-gated capabilities, whether this content may have them (a viewer
|
|
24
26
|
* allowing a widget to read their data). A no refuses every such call for the display's life;
|
|
25
27
|
* no `consent` function refuses them all (fail closed).
|
|
28
|
+
* - `show` (P100): the host's `show` function puts the call's whole effect in front of the person,
|
|
29
|
+
* outside the frame, before the handler has it; it asks nothing. No `show` function, or one that
|
|
30
|
+
* throws, means the call is refused (fail closed).
|
|
26
31
|
*/
|
|
27
|
-
export type Gate = "user-activation" | "confirm" | "consent" | {
|
|
32
|
+
export type Gate = "user-activation" | "confirm" | "consent" | "show" | {
|
|
28
33
|
readonly rateLimit: {
|
|
29
34
|
readonly perMinute: number;
|
|
30
35
|
};
|
|
@@ -32,8 +37,11 @@ export type Gate = "user-activation" | "confirm" | "consent" | {
|
|
|
32
37
|
export interface CapabilitySpec {
|
|
33
38
|
/** The gates a declared capability gets when its config names none. */
|
|
34
39
|
readonly defaultGates: readonly Gate[];
|
|
35
|
-
/**
|
|
36
|
-
|
|
40
|
+
/**
|
|
41
|
+
* `handler`: the host passes a function that performs it. `event`: the framework emits it.
|
|
42
|
+
* `viewer`: the framework answers it from the viewer the host gave the display (`user`).
|
|
43
|
+
*/
|
|
44
|
+
readonly served: "handler" | "event" | "viewer";
|
|
37
45
|
/** The global the shell defines for it (sugar over the protocol message), if any. */
|
|
38
46
|
readonly global?: string;
|
|
39
47
|
/**
|
|
@@ -48,6 +56,11 @@ export interface CapabilitySpec {
|
|
|
48
56
|
}
|
|
49
57
|
/** The most text one `copyText` call carries. */
|
|
50
58
|
export declare const MAX_COPY_CHARS = 20000;
|
|
59
|
+
/**
|
|
60
|
+
* The most one `setModelContext` update carries (P100): its text blocks' characters and its
|
|
61
|
+
* structured content's JSON, together. What the person is shown is all of it.
|
|
62
|
+
*/
|
|
63
|
+
export declare const MAX_CONTEXT_CHARS = 20000;
|
|
51
64
|
export declare const CAPABILITIES: {
|
|
52
65
|
readonly sendPrompt: {
|
|
53
66
|
readonly defaultGates: readonly ["user-activation", "confirm"];
|
|
@@ -76,7 +89,7 @@ export declare const CAPABILITIES: {
|
|
|
76
89
|
};
|
|
77
90
|
};
|
|
78
91
|
readonly callTool: {
|
|
79
|
-
readonly defaultGates: readonly ["confirm"];
|
|
92
|
+
readonly defaultGates: readonly ["confirm", Gate];
|
|
80
93
|
readonly served: "handler";
|
|
81
94
|
readonly request: {
|
|
82
95
|
readonly method: "tools/call";
|
|
@@ -105,8 +118,12 @@ export declare const CAPABILITIES: {
|
|
|
105
118
|
readonly method: "resources/subscribe";
|
|
106
119
|
};
|
|
107
120
|
};
|
|
121
|
+
/**
|
|
122
|
+
* Text for the model's next turns (P100): the content's own words, which the person never typed.
|
|
123
|
+
* Shown to them first by default (`show`), so nothing reaches the model they couldn't see.
|
|
124
|
+
*/
|
|
108
125
|
readonly setModelContext: {
|
|
109
|
-
readonly defaultGates: readonly [Gate];
|
|
126
|
+
readonly defaultGates: readonly [Gate, "show"];
|
|
110
127
|
readonly served: "handler";
|
|
111
128
|
readonly request: {
|
|
112
129
|
readonly method: "ui/update-model-context";
|
|
@@ -142,6 +159,46 @@ export declare const CAPABILITIES: {
|
|
|
142
159
|
readonly defaultGates: readonly [Gate];
|
|
143
160
|
readonly served: "event";
|
|
144
161
|
};
|
|
162
|
+
/** Who is viewing (P087): answered from the viewer the host gave the display. */
|
|
163
|
+
readonly user: {
|
|
164
|
+
readonly defaultGates: readonly [Gate];
|
|
165
|
+
readonly served: "viewer";
|
|
166
|
+
readonly request: {
|
|
167
|
+
readonly method: "porthole/call";
|
|
168
|
+
};
|
|
169
|
+
};
|
|
170
|
+
/** Opens the host's comment composer at the page's anchor (P090): write-only. */
|
|
171
|
+
readonly comments: {
|
|
172
|
+
readonly defaultGates: readonly ["user-activation", Gate];
|
|
173
|
+
readonly served: "handler";
|
|
174
|
+
readonly request: {
|
|
175
|
+
readonly method: "porthole/call";
|
|
176
|
+
};
|
|
177
|
+
};
|
|
178
|
+
/** This artifact's current version, and a new version of it, base-checked (P088). */
|
|
179
|
+
readonly artifact: {
|
|
180
|
+
readonly defaultGates: readonly [Gate];
|
|
181
|
+
readonly served: "handler";
|
|
182
|
+
readonly request: {
|
|
183
|
+
readonly method: "porthole/call";
|
|
184
|
+
};
|
|
185
|
+
};
|
|
186
|
+
/** The artifact's asset library, served at `/_blob/<id>` (P089). */
|
|
187
|
+
readonly assets: {
|
|
188
|
+
readonly defaultGates: readonly [Gate];
|
|
189
|
+
readonly served: "handler";
|
|
190
|
+
readonly request: {
|
|
191
|
+
readonly method: "porthole/call";
|
|
192
|
+
};
|
|
193
|
+
};
|
|
194
|
+
/** The artifact's shared document store (P088). */
|
|
195
|
+
readonly db: {
|
|
196
|
+
readonly defaultGates: readonly [Gate];
|
|
197
|
+
readonly served: "handler";
|
|
198
|
+
readonly request: {
|
|
199
|
+
readonly method: "porthole/call";
|
|
200
|
+
};
|
|
201
|
+
};
|
|
145
202
|
};
|
|
146
203
|
/** The arguments a call carries, once the adapter has validated them. */
|
|
147
204
|
export interface CapabilityArgs {
|
|
@@ -165,8 +222,15 @@ export interface CapabilityArgs {
|
|
|
165
222
|
readonly subscribeData: {
|
|
166
223
|
readonly uri: string;
|
|
167
224
|
};
|
|
225
|
+
/**
|
|
226
|
+
* Text blocks only (the modality the host offers), each rebuilt as `{ type, text }`; structured
|
|
227
|
+
* content plain JSON (P100). At most `MAX_CONTEXT_CHARS` together.
|
|
228
|
+
*/
|
|
168
229
|
readonly setModelContext: {
|
|
169
|
-
readonly content?: readonly
|
|
230
|
+
readonly content?: readonly {
|
|
231
|
+
readonly type: "text";
|
|
232
|
+
readonly text: string;
|
|
233
|
+
}[];
|
|
170
234
|
readonly structuredContent?: Readonly<Record<string, unknown>>;
|
|
171
235
|
};
|
|
172
236
|
/**
|
|
@@ -186,6 +250,12 @@ export interface CapabilityArgs {
|
|
|
186
250
|
};
|
|
187
251
|
/** What the frame reported, once checked (`AnnotationReport`). */
|
|
188
252
|
readonly annotate: AnnotationReport;
|
|
253
|
+
readonly user: Readonly<Record<string, never>>;
|
|
254
|
+
readonly comments: CommentRequest;
|
|
255
|
+
readonly artifact: ArtifactRequest;
|
|
256
|
+
readonly assets: AssetRequest;
|
|
257
|
+
/** Paths checked, `me` resolved, the viewer's own data only (P088). */
|
|
258
|
+
readonly db: DbRequest;
|
|
189
259
|
}
|
|
190
260
|
/** What a call resolves to. Protocol-shaped results (a tool's result) stay opaque to the core. */
|
|
191
261
|
export interface CapabilityResults {
|
|
@@ -205,6 +275,14 @@ export interface CapabilityResults {
|
|
|
205
275
|
/** Whether the text was copied. */
|
|
206
276
|
readonly copyText: boolean;
|
|
207
277
|
readonly annotate: undefined;
|
|
278
|
+
readonly user: UserInfo;
|
|
279
|
+
/** Whether the composer opened. Never a thread: content doesn't read comments (P090). */
|
|
280
|
+
readonly comments: boolean;
|
|
281
|
+
/** `get`: the current version; `publish`: the new one. */
|
|
282
|
+
readonly artifact: ArtifactInfo | PublishedVersion;
|
|
283
|
+
/** `list`: the library; `upload`: the new asset; `delete`: whether it was removed. */
|
|
284
|
+
readonly assets: AssetInfo | readonly AssetInfo[] | boolean;
|
|
285
|
+
readonly db: DbResult;
|
|
208
286
|
}
|
|
209
287
|
/** The capabilities a host serves with a handler. */
|
|
210
288
|
export type HandledCapability = {
|
|
@@ -19,10 +19,21 @@ export const CAPABILITY_NAMES = [
|
|
|
19
19
|
"resize",
|
|
20
20
|
"copyText",
|
|
21
21
|
"annotate",
|
|
22
|
+
// The capability runtime's own (P085, `config.runtime`): reached through `porthole.use`.
|
|
23
|
+
"user",
|
|
24
|
+
"comments",
|
|
25
|
+
"artifact",
|
|
26
|
+
"assets",
|
|
27
|
+
"db",
|
|
22
28
|
];
|
|
23
29
|
const rate = (perMinute) => ({ rateLimit: { perMinute } });
|
|
24
30
|
/** The most text one `copyText` call carries. */
|
|
25
31
|
export const MAX_COPY_CHARS = 20_000;
|
|
32
|
+
/**
|
|
33
|
+
* The most one `setModelContext` update carries (P100): its text blocks' characters and its
|
|
34
|
+
* structured content's JSON, together. What the person is shown is all of it.
|
|
35
|
+
*/
|
|
36
|
+
export const MAX_CONTEXT_CHARS = 20_000;
|
|
26
37
|
export const CAPABILITIES = {
|
|
27
38
|
sendPrompt: {
|
|
28
39
|
defaultGates: ["user-activation", "confirm"],
|
|
@@ -42,7 +53,8 @@ export const CAPABILITIES = {
|
|
|
42
53
|
request: { method: "ui/download-file", sdk: "app.downloadFile" },
|
|
43
54
|
},
|
|
44
55
|
callTool: {
|
|
45
|
-
|
|
56
|
+
// A rate as well (P103): it needs no gesture, and a host's `confirm` may say yes by itself.
|
|
57
|
+
defaultGates: ["confirm", rate(30)],
|
|
46
58
|
served: "handler",
|
|
47
59
|
request: { method: "tools/call", sdk: "app.callServerTool" },
|
|
48
60
|
},
|
|
@@ -63,8 +75,12 @@ export const CAPABILITIES = {
|
|
|
63
75
|
global: "subscribeData",
|
|
64
76
|
request: { method: "resources/subscribe" },
|
|
65
77
|
},
|
|
78
|
+
/**
|
|
79
|
+
* Text for the model's next turns (P100): the content's own words, which the person never typed.
|
|
80
|
+
* Shown to them first by default (`show`), so nothing reaches the model they couldn't see.
|
|
81
|
+
*/
|
|
66
82
|
setModelContext: {
|
|
67
|
-
defaultGates: [rate(30)],
|
|
83
|
+
defaultGates: [rate(30), "show"],
|
|
68
84
|
served: "handler",
|
|
69
85
|
request: { method: "ui/update-model-context", sdk: "app.updateModelContext" },
|
|
70
86
|
},
|
|
@@ -86,6 +102,20 @@ export const CAPABILITIES = {
|
|
|
86
102
|
* (it shares the realm): UI hints for the host, never permissions.
|
|
87
103
|
*/
|
|
88
104
|
annotate: { defaultGates: [rate(120)], served: "event" },
|
|
105
|
+
/** Who is viewing (P087): answered from the viewer the host gave the display. */
|
|
106
|
+
user: { defaultGates: [rate(60)], served: "viewer", request: { method: "porthole/call" } },
|
|
107
|
+
/** Opens the host's comment composer at the page's anchor (P090): write-only. */
|
|
108
|
+
comments: {
|
|
109
|
+
defaultGates: ["user-activation", rate(30)],
|
|
110
|
+
served: "handler",
|
|
111
|
+
request: { method: "porthole/call" },
|
|
112
|
+
},
|
|
113
|
+
/** This artifact's current version, and a new version of it, base-checked (P088). */
|
|
114
|
+
artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
|
|
115
|
+
/** The artifact's asset library, served at `/_blob/<id>` (P089). */
|
|
116
|
+
assets: { defaultGates: [rate(30)], served: "handler", request: { method: "porthole/call" } },
|
|
117
|
+
/** The artifact's shared document store (P088). */
|
|
118
|
+
db: { defaultGates: [rate(600)], served: "handler", request: { method: "porthole/call" } },
|
|
89
119
|
};
|
|
90
120
|
/** A capability's spec, as the general shape (the table above keeps literal types). */
|
|
91
121
|
export function capabilitySpec(name) {
|
package/dist/config/schema.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import type { RuntimeVersion } from "../runtime/contract.ts";
|
|
2
|
+
import type { ViewerLevel } from "../runtime/levels.ts";
|
|
1
3
|
import type { CapabilityName, Gate } from "./capabilities.ts";
|
|
2
4
|
/**
|
|
3
5
|
* One config per kind of display (PRINCIPLE 3). The compiler derives the frame's CSP, its sandbox
|
|
@@ -35,12 +37,37 @@ export type ThemeValue = string | {
|
|
|
35
37
|
export interface CapabilityConfig {
|
|
36
38
|
/** Every gate must pass. Omitted: the capability's default gates. `[]`: ungated. */
|
|
37
39
|
readonly gates?: readonly Gate[];
|
|
40
|
+
/**
|
|
41
|
+
* Says that `gates` leaves out the default `show` on purpose (P100: `setModelContext`): the
|
|
42
|
+
* host's handler shows the person each update itself, or the content is its own. Without it,
|
|
43
|
+
* such gates earn a warning (`configWarnings`); with `show` in the gates, or no gates named, it
|
|
44
|
+
* is an error.
|
|
45
|
+
*/
|
|
46
|
+
readonly withoutShow?: true;
|
|
38
47
|
/** Extra `connect-src` origins this capability needs. */
|
|
39
48
|
readonly connect?: readonly string[];
|
|
40
49
|
/** Extra script/style/img/font/media origins this capability needs. */
|
|
41
50
|
readonly resource?: readonly string[];
|
|
42
51
|
/** Replaces the generated manual entry for this capability. */
|
|
43
52
|
readonly guide?: string;
|
|
53
|
+
/**
|
|
54
|
+
* The least viewer level that may call each of the runtime methods it serves (P087), by method
|
|
55
|
+
* name (`db: { levels: { set: "admin" } }`, `sendPrompt: { levels: { send: "admin" } }`): over
|
|
56
|
+
* the contract's own, never below a method's floor (`RUNTIME_CAPABILITIES`). For
|
|
57
|
+
* `assets.upload`, `admin` or above also lets the page run what was uploaded as scripts and
|
|
58
|
+
* styles (P089); `interact` doesn't.
|
|
59
|
+
*/
|
|
60
|
+
readonly levels?: Readonly<Record<string, ViewerLevel>>;
|
|
61
|
+
/**
|
|
62
|
+
* Gates of each runtime method it serves, by name, in place of the contract's own (after the
|
|
63
|
+
* review: `artifact.publish` and `assets.delete` need a click and a yes; `assets.upload` a yes
|
|
64
|
+
* where uploaded code may run). Every one applies on top of `gates`. `[]`: none of its own.
|
|
65
|
+
* A call that runs other methods runs under theirs too (P094): a db `batch` under each of its
|
|
66
|
+
* writes' (`set`, `update`, `delete`; one confirmation for the whole batch, a rate counting each
|
|
67
|
+
* write), a `watch` under `get`'s (a document) or `query`'s (a collection), checked when it
|
|
68
|
+
* starts: its updates are its answers, so a rate counts once per watch, not per update.
|
|
69
|
+
*/
|
|
70
|
+
readonly methodGates?: Readonly<Record<string, readonly Gate[]>>;
|
|
44
71
|
}
|
|
45
72
|
/** The declared capabilities. Absent: not available, not wired, not in the CSP, not in the manual. */
|
|
46
73
|
export type CapabilityMap = {
|
|
@@ -203,6 +230,14 @@ export interface PortholeConfig {
|
|
|
203
230
|
* declares no `reportError`). Absent: the manual says they are reported to the app.
|
|
204
231
|
*/
|
|
205
232
|
readonly errors?: "agent" | "host" | "none";
|
|
233
|
+
/**
|
|
234
|
+
* The capability runtime (P085): content reaches capabilities through one global,
|
|
235
|
+
* `porthole.use(name)`, under this contract version, and the manual teaches it (with declaring
|
|
236
|
+
* them, `capabilities: { name: config }`, for pages that are published). Only with it may the
|
|
237
|
+
* config declare the runtime's own host functions (`user`, `comments`, `artifact`, `assets`,
|
|
238
|
+
* `db`). Absent: 0.6's frames, globals and manual, exactly.
|
|
239
|
+
*/
|
|
240
|
+
readonly runtime?: RuntimeVersion;
|
|
206
241
|
}
|
|
207
242
|
export interface StorageConfig {
|
|
208
243
|
/**
|