@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
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type ConfigWarning } from "./warnings.ts";
|
|
1
2
|
import { type PortholeConfig } from "./schema.ts";
|
|
2
3
|
/**
|
|
3
4
|
* Checks a config before anything is derived from it. Every string that ends up in a CSP, an
|
|
@@ -10,7 +11,7 @@ export declare class ConfigError extends Error {
|
|
|
10
11
|
constructor(path: string, message: string);
|
|
11
12
|
}
|
|
12
13
|
/** 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"];
|
|
14
|
+
export declare const BUILT_IN_TOPICS: readonly ["widget", "chart", "interactive", "capabilities"];
|
|
14
15
|
/**
|
|
15
16
|
* Whether `value` is a CSP host source Porthole accepts: a scheme, a host (optionally `*.` for
|
|
16
17
|
* every subdomain) and an optional port, nothing else. Insecure schemes only for loopback names.
|
|
@@ -18,5 +19,10 @@ export declare const BUILT_IN_TOPICS: readonly ["widget", "chart", "interactive"
|
|
|
18
19
|
export declare function isOriginSource(value: unknown): value is string;
|
|
19
20
|
/** Why `value` isn't an origin source Porthole accepts, in words to act on; null if it is. */
|
|
20
21
|
export declare function originSourceProblem(value: unknown): string | null;
|
|
21
|
-
/**
|
|
22
|
-
|
|
22
|
+
/**
|
|
23
|
+
* Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise.
|
|
24
|
+
* `onWarning` hears each `ConfigWarning` a valid config earns (`configWarnings`).
|
|
25
|
+
*/
|
|
26
|
+
export declare function validateConfig(input: unknown, options?: {
|
|
27
|
+
readonly onWarning?: (warning: ConfigWarning) => void;
|
|
28
|
+
}): PortholeConfig;
|
package/dist/config/validate.js
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
|
-
import { CAPABILITY_NAMES, isCapabilityName } from "./capabilities.js";
|
|
1
|
+
import { CAPABILITY_NAMES, capabilitySpec, isCapabilityName, } from "./capabilities.js";
|
|
2
|
+
import { configWarnings } from "./warnings.js";
|
|
3
|
+
import { RUNTIME_HOST_FUNCTIONS, RUNTIME_VERSIONS, familyOf, isRuntimeVersion, runtimeCapability, } from "../runtime/contract.js";
|
|
4
|
+
import { atLeast, isViewerLevel } from "../runtime/levels.js";
|
|
2
5
|
import { PASSIVE_KINDS, URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./schema.js";
|
|
3
6
|
/**
|
|
4
7
|
* Checks a config before anything is derived from it. Every string that ends up in a CSP, an
|
|
@@ -15,7 +18,7 @@ export class ConfigError extends Error {
|
|
|
15
18
|
}
|
|
16
19
|
}
|
|
17
20
|
/** The built-in manual topics; a host's own topics may not reuse these names. */
|
|
18
|
-
export const BUILT_IN_TOPICS = ["widget", "chart", "interactive"];
|
|
21
|
+
export const BUILT_IN_TOPICS = ["widget", "chart", "interactive", "capabilities"];
|
|
19
22
|
const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/u;
|
|
20
23
|
/**
|
|
21
24
|
* Suffixes under which anyone can register or publish a name (a public suffix): a wildcard over
|
|
@@ -229,12 +232,15 @@ function positive(value, path, max = Number.MAX_SAFE_INTEGER) {
|
|
|
229
232
|
}
|
|
230
233
|
}
|
|
231
234
|
function gate(value, path) {
|
|
232
|
-
if (value === "user-activation" ||
|
|
235
|
+
if (value === "user-activation" ||
|
|
236
|
+
value === "confirm" ||
|
|
237
|
+
value === "consent" ||
|
|
238
|
+
value === "show") {
|
|
233
239
|
return;
|
|
234
240
|
}
|
|
235
241
|
const limit = isObject(value) && isObject(value.rateLimit) ? value.rateLimit : null;
|
|
236
242
|
if (limit === null || Object.keys(value).length !== 1) {
|
|
237
|
-
fail(path, 'must be "user-activation", "confirm", "consent" or { rateLimit: { perMinute } }');
|
|
243
|
+
fail(path, 'must be "user-activation", "confirm", "consent", "show" or { rateLimit: { perMinute } }');
|
|
238
244
|
return;
|
|
239
245
|
}
|
|
240
246
|
only(limit, ["perMinute"], `${path}.rateLimit`);
|
|
@@ -242,8 +248,11 @@ function gate(value, path) {
|
|
|
242
248
|
}
|
|
243
249
|
const MODES = ["inline", "artifact", "mcp-app", "url"];
|
|
244
250
|
const ISOLATIONS = ["opaque", "domain", "external"];
|
|
245
|
-
/**
|
|
246
|
-
|
|
251
|
+
/**
|
|
252
|
+
* Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise.
|
|
253
|
+
* `onWarning` hears each `ConfigWarning` a valid config earns (`configWarnings`).
|
|
254
|
+
*/
|
|
255
|
+
export function validateConfig(input, options = {}) {
|
|
247
256
|
const config = object(input, "config");
|
|
248
257
|
only(config, [
|
|
249
258
|
"mode",
|
|
@@ -260,6 +269,7 @@ export function validateConfig(input) {
|
|
|
260
269
|
"permissions",
|
|
261
270
|
"storage",
|
|
262
271
|
"errors",
|
|
272
|
+
"runtime",
|
|
263
273
|
], "config");
|
|
264
274
|
if (!MODES.includes(config.mode)) {
|
|
265
275
|
fail("config.mode", `must be one of ${MODES.join(", ")}`);
|
|
@@ -277,13 +287,59 @@ export function validateConfig(input) {
|
|
|
277
287
|
fail(path, `is not a capability (${CAPABILITY_NAMES.join(", ")})`);
|
|
278
288
|
}
|
|
279
289
|
const capability = object(value, path);
|
|
280
|
-
only(capability, ["gates", "connect", "resource", "guide"], path);
|
|
290
|
+
only(capability, ["gates", "connect", "resource", "guide", "levels", "methodGates", "withoutShow"], path);
|
|
291
|
+
if (capability.methodGates !== undefined) {
|
|
292
|
+
const family = familyOf(name);
|
|
293
|
+
for (const [method, gates] of Object.entries(object(capability.methodGates, `${path}.methodGates`))) {
|
|
294
|
+
const methods = family === null ? undefined : runtimeCapability(family.name).methods;
|
|
295
|
+
if (methods === undefined ||
|
|
296
|
+
!Object.hasOwn(methods, method) ||
|
|
297
|
+
methods[method]?.serves !== name) {
|
|
298
|
+
fail(`${path}.methodGates.${method}`, `is not a runtime method ${name} serves`);
|
|
299
|
+
}
|
|
300
|
+
if (!Array.isArray(gates)) {
|
|
301
|
+
fail(`${path}.methodGates.${method}`, "must be an array of gates");
|
|
302
|
+
}
|
|
303
|
+
gates.forEach((each, index) => gate(each, `${path}.methodGates.${method}[${index}]`));
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
if (capability.levels !== undefined) {
|
|
307
|
+
const levels = object(capability.levels, `${path}.levels`);
|
|
308
|
+
const family = familyOf(name);
|
|
309
|
+
for (const [method, level] of Object.entries(levels)) {
|
|
310
|
+
const methods = family === null ? undefined : runtimeCapability(family.name).methods;
|
|
311
|
+
const spec = methods !== undefined && Object.hasOwn(methods, method) ? methods[method] : undefined;
|
|
312
|
+
if (family === null || spec === undefined || spec.serves !== name) {
|
|
313
|
+
fail(`${path}.levels.${method}`, family === null
|
|
314
|
+
? `${name} serves no runtime method: it has no levels`
|
|
315
|
+
: `is not a method ${name} serves (${family.methods.join(", ")})`);
|
|
316
|
+
}
|
|
317
|
+
if (!isViewerLevel(level)) {
|
|
318
|
+
fail(`${path}.levels.${method}`, "must be view, interact, admin or owner");
|
|
319
|
+
}
|
|
320
|
+
if (spec !== undefined && !atLeast(level, spec.floor)) {
|
|
321
|
+
fail(`${path}.levels.${method}`, `can't be below ${spec.floor} (${family?.name}.${method}'s floor, P087)`);
|
|
322
|
+
}
|
|
323
|
+
}
|
|
324
|
+
}
|
|
281
325
|
if (capability.gates !== undefined) {
|
|
282
326
|
if (!Array.isArray(capability.gates)) {
|
|
283
327
|
fail(`${path}.gates`, "must be an array");
|
|
284
328
|
}
|
|
285
329
|
capability.gates.forEach((each, index) => gate(each, `${path}.gates[${index}]`));
|
|
286
330
|
}
|
|
331
|
+
// Leaving the default `show` out on purpose (P100): only where there is one, left out.
|
|
332
|
+
if (capability.withoutShow !== undefined) {
|
|
333
|
+
if (capability.withoutShow !== true) {
|
|
334
|
+
fail(`${path}.withoutShow`, "must be true: it says the gates leave show out on purpose");
|
|
335
|
+
}
|
|
336
|
+
if (!capabilitySpec(name).defaultGates.includes("show")) {
|
|
337
|
+
fail(`${path}.withoutShow`, `${name} has no show gate to leave out`);
|
|
338
|
+
}
|
|
339
|
+
if (!Array.isArray(capability.gates) || capability.gates.includes("show")) {
|
|
340
|
+
fail(`${path}.withoutShow`, "says show is left out, so the gates must be named, without it");
|
|
341
|
+
}
|
|
342
|
+
}
|
|
287
343
|
sources(capability.connect, `${path}.connect`);
|
|
288
344
|
sources(capability.resource, `${path}.resource`);
|
|
289
345
|
if (capability.guide !== undefined && typeof capability.guide !== "string") {
|
|
@@ -293,6 +349,29 @@ export function validateConfig(input) {
|
|
|
293
349
|
if (config.mode === "url" && Object.keys(capabilities).length > 0) {
|
|
294
350
|
fail("config.capabilities", "url mode has no shell, so it can declare no capabilities");
|
|
295
351
|
}
|
|
352
|
+
// The capability runtime (P085): its global and its own host functions.
|
|
353
|
+
if (config.runtime !== undefined) {
|
|
354
|
+
if (!isRuntimeVersion(config.runtime)) {
|
|
355
|
+
fail("config.runtime", `must be a runtime contract version: ${RUNTIME_VERSIONS.join(", ")}`);
|
|
356
|
+
}
|
|
357
|
+
if (config.mode !== "inline" && config.mode !== "artifact") {
|
|
358
|
+
fail("config.runtime", "the runtime is the shell's: inline widgets and artifact pages only");
|
|
359
|
+
}
|
|
360
|
+
}
|
|
361
|
+
for (const name of RUNTIME_HOST_FUNCTIONS) {
|
|
362
|
+
if (capabilities[name] === undefined) {
|
|
363
|
+
continue;
|
|
364
|
+
}
|
|
365
|
+
if (config.runtime === undefined) {
|
|
366
|
+
fail(`config.capabilities.${name}`, "is the capability runtime's: set config.runtime (content reaches it through porthole.use)");
|
|
367
|
+
}
|
|
368
|
+
if ((name === "artifact" || name === "assets") && config.mode !== "artifact") {
|
|
369
|
+
fail(`config.capabilities.${name}`, "is an artifact page's: artifact mode only");
|
|
370
|
+
}
|
|
371
|
+
}
|
|
372
|
+
if (capabilities.assets !== undefined && config.isolation !== "domain") {
|
|
373
|
+
fail("config.capabilities.assets", "assets are served from the page's own origin (/_blob/): domain isolation only");
|
|
374
|
+
}
|
|
296
375
|
const egress = object(config.egress, "config.egress");
|
|
297
376
|
const kinds = ["connect", "script", "style", "img", "font", "media"];
|
|
298
377
|
only(egress, [...kinds, "anyHttps", "libraries"], "config.egress");
|
|
@@ -408,7 +487,9 @@ export function validateConfig(input) {
|
|
|
408
487
|
for (const [name, text] of Object.entries(object(guide.topics, "config.guide.topics"))) {
|
|
409
488
|
const path = `config.guide.topics.${name}`;
|
|
410
489
|
if (!/^[a-z][a-z0-9-]{0,31}$/u.test(name) ||
|
|
411
|
-
|
|
490
|
+
// `capabilities` is built in only under the runtime (P085): a 0.6 config's own stays.
|
|
491
|
+
(BUILT_IN_TOPICS.includes(name) &&
|
|
492
|
+
(name !== "capabilities" || config.runtime !== undefined))) {
|
|
412
493
|
fail(path, "must be a new topic name (lowercase), not a built-in one");
|
|
413
494
|
}
|
|
414
495
|
if (typeof text !== "string" || text.trim() === "") {
|
|
@@ -486,5 +567,8 @@ export function validateConfig(input) {
|
|
|
486
567
|
}
|
|
487
568
|
});
|
|
488
569
|
}
|
|
570
|
+
for (const warning of configWarnings(input)) {
|
|
571
|
+
options.onWarning?.(warning);
|
|
572
|
+
}
|
|
489
573
|
return input;
|
|
490
574
|
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { PortholeConfig } from "./schema.ts";
|
|
2
|
+
/**
|
|
3
|
+
* What a valid config says that its host likely didn't mean (the review of P100): never an error,
|
|
4
|
+
* since the config is the host's to write. Porthole logs nothing itself (no console in library
|
|
5
|
+
* code): `validateConfig(config, { onWarning })` hands each one over, and `compile(config).warnings`
|
|
6
|
+
* (`host.compiled.warnings`) holds them, for a host to log at startup or fail its tests on.
|
|
7
|
+
*/
|
|
8
|
+
export interface ConfigWarning {
|
|
9
|
+
/** `model-context-unshown`: a capability whose defaults have `show` lost it to named gates. */
|
|
10
|
+
readonly code: "model-context-unshown";
|
|
11
|
+
readonly path: string;
|
|
12
|
+
readonly message: string;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Each warning `config` earns. Since 0.8 (P100), `setModelContext`'s defaults have `show`; a
|
|
16
|
+
* config that names its gates (one written for 0.7 did, to change the rate) and leaves `show` out
|
|
17
|
+
* sends content's text to the model unseen, so it is said, unless `withoutShow: true` says the
|
|
18
|
+
* host meant it (its handler shows the person each update, or the content is its own).
|
|
19
|
+
*/
|
|
20
|
+
export declare function configWarnings(config: PortholeConfig): readonly ConfigWarning[];
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { capabilitySpec, isCapabilityName } from "./capabilities.js";
|
|
2
|
+
/**
|
|
3
|
+
* Each warning `config` earns. Since 0.8 (P100), `setModelContext`'s defaults have `show`; a
|
|
4
|
+
* config that names its gates (one written for 0.7 did, to change the rate) and leaves `show` out
|
|
5
|
+
* sends content's text to the model unseen, so it is said, unless `withoutShow: true` says the
|
|
6
|
+
* host meant it (its handler shows the person each update, or the content is its own).
|
|
7
|
+
*/
|
|
8
|
+
export function configWarnings(config) {
|
|
9
|
+
const warnings = [];
|
|
10
|
+
for (const [name, capability] of Object.entries(config.capabilities)) {
|
|
11
|
+
if (!isCapabilityName(name) ||
|
|
12
|
+
capability?.gates === undefined ||
|
|
13
|
+
!capabilitySpec(name).defaultGates.includes("show") ||
|
|
14
|
+
capability.gates.includes("show") ||
|
|
15
|
+
capability.withoutShow === true) {
|
|
16
|
+
continue;
|
|
17
|
+
}
|
|
18
|
+
warnings.push({
|
|
19
|
+
code: "model-context-unshown",
|
|
20
|
+
path: `config.capabilities.${name}.gates`,
|
|
21
|
+
message: `${name}'s gates leave out "show" (P100): what content tells the model reaches it without the person seeing it. Add "show" to the gates, or set withoutShow: true where your handler shows the person each update itself.`,
|
|
22
|
+
});
|
|
23
|
+
}
|
|
24
|
+
return warnings;
|
|
25
|
+
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { expect } from "@playwright/test";
|
|
2
2
|
import { presets } from "../presets/presets.js";
|
|
3
3
|
import { resolveTheme } from "../theme/variables.js";
|
|
4
|
-
import { inline } from "./kit.js";
|
|
4
|
+
import { inline, js } from "./kit.js";
|
|
5
5
|
import { settle } from "./oracles.js";
|
|
6
6
|
/**
|
|
7
7
|
* The display's behavior in a real frame (item 11: streaming, sizing, theming, base styles) and
|
|
@@ -52,6 +52,19 @@ async function bodyData(display, name, timeout = 5_000) {
|
|
|
52
52
|
.not.toBeNull();
|
|
53
53
|
return (await frame.locator("body").getAttribute(`data-${name}`)) ?? "";
|
|
54
54
|
}
|
|
55
|
+
/** A model context update (P100): what the view says the person is looking at. */
|
|
56
|
+
const CONTEXT_UPDATE = {
|
|
57
|
+
content: [{ type: "text", text: "The person is looking at March's signups." }],
|
|
58
|
+
structuredContent: { month: "March", signups: 412 },
|
|
59
|
+
};
|
|
60
|
+
/** Content that sends it as the App SDK does (`ui/update-model-context`), and keeps the answer. */
|
|
61
|
+
const CONTEXT_CONTENT = `<p>signups</p>
|
|
62
|
+
<script>
|
|
63
|
+
addEventListener("message", (event) => {
|
|
64
|
+
if (event.data && event.data.id === "ctx-1") document.body.dataset.answer = JSON.stringify(event.data.error ? event.data.error.data : event.data.result);
|
|
65
|
+
});
|
|
66
|
+
parent.postMessage({ jsonrpc: "2.0", id: "ctx-1", method: "ui/update-model-context", params: ${js(CONTEXT_UPDATE)} }, "*");
|
|
67
|
+
</script>`;
|
|
55
68
|
const PROMPT_CONTENT = `<button id="ask">Explain March</button>
|
|
56
69
|
<script>
|
|
57
70
|
document.getElementById("ask").addEventListener("click", () => {
|
|
@@ -436,4 +449,36 @@ export const BEHAVIOR_PROBES = [
|
|
|
436
449
|
expect(await display.calls()).toEqual([]);
|
|
437
450
|
},
|
|
438
451
|
},
|
|
452
|
+
{
|
|
453
|
+
id: "12.model-context",
|
|
454
|
+
item: 12,
|
|
455
|
+
title: "what content tells the model, the person is shown first, whole; a host that can't show it gets none (S5, P100)",
|
|
456
|
+
async run(context) {
|
|
457
|
+
const config = inline({ capabilities: { setModelContext: {} } });
|
|
458
|
+
const display = await context.launch({ config, content: CONTEXT_CONTENT });
|
|
459
|
+
const said = display.shown?.bind(display);
|
|
460
|
+
if (said === undefined) {
|
|
461
|
+
return context.inapplicable("this host's harness doesn't say what it shows the person (LaunchedDisplay.shown)");
|
|
462
|
+
}
|
|
463
|
+
expect(await bodyData(display, "answer")).toBe("{}");
|
|
464
|
+
const shown = await said();
|
|
465
|
+
expect(shown, "the update reached the model unseen").toHaveLength(1);
|
|
466
|
+
expect(shown[0]).toMatchObject({
|
|
467
|
+
capability: "setModelContext",
|
|
468
|
+
args: CONTEXT_UPDATE,
|
|
469
|
+
display: { title: "Probe" },
|
|
470
|
+
});
|
|
471
|
+
expect(await display.calls()).toEqual([
|
|
472
|
+
{ capability: "setModelContext", args: CONTEXT_UPDATE },
|
|
473
|
+
]);
|
|
474
|
+
const unseen = await context.launch({ config, shows: false, content: CONTEXT_CONTENT });
|
|
475
|
+
const answer = JSON.parse(await bodyData(unseen, "answer"));
|
|
476
|
+
if (answer.code === undefined && ((await unseen.shown?.()) ?? []).length > 0) {
|
|
477
|
+
return context.inapplicable("this host always has a show function (a default surface), so a display without one can't be shown; it showed the person instead");
|
|
478
|
+
}
|
|
479
|
+
expect(answer.code, "an update nobody could see was taken").toBe("not_allowed");
|
|
480
|
+
expect(await refusals(unseen)).toContain("setModelContext:no-show");
|
|
481
|
+
expect(await unseen.calls()).toEqual([]);
|
|
482
|
+
},
|
|
483
|
+
},
|
|
439
484
|
];
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { Page } from "@playwright/test";
|
|
2
|
+
/**
|
|
3
|
+
* Whether this browser keeps a cookie a cross-site frame's own document was answered with
|
|
4
|
+
* (P025, P098): what a framed url-mode app needs, since its every request rides on the cookie its
|
|
5
|
+
* ticket's answer set. Measured, never assumed from the engine's name: Playwright's WebKit keeps
|
|
6
|
+
* none on Linux and keeps them on macOS (the audit of 2026-10-19), and an engine's policy changes
|
|
7
|
+
* between versions.
|
|
8
|
+
*
|
|
9
|
+
* The probe is the browser's own, outside the host under test: in a context of its own, a page on
|
|
10
|
+
* one site frames a page on another (both answered by the probe's routes, never the network,
|
|
11
|
+
* never the host's server), whose answer sets a cookie as Porthole's server sets a framed one
|
|
12
|
+
* (`Secure; SameSite=None; Partitioned`, over the display's own scheme); the frame then reads
|
|
13
|
+
* whether it was kept. Asked once per browser.
|
|
14
|
+
*/
|
|
15
|
+
export declare function keepsFramedCookies(page: Page, scheme: "http:" | "https:"): Promise<boolean>;
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether this browser keeps a cookie a cross-site frame's own document was answered with
|
|
3
|
+
* (P025, P098): what a framed url-mode app needs, since its every request rides on the cookie its
|
|
4
|
+
* ticket's answer set. Measured, never assumed from the engine's name: Playwright's WebKit keeps
|
|
5
|
+
* none on Linux and keeps them on macOS (the audit of 2026-10-19), and an engine's policy changes
|
|
6
|
+
* between versions.
|
|
7
|
+
*
|
|
8
|
+
* The probe is the browser's own, outside the host under test: in a context of its own, a page on
|
|
9
|
+
* one site frames a page on another (both answered by the probe's routes, never the network,
|
|
10
|
+
* never the host's server), whose answer sets a cookie as Porthole's server sets a framed one
|
|
11
|
+
* (`Secure; SameSite=None; Partitioned`, over the display's own scheme); the frame then reads
|
|
12
|
+
* whether it was kept. Asked once per browser.
|
|
13
|
+
*/
|
|
14
|
+
export function keepsFramedCookies(page, scheme) {
|
|
15
|
+
const browser = page.context().browser();
|
|
16
|
+
const key = `${scheme} ${browser === null ? "persistent" : browser.version()}`;
|
|
17
|
+
const known = cache(browser ?? page.context());
|
|
18
|
+
let answer = known.get(key);
|
|
19
|
+
if (answer === undefined) {
|
|
20
|
+
answer = probe(browser, page.context(), scheme);
|
|
21
|
+
known.set(key, answer);
|
|
22
|
+
}
|
|
23
|
+
return answer;
|
|
24
|
+
}
|
|
25
|
+
const answers = new WeakMap();
|
|
26
|
+
function cache(owner) {
|
|
27
|
+
let known = answers.get(owner);
|
|
28
|
+
if (known === undefined) {
|
|
29
|
+
known = new Map();
|
|
30
|
+
answers.set(owner, known);
|
|
31
|
+
}
|
|
32
|
+
return known;
|
|
33
|
+
}
|
|
34
|
+
/** Two sites the probe makes up: the embedding page's, and the frame's. */
|
|
35
|
+
function sites(scheme) {
|
|
36
|
+
// Over http, as a loopback host and its content origins are (a `*.localhost` frame on a
|
|
37
|
+
// `127.0.0.1` page, the leak suite's own shape); over https, two names that are each a site.
|
|
38
|
+
// Default ports: a browser refuses to navigate to some others (9 is on Fetch's bad-port list).
|
|
39
|
+
return scheme === "http:"
|
|
40
|
+
? {
|
|
41
|
+
top: "http://127.0.0.1/__porthole-cookie-probe/",
|
|
42
|
+
framed: "http://porthole-cookie-probe.localhost/",
|
|
43
|
+
}
|
|
44
|
+
: {
|
|
45
|
+
top: "https://porthole-cookie-probe-top.test/",
|
|
46
|
+
framed: "https://porthole-cookie-probe-frame.test/",
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
async function probe(browser, context, scheme) {
|
|
50
|
+
const own = browser === null ? null : await browser.newContext();
|
|
51
|
+
const page = await (own ?? context).newPage();
|
|
52
|
+
try {
|
|
53
|
+
const { top, framed } = sites(scheme);
|
|
54
|
+
await page.route(`${framed}**`, (route) => route.fulfill({
|
|
55
|
+
status: 200,
|
|
56
|
+
headers: {
|
|
57
|
+
"content-type": "text/html; charset=utf-8",
|
|
58
|
+
"cache-control": "no-store",
|
|
59
|
+
"set-cookie": "porthole-cookie-probe=1; Path=/; Secure; SameSite=None; Partitioned",
|
|
60
|
+
},
|
|
61
|
+
body: "<!doctype html><title>probe</title>",
|
|
62
|
+
}));
|
|
63
|
+
await page.route(top, (route) => route.fulfill({
|
|
64
|
+
status: 200,
|
|
65
|
+
headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
|
|
66
|
+
body: `<!doctype html><title>probe</title><iframe src="${framed}frame"></iframe>`,
|
|
67
|
+
}));
|
|
68
|
+
await page.goto(top);
|
|
69
|
+
const frame = await (await page.locator("iframe").elementHandle())?.contentFrame();
|
|
70
|
+
if (frame === null || frame === undefined) {
|
|
71
|
+
throw new Error("keepsFramedCookies: the probe's frame didn't load");
|
|
72
|
+
}
|
|
73
|
+
await frame.waitForLoadState("load");
|
|
74
|
+
return await frame.evaluate(() => document.cookie.includes("porthole-cookie-probe=1"));
|
|
75
|
+
}
|
|
76
|
+
finally {
|
|
77
|
+
await page.close();
|
|
78
|
+
await own?.close();
|
|
79
|
+
}
|
|
80
|
+
}
|
|
@@ -21,6 +21,7 @@ declare const harness: {
|
|
|
21
21
|
post(id: number, message: unknown): void;
|
|
22
22
|
setContent(id: number, html: string, partial: boolean): void;
|
|
23
23
|
calls: (id: number) => RecordedCall[];
|
|
24
|
+
shown: (id: number) => ConfirmRequest[];
|
|
24
25
|
events: (id: number) => RecordedEvent[];
|
|
25
26
|
errors: (id: number) => string[];
|
|
26
27
|
pendingConfirmations: (id: number) => number;
|
|
@@ -78,6 +78,7 @@ const harness = {
|
|
|
78
78
|
const container = box(id, spec.widthPx ?? 600, spec.heightPx);
|
|
79
79
|
const calls = [];
|
|
80
80
|
const confirmations = [];
|
|
81
|
+
const disclosed = [];
|
|
81
82
|
const host = createHost(spec.config, {
|
|
82
83
|
handlers: recorder(calls),
|
|
83
84
|
...(spec.confirms === false
|
|
@@ -85,6 +86,9 @@ const harness = {
|
|
|
85
86
|
: {
|
|
86
87
|
confirm: (request) => new Promise((resolve) => confirmations.push({ request, resolve })),
|
|
87
88
|
}),
|
|
89
|
+
...(spec.shows === false
|
|
90
|
+
? {}
|
|
91
|
+
: { show: (request) => void disclosed.push(request) }),
|
|
88
92
|
theme: (scheme) => spec.hostTheme?.[scheme] ?? {},
|
|
89
93
|
hostInfo: { name: "porthole-conformance", version: "1" },
|
|
90
94
|
...(nonce === undefined ? {} : { nonce }),
|
|
@@ -95,18 +99,19 @@ const harness = {
|
|
|
95
99
|
scheme: spec.scheme ?? "light",
|
|
96
100
|
...(spec.document === undefined ? {} : { document: spec.document }),
|
|
97
101
|
});
|
|
98
|
-
const
|
|
102
|
+
const display = {
|
|
99
103
|
handle,
|
|
100
104
|
calls,
|
|
101
105
|
events: [],
|
|
102
106
|
confirmations,
|
|
107
|
+
disclosed,
|
|
103
108
|
received: [],
|
|
104
109
|
origin: null,
|
|
105
110
|
failure: null,
|
|
106
111
|
frame: null,
|
|
107
112
|
};
|
|
108
113
|
const initialized = new Promise((resolve) => handle.on("initialized", () => resolve()));
|
|
109
|
-
watch(id,
|
|
114
|
+
watch(id, display);
|
|
110
115
|
if (spec.document === undefined) {
|
|
111
116
|
await Promise.race([initialized, pause(5_000)]);
|
|
112
117
|
for (const partial of spec.partials ?? []) {
|
|
@@ -133,6 +138,7 @@ const harness = {
|
|
|
133
138
|
calls,
|
|
134
139
|
events: [],
|
|
135
140
|
confirmations: [],
|
|
141
|
+
disclosed: [],
|
|
136
142
|
received: [],
|
|
137
143
|
origin: null,
|
|
138
144
|
failure: null,
|
|
@@ -194,6 +200,7 @@ const harness = {
|
|
|
194
200
|
displays.get(id)?.handle.setContent(html, { partial });
|
|
195
201
|
},
|
|
196
202
|
calls: (id) => displays.get(id)?.calls ?? [],
|
|
203
|
+
shown: (id) => displays.get(id)?.disclosed ?? [],
|
|
197
204
|
events: (id) => displays.get(id)?.events ?? [],
|
|
198
205
|
errors: (id) => (displays.get(id)?.events ?? []).flatMap((event) => event.type === "error" ? [event.detail.message] : []),
|
|
199
206
|
pendingConfirmations: (id) => displays.get(id)?.confirmations.length ?? 0,
|