@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
|
@@ -5,7 +5,7 @@ import { entryTests } from "./entry.js";
|
|
|
5
5
|
import HARNESS from "./harness-source.js";
|
|
6
6
|
export { conformancePage } from "./page.js";
|
|
7
7
|
import { leakTests } from "./probes.js";
|
|
8
|
-
import { servedTests } from "./served.js";
|
|
8
|
+
import { servedTests, TAB_CASES, } from "./served.js";
|
|
9
9
|
const CANARY = "https://porthole-canary.example";
|
|
10
10
|
/** A page on no one's origin that frames what a case asks (routed by the test, like the canary). */
|
|
11
11
|
const FOREIGN = "http://porthole-foreign.example";
|
|
@@ -112,6 +112,7 @@ export function hostConformance(options) {
|
|
|
112
112
|
return request;
|
|
113
113
|
},
|
|
114
114
|
calls: () => invoke(page, "calls", id),
|
|
115
|
+
shown: () => invoke(page, "shown", id),
|
|
115
116
|
errors: () => invoke(page, "errors", id),
|
|
116
117
|
events: () => invoke(page, "events", id),
|
|
117
118
|
destroy: () => invoke(page, "destroy", id),
|
|
@@ -282,6 +283,7 @@ const URL_CASES = [
|
|
|
282
283
|
"served.url.ticket",
|
|
283
284
|
"served.url.tab",
|
|
284
285
|
"served.url.framed",
|
|
286
|
+
"served.url.siblings",
|
|
285
287
|
];
|
|
286
288
|
const PROXY_CASES = ["served.proxy.view", "served.proxy.parent-only", "served.proxy.egress"];
|
|
287
289
|
const DOMAIN_CASES = [
|
|
@@ -292,6 +294,8 @@ const DOMAIN_CASES = [
|
|
|
292
294
|
"served.domain.address",
|
|
293
295
|
"served.domain.storage-scope",
|
|
294
296
|
"served.domain.ticket-once",
|
|
297
|
+
"served.domain.self-navigation",
|
|
298
|
+
...TAB_CASES,
|
|
295
299
|
"served.domain.frame-ancestors",
|
|
296
300
|
"served.domain.egress",
|
|
297
301
|
];
|
|
@@ -48,6 +48,11 @@ export interface LaunchSpec {
|
|
|
48
48
|
};
|
|
49
49
|
/** Whether the host has a `confirm` function (default true): without one, gated calls are refused. */
|
|
50
50
|
readonly confirms?: boolean;
|
|
51
|
+
/**
|
|
52
|
+
* Whether the host has a `show` function (default true, P100): without one, `show`-gated calls
|
|
53
|
+
* (a model context update, by default) are refused.
|
|
54
|
+
*/
|
|
55
|
+
readonly shows?: boolean;
|
|
51
56
|
}
|
|
52
57
|
export interface RecordedCall {
|
|
53
58
|
readonly capability: CapabilityName;
|
|
@@ -78,6 +83,11 @@ export interface LaunchedDisplay {
|
|
|
78
83
|
}): Promise<ConfirmRequest>;
|
|
79
84
|
/** The calls that reached the host's handlers, in order. */
|
|
80
85
|
calls(): Promise<readonly RecordedCall[]>;
|
|
86
|
+
/**
|
|
87
|
+
* What the host showed the person for `show`-gated calls (P100: each model context update), in
|
|
88
|
+
* order. A host whose harness doesn't say has `12.model-context` reported inapplicable.
|
|
89
|
+
*/
|
|
90
|
+
shown?(): Promise<readonly ConfirmRequest[]>;
|
|
81
91
|
/** The errors the display reported. */
|
|
82
92
|
errors(): Promise<readonly string[]>;
|
|
83
93
|
/** Every event the display emitted, in order. */
|
|
@@ -102,4 +112,5 @@ export { defineLeakSuite, leakTests, PROBES, type ConformanceFixtures, type Conf
|
|
|
102
112
|
export { httpOracle, settle, udpOracle, type HttpOracle, type UdpOracle } from "./oracles.ts";
|
|
103
113
|
export { defineServedSuite, servedTests, type ServedConformanceHost, type ServedDisplay, type ServedSuiteOptions, } from "./served.ts";
|
|
104
114
|
export { entryTests, type EntryConformanceHost, type EntrySuiteOptions } from "./entry.ts";
|
|
115
|
+
export { defineRuntimeConformance, type RuntimeCase, type RuntimeConformanceOptions, } from "./runtime.ts";
|
|
105
116
|
export { conformancePage, conformanceProjects, defineHostConformance, harnessScript, hostConformance, onDemand, type ConformanceProject, type ConformanceProjectsOptions, type HostConformance, type HostConformanceOptions, } from "./host-kit.ts";
|
|
@@ -4,5 +4,7 @@ export { httpOracle, settle, udpOracle } from "./oracles.js";
|
|
|
4
4
|
export { defineServedSuite, servedTests, } from "./served.js";
|
|
5
5
|
// Redirect entry's cases (P068).
|
|
6
6
|
export { entryTests } from "./entry.js";
|
|
7
|
+
// The capability runtime's cases an app runs against its own handlers (P085-P090): no browser.
|
|
8
|
+
export { defineRuntimeConformance, } from "./runtime.js";
|
|
7
9
|
// The runner an app points at its real page and issue endpoint (P066).
|
|
8
10
|
export { conformancePage, conformanceProjects, defineHostConformance, harnessScript, hostConformance, onDemand, } from "./host-kit.js";
|
|
@@ -118,6 +118,43 @@ export const LIMIT_PROBES = [
|
|
|
118
118
|
expect(await quiet.errors()).toEqual([]);
|
|
119
119
|
},
|
|
120
120
|
},
|
|
121
|
+
{
|
|
122
|
+
id: "14.error-shapes",
|
|
123
|
+
item: 14,
|
|
124
|
+
title: "what content logs as an error reaches the host as bounded text in any shape structured clone carries: a cycle, a BigInt, a shared graph (S05)",
|
|
125
|
+
async run(context) {
|
|
126
|
+
// A graph of 20 objects each holding the next twice: 2^20 leaves written as a tree.
|
|
127
|
+
const logs = `<script>
|
|
128
|
+
(() => {
|
|
129
|
+
const say = (data) => parent.postMessage({ jsonrpc: "2.0", method: "notifications/message", params: { level: "error", data } }, "*");
|
|
130
|
+
const cycle = { name: "porthole-cycle" };
|
|
131
|
+
cycle.self = cycle;
|
|
132
|
+
let graph = "leaf";
|
|
133
|
+
for (let i = 0; i < 20; i += 1) graph = { a: graph, b: graph };
|
|
134
|
+
say(cycle);
|
|
135
|
+
say({ big: 5n });
|
|
136
|
+
say(graph);
|
|
137
|
+
say("porthole-after");
|
|
138
|
+
})();
|
|
139
|
+
</script>`;
|
|
140
|
+
const page = `<!doctype html><html><head><title>View</title></head><body><p>x</p>${logs}</body></html>`;
|
|
141
|
+
for (const display of [
|
|
142
|
+
await context.launch({ config: inline(), content: `<p>x</p>${logs}` }),
|
|
143
|
+
await context.launch({ config: presets.mcpApp(), content: "", document: page }),
|
|
144
|
+
]) {
|
|
145
|
+
await expect
|
|
146
|
+
.poll(async () => (await display.errors()).includes("porthole-after"))
|
|
147
|
+
.toBe(true);
|
|
148
|
+
const errors = await display.errors();
|
|
149
|
+
expect(errors).toContain('{"name":"porthole-cycle","self":"[Circular]"}');
|
|
150
|
+
expect(errors).toContain('{"big":"5n"}');
|
|
151
|
+
const graph = errors.find((each) => each.startsWith('{"a":{"a":'));
|
|
152
|
+
expect(graph, "the shared graph, reported").toBeDefined();
|
|
153
|
+
expect(graph).toContain('"b":"[Repeated]"');
|
|
154
|
+
expect(graph?.length).toBeLessThanOrEqual(2_000);
|
|
155
|
+
}
|
|
156
|
+
},
|
|
157
|
+
},
|
|
121
158
|
{
|
|
122
159
|
id: "14.silent",
|
|
123
160
|
item: 14,
|
|
@@ -523,7 +560,7 @@ export const LIMIT_PROBES = [
|
|
|
523
560
|
export const LIMIT_CHECKS = {
|
|
524
561
|
layout: ["11.size", "14.fill"],
|
|
525
562
|
theme: ["11.theme-flip", "11.document-theme", "14.theme-never"],
|
|
526
|
-
errors: ["14.errors"],
|
|
563
|
+
errors: ["14.errors", "14.error-shapes"],
|
|
527
564
|
silent: ["14.silent"],
|
|
528
565
|
network: ["1.connect", "2.resources"],
|
|
529
566
|
"inline-assets": ["14.inline-assets"],
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { CapabilityHandlers } from "../bridge/types.ts";
|
|
2
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
3
|
+
import type { InstanceRef } from "../isolation/types.ts";
|
|
4
|
+
import type { ViewerInfo } from "../runtime/levels.ts";
|
|
5
|
+
import type { AssetStore } from "../server/types.ts";
|
|
6
|
+
/**
|
|
7
|
+
* The capability runtime's host conformance (P085–P090): cases an app runs against its own
|
|
8
|
+
* handlers (the ones it gives `createHost`), through Porthole's real bridge, as a page would call
|
|
9
|
+
* them, and straight to the handler, as a page that got past the bridge would (the app's API is
|
|
10
|
+
* its data's wall). No browser and no test runner: each case is a function that throws on a
|
|
11
|
+
* failure; register them with yours (P041), `for (const each of cases) test(each.name, each.run)`.
|
|
12
|
+
*
|
|
13
|
+
* What a host's services must do: `db` versions every write and refuses a stale one (`conflict`),
|
|
14
|
+
* applies a batch whole or not at all, follows a document, keeps each person's `data/users/<id>`
|
|
15
|
+
* theirs and the page's rules; `artifact` answers its current version and refuses a publish from
|
|
16
|
+
* a base that moved, or by someone below admin; `assets` stores an upload where `/server` serves
|
|
17
|
+
* it, lists it, and removes it; `comments` answers only whether the composer opened.
|
|
18
|
+
*/
|
|
19
|
+
export interface RuntimeConformanceOptions {
|
|
20
|
+
/** The config the handlers serve under, its runtime capabilities declared. */
|
|
21
|
+
readonly config: PortholeConfig;
|
|
22
|
+
/**
|
|
23
|
+
* Fresh handlers for one artifact, made for each case (a new artifact, a clean store): the
|
|
24
|
+
* functions the app passes `createHost`.
|
|
25
|
+
*/
|
|
26
|
+
readonly handlers: () => CapabilityHandlers | Promise<CapabilityHandlers>;
|
|
27
|
+
/** People at each level; `other` is a second person at interact (whose data isn't `interact`'s). */
|
|
28
|
+
readonly viewers: {
|
|
29
|
+
readonly view: ViewerInfo;
|
|
30
|
+
readonly interact: ViewerInfo;
|
|
31
|
+
readonly admin: ViewerInfo;
|
|
32
|
+
readonly other: ViewerInfo;
|
|
33
|
+
};
|
|
34
|
+
/** The instance the handlers act on, as the app's mount names it. */
|
|
35
|
+
readonly instance?: InstanceRef;
|
|
36
|
+
/** The asset store `/server` serves from (`ServerOptions.assets`), to see an upload served. */
|
|
37
|
+
readonly assets?: (handlers: CapabilityHandlers) => AssetStore;
|
|
38
|
+
/**
|
|
39
|
+
* The app's own API for the same artifact, signed in as `viewer` with that person's real session
|
|
40
|
+
* (after the review): the raw mode. The cases that go past the bridge then call it with a
|
|
41
|
+
* forged context (a viewer claiming to be the owner, no rules), as a page that got past the
|
|
42
|
+
* bridge could, so an API that trusts `context.viewer` or `context.declared` fails them. Without
|
|
43
|
+
* it they call `handlers` with an honest context, which can't catch that: never trust
|
|
44
|
+
* `context.viewer` or `context.declared` for what your data allows.
|
|
45
|
+
*/
|
|
46
|
+
readonly api?: (handlers: CapabilityHandlers, viewer: ViewerInfo) => CapabilityHandlers | Promise<CapabilityHandlers>;
|
|
47
|
+
/** The page's db rules the cases declare (default: `config` writable by admins only). */
|
|
48
|
+
readonly rules?: Readonly<Record<string, {
|
|
49
|
+
read?: ViewerInfo["level"];
|
|
50
|
+
write?: ViewerInfo["level"];
|
|
51
|
+
}>>;
|
|
52
|
+
}
|
|
53
|
+
export interface RuntimeCase {
|
|
54
|
+
readonly name: string;
|
|
55
|
+
run(): Promise<void>;
|
|
56
|
+
}
|
|
57
|
+
/** The runtime's conformance cases for an app's handlers. */
|
|
58
|
+
export declare function defineRuntimeConformance(options: RuntimeConformanceOptions): readonly RuntimeCase[];
|
|
@@ -0,0 +1,324 @@
|
|
|
1
|
+
import { createBridge } from "../bridge/bridge.js";
|
|
2
|
+
import { isRefused } from "../bridge/refusal.js";
|
|
3
|
+
import { RUNTIME_VERSION } from "../runtime/contract.js";
|
|
4
|
+
import { checkDeclaration } from "../runtime/declaration.js";
|
|
5
|
+
import { ASSET_ID, assetUrl } from "../runtime/requests.js";
|
|
6
|
+
class ConformanceFailure extends Error {
|
|
7
|
+
name = "ConformanceFailure";
|
|
8
|
+
}
|
|
9
|
+
function expect(condition, message) {
|
|
10
|
+
if (!condition) {
|
|
11
|
+
throw new ConformanceFailure(message);
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
const codeOf = (outcome) => outcome.ok ? null : (outcome.reason?.code ?? null);
|
|
15
|
+
const ok = (outcome, what) => {
|
|
16
|
+
if (!outcome.ok) {
|
|
17
|
+
throw new ConformanceFailure(`${what}: refused (${outcome.refusal}, ${outcome.reason?.code ?? "no code"}): ${outcome.message ?? ""}`);
|
|
18
|
+
}
|
|
19
|
+
return outcome.value;
|
|
20
|
+
};
|
|
21
|
+
/** The runtime's conformance cases for an app's handlers. */
|
|
22
|
+
export function defineRuntimeConformance(options) {
|
|
23
|
+
const { config, viewers } = options;
|
|
24
|
+
const rules = options.rules ?? { config: { write: "admin" } };
|
|
25
|
+
const declared = {
|
|
26
|
+
...(config.capabilities.db === undefined ? {} : { db: { rules } }),
|
|
27
|
+
...(config.capabilities.artifact === undefined ? {} : { artifact: {} }),
|
|
28
|
+
...(config.capabilities.assets === undefined ? {} : { assets: {} }),
|
|
29
|
+
};
|
|
30
|
+
const declaration = checkDeclaration({ capabilities: declared, runtime: RUNTIME_VERSION }, config);
|
|
31
|
+
const display = {
|
|
32
|
+
id: "conformance",
|
|
33
|
+
title: "Runtime conformance",
|
|
34
|
+
...(options.instance === undefined ? {} : { instance: options.instance }),
|
|
35
|
+
};
|
|
36
|
+
/** A page's calls as `viewer`, through the bridge. */
|
|
37
|
+
const as = (handlers, viewer) => {
|
|
38
|
+
const bridge = createBridge({
|
|
39
|
+
config,
|
|
40
|
+
display,
|
|
41
|
+
handlers,
|
|
42
|
+
declaration,
|
|
43
|
+
viewer,
|
|
44
|
+
// Gates the person answers are the app's UI: a yes here, so the services are what's tested.
|
|
45
|
+
confirm: () => Promise.resolve(true),
|
|
46
|
+
consent: () => true,
|
|
47
|
+
show: () => { },
|
|
48
|
+
userActivation: () => true,
|
|
49
|
+
onEvent: () => { },
|
|
50
|
+
});
|
|
51
|
+
return (capability, args, subscription) => bridge.call(capability, args, subscription);
|
|
52
|
+
};
|
|
53
|
+
/** A call straight to the handler, as a page past the bridge would make it (the app's wall). */
|
|
54
|
+
const direct = async (handlers, capability, args, viewer) => {
|
|
55
|
+
const raw = options.api === undefined ? null : await options.api(handlers, viewer);
|
|
56
|
+
const handler = (raw ?? handlers)[capability];
|
|
57
|
+
if (handler === undefined) {
|
|
58
|
+
throw new ConformanceFailure(`no ${capability} handler`);
|
|
59
|
+
}
|
|
60
|
+
try {
|
|
61
|
+
const value = await handler(args, {
|
|
62
|
+
displayId: display.id,
|
|
63
|
+
title: display.title,
|
|
64
|
+
capability,
|
|
65
|
+
...(options.instance === undefined ? {} : { instance: options.instance }),
|
|
66
|
+
// The raw mode forges what a page past the bridge would claim; else the honest context.
|
|
67
|
+
...(raw === null
|
|
68
|
+
? { viewer, ...(capability === "db" ? { declared: { rules } } : {}) }
|
|
69
|
+
: {
|
|
70
|
+
viewer: { level: "owner", ...(viewer.id === undefined ? {} : { id: viewer.id }) },
|
|
71
|
+
declared: {},
|
|
72
|
+
}),
|
|
73
|
+
});
|
|
74
|
+
return { ok: true, value };
|
|
75
|
+
}
|
|
76
|
+
catch (error) {
|
|
77
|
+
return { ok: false, code: isRefused(error) ? error.code : null };
|
|
78
|
+
}
|
|
79
|
+
};
|
|
80
|
+
/** An access for the instance, as `/server` asks the store with it. */
|
|
81
|
+
const access = {
|
|
82
|
+
instance: options.instance ?? {
|
|
83
|
+
scope: "conformance",
|
|
84
|
+
document: { kind: "artifact", id: "page", version: "1" },
|
|
85
|
+
},
|
|
86
|
+
viewer: "conformance",
|
|
87
|
+
origin: "https://conformance.invalid",
|
|
88
|
+
expiresAt: Date.now() + 3_600_000,
|
|
89
|
+
};
|
|
90
|
+
const cases = [];
|
|
91
|
+
const add = (name, run) => {
|
|
92
|
+
cases.push({ name, run: async () => run(await options.handlers()) });
|
|
93
|
+
};
|
|
94
|
+
if (config.capabilities.db !== undefined) {
|
|
95
|
+
add("db: a set is read back, versioned from 1", async (handlers) => {
|
|
96
|
+
const call = as(handlers, viewers.interact);
|
|
97
|
+
const set = ok(await call("db", { op: "set", path: "notes/a", data: { text: "hi" } }), "set");
|
|
98
|
+
expect(set.version === 1, "a first write is version 1");
|
|
99
|
+
const got = ok(await call("db", { op: "get", path: "notes/a" }), "get");
|
|
100
|
+
expect(got.exists && got.version === 1 && got.data?.text === "hi", "get reads it back");
|
|
101
|
+
const missing = ok(await call("db", { op: "get", path: "notes/none" }), "get");
|
|
102
|
+
expect(!missing.exists && missing.version === 0, "a missing document: exists false, version 0");
|
|
103
|
+
});
|
|
104
|
+
add("db: a write that names a stale version, or none for a document that exists, is a conflict", async (handlers) => {
|
|
105
|
+
const call = as(handlers, viewers.interact);
|
|
106
|
+
ok(await call("db", { op: "set", path: "notes/a", data: { n: 1 } }), "set");
|
|
107
|
+
expect(codeOf(await call("db", { op: "set", path: "notes/a", data: { n: 2 } })) === "conflict", "set without ifVersion over an existing document: conflict");
|
|
108
|
+
expect(codeOf(await call("db", { op: "update", path: "notes/a", data: { n: 2 }, ifVersion: 7 })) === "conflict", "update with a stale ifVersion: conflict");
|
|
109
|
+
const updated = ok(await call("db", { op: "update", path: "notes/a", data: { m: 3 }, ifVersion: 1 }), "update");
|
|
110
|
+
expect(updated.version === 2, "an update with the right version is the next one");
|
|
111
|
+
const got = ok(await call("db", { op: "get", path: "notes/a" }), "get");
|
|
112
|
+
expect(got.data?.n === 1 && got.data?.m === 3, "update merges fields");
|
|
113
|
+
expect(codeOf(await call("db", { op: "set", path: "notes/b", data: {}, ifVersion: 0 })) === null, "ifVersion 0 creates");
|
|
114
|
+
ok(await call("db", { op: "delete", path: "notes/a", ifVersion: 2 }), "delete");
|
|
115
|
+
const gone = ok(await call("db", { op: "get", path: "notes/a" }), "get");
|
|
116
|
+
expect(!gone.exists, "a deleted document is gone");
|
|
117
|
+
});
|
|
118
|
+
add("db: a query answers a collection's documents, filtered, ordered, limited", async (handlers) => {
|
|
119
|
+
const call = as(handlers, viewers.interact);
|
|
120
|
+
for (const [id, score] of [
|
|
121
|
+
["a", 3],
|
|
122
|
+
["b", 1],
|
|
123
|
+
["c", 2],
|
|
124
|
+
]) {
|
|
125
|
+
ok(await call("db", { op: "set", path: `scores/${id}`, data: { score } }), "set");
|
|
126
|
+
}
|
|
127
|
+
ok(await call("db", { op: "set", path: "scores/a/history/1", data: { score: 9 } }), "set");
|
|
128
|
+
const found = ok(await call("db", {
|
|
129
|
+
op: "query",
|
|
130
|
+
collection: "scores",
|
|
131
|
+
where: [["score", ">=", 2]],
|
|
132
|
+
orderBy: { field: "score", direction: "desc" },
|
|
133
|
+
limit: 5,
|
|
134
|
+
}), "query");
|
|
135
|
+
expect(JSON.stringify(found.docs.map((each) => each.id)) === '["a","c"]', `a query answers its collection's own documents, filtered and ordered: ${JSON.stringify(found.docs.map((each) => each.id))}`);
|
|
136
|
+
});
|
|
137
|
+
add("db: a batch is applied whole or not at all", async (handlers) => {
|
|
138
|
+
const call = as(handlers, viewers.interact);
|
|
139
|
+
ok(await call("db", { op: "set", path: "items/x", data: { n: 1 } }), "set");
|
|
140
|
+
const refused = await call("db", {
|
|
141
|
+
op: "batch",
|
|
142
|
+
writes: [
|
|
143
|
+
{ op: "set", path: "items/y", data: { n: 1 } },
|
|
144
|
+
{ op: "update", path: "items/x", data: { n: 2 }, ifVersion: 9 },
|
|
145
|
+
],
|
|
146
|
+
});
|
|
147
|
+
expect(codeOf(refused) === "conflict", "a batch with a stale write: conflict");
|
|
148
|
+
const y = ok(await call("db", { op: "get", path: "items/y" }), "get");
|
|
149
|
+
expect(!y.exists, "nothing of a refused batch is written");
|
|
150
|
+
const done = ok(await call("db", {
|
|
151
|
+
op: "batch",
|
|
152
|
+
writes: [
|
|
153
|
+
{ op: "set", path: "items/y", data: { n: 1 } },
|
|
154
|
+
{ op: "update", path: "items/x", data: { n: 2 }, ifVersion: 1 },
|
|
155
|
+
],
|
|
156
|
+
}), "batch");
|
|
157
|
+
expect(JSON.stringify(done.versions) === "[1,2]", "a batch answers each write's version");
|
|
158
|
+
});
|
|
159
|
+
add("db: a watch hears the document now and at each change", async (handlers) => {
|
|
160
|
+
const heard = [];
|
|
161
|
+
const controller = new AbortController();
|
|
162
|
+
const watching = as(handlers, viewers.view);
|
|
163
|
+
ok(await watching("db", { op: "watch", path: "notes/w" }, {
|
|
164
|
+
subscription: {
|
|
165
|
+
changed: (state) => heard.push(state),
|
|
166
|
+
signal: controller.signal,
|
|
167
|
+
},
|
|
168
|
+
}), "watch");
|
|
169
|
+
ok(await as(handlers, viewers.interact)("db", { op: "set", path: "notes/w", data: { n: 1 } }), "set");
|
|
170
|
+
await new Promise((resolve) => setTimeout(resolve, 50));
|
|
171
|
+
controller.abort();
|
|
172
|
+
ok(await as(handlers, viewers.interact)("db", {
|
|
173
|
+
op: "set",
|
|
174
|
+
path: "notes/w",
|
|
175
|
+
data: { n: 2 },
|
|
176
|
+
ifVersion: 1,
|
|
177
|
+
}), "set");
|
|
178
|
+
await new Promise((resolve) => setTimeout(resolve, 50));
|
|
179
|
+
expect(heard.length >= 1 && heard.some((each) => each.exists && each.data?.n === 1), "a watch hears a write");
|
|
180
|
+
expect(!heard.some((each) => each.data?.n === 2), "a watch ends with its signal");
|
|
181
|
+
});
|
|
182
|
+
add("db: a person's own data is theirs: data/users/me is them, another's is refused, even past the bridge", async (handlers) => {
|
|
183
|
+
const mine = as(handlers, viewers.interact);
|
|
184
|
+
ok(await mine("db", { op: "set", path: "data/users/me/prefs", data: { dark: true } }), "set own");
|
|
185
|
+
const own = ok(await mine("db", { op: "get", path: `data/users/${viewers.interact.id}/prefs` }), "get own");
|
|
186
|
+
expect(own.exists, "me is the viewer's own id");
|
|
187
|
+
const theirs = as(handlers, viewers.other);
|
|
188
|
+
const path = `data/users/${viewers.interact.id}/prefs`;
|
|
189
|
+
expect(codeOf(await theirs("db", { op: "get", path })) === "forbidden", "another person's data: forbidden");
|
|
190
|
+
const past = await direct(handlers, "db", { op: "get", path }, viewers.other);
|
|
191
|
+
expect(!past.ok, "the app's handler refuses another person's data itself");
|
|
192
|
+
const listed = await direct(handlers, "db", { op: "query", collection: `data/users/${viewers.interact.id}` }, viewers.other);
|
|
193
|
+
expect(!listed.ok, "and their collections");
|
|
194
|
+
});
|
|
195
|
+
add("db: a person's own paths come back as data/users/me, never their id", async (handlers) => {
|
|
196
|
+
const mine = as(handlers, viewers.interact);
|
|
197
|
+
ok(await mine("db", { op: "set", path: "data/users/me/prefs", data: { n: 1 } }), "set own");
|
|
198
|
+
const got = ok(await mine("db", { op: "get", path: "data/users/me/prefs" }), "get");
|
|
199
|
+
const listed = ok(await mine("db", { op: "query", collection: "data/users/me" }), "query");
|
|
200
|
+
const said = JSON.stringify([got, listed]);
|
|
201
|
+
expect(got.path === "data/users/me/prefs", `a snapshot says me: ${got.path}`);
|
|
202
|
+
expect(viewers.interact.id === undefined || !said.includes(viewers.interact.id), "no answer names the viewer's id");
|
|
203
|
+
});
|
|
204
|
+
add("db: the page's rules hold, at the bridge and in the app", async (handlers) => {
|
|
205
|
+
expect(codeOf(await as(handlers, viewers.interact)("db", { op: "set", path: "config/main", data: {} })) === "forbidden", "a rule's write level holds at the bridge");
|
|
206
|
+
const past = await direct(handlers, "db", { op: "set", path: "config/main", data: {} }, viewers.interact);
|
|
207
|
+
expect(!past.ok, "the app's handler applies the page's rules itself");
|
|
208
|
+
const view = await direct(handlers, "db", { op: "set", path: "notes/v", data: {} }, viewers.view);
|
|
209
|
+
expect(!view.ok, "a view-only person writes nothing, even past the bridge");
|
|
210
|
+
ok(await as(handlers, viewers.admin)("db", { op: "set", path: "config/main", data: {} }), "an admin writes it");
|
|
211
|
+
});
|
|
212
|
+
// P093: a store that folds case keeps `Config/main` where `config/main` is.
|
|
213
|
+
add("db: a rule holds for its collection in any case, at the bridge and in the app", async (handlers) => {
|
|
214
|
+
for (const path of ["Config/main", "CONFIG/main"]) {
|
|
215
|
+
expect(codeOf(await as(handlers, viewers.interact)("db", { op: "set", path, data: {} })) ===
|
|
216
|
+
"forbidden", `the rule for config holds at the bridge for ${path}`);
|
|
217
|
+
const past = await direct(handlers, "db", { op: "set", path, data: {} }, viewers.interact);
|
|
218
|
+
expect(!past.ok, `the app's handler holds the rule for config for ${path} itself`);
|
|
219
|
+
}
|
|
220
|
+
});
|
|
221
|
+
}
|
|
222
|
+
if (config.capabilities.artifact !== undefined) {
|
|
223
|
+
add("artifact: get answers the current version; a publish from it makes the next", async (handlers) => {
|
|
224
|
+
const call = as(handlers, viewers.admin);
|
|
225
|
+
const current = ok(await call("artifact", { op: "get" }), "get");
|
|
226
|
+
expect(typeof current.version === "string" && Array.isArray(current.files), "get: { version, files }");
|
|
227
|
+
const published = ok(await call("artifact", {
|
|
228
|
+
op: "publish",
|
|
229
|
+
base: current.version,
|
|
230
|
+
files: { "notes.txt": { text: "new" } },
|
|
231
|
+
label: "From the page",
|
|
232
|
+
}), "publish");
|
|
233
|
+
expect(published.version !== current.version, "a publish makes a new version");
|
|
234
|
+
const after = ok(await call("artifact", { op: "get" }), "get");
|
|
235
|
+
expect(after.version === published.version, "the new version is current");
|
|
236
|
+
expect(after.files.some((each) => each.path === "notes.txt"), "with the patch applied");
|
|
237
|
+
expect(current.files.every((file) => after.files.some((each) => each.path === file.path)), "and the base's other files kept");
|
|
238
|
+
});
|
|
239
|
+
add("artifact: a publish from a base that moved is a conflict; below admin, refused even past the bridge", async (handlers) => {
|
|
240
|
+
const call = as(handlers, viewers.admin);
|
|
241
|
+
const current = ok(await call("artifact", { op: "get" }), "get");
|
|
242
|
+
ok(await call("artifact", {
|
|
243
|
+
op: "publish",
|
|
244
|
+
base: current.version,
|
|
245
|
+
files: { "a.txt": { text: "1" } },
|
|
246
|
+
}), "publish");
|
|
247
|
+
expect(codeOf(await call("artifact", {
|
|
248
|
+
op: "publish",
|
|
249
|
+
base: current.version,
|
|
250
|
+
files: { "a.txt": { text: "2" } },
|
|
251
|
+
})) === "conflict", "a stale base: conflict");
|
|
252
|
+
expect(codeOf(await as(handlers, viewers.interact)("artifact", {
|
|
253
|
+
op: "publish",
|
|
254
|
+
base: "x",
|
|
255
|
+
files: { "a.txt": { text: "3" } },
|
|
256
|
+
})) === "forbidden", "below admin: forbidden at the bridge");
|
|
257
|
+
const now = ok(await call("artifact", { op: "get" }), "get");
|
|
258
|
+
const past = await direct(handlers, "artifact", { op: "publish", base: now.version, files: { "a.txt": { text: "4" } } }, viewers.interact);
|
|
259
|
+
expect(!past.ok, "the app's handler refuses a publish below admin itself");
|
|
260
|
+
});
|
|
261
|
+
}
|
|
262
|
+
if (config.capabilities.artifact !== undefined) {
|
|
263
|
+
add("artifact: a publish whose merged files make no page is refused", async (handlers) => {
|
|
264
|
+
const call = as(handlers, viewers.admin);
|
|
265
|
+
const current = ok(await call("artifact", { op: "get" }), "get");
|
|
266
|
+
const refused = await call("artifact", {
|
|
267
|
+
op: "publish",
|
|
268
|
+
base: current.version,
|
|
269
|
+
files: { [current.entry]: null },
|
|
270
|
+
});
|
|
271
|
+
expect(!refused.ok, "a publish that removes the entry is refused (check the merged set)");
|
|
272
|
+
});
|
|
273
|
+
}
|
|
274
|
+
if (config.capabilities.assets !== undefined) {
|
|
275
|
+
add("assets: an upload is listed, served by its id, and removed", async (handlers) => {
|
|
276
|
+
const call = as(handlers, viewers.admin);
|
|
277
|
+
const bytes = "R0lGODlhAQABAAAAACw="; // a small GIF's start: its bytes, as base64
|
|
278
|
+
const asset = ok(await call("assets", { op: "upload", name: "pixel.gif", base64: bytes }), "upload");
|
|
279
|
+
expect(ASSET_ID.test(asset.id), "an asset's id is 32 lowercase hex characters");
|
|
280
|
+
expect(asset.url === assetUrl(asset.id), "its url is /_blob/<id>");
|
|
281
|
+
expect(asset.type === "image/gif" && asset.size === 14, "its type is the name's; its size the bytes'");
|
|
282
|
+
const listed = ok(await as(handlers, viewers.view)("assets", { op: "list" }), "list");
|
|
283
|
+
expect(listed.some((each) => each.id === asset.id), "the library lists it");
|
|
284
|
+
const store = options.assets?.(handlers);
|
|
285
|
+
if (store !== undefined) {
|
|
286
|
+
const stored = await store.get(asset.id, access);
|
|
287
|
+
expect(stored !== null && stored.size === 14, "the server's store has it");
|
|
288
|
+
const body = await stored?.read();
|
|
289
|
+
const length = body instanceof Uint8Array
|
|
290
|
+
? body.length
|
|
291
|
+
: body === null || body === undefined
|
|
292
|
+
? -1
|
|
293
|
+
: (await new Response(body).arrayBuffer()).byteLength;
|
|
294
|
+
expect(length === 14, "with its bytes");
|
|
295
|
+
}
|
|
296
|
+
ok(await call("assets", { op: "delete", id: asset.id }), "delete");
|
|
297
|
+
const after = ok(await call("assets", { op: "list" }), "list");
|
|
298
|
+
expect(!after.some((each) => each.id === asset.id), "a removed asset isn't listed");
|
|
299
|
+
if (store !== undefined) {
|
|
300
|
+
expect((await store.get(asset.id, access)) === null, "nor served");
|
|
301
|
+
}
|
|
302
|
+
});
|
|
303
|
+
add("assets: removing is the admins', even past the bridge", async (handlers) => {
|
|
304
|
+
const asset = ok(await as(handlers, viewers.admin)("assets", {
|
|
305
|
+
op: "upload",
|
|
306
|
+
name: "a.txt",
|
|
307
|
+
base64: "aGk=",
|
|
308
|
+
}), "upload");
|
|
309
|
+
expect(codeOf(await as(handlers, viewers.interact)("assets", { op: "delete", id: asset.id })) ===
|
|
310
|
+
"forbidden", "below admin: forbidden at the bridge");
|
|
311
|
+
const past = await direct(handlers, "assets", { op: "delete", id: asset.id }, viewers.view);
|
|
312
|
+
expect(!past.ok || past.value !== true, "the app's handler refuses a removal below admin itself");
|
|
313
|
+
});
|
|
314
|
+
}
|
|
315
|
+
if (config.capabilities.comments !== undefined) {
|
|
316
|
+
add("comments: content hears only whether the composer opened", async (handlers) => {
|
|
317
|
+
const opened = ok(await as(handlers, viewers.view)("comments", {
|
|
318
|
+
anchor: { name: "slide-3", label: "Slide 3" },
|
|
319
|
+
}), "open");
|
|
320
|
+
expect(typeof opened === "boolean", "comments.open answers a boolean");
|
|
321
|
+
});
|
|
322
|
+
}
|
|
323
|
+
return cases;
|
|
324
|
+
}
|
|
@@ -72,6 +72,8 @@ export interface ServedSuiteOptions {
|
|
|
72
72
|
/** Case ids to skip, each with the reason (shown in the report). */
|
|
73
73
|
readonly skip?: Readonly<Record<string, string>>;
|
|
74
74
|
}
|
|
75
|
+
/** The cases of a served page on a tab of its own (P099), one per wall. */
|
|
76
|
+
export declare const TAB_CASES: readonly string[];
|
|
75
77
|
/** Registers every served-mode case as a test. */
|
|
76
78
|
/**
|
|
77
79
|
* Registers every served-mode case as a test. A host that wants to select them by its own spec
|