@botiverse/porthole 0.15.3 → 0.16.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/CHANGELOG.md +58 -0
- package/dist/bridge/bridge.d.ts +1 -8
- package/dist/bridge/bridge.js +0 -7
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +1 -1
- package/dist/compile/policy.d.ts +0 -7
- package/dist/compile/policy.js +1 -10
- package/dist/config/capabilities.d.ts +8 -14
- package/dist/config/capabilities.js +4 -5
- package/dist/config/schema.d.ts +2 -13
- package/dist/config/validate.js +0 -24
- package/dist/conformance/behavior.js +26 -37
- package/dist/conformance/clipboard.js +47 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +1 -3
- package/dist/guide/limits.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +1 -1
- package/dist/host/create-host.js +6 -51
- package/dist/host/door.d.ts +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +5 -12
- package/dist/host/outcome.js +8 -16
- package/dist/host/types.d.ts +6 -22
- package/dist/index.d.ts +2 -4
- package/dist/index.js +2 -4
- package/dist/isolation/served.d.ts +4 -14
- package/dist/isolation/served.js +7 -28
- package/dist/isolation/types.d.ts +2 -25
- package/dist/isolation/types.js +0 -23
- package/dist/platform/focus-field.d.ts +11 -0
- package/dist/platform/focus-field.js +18 -0
- package/dist/platform/types.d.ts +6 -22
- package/dist/platform/web.js +8 -106
- package/dist/presets/presets.d.ts +0 -2
- package/dist/presets/presets.js +0 -1
- package/dist/react/frame.d.ts +0 -8
- package/dist/react/frame.js +0 -4
- package/dist/runtime/contract.d.ts +2 -2
- package/dist/runtime/contract.js +2 -2
- package/dist/runtime/types.generated.js +6 -6
- package/dist/server/files.js +7 -23
- package/dist/server/host.d.ts +1 -1
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +4 -6
- package/dist/server/naming.js +1 -1
- package/dist/server/server.js +28 -166
- package/dist/server/types.d.ts +7 -7
- package/dist/shell/plan.d.ts +0 -5
- package/dist/shell/plan.js +2 -4
- package/dist/shell/runtime.js +1 -268
- package/docs/ADOPTING.md +42 -138
- package/docs/ARCHITECTURE.md +0 -33
- package/docs/DECISIONS.md +115 -10
- package/docs/DESIGN.md +27 -64
- package/docs/THREAT_MODEL.md +128 -255
- package/package.json +1 -1
- package/src/bridge/bridge.ts +1 -17
- package/src/check/page.ts +1 -1
- package/src/compile/policy.ts +1 -11
- package/src/config/capabilities.ts +8 -14
- package/src/config/schema.ts +2 -13
- package/src/config/validate.ts +0 -28
- package/src/conformance/behavior.ts +50 -52
- package/src/conformance/clipboard.ts +56 -1
- package/src/displays/displays.ts +1 -3
- package/src/guide/limits.ts +1 -1
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +6 -52
- package/src/host/door.ts +1 -1
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +8 -21
- package/src/host/types.ts +6 -20
- package/src/index.ts +2 -4
- package/src/isolation/served.ts +6 -34
- package/src/isolation/types.ts +2 -31
- package/src/platform/focus-field.ts +18 -0
- package/src/platform/types.ts +6 -21
- package/src/platform/web.ts +8 -129
- package/src/presets/presets.ts +0 -3
- package/src/react/frame.tsx +0 -10
- package/src/runtime/contract.ts +4 -4
- package/src/runtime/types.generated.ts +6 -6
- package/src/server/files.ts +4 -19
- package/src/server/host.ts +1 -1
- package/src/server/index.ts +4 -16
- package/src/server/naming.ts +1 -1
- package/src/server/server.ts +29 -189
- package/src/server/types.ts +7 -7
- package/src/shell/plan.ts +2 -9
- package/src/shell/runtime.ts +1 -268
- package/types/runtime/v1/artifact.d.ts +2 -3
- package/types/runtime/v1/assets.d.ts +1 -1
- package/types/runtime/v1/chat.d.ts +2 -2
- package/types/runtime/v1/comments.d.ts +1 -1
- package/types/runtime/v1/downloads.d.ts +2 -2
- package/types/runtime/v1/links.d.ts +2 -2
- package/dist/platform/focus-guard.d.ts +0 -288
- package/dist/platform/focus-guard.js +0 -838
- package/dist/server/nested.d.ts +0 -66
- package/dist/server/nested.js +0 -121
- package/dist/shell/frame.d.ts +0 -28
- package/dist/shell/frame.js +0 -407
- package/src/platform/focus-guard.ts +0 -1114
- package/src/server/nested.ts +0 -157
- package/src/shell/frame.ts +0 -444
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.16.0",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
package/src/bridge/bridge.ts
CHANGED
|
@@ -73,8 +73,7 @@ import type {
|
|
|
73
73
|
* every capability its host function's own rate (P091, P095) → arguments well formed and within
|
|
74
74
|
* their limits → who may (P087: the level of each method the call runs for the viewer, a page's
|
|
75
75
|
* named data with or without a viewer, db's rules) → not muted, if confirm-gated → the own rate
|
|
76
|
-
* of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so
|
|
77
|
-
* for `comments`, the host page's focus in the calling frame: P109) → the
|
|
76
|
+
* of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so → the
|
|
78
77
|
* viewer's consent, if gated so → a person's confirmation, if gated so (at most 10 waiting) →
|
|
79
78
|
* shown to the person, if gated so (P100) → the handler (or, for a read, a result the host already
|
|
80
79
|
* gave for it, or for a stale-allowed one the host's cache).
|
|
@@ -111,12 +110,6 @@ export interface BridgeOptions {
|
|
|
111
110
|
readonly cached?: DataCache;
|
|
112
111
|
/** Whether the embedding page has user activation now; undefined where it can't tell. */
|
|
113
112
|
readonly userActivation?: () => boolean | undefined;
|
|
114
|
-
/**
|
|
115
|
-
* Whether the embedding page's focus is in this display's frame now (P109); undefined where it
|
|
116
|
-
* can't tell. A capability whose gesture must be in its frame (`inFrame`: `comments`) is refused
|
|
117
|
-
* without it.
|
|
118
|
-
*/
|
|
119
|
-
readonly focused?: () => boolean | undefined;
|
|
120
113
|
readonly onEvent: (event: BridgeEvent) => void;
|
|
121
114
|
/** The clock, in milliseconds (tests pass their own). */
|
|
122
115
|
readonly now?: () => number;
|
|
@@ -136,10 +129,6 @@ export interface BridgeOptions {
|
|
|
136
129
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
137
130
|
value !== null && typeof value === "object" && !Array.isArray(value);
|
|
138
131
|
|
|
139
|
-
/** Whether `capability`'s gesture must be in its own frame (P109: the host page's focus there). */
|
|
140
|
-
const inFrame = (capability: CapabilityName): boolean =>
|
|
141
|
-
capabilitySpec(capability).inFrame === true;
|
|
142
|
-
|
|
143
132
|
const MAX_URL = 4_096;
|
|
144
133
|
|
|
145
134
|
/**
|
|
@@ -669,11 +658,6 @@ export function createBridge(options: BridgeOptions): DisplayBridge {
|
|
|
669
658
|
if (activated === false) {
|
|
670
659
|
return refuse<Result>(capability, "no-user-activation");
|
|
671
660
|
}
|
|
672
|
-
// A gesture in this frame, not anywhere on the host's page (P109): the person typing in
|
|
673
|
-
// the host's composer gives its page activation, which a frame's call would borrow.
|
|
674
|
-
if (inFrame(capability) && options.focused?.() === false) {
|
|
675
|
-
return refuse<Result>(capability, "no-user-activation");
|
|
676
|
-
}
|
|
677
661
|
}
|
|
678
662
|
if (gates.includes("consent")) {
|
|
679
663
|
const consent = options.consent;
|
package/src/check/page.ts
CHANGED
|
@@ -63,7 +63,7 @@ const NOBODY: PlatformHost = {
|
|
|
63
63
|
return { ...surface, userActivation: () => false };
|
|
64
64
|
},
|
|
65
65
|
// A served display's door (P125), as the web platform makes it: a platform without doors frames
|
|
66
|
-
// no served display
|
|
66
|
+
// no served display.
|
|
67
67
|
createDoor: (container, spec) => webPlatform.createDoor!(container, spec),
|
|
68
68
|
};
|
|
69
69
|
|
package/src/compile/policy.ts
CHANGED
|
@@ -234,8 +234,6 @@ export function sandboxTokens(config: PortholeConfig): string[] {
|
|
|
234
234
|
case "opaque":
|
|
235
235
|
return ["allow-scripts"];
|
|
236
236
|
case "domain":
|
|
237
|
-
// Nested (P111), this frame holds Porthole's shell, on a label of its own where no content
|
|
238
|
-
// runs with this origin (P114), and the page is the shell's child (`PAGE_SANDBOX_TOKENS`).
|
|
239
237
|
return ["allow-scripts", "allow-same-origin"];
|
|
240
238
|
case "external":
|
|
241
239
|
// The host may add a documented few (popups, modals, downloads), never top navigation.
|
|
@@ -257,17 +255,9 @@ export function servedSandboxDirective(config: PortholeConfig): CspDirective | n
|
|
|
257
255
|
if (config.isolation !== "domain") {
|
|
258
256
|
return null;
|
|
259
257
|
}
|
|
260
|
-
return ["sandbox", ...
|
|
258
|
+
return ["sandbox", ...sandboxTokens(config)];
|
|
261
259
|
}
|
|
262
260
|
|
|
263
|
-
/**
|
|
264
|
-
* A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
|
|
265
|
-
* header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
|
|
266
|
-
* only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
|
|
267
|
-
* so the shell's realm (a test holds every sandbox Porthole writes to this).
|
|
268
|
-
*/
|
|
269
|
-
export const PAGE_SANDBOX_TOKENS: readonly string[] = ["allow-scripts"];
|
|
270
|
-
|
|
271
261
|
/**
|
|
272
262
|
* A served display's door's sandbox (P125): its frame's attribute, which the host writes, and its
|
|
273
263
|
* answer's CSP header's. Scripts only: an opaque origin, a new one each time, that no content of
|
|
@@ -53,8 +53,10 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
|
53
53
|
* propagates to, and which lasts 5 s after any gesture anywhere on the host's page: a click on
|
|
54
54
|
* the host's own UI, or the person typing in its own composer, counts. So it stops calls made on
|
|
55
55
|
* load, or on a timer while nobody does anything; it is not proof that the gesture was in this
|
|
56
|
-
* frame, nor of intent.
|
|
57
|
-
*
|
|
56
|
+
* frame, nor of intent. Since 0.16.0 (P149) only `copyText` has it by default: nothing else
|
|
57
|
+
* stands between a page and the person's clipboard. Every other call either shows the person
|
|
58
|
+
* its whole effect first (`confirm`) or opens something of the host's that does nothing by
|
|
59
|
+
* itself (`comments`), and a guess at who pressed what refused real presses.
|
|
58
60
|
* - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
|
|
59
61
|
* goes only if they accept. No `confirm` function means the call is refused (fail closed).
|
|
60
62
|
* - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
|
|
@@ -89,13 +91,6 @@ export interface CapabilitySpec {
|
|
|
89
91
|
* Absent for what the shell does by itself (sizes, errors, annotations, find).
|
|
90
92
|
*/
|
|
91
93
|
readonly request?: { readonly method: string; readonly sdk?: string };
|
|
92
|
-
/**
|
|
93
|
-
* Its `user-activation` gate also needs the person in the calling frame (P109): the host page's
|
|
94
|
-
* focus in that frame, which a press on it or a Tab into it gives and the focus guard keeps from
|
|
95
|
-
* a frame's own `focus()`. Activation alone lasts 5 s after any gesture on the host's page,
|
|
96
|
-
* typing in its own composer included.
|
|
97
|
-
*/
|
|
98
|
-
readonly inFrame?: true;
|
|
99
94
|
}
|
|
100
95
|
|
|
101
96
|
const rate = (perMinute: number): Gate => ({ rateLimit: { perMinute } });
|
|
@@ -111,19 +106,19 @@ export const MAX_CONTEXT_CHARS = 20_000;
|
|
|
111
106
|
|
|
112
107
|
export const CAPABILITIES = {
|
|
113
108
|
sendPrompt: {
|
|
114
|
-
defaultGates: ["
|
|
109
|
+
defaultGates: ["confirm", rate(30)],
|
|
115
110
|
served: "handler",
|
|
116
111
|
global: "sendPrompt",
|
|
117
112
|
request: { method: "ui/message", sdk: "app.sendMessage" },
|
|
118
113
|
},
|
|
119
114
|
openLink: {
|
|
120
|
-
defaultGates: ["
|
|
115
|
+
defaultGates: ["confirm", rate(30)],
|
|
121
116
|
served: "handler",
|
|
122
117
|
global: "openLink",
|
|
123
118
|
request: { method: "ui/open-link", sdk: "app.openLink" },
|
|
124
119
|
},
|
|
125
120
|
downloadFile: {
|
|
126
|
-
defaultGates: ["
|
|
121
|
+
defaultGates: ["confirm", rate(30)],
|
|
127
122
|
served: "handler",
|
|
128
123
|
request: { method: "ui/download-file", sdk: "app.downloadFile" },
|
|
129
124
|
},
|
|
@@ -188,10 +183,9 @@ export const CAPABILITIES = {
|
|
|
188
183
|
user: { defaultGates: [rate(60)], served: "viewer", request: { method: "porthole/call" } },
|
|
189
184
|
/** Opens the host's comment composer at the page's anchor (P090): write-only. */
|
|
190
185
|
comments: {
|
|
191
|
-
defaultGates: [
|
|
186
|
+
defaultGates: [rate(30)],
|
|
192
187
|
served: "handler",
|
|
193
188
|
request: { method: "porthole/call" },
|
|
194
|
-
inFrame: true,
|
|
195
189
|
},
|
|
196
190
|
/** This artifact's current version, and a new version of it, base-checked (P088). */
|
|
197
191
|
artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
|
package/src/config/schema.ts
CHANGED
|
@@ -258,17 +258,6 @@ export interface PortholeConfig {
|
|
|
258
258
|
* `db`). Absent: 0.6's frames, globals and manual, exactly.
|
|
259
259
|
*/
|
|
260
260
|
readonly runtime?: RuntimeVersion;
|
|
261
|
-
/**
|
|
262
|
-
* Domain isolation, artifact pages (P111): the address the host frames serves Porthole's shell
|
|
263
|
-
* alone, a document of Porthole's own with no content in it, and the page runs in a child frame
|
|
264
|
-
* of the shell's, sandboxed without `allow-same-origin` (an opaque origin), served from the same
|
|
265
|
-
* origin at its files' sealed address. The shell is then a realm the page can't reach, above the
|
|
266
|
-
* page's frame: it relays the page's messages, and tells the host when its own transient
|
|
267
|
-
* activation turns on (a press in the page activates its ancestors only), which is how the host
|
|
268
|
-
* knows the person, not the page, moved the keyboard into the frame or opened a comment. The
|
|
269
|
-
* page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
|
|
270
|
-
*/
|
|
271
|
-
readonly nested?: true;
|
|
272
261
|
/**
|
|
273
262
|
* Which nested frames content may make (P128). `none` (default, and absent): the shell removes
|
|
274
263
|
* every frame-like element content adds, and the CSP's `frame-src` is `'none'`. `own`: an
|
|
@@ -278,8 +267,8 @@ export interface PortholeConfig {
|
|
|
278
267
|
* A weakening, opted into: a child frame is a realm of its own, where the shell's WebRTC
|
|
279
268
|
* removal, clipboard guards and navigation cancel never ran (a page of the set framed there has
|
|
280
269
|
* its own shell; a `srcdoc` frame, or the `about:blank` a new frame starts as, has none), so
|
|
281
|
-
* content reaches WebRTC and the clipboard's events there. Not for url mode
|
|
282
|
-
* (no network of its own, P079)
|
|
270
|
+
* content reaches WebRTC and the clipboard's events there. Not for url mode or a live widget
|
|
271
|
+
* (no network of its own, P079).
|
|
283
272
|
*/
|
|
284
273
|
readonly nestedFrames?: "none" | "own";
|
|
285
274
|
}
|
package/src/config/validate.ts
CHANGED
|
@@ -324,7 +324,6 @@ export function validateConfig(
|
|
|
324
324
|
"storage",
|
|
325
325
|
"errors",
|
|
326
326
|
"runtime",
|
|
327
|
-
"nested",
|
|
328
327
|
"nestedFrames",
|
|
329
328
|
],
|
|
330
329
|
"config",
|
|
@@ -689,28 +688,6 @@ export function validateConfig(
|
|
|
689
688
|
}
|
|
690
689
|
}
|
|
691
690
|
|
|
692
|
-
if (config.nested !== undefined) {
|
|
693
|
-
if (config.nested !== true) {
|
|
694
|
-
fail("config.nested", "must be true, or left out");
|
|
695
|
-
}
|
|
696
|
-
if (config.isolation !== "domain" || config.mode !== "artifact") {
|
|
697
|
-
fail("config.nested", "nests artifact pages served on their own origin (domain isolation)");
|
|
698
|
-
}
|
|
699
|
-
// The page's origin is opaque (P111): nothing of the content origin's own is its.
|
|
700
|
-
if (config.storage !== undefined) {
|
|
701
|
-
fail("config.nested", "a nested page keeps no storage: drop config.storage");
|
|
702
|
-
}
|
|
703
|
-
if (capabilities.assets !== undefined) {
|
|
704
|
-
fail(
|
|
705
|
-
"config.nested",
|
|
706
|
-
"a nested page can't load its asset library (/_blob/) yet: drop assets",
|
|
707
|
-
);
|
|
708
|
-
}
|
|
709
|
-
if (isObject(config.egress) && config.egress.libraries === true) {
|
|
710
|
-
fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
|
|
711
|
-
}
|
|
712
|
-
}
|
|
713
|
-
|
|
714
691
|
// A page's own nested frames (P128): opted into, never a default.
|
|
715
692
|
if (config.nestedFrames !== undefined) {
|
|
716
693
|
if (config.nestedFrames !== "none" && config.nestedFrames !== "own") {
|
|
@@ -719,11 +696,6 @@ export function validateConfig(
|
|
|
719
696
|
if (config.nestedFrames === "own" && config.mode === "url") {
|
|
720
697
|
fail("config.nestedFrames", "url mode has no shell: its app's frames are its own");
|
|
721
698
|
}
|
|
722
|
-
// A nested page's frames have an opaque ancestor, which no frame-ancestors source matches:
|
|
723
|
-
// none of its own files would load in one. Not measured yet.
|
|
724
|
-
if (config.nestedFrames === "own" && config.nested === true) {
|
|
725
|
-
fail("config.nestedFrames", 'a nested page (P111) has no "own" frames yet: leave it out');
|
|
726
|
-
}
|
|
727
699
|
}
|
|
728
700
|
|
|
729
701
|
if (config.errors !== undefined) {
|
|
@@ -49,28 +49,6 @@ async function click(display: LaunchedDisplay, selector: string): Promise<void>
|
|
|
49
49
|
await (await display.frame()).locator(selector).click();
|
|
50
50
|
}
|
|
51
51
|
|
|
52
|
-
/**
|
|
53
|
-
* Lets any user activation the test harness gave the host page lapse: Playwright's own
|
|
54
|
-
* evaluations count as gestures in some engines, and Chromium keeps one for 5 s. Between this and
|
|
55
|
-
* the next raw input, the test must not evaluate anything in the page.
|
|
56
|
-
*/
|
|
57
|
-
const ACTIVATION_LAPSE_MS = 6_000;
|
|
58
|
-
|
|
59
|
-
/** A click by raw mouse input at `selector`'s center, after any harness activation has lapsed. */
|
|
60
|
-
async function clickAfterLapse(
|
|
61
|
-
context: ProbeContext,
|
|
62
|
-
display: LaunchedDisplay,
|
|
63
|
-
selector: string,
|
|
64
|
-
): Promise<void> {
|
|
65
|
-
const frame = await display.frame();
|
|
66
|
-
const box = await frame.locator(selector).boundingBox();
|
|
67
|
-
if (box === null) {
|
|
68
|
-
throw new Error(`${selector} is not on screen`);
|
|
69
|
-
}
|
|
70
|
-
await context.page.waitForTimeout(ACTIVATION_LAPSE_MS);
|
|
71
|
-
await context.page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
|
|
72
|
-
}
|
|
73
|
-
|
|
74
52
|
/**
|
|
75
53
|
* The attribute `name` of the frame's body, once set. Where it is a gate's answer to the content,
|
|
76
54
|
* `verdict` is the probe's: an answer that never comes (a call left waiting on a gate that should
|
|
@@ -130,8 +108,13 @@ const PROMPT_CONTENT = `<button id="ask">Explain March</button>
|
|
|
130
108
|
(error) => (document.body.dataset.result = "refused: " + error.message),
|
|
131
109
|
);
|
|
132
110
|
});
|
|
111
|
+
</script>`;
|
|
112
|
+
|
|
113
|
+
/** A prompt asked as the page loads, with no click anywhere. */
|
|
114
|
+
const PROMPT_ON_LOAD = `<p>Asks on load</p>
|
|
115
|
+
<script>
|
|
133
116
|
sendPrompt("asked on load").then(
|
|
134
|
-
() => (document.body.dataset.onload =
|
|
117
|
+
(sent) => (document.body.dataset.onload = String(sent)),
|
|
135
118
|
(error) => (document.body.dataset.onload = "refused: " + error.message),
|
|
136
119
|
);
|
|
137
120
|
</script>`;
|
|
@@ -466,29 +449,36 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
|
|
|
466
449
|
|
|
467
450
|
// ── 12: the host-function gates ────────────────────────────────────────────────────────────
|
|
468
451
|
{
|
|
469
|
-
id: "12.prompt-
|
|
452
|
+
id: "12.prompt-confirm",
|
|
470
453
|
item: 12,
|
|
471
|
-
title: "sendPrompt needs
|
|
454
|
+
title: "sendPrompt needs the person's yes, from a click or not; a no sends nothing",
|
|
472
455
|
async run(context) {
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
456
|
+
// No proof of a click is asked (0.16.0, P149): a prompt made as the page loads is the
|
|
457
|
+
// person's to answer like any other, and their no sends nothing.
|
|
458
|
+
const loading = await context.launch({ config: prompts(), content: PROMPT_ON_LOAD });
|
|
459
|
+
const unasked = await answered(
|
|
460
|
+
loading,
|
|
461
|
+
false,
|
|
462
|
+
"probe: the person was asked about a prompt made on load",
|
|
463
|
+
);
|
|
464
|
+
expect(unasked, "probe: the person was asked about the whole prompt").toMatchObject({
|
|
465
|
+
capability: "sendPrompt",
|
|
466
|
+
args: { text: "asked on load" },
|
|
467
|
+
});
|
|
478
468
|
expect(
|
|
479
|
-
await
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
await
|
|
487
|
-
|
|
488
|
-
context.measured(
|
|
489
|
-
`${context.engine}: a click in the frame ${refused.includes("sendPrompt:no-user-activation") ? "does not reach" : "reaches"} the host page's user activation`,
|
|
469
|
+
await bodyData(
|
|
470
|
+
loading,
|
|
471
|
+
"onload",
|
|
472
|
+
"probe: the content is told a declined prompt wasn't sent",
|
|
473
|
+
),
|
|
474
|
+
"probe: the content is told a declined prompt wasn't sent",
|
|
475
|
+
).toBe("false");
|
|
476
|
+
expect(await loading.calls(), "probe: a declined prompt reached the host's handler").toEqual(
|
|
477
|
+
[],
|
|
490
478
|
);
|
|
491
|
-
|
|
479
|
+
|
|
480
|
+
const display = await context.launch({ config: prompts(), content: PROMPT_CONTENT });
|
|
481
|
+
await click(display, "#ask");
|
|
492
482
|
const declined = await answered(
|
|
493
483
|
display,
|
|
494
484
|
false,
|
|
@@ -522,7 +512,8 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
|
|
|
522
512
|
{
|
|
523
513
|
id: "12.raw-message",
|
|
524
514
|
item: 12,
|
|
525
|
-
title:
|
|
515
|
+
title:
|
|
516
|
+
"a prompt sent around the shell (raw ui/message, no click) is the person's to answer too; a no sends nothing",
|
|
526
517
|
async run(context) {
|
|
527
518
|
const display = await context.launch({
|
|
528
519
|
config: prompts(),
|
|
@@ -530,22 +521,29 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
|
|
|
530
521
|
addEventListener("message", (event) => {
|
|
531
522
|
if (event.data && event.data.id === "raw-1") document.body.dataset.answer = JSON.stringify(event.data.result ?? event.data.error);
|
|
532
523
|
});
|
|
533
|
-
|
|
534
|
-
setTimeout(() => parent.postMessage({ jsonrpc: "2.0", id: "raw-1", method: "ui/message", params: { role: "user", content: [{ type: "text", text: "sent around the shell" }] } }, "*"), ${ACTIVATION_LAPSE_MS});
|
|
524
|
+
parent.postMessage({ jsonrpc: "2.0", id: "raw-1", method: "ui/message", params: { role: "user", content: [{ type: "text", text: "sent around the shell" }] } }, "*");
|
|
535
525
|
</script>`,
|
|
536
526
|
});
|
|
537
|
-
|
|
538
|
-
|
|
527
|
+
const asked = await answered(
|
|
528
|
+
display,
|
|
529
|
+
false,
|
|
530
|
+
"probe: the person was asked about a raw ui/message",
|
|
531
|
+
);
|
|
532
|
+
expect(asked, "probe: the person was asked about the whole prompt").toMatchObject({
|
|
533
|
+
capability: "sendPrompt",
|
|
534
|
+
args: { text: "sent around the shell" },
|
|
535
|
+
});
|
|
539
536
|
expect(
|
|
540
|
-
await bodyData(
|
|
541
|
-
|
|
537
|
+
await bodyData(
|
|
538
|
+
display,
|
|
539
|
+
"answer",
|
|
540
|
+
"probe: a declined raw ui/message is answered as not sent",
|
|
541
|
+
),
|
|
542
|
+
"probe: a declined raw ui/message is answered as not sent",
|
|
542
543
|
).toBe(JSON.stringify({ isError: true }));
|
|
543
544
|
expect(await display.calls(), "probe: a raw ui/message reached the host's handler").toEqual(
|
|
544
545
|
[],
|
|
545
546
|
);
|
|
546
|
-
expect(await refusals(display), "probe: the host refused it for no user activation").toEqual([
|
|
547
|
-
"sendPrompt:no-user-activation",
|
|
548
|
-
]);
|
|
549
547
|
},
|
|
550
548
|
},
|
|
551
549
|
{
|
|
@@ -52,6 +52,20 @@ async function pasted(page: Page): Promise<string> {
|
|
|
52
52
|
);
|
|
53
53
|
}
|
|
54
54
|
|
|
55
|
+
/**
|
|
56
|
+
* Lets any user activation the test harness gave the host page lapse: Playwright's own
|
|
57
|
+
* evaluations count as gestures in some engines, and Chromium keeps one for 5 s. Between this and
|
|
58
|
+
* the next raw input, the test must not evaluate anything in the page.
|
|
59
|
+
*/
|
|
60
|
+
const ACTIVATION_LAPSE_MS = 6_000;
|
|
61
|
+
|
|
62
|
+
/** The refusals the display reported, by capability. */
|
|
63
|
+
async function refusals(display: LaunchedDisplay): Promise<string[]> {
|
|
64
|
+
return (await display.events()).flatMap((event) =>
|
|
65
|
+
event.type === "refused" ? [`${event.detail.capability}:${event.detail.refusal}`] : [],
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
|
|
55
69
|
/** Clicks `selector` in the display (a real click: the user activation a person gives). */
|
|
56
70
|
async function click(display: LaunchedDisplay, selector: string): Promise<void> {
|
|
57
71
|
await (await display.frame()).locator(selector).click();
|
|
@@ -206,7 +220,21 @@ export const CLIPBOARD_PROBES: readonly Probe[] = [
|
|
|
206
220
|
await bodyData(display, "onload", "probe: copyText without a click is refused"),
|
|
207
221
|
"probe: copyText without a click is refused",
|
|
208
222
|
).toMatch(/^refused/u);
|
|
209
|
-
|
|
223
|
+
// The host's own check needs the frame's click to reach the host page (activation
|
|
224
|
+
// propagates to ancestors): measured with raw input, after the harness's activation lapsed.
|
|
225
|
+
const frame = await display.frame();
|
|
226
|
+
const box = await frame.locator("#copy").boundingBox();
|
|
227
|
+
if (box === null) {
|
|
228
|
+
throw new Error("#copy is not on screen");
|
|
229
|
+
}
|
|
230
|
+
await context.page.waitForTimeout(ACTIVATION_LAPSE_MS);
|
|
231
|
+
await context.page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
|
|
232
|
+
await context.page.waitForTimeout(500);
|
|
233
|
+
const refused = await refusals(display);
|
|
234
|
+
context.measured(
|
|
235
|
+
`${context.engine}: a click in the frame ${refused.includes("copyText:no-user-activation") ? "does not reach" : "reaches"} the host page's user activation`,
|
|
236
|
+
);
|
|
237
|
+
expect(refused, "the frame's click didn't count as a gesture on the host page").toEqual([]);
|
|
210
238
|
expect(await bodyData(display, "result")).toBe("true");
|
|
211
239
|
expect(
|
|
212
240
|
await display.calls(),
|
|
@@ -214,4 +242,31 @@ export const CLIPBOARD_PROBES: readonly Probe[] = [
|
|
|
214
242
|
).toEqual([{ capability: "copyText", args: { text: "npm test -- --run" } }]);
|
|
215
243
|
},
|
|
216
244
|
},
|
|
245
|
+
{
|
|
246
|
+
id: "12.raw-copy",
|
|
247
|
+
item: 12,
|
|
248
|
+
title: "a copy sent around the shell (raw porthole/copy-text, no click) is refused by the host",
|
|
249
|
+
async run(context) {
|
|
250
|
+
const display = await context.launch({
|
|
251
|
+
config: inline({ capabilities: { copyText: {} } }),
|
|
252
|
+
content: `<script>
|
|
253
|
+
addEventListener("message", (event) => {
|
|
254
|
+
if (event.data && event.data.id === "raw-1") document.body.dataset.answer = JSON.stringify(event.data.result ?? event.data.error);
|
|
255
|
+
});
|
|
256
|
+
// Late enough that no harness gesture is still active on the host page.
|
|
257
|
+
setTimeout(() => parent.postMessage({ jsonrpc: "2.0", id: "raw-1", method: "porthole/copy-text", params: { text: "copied around the shell" } }, "*"), ${ACTIVATION_LAPSE_MS});
|
|
258
|
+
</script>`,
|
|
259
|
+
});
|
|
260
|
+
// Nothing is evaluated in the page until the message has been answered.
|
|
261
|
+
await context.page.waitForTimeout(ACTIVATION_LAPSE_MS + 1_500);
|
|
262
|
+
expect(
|
|
263
|
+
await bodyData(display, "answer", "probe: a raw copy without a click is refused"),
|
|
264
|
+
"probe: a raw copy without a click is refused",
|
|
265
|
+
).toBe(JSON.stringify({ isError: true }));
|
|
266
|
+
expect(await display.calls(), "probe: a raw copy reached the host's handler").toEqual([]);
|
|
267
|
+
expect(await refusals(display), "probe: the host refused it for no user activation").toEqual([
|
|
268
|
+
"copyText:no-user-activation",
|
|
269
|
+
]);
|
|
270
|
+
},
|
|
271
|
+
},
|
|
217
272
|
];
|
package/src/displays/displays.ts
CHANGED
|
@@ -93,11 +93,9 @@ export function defineDisplays<N extends string>(
|
|
|
93
93
|
return presets.url({ ...kind.options, contentOrigins: [source] });
|
|
94
94
|
}
|
|
95
95
|
const options = kind.options ?? {};
|
|
96
|
-
// Nesting (P111) is a served page's: an opaque frame has nothing to nest.
|
|
97
|
-
const { nested: _nested, ...opaque } = options;
|
|
98
96
|
return presets[kind.preset](
|
|
99
97
|
source === null
|
|
100
|
-
?
|
|
98
|
+
? options
|
|
101
99
|
: { ...options, ...kind.served, isolation: "domain", contentOrigins: [source] },
|
|
102
100
|
);
|
|
103
101
|
};
|
package/src/guide/limits.ts
CHANGED
|
@@ -204,7 +204,7 @@ export function manualLimits(config: PortholeConfig, network: string): ManualLim
|
|
|
204
204
|
);
|
|
205
205
|
add(
|
|
206
206
|
"storage",
|
|
207
|
-
config.isolation === "opaque"
|
|
207
|
+
config.isolation === "opaque"
|
|
208
208
|
? `State isn't saved: localStorage works but lasts only while the ${it} is on screen, and a reload or another device starts fresh. Keep what matters in the ${it}'s code.`
|
|
209
209
|
: config.storage?.scope !== undefined
|
|
210
210
|
? `localStorage is kept for ${config.storage.scope}, in this browser; another browser or device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`
|
package/src/guide/runtime.ts
CHANGED
|
@@ -61,7 +61,7 @@ const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, stri
|
|
|
61
61
|
const WHAT: Readonly<Partial<Record<CapabilityName, (config: PortholeConfig) => string>>> = {
|
|
62
62
|
user: () => "who is viewing: { id, name, level }, as the app says",
|
|
63
63
|
comments: () =>
|
|
64
|
-
"opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't.
|
|
64
|
+
"opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. True if it opened. Write-only: a page never reads comments, and never posts one",
|
|
65
65
|
copyText: () =>
|
|
66
66
|
`copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied; nothing else in the page can write the clipboard. True if copied`,
|
|
67
67
|
openLink: () =>
|
package/src/host/create-host.ts
CHANGED
|
@@ -32,7 +32,6 @@ import { watchDoor, type DoorWatch } from "./door.ts";
|
|
|
32
32
|
import { outcomeOfRefusal } from "./locator.ts";
|
|
33
33
|
import { STORAGE_USED_METHOD, type FrameSource } from "../isolation/types.ts";
|
|
34
34
|
import { webPlatform } from "../platform/web.ts";
|
|
35
|
-
import { TAKES } from "../platform/focus-guard.ts";
|
|
36
35
|
import type { DoorSurface, Surface } from "../platform/types.ts";
|
|
37
36
|
import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
|
|
38
37
|
import {
|
|
@@ -75,7 +74,7 @@ export const REUSED_LOCATION =
|
|
|
75
74
|
|
|
76
75
|
/** What the host is told when its platform makes no doors (P125): no served frame is made. */
|
|
77
76
|
export const NO_DOOR_PLATFORM =
|
|
78
|
-
"This platform makes no door frames (PlatformHost.createDoor, P125), so no served display
|
|
77
|
+
"This platform makes no door frames (PlatformHost.createDoor, P125), so no served display is framed on it";
|
|
79
78
|
|
|
80
79
|
const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
|
|
81
80
|
|
|
@@ -120,10 +119,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
120
119
|
}
|
|
121
120
|
// A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
|
|
122
121
|
const speaks = config.mode !== "url";
|
|
123
|
-
const nested = config.nested === true;
|
|
124
122
|
// A served display on its scope's origin, beside the scope's other content (P125): its door
|
|
125
123
|
// says how loading went, before its frame is made.
|
|
126
|
-
const hasDoor = config.isolation === "domain" && speaks
|
|
124
|
+
const hasDoor = config.isolation === "domain" && speaks;
|
|
127
125
|
const adapter = (options.adapter ?? shellAdapter) as ProtocolAdapter<C>;
|
|
128
126
|
const platform = options.platform ?? webPlatform;
|
|
129
127
|
const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
|
|
@@ -381,18 +379,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
381
379
|
return undefined;
|
|
382
380
|
}
|
|
383
381
|
};
|
|
384
|
-
/**
|
|
385
|
-
* Whether the person is known to have made no gesture just now (P105): the platform says the
|
|
386
|
-
* page has no transient activation, or fails to say. Where it can't tell (undefined), as for
|
|
387
|
-
* the gesture gate, a report passes.
|
|
388
|
-
*/
|
|
389
|
-
const noGesture = (): boolean => {
|
|
390
|
-
try {
|
|
391
|
-
return surface?.userActivation() === false;
|
|
392
|
-
} catch {
|
|
393
|
-
return true;
|
|
394
|
-
}
|
|
395
|
-
};
|
|
396
382
|
/**
|
|
397
383
|
* Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
|
|
398
384
|
* places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
|
|
@@ -432,7 +418,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
432
418
|
/**
|
|
433
419
|
* A report from the frame: checked, taken only while the host asked for it (a selection
|
|
434
420
|
* only in select mode, results only for its own marks, a marker's click only for a mark it
|
|
435
|
-
* shows with one, a count's or a draft's
|
|
421
|
+
* shows with one, a count's or a draft's), then through the bridge's gates. No proof of a
|
|
422
|
+
* gesture is asked of a marker's click (0.16.0, P149): what a host opens for one takes no
|
|
423
|
+
* focus and does nothing by itself (THREAT_MODEL §6), and a page that says it unasked only
|
|
424
|
+
* shows that.
|
|
436
425
|
*/
|
|
437
426
|
const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
|
|
438
427
|
if (
|
|
@@ -536,13 +525,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
536
525
|
if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
537
526
|
return;
|
|
538
527
|
}
|
|
539
|
-
// A marker's real click gives the host's page transient activation (measured on all
|
|
540
|
-
// three engines, P105); a click a page posts at load, on a timer or on a scroll has
|
|
541
|
-
// none and is dropped. One posted on the person's own press in the content passes: the
|
|
542
|
-
// host's view guards itself against that (THREAT_MODEL §6).
|
|
543
|
-
if (noGesture()) {
|
|
544
|
-
return;
|
|
545
|
-
}
|
|
546
528
|
break;
|
|
547
529
|
}
|
|
548
530
|
}
|
|
@@ -910,8 +892,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
910
892
|
allow: compiled.allow,
|
|
911
893
|
referrerPolicy: compiled.referrerPolicy,
|
|
912
894
|
colorScheme: scheme,
|
|
913
|
-
// A nested page's shell (P111): the config's word, never the frame's.
|
|
914
|
-
...(config.nested === true ? { nested: true } : {}),
|
|
915
895
|
// An app reports no size: its frame fills the host's container, at least the minimum;
|
|
916
896
|
// so does any display the host mounts to fill, or whose layout fills (P065): its
|
|
917
897
|
// content scrolls itself.
|
|
@@ -939,34 +919,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
939
919
|
})
|
|
940
920
|
: framed;
|
|
941
921
|
surface = created;
|
|
942
|
-
// The focus guard undid a move of the keyboard into this frame (P109): heard each time,
|
|
943
|
-
// and a frame that keeps taking it is stopped, as one that keeps navigating away is.
|
|
944
|
-
const takes: { at: number; counts: boolean }[] = [];
|
|
945
|
-
created.onFocusTaken?.(({ typing, failed }) => {
|
|
946
|
-
const at = Date.now();
|
|
947
|
-
// While the person typed, or a take-back that failed (the keys then go to the frame and
|
|
948
|
-
// the page sees no typing): either counts toward the first rule.
|
|
949
|
-
takes.push({ at, counts: typing || failed });
|
|
950
|
-
const within = (ms: number) => takes.filter((take) => at - take.at <= ms);
|
|
951
|
-
emit("focusTaken", { typing });
|
|
952
|
-
if (
|
|
953
|
-
surface === created &&
|
|
954
|
-
(within(TAKES.typing.withinMs).filter((take) => take.counts).length >=
|
|
955
|
-
TAKES.typing.most ||
|
|
956
|
-
within(TAKES.any.withinMs).length >= TAKES.any.most)
|
|
957
|
-
) {
|
|
958
|
-
stop();
|
|
959
|
-
contentError("The content kept taking the keyboard from the page; it was stopped.");
|
|
960
|
-
}
|
|
961
|
-
while (takes.length > 0 && at - (takes[0] as { at: number }).at > TAKES.typing.withinMs) {
|
|
962
|
-
takes.shift();
|
|
963
|
-
}
|
|
964
|
-
});
|
|
965
922
|
const watch = watchOutcome({
|
|
966
923
|
surface: created,
|
|
967
924
|
source,
|
|
968
925
|
speaks,
|
|
969
|
-
nested,
|
|
970
926
|
timeoutMs: timeLeft,
|
|
971
927
|
onOutcome: (outcome) => emit("outcome", outcome),
|
|
972
928
|
// A frame status from the content (P124): never shown, the host's to hear.
|
|
@@ -1000,8 +956,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
1000
956
|
...(options.show === undefined ? {} : { show: options.show }),
|
|
1001
957
|
...(options.cached === undefined ? {} : { cached: options.cached }),
|
|
1002
958
|
userActivation: () => created.userActivation(),
|
|
1003
|
-
// The person in this frame (P109): the page's focus in it, after the focus guard.
|
|
1004
|
-
focused: () => created.focused?.(),
|
|
1005
959
|
onEvent: onBridge,
|
|
1006
960
|
...(declaration === null ? {} : { declaration }),
|
|
1007
961
|
...(viewer === undefined ? {} : { viewer }),
|
package/src/host/door.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { parseFrameStatus, SETTLE_MS } from "./outcome.ts";
|
|
|
3
3
|
import type { FrameOutcome } from "./types.ts";
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
* A served display's door (P125). A served display
|
|
6
|
+
* A served display's door (P125). A served display (a served shell, a page, a
|
|
7
7
|
* view through the sandbox proxy) is framed on its scope's origin, where the scope's other displays
|
|
8
8
|
* run content with `allow-same-origin`: one of them reaches a new document there before its first
|
|
9
9
|
* script runs, so nothing its frame says, and nothing its silence suggests, is Porthole's word.
|