@botiverse/porthole 0.6.0 → 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 (145) hide show
  1. package/README.md +16 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +200 -8
  4. package/dist/bridge/refusal.d.ts +5 -1
  5. package/dist/bridge/refusal.js +16 -0
  6. package/dist/bridge/types.d.ts +41 -4
  7. package/dist/check/check.d.ts +7 -0
  8. package/dist/check/check.js +1 -0
  9. package/dist/check/instrument.d.ts +3 -0
  10. package/dist/check/lint.js +4 -2
  11. package/dist/check/page-source.js +1 -1
  12. package/dist/check/page.js +14 -0
  13. package/dist/check/tools.js +2 -3
  14. package/dist/compile/policy.d.ts +19 -0
  15. package/dist/compile/policy.js +42 -0
  16. package/dist/config/capabilities.d.ts +62 -3
  17. package/dist/config/capabilities.js +20 -0
  18. package/dist/config/schema.d.ts +24 -0
  19. package/dist/config/validate.d.ts +1 -1
  20. package/dist/config/validate.js +66 -4
  21. package/dist/conformance/harness-source.js +1 -1
  22. package/dist/conformance/index.d.ts +1 -0
  23. package/dist/conformance/index.js +2 -0
  24. package/dist/conformance/runtime.d.ts +58 -0
  25. package/dist/conformance/runtime.js +314 -0
  26. package/dist/guide/gates.d.ts +3 -0
  27. package/dist/guide/gates.js +19 -0
  28. package/dist/guide/guide.d.ts +2 -0
  29. package/dist/guide/guide.js +34 -32
  30. package/dist/guide/limits.js +4 -4
  31. package/dist/guide/runtime.d.ts +13 -0
  32. package/dist/guide/runtime.js +202 -0
  33. package/dist/host/create-host.js +24 -0
  34. package/dist/host/locate.js +8 -0
  35. package/dist/host/locator.js +7 -0
  36. package/dist/host/types.d.ts +18 -0
  37. package/dist/index.d.ts +8 -2
  38. package/dist/index.js +9 -1
  39. package/dist/isolation/types.d.ts +8 -0
  40. package/dist/presets/presets.d.ts +6 -0
  41. package/dist/presets/presets.js +1 -0
  42. package/dist/protocol/runtime-calls.d.ts +28 -0
  43. package/dist/protocol/runtime-calls.js +113 -0
  44. package/dist/protocol/shell-adapter.js +48 -3
  45. package/dist/react/dialog.js +31 -0
  46. package/dist/react/frame.d.ts +13 -0
  47. package/dist/react/frame.js +6 -0
  48. package/dist/runtime/contract.d.ts +193 -0
  49. package/dist/runtime/contract.js +216 -0
  50. package/dist/runtime/db.d.ts +153 -0
  51. package/dist/runtime/db.js +398 -0
  52. package/dist/runtime/declaration.d.ts +86 -0
  53. package/dist/runtime/declaration.js +266 -0
  54. package/dist/runtime/levels.d.ts +33 -0
  55. package/dist/runtime/levels.js +41 -0
  56. package/dist/runtime/requests.d.ts +125 -0
  57. package/dist/runtime/requests.js +199 -0
  58. package/dist/runtime/segments.d.ts +8 -0
  59. package/dist/runtime/segments.js +14 -0
  60. package/dist/runtime/types.generated.d.ts +1 -0
  61. package/dist/runtime/types.generated.js +19 -0
  62. package/dist/server/files.d.ts +14 -1
  63. package/dist/server/files.js +97 -3
  64. package/dist/server/host.d.ts +6 -1
  65. package/dist/server/host.js +5 -0
  66. package/dist/server/index.d.ts +2 -1
  67. package/dist/server/index.js +1 -0
  68. package/dist/server/pseudonym.d.ts +9 -0
  69. package/dist/server/pseudonym.js +20 -0
  70. package/dist/server/server.d.ts +0 -5
  71. package/dist/server/server.js +214 -35
  72. package/dist/server/types.d.ts +69 -0
  73. package/dist/shell/document.d.ts +8 -0
  74. package/dist/shell/document.js +16 -2
  75. package/dist/shell/legacy.d.ts +21 -0
  76. package/dist/shell/legacy.js +63 -0
  77. package/dist/shell/plan.d.ts +17 -1
  78. package/dist/shell/plan.js +13 -2
  79. package/dist/shell/runtime.js +29 -42
  80. package/dist/shell/use.d.ts +15 -0
  81. package/dist/shell/use.js +235 -0
  82. package/docs/ADOPTING.md +91 -6
  83. package/docs/ARCHITECTURE.md +22 -3
  84. package/docs/DECISIONS.md +415 -6
  85. package/docs/DESIGN.md +66 -0
  86. package/package.json +3 -1
  87. package/src/bridge/bridge.ts +273 -12
  88. package/src/bridge/refusal.ts +16 -0
  89. package/src/bridge/types.ts +46 -4
  90. package/src/check/check.ts +8 -0
  91. package/src/check/instrument.ts +3 -0
  92. package/src/check/lint.ts +4 -2
  93. package/src/check/page.ts +14 -0
  94. package/src/check/tools.ts +2 -3
  95. package/src/compile/policy.ts +54 -0
  96. package/src/config/capabilities.ts +49 -2
  97. package/src/config/schema.ts +24 -0
  98. package/src/config/validate.ts +99 -4
  99. package/src/conformance/index.ts +7 -0
  100. package/src/conformance/runtime.ts +573 -0
  101. package/src/guide/gates.ts +25 -0
  102. package/src/guide/guide.ts +59 -53
  103. package/src/guide/limits.ts +4 -4
  104. package/src/guide/runtime.ts +244 -0
  105. package/src/host/create-host.ts +34 -0
  106. package/src/host/locate.ts +10 -0
  107. package/src/host/locator.ts +11 -0
  108. package/src/host/types.ts +18 -0
  109. package/src/index.ts +89 -0
  110. package/src/isolation/types.ts +8 -0
  111. package/src/presets/presets.ts +7 -0
  112. package/src/protocol/runtime-calls.ts +138 -0
  113. package/src/protocol/shell-adapter.ts +52 -3
  114. package/src/react/dialog.tsx +33 -0
  115. package/src/react/frame.tsx +19 -0
  116. package/src/runtime/contract.ts +305 -0
  117. package/src/runtime/db.ts +530 -0
  118. package/src/runtime/declaration.ts +378 -0
  119. package/src/runtime/levels.ts +69 -0
  120. package/src/runtime/requests.ts +339 -0
  121. package/src/runtime/segments.ts +17 -0
  122. package/src/runtime/types.generated.ts +19 -0
  123. package/src/server/files.ts +117 -4
  124. package/src/server/host.ts +12 -0
  125. package/src/server/index.ts +3 -0
  126. package/src/server/pseudonym.ts +21 -0
  127. package/src/server/server.ts +247 -37
  128. package/src/server/types.ts +68 -0
  129. package/src/shell/document.ts +21 -4
  130. package/src/shell/legacy.ts +64 -0
  131. package/src/shell/plan.ts +37 -3
  132. package/src/shell/runtime.ts +29 -42
  133. package/src/shell/use.ts +235 -0
  134. package/types/runtime/v1/artifact.d.ts +50 -0
  135. package/types/runtime/v1/assets.d.ts +43 -0
  136. package/types/runtime/v1/chat.d.ts +13 -0
  137. package/types/runtime/v1/clipboard.d.ts +14 -0
  138. package/types/runtime/v1/comments.d.ts +24 -0
  139. package/types/runtime/v1/context.d.ts +16 -0
  140. package/types/runtime/v1/data.d.ts +29 -0
  141. package/types/runtime/v1/db.d.ts +110 -0
  142. package/types/runtime/v1/downloads.d.ts +22 -0
  143. package/types/runtime/v1/links.d.ts +13 -0
  144. package/types/runtime/v1/porthole.d.ts +44 -0
  145. package/types/runtime/v1/user.d.ts +19 -0
@@ -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
@@ -125,6 +135,10 @@ const check = {
125
135
  title: "Check",
126
136
  scheme: spec.scheme,
127
137
  ...(spec.instance === undefined ? {} : { instance: spec.instance }),
138
+ // Under a runtime: the page's declaration (none by default), a viewer who only views.
139
+ ...(spec.config.runtime === undefined
140
+ ? {}
141
+ : { declaration: spec.declaration ?? null, viewer: { level: "view" } }),
128
142
  });
129
143
  const run = {
130
144
  display,
@@ -1,5 +1,4 @@
1
- import { BUILT_IN_TOPICS } from "../config/validate.js";
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 [...BUILT_IN_TOPICS, ...Object.keys(config.guide.topics ?? {})];
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,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,11 @@ 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 its runtime method's own (after the
20
+ * review: `artifact.publish`, `assets.delete`, an upload whose code may run), every one applying.
21
+ */
22
+ export declare function callGates(config: PortholeConfig, name: CapabilityName, args: unknown): readonly Gate[];
17
23
  /** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
18
24
  export declare function egressOrigins(config: PortholeConfig, kind: EgressKind): string[];
19
25
  /** Every origin content may reach, of any kind. */
@@ -41,6 +47,19 @@ export declare const FILE_SET_DIRECTIVES: readonly ["script-src", "style-src", "
41
47
  * `'none'`. Opaque frames have no files, and keep P022's rule whole.
42
48
  */
43
49
  export declare function fileSetCspDirectives(directives: readonly CspDirective[], source: string): CspDirective[];
50
+ /**
51
+ * The directives a page opens its artifact's asset library to (P089), at `/_blob/` on its own
52
+ * origin: what loads without running, always; what runs (scripts, styles) only where uploads are
53
+ * the admins' alone, who publish the page's code anyway.
54
+ */
55
+ export declare const ASSET_DIRECTIVES: readonly ["img-src", "media-src", "font-src", "connect-src"];
56
+ export declare const ASSET_CODE_DIRECTIVES: readonly ["script-src", "style-src"];
57
+ export { assetCodeRuns };
58
+ /**
59
+ * A served page's CSP with its asset library opened (P089), on `origin` (the page's own, exact:
60
+ * never a sibling's): only where the config declares `assets`. Never `'self'`.
61
+ */
62
+ export declare function assetCspDirectives(config: PortholeConfig, directives: readonly CspDirective[], origin: string): CspDirective[];
44
63
  /**
45
64
  * The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
46
65
  * and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
@@ -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, methodOf } 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,17 @@ 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 its runtime method's own (after the
19
+ * review: `artifact.publish`, `assets.delete`, an upload whose code may run), every one applying.
20
+ */
21
+ export function callGates(config, name, args) {
22
+ const gates = effectiveGates(config, name);
23
+ const family = familyOf(name);
24
+ const method = family === null ? null : methodOf(name, args);
25
+ const own = family === null || method === null ? [] : methodGates(config, family.name, method);
26
+ return own.length === 0 ? gates : [...gates, ...own.filter((gate) => !gates.includes(gate))];
27
+ }
15
28
  const unique = (values) => [...new Set(values)];
16
29
  /** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
17
30
  export function egressOrigins(config, kind) {
@@ -103,6 +116,35 @@ export function fileSetCspDirectives(directives, source) {
103
116
  return [name, ...kept, source];
104
117
  });
105
118
  }
119
+ /**
120
+ * The directives a page opens its artifact's asset library to (P089), at `/_blob/` on its own
121
+ * origin: what loads without running, always; what runs (scripts, styles) only where uploads are
122
+ * the admins' alone, who publish the page's code anyway.
123
+ */
124
+ export const ASSET_DIRECTIVES = ["img-src", "media-src", "font-src", "connect-src"];
125
+ export const ASSET_CODE_DIRECTIVES = ["script-src", "style-src"];
126
+ export { assetCodeRuns };
127
+ /**
128
+ * A served page's CSP with its asset library opened (P089), on `origin` (the page's own, exact:
129
+ * never a sibling's): only where the config declares `assets`. Never `'self'`.
130
+ */
131
+ export function assetCspDirectives(config, directives, origin) {
132
+ if (config.capabilities.assets === undefined || config.isolation !== "domain") {
133
+ return [...directives];
134
+ }
135
+ const source = `${origin}${ASSET_PATH}`;
136
+ const opened = new Set([
137
+ ...ASSET_DIRECTIVES,
138
+ ...(assetCodeRuns(config) ? ASSET_CODE_DIRECTIVES : []),
139
+ ]);
140
+ return directives.map(([name, ...sources]) => {
141
+ if (!opened.has(name)) {
142
+ return [name, ...sources];
143
+ }
144
+ const kept = sources.filter((each) => each !== "'none'");
145
+ return [name, ...kept, source];
146
+ });
147
+ }
106
148
  /**
107
149
  * The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
108
150
  * and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
@@ -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.
@@ -32,8 +34,11 @@ export type Gate = "user-activation" | "confirm" | "consent" | {
32
34
  export interface CapabilitySpec {
33
35
  /** The gates a declared capability gets when its config names none. */
34
36
  readonly defaultGates: readonly Gate[];
35
- /** `handler`: the host passes a function that performs it. `event`: the framework emits it. */
36
- readonly served: "handler" | "event";
37
+ /**
38
+ * `handler`: the host passes a function that performs it. `event`: the framework emits it.
39
+ * `viewer`: the framework answers it from the viewer the host gave the display (`user`).
40
+ */
41
+ readonly served: "handler" | "event" | "viewer";
37
42
  /** The global the shell defines for it (sugar over the protocol message), if any. */
38
43
  readonly global?: string;
39
44
  /**
@@ -142,6 +147,46 @@ export declare const CAPABILITIES: {
142
147
  readonly defaultGates: readonly [Gate];
143
148
  readonly served: "event";
144
149
  };
150
+ /** Who is viewing (P087): answered from the viewer the host gave the display. */
151
+ readonly user: {
152
+ readonly defaultGates: readonly [Gate];
153
+ readonly served: "viewer";
154
+ readonly request: {
155
+ readonly method: "porthole/call";
156
+ };
157
+ };
158
+ /** Opens the host's comment composer at the page's anchor (P090): write-only. */
159
+ readonly comments: {
160
+ readonly defaultGates: readonly ["user-activation", Gate];
161
+ readonly served: "handler";
162
+ readonly request: {
163
+ readonly method: "porthole/call";
164
+ };
165
+ };
166
+ /** This artifact's current version, and a new version of it, base-checked (P088). */
167
+ readonly artifact: {
168
+ readonly defaultGates: readonly [Gate];
169
+ readonly served: "handler";
170
+ readonly request: {
171
+ readonly method: "porthole/call";
172
+ };
173
+ };
174
+ /** The artifact's asset library, served at `/_blob/<id>` (P089). */
175
+ readonly assets: {
176
+ readonly defaultGates: readonly [Gate];
177
+ readonly served: "handler";
178
+ readonly request: {
179
+ readonly method: "porthole/call";
180
+ };
181
+ };
182
+ /** The artifact's shared document store (P088). */
183
+ readonly db: {
184
+ readonly defaultGates: readonly [Gate];
185
+ readonly served: "handler";
186
+ readonly request: {
187
+ readonly method: "porthole/call";
188
+ };
189
+ };
145
190
  };
146
191
  /** The arguments a call carries, once the adapter has validated them. */
147
192
  export interface CapabilityArgs {
@@ -186,6 +231,12 @@ export interface CapabilityArgs {
186
231
  };
187
232
  /** What the frame reported, once checked (`AnnotationReport`). */
188
233
  readonly annotate: AnnotationReport;
234
+ readonly user: Readonly<Record<string, never>>;
235
+ readonly comments: CommentRequest;
236
+ readonly artifact: ArtifactRequest;
237
+ readonly assets: AssetRequest;
238
+ /** Paths checked, `me` resolved, the viewer's own data only (P088). */
239
+ readonly db: DbRequest;
189
240
  }
190
241
  /** What a call resolves to. Protocol-shaped results (a tool's result) stay opaque to the core. */
191
242
  export interface CapabilityResults {
@@ -205,6 +256,14 @@ export interface CapabilityResults {
205
256
  /** Whether the text was copied. */
206
257
  readonly copyText: boolean;
207
258
  readonly annotate: undefined;
259
+ readonly user: UserInfo;
260
+ /** Whether the composer opened. Never a thread: content doesn't read comments (P090). */
261
+ readonly comments: boolean;
262
+ /** `get`: the current version; `publish`: the new one. */
263
+ readonly artifact: ArtifactInfo | PublishedVersion;
264
+ /** `list`: the library; `upload`: the new asset; `delete`: whether it was removed. */
265
+ readonly assets: AssetInfo | readonly AssetInfo[] | boolean;
266
+ readonly db: DbResult;
208
267
  }
209
268
  /** The capabilities a host serves with a handler. */
210
269
  export type HandledCapability = {
@@ -19,6 +19,12 @@ 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. */
@@ -86,6 +92,20 @@ export const CAPABILITIES = {
86
92
  * (it shares the realm): UI hints for the host, never permissions.
87
93
  */
88
94
  annotate: { defaultGates: [rate(120)], served: "event" },
95
+ /** Who is viewing (P087): answered from the viewer the host gave the display. */
96
+ user: { defaultGates: [rate(60)], served: "viewer", request: { method: "porthole/call" } },
97
+ /** Opens the host's comment composer at the page's anchor (P090): write-only. */
98
+ comments: {
99
+ defaultGates: ["user-activation", rate(30)],
100
+ served: "handler",
101
+ request: { method: "porthole/call" },
102
+ },
103
+ /** This artifact's current version, and a new version of it, base-checked (P088). */
104
+ artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
105
+ /** The artifact's asset library, served at `/_blob/<id>` (P089). */
106
+ assets: { defaultGates: [rate(30)], served: "handler", request: { method: "porthole/call" } },
107
+ /** The artifact's shared document store (P088). */
108
+ db: { defaultGates: [rate(600)], served: "handler", request: { method: "porthole/call" } },
89
109
  };
90
110
  /** A capability's spec, as the general shape (the table above keeps literal types). */
91
111
  export function capabilitySpec(name) {
@@ -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
@@ -41,6 +43,20 @@ export interface CapabilityConfig {
41
43
  readonly resource?: readonly string[];
42
44
  /** Replaces the generated manual entry for this capability. */
43
45
  readonly guide?: string;
46
+ /**
47
+ * The least viewer level that may call each of the runtime methods it serves (P087), by method
48
+ * name (`db: { levels: { set: "admin" } }`, `sendPrompt: { levels: { send: "admin" } }`): over
49
+ * the contract's own, never below a method's floor (`RUNTIME_CAPABILITIES`). For
50
+ * `assets.upload`, `admin` or above also lets the page run what was uploaded as scripts and
51
+ * styles (P089); `interact` doesn't.
52
+ */
53
+ readonly levels?: Readonly<Record<string, ViewerLevel>>;
54
+ /**
55
+ * Gates of each runtime method it serves, by name, in place of the contract's own (after the
56
+ * review: `artifact.publish` and `assets.delete` need a click and a yes; `assets.upload` a yes
57
+ * where uploaded code may run). Every one applies on top of `gates`. `[]`: none of its own.
58
+ */
59
+ readonly methodGates?: Readonly<Record<string, readonly Gate[]>>;
44
60
  }
45
61
  /** The declared capabilities. Absent: not available, not wired, not in the CSP, not in the manual. */
46
62
  export type CapabilityMap = {
@@ -203,6 +219,14 @@ export interface PortholeConfig {
203
219
  * declares no `reportError`). Absent: the manual says they are reported to the app.
204
220
  */
205
221
  readonly errors?: "agent" | "host" | "none";
222
+ /**
223
+ * The capability runtime (P085): content reaches capabilities through one global,
224
+ * `porthole.use(name)`, under this contract version, and the manual teaches it (with declaring
225
+ * them, `capabilities: { name: config }`, for pages that are published). Only with it may the
226
+ * config declare the runtime's own host functions (`user`, `comments`, `artifact`, `assets`,
227
+ * `db`). Absent: 0.6's frames, globals and manual, exactly.
228
+ */
229
+ readonly runtime?: RuntimeVersion;
206
230
  }
207
231
  export interface StorageConfig {
208
232
  /**
@@ -10,7 +10,7 @@ export declare class ConfigError extends Error {
10
10
  constructor(path: string, message: string);
11
11
  }
12
12
  /** The built-in manual topics; a host's own topics may not reuse these names. */
13
- export declare const BUILT_IN_TOPICS: readonly ["widget", "chart", "interactive"];
13
+ export declare const BUILT_IN_TOPICS: readonly ["widget", "chart", "interactive", "capabilities"];
14
14
  /**
15
15
  * Whether `value` is a CSP host source Porthole accepts: a scheme, a host (optionally `*.` for
16
16
  * every subdomain) and an optional port, nothing else. Insecure schemes only for loopback names.
@@ -1,4 +1,6 @@
1
- import { CAPABILITY_NAMES, isCapabilityName } from "./capabilities.js";
1
+ import { CAPABILITY_NAMES, isCapabilityName, } from "./capabilities.js";
2
+ import { RUNTIME_HOST_FUNCTIONS, RUNTIME_VERSIONS, familyOf, isRuntimeVersion, runtimeCapability, } from "../runtime/contract.js";
3
+ import { atLeast, isViewerLevel } from "../runtime/levels.js";
2
4
  import { PASSIVE_KINDS, URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./schema.js";
3
5
  /**
4
6
  * Checks a config before anything is derived from it. Every string that ends up in a CSP, an
@@ -15,7 +17,7 @@ export class ConfigError extends Error {
15
17
  }
16
18
  }
17
19
  /** The built-in manual topics; a host's own topics may not reuse these names. */
18
- export const BUILT_IN_TOPICS = ["widget", "chart", "interactive"];
20
+ export const BUILT_IN_TOPICS = ["widget", "chart", "interactive", "capabilities"];
19
21
  const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/u;
20
22
  /**
21
23
  * Suffixes under which anyone can register or publish a name (a public suffix): a wildcard over
@@ -260,6 +262,7 @@ export function validateConfig(input) {
260
262
  "permissions",
261
263
  "storage",
262
264
  "errors",
265
+ "runtime",
263
266
  ], "config");
264
267
  if (!MODES.includes(config.mode)) {
265
268
  fail("config.mode", `must be one of ${MODES.join(", ")}`);
@@ -277,7 +280,41 @@ export function validateConfig(input) {
277
280
  fail(path, `is not a capability (${CAPABILITY_NAMES.join(", ")})`);
278
281
  }
279
282
  const capability = object(value, path);
280
- only(capability, ["gates", "connect", "resource", "guide"], path);
283
+ only(capability, ["gates", "connect", "resource", "guide", "levels", "methodGates"], path);
284
+ if (capability.methodGates !== undefined) {
285
+ const family = familyOf(name);
286
+ for (const [method, gates] of Object.entries(object(capability.methodGates, `${path}.methodGates`))) {
287
+ const methods = family === null ? undefined : runtimeCapability(family.name).methods;
288
+ if (methods === undefined ||
289
+ !Object.hasOwn(methods, method) ||
290
+ methods[method]?.serves !== name) {
291
+ fail(`${path}.methodGates.${method}`, `is not a runtime method ${name} serves`);
292
+ }
293
+ if (!Array.isArray(gates)) {
294
+ fail(`${path}.methodGates.${method}`, "must be an array of gates");
295
+ }
296
+ gates.forEach((each, index) => gate(each, `${path}.methodGates.${method}[${index}]`));
297
+ }
298
+ }
299
+ if (capability.levels !== undefined) {
300
+ const levels = object(capability.levels, `${path}.levels`);
301
+ const family = familyOf(name);
302
+ for (const [method, level] of Object.entries(levels)) {
303
+ const methods = family === null ? undefined : runtimeCapability(family.name).methods;
304
+ const spec = methods !== undefined && Object.hasOwn(methods, method) ? methods[method] : undefined;
305
+ if (family === null || spec === undefined || spec.serves !== name) {
306
+ fail(`${path}.levels.${method}`, family === null
307
+ ? `${name} serves no runtime method: it has no levels`
308
+ : `is not a method ${name} serves (${family.methods.join(", ")})`);
309
+ }
310
+ if (!isViewerLevel(level)) {
311
+ fail(`${path}.levels.${method}`, "must be view, interact, admin or owner");
312
+ }
313
+ if (spec !== undefined && !atLeast(level, spec.floor)) {
314
+ fail(`${path}.levels.${method}`, `can't be below ${spec.floor} (${family?.name}.${method}'s floor, P087)`);
315
+ }
316
+ }
317
+ }
281
318
  if (capability.gates !== undefined) {
282
319
  if (!Array.isArray(capability.gates)) {
283
320
  fail(`${path}.gates`, "must be an array");
@@ -293,6 +330,29 @@ export function validateConfig(input) {
293
330
  if (config.mode === "url" && Object.keys(capabilities).length > 0) {
294
331
  fail("config.capabilities", "url mode has no shell, so it can declare no capabilities");
295
332
  }
333
+ // The capability runtime (P085): its global and its own host functions.
334
+ if (config.runtime !== undefined) {
335
+ if (!isRuntimeVersion(config.runtime)) {
336
+ fail("config.runtime", `must be a runtime contract version: ${RUNTIME_VERSIONS.join(", ")}`);
337
+ }
338
+ if (config.mode !== "inline" && config.mode !== "artifact") {
339
+ fail("config.runtime", "the runtime is the shell's: inline widgets and artifact pages only");
340
+ }
341
+ }
342
+ for (const name of RUNTIME_HOST_FUNCTIONS) {
343
+ if (capabilities[name] === undefined) {
344
+ continue;
345
+ }
346
+ if (config.runtime === undefined) {
347
+ fail(`config.capabilities.${name}`, "is the capability runtime's: set config.runtime (content reaches it through porthole.use)");
348
+ }
349
+ if ((name === "artifact" || name === "assets") && config.mode !== "artifact") {
350
+ fail(`config.capabilities.${name}`, "is an artifact page's: artifact mode only");
351
+ }
352
+ }
353
+ if (capabilities.assets !== undefined && config.isolation !== "domain") {
354
+ fail("config.capabilities.assets", "assets are served from the page's own origin (/_blob/): domain isolation only");
355
+ }
296
356
  const egress = object(config.egress, "config.egress");
297
357
  const kinds = ["connect", "script", "style", "img", "font", "media"];
298
358
  only(egress, [...kinds, "anyHttps", "libraries"], "config.egress");
@@ -408,7 +468,9 @@ export function validateConfig(input) {
408
468
  for (const [name, text] of Object.entries(object(guide.topics, "config.guide.topics"))) {
409
469
  const path = `config.guide.topics.${name}`;
410
470
  if (!/^[a-z][a-z0-9-]{0,31}$/u.test(name) ||
411
- BUILT_IN_TOPICS.includes(name)) {
471
+ // `capabilities` is built in only under the runtime (P085): a 0.6 config's own stays.
472
+ (BUILT_IN_TOPICS.includes(name) &&
473
+ (name !== "capabilities" || config.runtime !== undefined))) {
412
474
  fail(path, "must be a new topic name (lowercase), not a built-in one");
413
475
  }
414
476
  if (typeof text !== "string" || text.trim() === "") {