@botiverse/porthole 0.15.2 → 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 +89 -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 +9 -14
- package/dist/isolation/served.js +17 -31
- package/dist/isolation/types.d.ts +2 -19
- package/dist/isolation/types.js +0 -17
- 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 -98
- 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/pages.d.ts +9 -2
- package/dist/server/pages.js +28 -8
- package/dist/server/server.js +28 -166
- package/dist/server/types.d.ts +7 -7
- package/dist/shell/plan.js +2 -2
- package/dist/shell/runtime.js +1 -9
- package/docs/ADOPTING.md +42 -135
- package/docs/ARCHITECTURE.md +0 -33
- package/docs/DECISIONS.md +296 -9
- package/docs/DESIGN.md +27 -50
- package/docs/THREAT_MODEL.md +140 -242
- 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 +18 -37
- package/src/isolation/types.ts +2 -24
- package/src/platform/focus-field.ts +18 -0
- package/src/platform/types.ts +6 -21
- package/src/platform/web.ts +8 -116
- 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/pages.ts +38 -12
- package/src/server/server.ts +29 -189
- package/src/server/types.ts +7 -7
- package/src/shell/plan.ts +2 -2
- package/src/shell/runtime.ts +1 -9
- 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 -252
- package/dist/platform/focus-guard.js +0 -764
- package/dist/server/nested.d.ts +0 -66
- package/dist/server/nested.js +0 -120
- package/dist/shell/frame.d.ts +0 -28
- package/dist/shell/frame.js +0 -338
- package/src/platform/focus-guard.ts +0 -999
- package/src/server/nested.ts +0 -156
- package/src/shell/frame.ts +0 -371
package/src/host/locate.ts
CHANGED
|
@@ -6,7 +6,7 @@ import { parseViewer } from "../runtime/levels.ts";
|
|
|
6
6
|
/**
|
|
7
7
|
* Where a served frame (domain or external isolation) loads from: the host's locator answers, and
|
|
8
8
|
* `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
|
|
9
|
-
* own site
|
|
9
|
+
* own site) before any frame is made.
|
|
10
10
|
*/
|
|
11
11
|
export async function locateServed(
|
|
12
12
|
locator: InstanceLocator,
|
|
@@ -16,7 +16,7 @@ export async function locateServed(
|
|
|
16
16
|
signal?: AbortSignal,
|
|
17
17
|
): Promise<FrameSource> {
|
|
18
18
|
const location = await locator.locate(instance, signal);
|
|
19
|
-
checkFrameLocation(location, config.contentOrigins, hostOrigin
|
|
19
|
+
checkFrameLocation(location, config.contentOrigins, hostOrigin);
|
|
20
20
|
// The host's access, as its backend answered (P087): a viewer that doesn't parse is the host's
|
|
21
21
|
// error, never no viewer (after the review: a mount's own would take its place).
|
|
22
22
|
const viewer = location.viewer === undefined ? null : parseViewer(location.viewer);
|
package/src/host/outcome.ts
CHANGED
|
@@ -24,10 +24,9 @@ import type { FrameBlock, FrameOutcome } from "./types.ts";
|
|
|
24
24
|
*
|
|
25
25
|
* - An opaque frame's only document is the host's own shell, with the content in it: no page of
|
|
26
26
|
* Porthole's server ever loads there, so its every frame status is the content's.
|
|
27
|
-
* - A frame that speaks (a served shell, a view through the sandbox proxy
|
|
27
|
+
* - A frame that speaks (a served shell, a view through the sandbox proxy)
|
|
28
28
|
* says Porthole's own word first in every document that holds content, before any of the
|
|
29
|
-
* content's code runs: the shell's hello, the proxy's ready
|
|
30
|
-
* reaches the host before anything its page says, through its shell). A status page says
|
|
29
|
+
* content's code runs: the shell's hello, the proxy's ready. A status page says
|
|
31
30
|
* nothing but its frame status. So a frame status is taken only before anything else was heard
|
|
32
31
|
* from the frame in this run: from its first document, which then was a page of Porthole's.
|
|
33
32
|
* After that, it came from the content (or from a later document, which in a display without
|
|
@@ -35,9 +34,9 @@ import type { FrameBlock, FrameOutcome } from "./types.ts";
|
|
|
35
34
|
* That holds against the display's own content, not against another display's (P125): a
|
|
36
35
|
* scope's displays share its origin, and one that runs reaches a new document of another's
|
|
37
36
|
* before that document's first script, where it can speak first, or stop or rewrite it so it
|
|
38
|
-
* says nothing. So the rule holds only where no content runs on the frame's origin
|
|
39
|
-
*
|
|
40
|
-
* - A served display
|
|
37
|
+
* says nothing. So the rule holds only where no content runs on the frame's origin, and no
|
|
38
|
+
* served frame is such a place (the nested shell that was, P114, went in 0.16.0: P149).
|
|
39
|
+
* - A served display (a served shell, a page, a view through the sandbox proxy)
|
|
41
40
|
* takes no frame status from its frame at all, and infers nothing from its silence (a load and
|
|
42
41
|
* no word is a timeout, never `framing`): its door said how loading went before the frame was
|
|
43
42
|
* made (P125, `watchDoor`), from an opaque frame of the host's that no content can reach.
|
|
@@ -129,19 +128,12 @@ export function watchOutcome(options: {
|
|
|
129
128
|
readonly source: FrameSource;
|
|
130
129
|
/** Whether the frame speaks for itself (a shell or a view): then its handshake is the proof. */
|
|
131
130
|
readonly speaks: boolean;
|
|
132
|
-
/**
|
|
133
|
-
* The config nests its pages (P111): the frame holds Porthole's shell, on a label no content
|
|
134
|
-
* runs on, whose first word may be a frame status. Any other served frame that speaks takes
|
|
135
|
-
* none: its door told (P125).
|
|
136
|
-
*/
|
|
137
|
-
readonly nested?: boolean;
|
|
138
131
|
readonly timeoutMs: number;
|
|
139
132
|
readonly onOutcome: (outcome: FrameOutcome) => void;
|
|
140
133
|
/** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
|
|
141
134
|
readonly refused?: (message: string) => void;
|
|
142
135
|
}): OutcomeWatch {
|
|
143
136
|
const { surface, source, speaks } = options;
|
|
144
|
-
const nested = options.nested === true;
|
|
145
137
|
const reports = source.kind === "url" && source.reports === true;
|
|
146
138
|
// The first outcome; after a load, only a later block (a status page, access revoked) is told.
|
|
147
139
|
let decided: FrameOutcome["state"] | null = null;
|
|
@@ -181,7 +173,7 @@ export function watchOutcome(options: {
|
|
|
181
173
|
}
|
|
182
174
|
};
|
|
183
175
|
// Whether a frame status may be the word of a page of Porthole's (P124, P125, above).
|
|
184
|
-
const mayBePorthole = () => source.kind === "url" &&
|
|
176
|
+
const mayBePorthole = () => source.kind === "url" && !speaks;
|
|
185
177
|
const unlisten = surface.transport.listen((data) => {
|
|
186
178
|
heard = true;
|
|
187
179
|
if (!namesFrameStatus(data)) {
|
|
@@ -229,15 +221,10 @@ export function watchOutcome(options: {
|
|
|
229
221
|
return;
|
|
230
222
|
}
|
|
231
223
|
if (speaks) {
|
|
232
|
-
// A served
|
|
233
|
-
// that never did never ran. Any other served frame's silence tells nothing (P125). (An
|
|
224
|
+
// A served frame's silence tells nothing (P125): its door said how loading went. (An
|
|
234
225
|
// opaque srcdoc frame always runs: its handshake decides.)
|
|
235
226
|
if (source.kind === "url") {
|
|
236
|
-
|
|
237
|
-
neverRan();
|
|
238
|
-
} else {
|
|
239
|
-
silent();
|
|
240
|
-
}
|
|
227
|
+
silent();
|
|
241
228
|
}
|
|
242
229
|
return;
|
|
243
230
|
}
|
package/src/host/types.ts
CHANGED
|
@@ -137,12 +137,12 @@ export type HostErrorKind =
|
|
|
137
137
|
/**
|
|
138
138
|
* A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
|
|
139
139
|
* from the frame's content, not from a page of Porthole's server (P124): never shown, never an
|
|
140
|
-
* outcome. Told once a run. A served display
|
|
140
|
+
* outcome. Told once a run. A served display takes none from its frame at
|
|
141
141
|
* all: its door says how loading went (P125).
|
|
142
142
|
*/
|
|
143
143
|
| "frame-status"
|
|
144
144
|
/**
|
|
145
|
-
* A served display that has a door (P125: a served shell, a page
|
|
145
|
+
* A served display that has a door (P125: a served shell, a page, the sandbox
|
|
146
146
|
* proxy) was located without one: the server is older than the host (upgrade it first), or a
|
|
147
147
|
* locator dropped `FrameLocation.door`. The display shows, but no frame status is taken, so a
|
|
148
148
|
* block is told as a timeout. Told once a mount.
|
|
@@ -225,17 +225,9 @@ export interface DisplayEvents {
|
|
|
225
225
|
readonly refused: { readonly capability: CapabilityName; readonly refusal: Refusal };
|
|
226
226
|
/** Too many declines: the display stops asking until it runs again. */
|
|
227
227
|
readonly muted: undefined;
|
|
228
|
-
/**
|
|
229
|
-
* The content moved the keyboard into its frame from one of the page's text fields without the
|
|
230
|
-
* person (no press on the frame, no Tab, P109), and focus went back where it was; `typing`: the
|
|
231
|
-
* person had pressed a key on the page within the last second. The content's doing. Three while
|
|
232
|
-
* typing within 10 s, or five within 2 s, stop the display (`contentError` says so; `reload()`
|
|
233
|
-
* runs it again).
|
|
234
|
-
*/
|
|
235
|
-
readonly focusTaken: { readonly typing: boolean };
|
|
236
228
|
/**
|
|
237
229
|
* Whether the page touched `localStorage` or `sessionStorage` (the in-memory stand-in of a frame
|
|
238
|
-
* without storage of its own: opaque
|
|
230
|
+
* without storage of its own: an opaque one): once per run, `used: true` when
|
|
239
231
|
* the page first did, else `used: false` as the run ends. Never what it kept: for a host to count
|
|
240
232
|
* the pages that would need storage.
|
|
241
233
|
*/
|
|
@@ -352,9 +344,7 @@ export interface AnnotationControls {
|
|
|
352
344
|
* comes of it. Nothing happens, and nothing throws, for an id no mark with a marker is shown
|
|
353
345
|
* under, or if the frame has no such marker now (its words are gone, elements are being picked):
|
|
354
346
|
* the display's own `focus()` isn't used, so the frame takes no focus for a marker it hasn't got.
|
|
355
|
-
*
|
|
356
|
-
* move is the frame's own to the focus guard, undone and counted (P109). The page can take the
|
|
357
|
-
* focus back at once. Not kept for a frame that runs later.
|
|
347
|
+
* The page can take the focus back at once. Not kept for a frame that runs later.
|
|
358
348
|
*
|
|
359
349
|
* On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
|
|
360
350
|
* its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
|
|
@@ -362,8 +352,7 @@ export interface AnnotationControls {
|
|
|
362
352
|
* it (its page is busy) is held to the same test (P137), so a word that comes late takes no
|
|
363
353
|
* keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
|
|
364
354
|
* `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
|
|
365
|
-
* `focusMark(id)` again.
|
|
366
|
-
* `focus()` stops at its shell, and a second call that waits is dropped.
|
|
355
|
+
* `focusMark(id)` again.
|
|
367
356
|
*/
|
|
368
357
|
focusMark(id: string): void;
|
|
369
358
|
}
|
|
@@ -387,10 +376,7 @@ export interface DisplayControls {
|
|
|
387
376
|
readonly find: FindControls;
|
|
388
377
|
/** Runs the content again from the start, in a new frame. */
|
|
389
378
|
reload(): void;
|
|
390
|
-
/**
|
|
391
|
-
* Moves focus into the display's frame, as the host's own move: from one of the page's text
|
|
392
|
-
* fields, a frame's own `focus()` is taken for the content's and undone (P109).
|
|
393
|
-
*/
|
|
379
|
+
/** Moves focus into the display's frame. */
|
|
394
380
|
focus(): void;
|
|
395
381
|
/** Tears the view down and removes the frame. */
|
|
396
382
|
destroy(): void;
|
package/src/index.ts
CHANGED
|
@@ -50,9 +50,7 @@ export {
|
|
|
50
50
|
type UrlSandboxExtra,
|
|
51
51
|
} from "./config/schema.ts";
|
|
52
52
|
export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
|
|
53
|
-
export { FRAME_STATUS_METHOD,
|
|
54
|
-
export { PAGE_SANDBOX_TOKENS } from "./compile/policy.ts";
|
|
55
|
-
export { SHELL_GESTURE_MS } from "./platform/focus-guard.ts";
|
|
53
|
+
export { FRAME_STATUS_METHOD, STORAGE_USED_METHOD } from "./isolation/types.ts";
|
|
56
54
|
|
|
57
55
|
// The capability runtime (P085-P090): its contract, levels, a page's declaration, its services'
|
|
58
56
|
// shapes. Hosts implement the services; Porthole carries, checks and gates the calls.
|
|
@@ -279,7 +277,7 @@ export type {
|
|
|
279
277
|
} from "./bridge/types.ts";
|
|
280
278
|
export { createHost } from "./host/create-host.ts";
|
|
281
279
|
export { mayPassOn } from "./host/pass-on.ts";
|
|
282
|
-
export { focusField } from "./platform/focus-
|
|
280
|
+
export { focusField } from "./platform/focus-field.ts";
|
|
283
281
|
// The client half of the host kit, and the display registry (P072).
|
|
284
282
|
export {
|
|
285
283
|
entryTarget,
|
package/src/isolation/served.ts
CHANGED
|
@@ -28,27 +28,12 @@ export function parseOrigin(origin: string): ParsedOrigin | null {
|
|
|
28
28
|
}
|
|
29
29
|
|
|
30
30
|
/**
|
|
31
|
-
* The start of every label Porthole
|
|
32
|
-
* may make one (`content.name` is
|
|
31
|
+
* The start of every label Porthole keeps for itself on a content domain (its health label;
|
|
32
|
+
* until 0.16.0 a nested page's shell's, P114): no host's naming may make one (`content.name` is
|
|
33
|
+
* refused one, and `prefixedName` won't take the prefix), and no display is served on one.
|
|
33
34
|
*/
|
|
34
35
|
export const PORTHOLE_LABEL_PREFIX = "porthole-";
|
|
35
36
|
|
|
36
|
-
const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
|
|
37
|
-
|
|
38
|
-
/** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
|
|
39
|
-
export const isNestedLabel = (label: string): boolean => NESTED_LABEL.test(label);
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
|
|
43
|
-
* The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
|
|
44
|
-
* each refuse any other origin, so a content Worker of a host's own can't put it beside other
|
|
45
|
-
* content by mistake.
|
|
46
|
-
*/
|
|
47
|
-
export function onNestedLabel(origin: string): boolean {
|
|
48
|
-
const parsed = parseOrigin(origin);
|
|
49
|
-
return parsed !== null && isNestedLabel(parsed.host.split(".")[0] ?? "");
|
|
50
|
-
}
|
|
51
|
-
|
|
52
37
|
/** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
|
|
53
38
|
export function isExactOrigin(origin: unknown): origin is string {
|
|
54
39
|
return typeof origin === "string" && parseOrigin(origin) !== null;
|
|
@@ -63,8 +48,17 @@ export function isExactOrigin(origin: unknown): origin is string {
|
|
|
63
48
|
const HOST_ORIGIN =
|
|
64
49
|
/^[a-z][a-z0-9+.-]*:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*|\[[0-9a-f:.]+\])(:\d{1,5})?$/u;
|
|
65
50
|
|
|
51
|
+
/** Whether `origin` is written as an origin is (`HOST_ORIGIN`), whatever a browser makes of it. */
|
|
52
|
+
const shapedAsOrigin = (origin: unknown): origin is string =>
|
|
53
|
+
typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Whether `origin` can be a host origin: written as one, and one a browser serializes as it is
|
|
57
|
+
* written (`serializable`: never `:0`, a port past 65535 or with a leading zero, a host the URL
|
|
58
|
+
* parser would rewrite). `hostOriginProblem` says why not.
|
|
59
|
+
*/
|
|
66
60
|
export function isHostOrigin(origin: unknown): origin is string {
|
|
67
|
-
return
|
|
61
|
+
return shapedAsOrigin(origin) && serializable(origin);
|
|
68
62
|
}
|
|
69
63
|
|
|
70
64
|
/**
|
|
@@ -94,7 +88,7 @@ function serializable(origin: string): boolean {
|
|
|
94
88
|
|
|
95
89
|
/** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
|
|
96
90
|
export function hostOriginProblem(origin: unknown): string | null {
|
|
97
|
-
if (
|
|
91
|
+
if (shapedAsOrigin(origin)) {
|
|
98
92
|
return serializable(origin)
|
|
99
93
|
? null
|
|
100
94
|
: `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
|
|
@@ -142,7 +136,7 @@ const LOOPBACK_HOST = (host: string): boolean =>
|
|
|
142
136
|
* in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
|
|
143
137
|
*/
|
|
144
138
|
export function framedByProblem(origin: unknown): string | null {
|
|
145
|
-
const parsed =
|
|
139
|
+
const parsed = shapedAsOrigin(origin) ? parseOrigin(origin) : null;
|
|
146
140
|
if (
|
|
147
141
|
parsed === null ||
|
|
148
142
|
!(parsed.scheme === "https" || (parsed.scheme === "http" && LOOPBACK_HOST(parsed.host)))
|
|
@@ -223,8 +217,6 @@ export function checkFrameLocation(
|
|
|
223
217
|
location: FrameLocation,
|
|
224
218
|
contentOrigins: readonly string[],
|
|
225
219
|
hostOrigin: string,
|
|
226
|
-
/** The config nests its pages (P111): the location must be on a shell's own label (P121). */
|
|
227
|
-
nested = false,
|
|
228
220
|
): void {
|
|
229
221
|
const origin = parseOrigin(location.origin);
|
|
230
222
|
let url: URL;
|
|
@@ -244,13 +236,8 @@ export function checkFrameLocation(
|
|
|
244
236
|
`The located origin ${location.origin} is not one of the config's content origins`,
|
|
245
237
|
);
|
|
246
238
|
}
|
|
247
|
-
if (nested && !onNestedLabel(location.origin)) {
|
|
248
|
-
throw new TypeError(
|
|
249
|
-
`The located origin ${location.origin} isn't a nested page's own: its shell is served on a label of its own alone (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf(label), P114), never beside other content`,
|
|
250
|
-
);
|
|
251
|
-
}
|
|
252
239
|
if (location.door !== undefined) {
|
|
253
|
-
checkDoor(location.door, location.origin
|
|
240
|
+
checkDoor(location.door, location.origin);
|
|
254
241
|
}
|
|
255
242
|
const host = parseOrigin(hostOrigin);
|
|
256
243
|
if (host !== null && maybeSameSite(origin.host, host.host)) {
|
|
@@ -261,21 +248,15 @@ export function checkFrameLocation(
|
|
|
261
248
|
}
|
|
262
249
|
|
|
263
250
|
/**
|
|
264
|
-
* A location's door (P125): on the location's own origin, at Porthole's door path
|
|
265
|
-
* nested page (its shell's label serves no door: its first document is Porthole's own, P114).
|
|
251
|
+
* A location's door (P125): on the location's own origin, at Porthole's door path.
|
|
266
252
|
* Named by its origin only in what is thrown: the door's address carries a ticket.
|
|
267
253
|
*/
|
|
268
|
-
function checkDoor(door: unknown, origin: string
|
|
254
|
+
function checkDoor(door: unknown, origin: string): void {
|
|
269
255
|
const url =
|
|
270
256
|
door !== null && typeof door === "object" ? (door as { url?: unknown }).url : undefined;
|
|
271
257
|
if (typeof url !== "string") {
|
|
272
258
|
throw new TypeError("The located door is not { url }");
|
|
273
259
|
}
|
|
274
|
-
if (nested) {
|
|
275
|
-
throw new TypeError(
|
|
276
|
-
"A nested page is located with no door: its shell is Porthole's own first document (P125)",
|
|
277
|
-
);
|
|
278
|
-
}
|
|
279
260
|
let parsed: URL;
|
|
280
261
|
try {
|
|
281
262
|
parsed = new URL(url);
|
package/src/isolation/types.ts
CHANGED
|
@@ -73,8 +73,8 @@ export interface FrameLocation {
|
|
|
73
73
|
* The display's door (P125): a page of Porthole's on the same origin, at
|
|
74
74
|
* `/__porthole/door/<instance key>?ticket=<its own ticket>`, that says how loading went before
|
|
75
75
|
* any content is framed. The host frames it opaque and hidden, and takes its one frame status
|
|
76
|
-
* (`open`, or `blocked` and why); then frames `url`. Given for a served shell, a page
|
|
77
|
-
*
|
|
76
|
+
* (`open`, or `blocked` and why); then frames `url`. Given for a served shell, a page and the
|
|
77
|
+
* sandbox proxy: content of the scope runs on their origin, so no frame status
|
|
78
78
|
* from their own frame is ever Porthole's. A host that is given none for one of them takes no
|
|
79
79
|
* frame status at all (a load that shows nothing is a timeout) and says so (`hostError` kind
|
|
80
80
|
* `door`). A custom locator passes it on as it came.
|
|
@@ -88,28 +88,6 @@ export const DOOR_PATH = "/__porthole/door/";
|
|
|
88
88
|
/** The message a served page sends its host about loading (own-prefixed, P040). */
|
|
89
89
|
export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
|
|
90
90
|
|
|
91
|
-
/** A nested page's shell's report of its own state to the host (P111). */
|
|
92
|
-
export const SHELL_STATE_METHOD = "porthole/shell/state";
|
|
93
|
-
|
|
94
|
-
/** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
|
|
95
|
-
export const SHELL_BEAT_METHOD = "porthole/shell/beat";
|
|
96
|
-
|
|
97
|
-
/**
|
|
98
|
-
* The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
|
|
99
|
-
* that names the ask (`asked`). The host asks as it hears focus move into the frame.
|
|
100
|
-
*/
|
|
101
|
-
export const SHELL_LOOK_METHOD = "porthole/shell/look";
|
|
102
|
-
|
|
103
|
-
/**
|
|
104
|
-
* The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
|
|
105
|
-
* to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
|
|
106
|
-
* `display.focus()` alone; a page has no way to say it.
|
|
107
|
-
*/
|
|
108
|
-
export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
|
|
109
|
-
|
|
110
|
-
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
111
|
-
export const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
112
|
-
|
|
113
91
|
/** A page's word that it used storage, once per load (P111): never a key or a value. */
|
|
114
92
|
export const STORAGE_USED_METHOD = "porthole/storage-used";
|
|
115
93
|
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Moves focus into one of the host page's own text fields (a composer that opens beside a
|
|
3
|
+
* display): `field.focus()` for a host to call instead. Firefox doesn't move focus out of a frame
|
|
4
|
+
* that holds it with a gesture of the person's, and takes it back on its own blur (measured: the
|
|
5
|
+
* keys then go on to the frame); so where a frame of the page holds the focus, it is blurred
|
|
6
|
+
* first. Elsewhere it is `field.focus()`.
|
|
7
|
+
*
|
|
8
|
+
* Nothing watches what happens next: until 0.16.0 a focus guard did, and counted a frame that
|
|
9
|
+
* took the focus back toward stopping its display (P109, removed by P149).
|
|
10
|
+
*/
|
|
11
|
+
export function focusField(field: HTMLElement): void {
|
|
12
|
+
const holder = field.ownerDocument.activeElement;
|
|
13
|
+
const view = field.ownerDocument.defaultView;
|
|
14
|
+
if (view !== null && holder instanceof view.HTMLIFrameElement) {
|
|
15
|
+
holder.blur();
|
|
16
|
+
}
|
|
17
|
+
field.focus({ preventScroll: true });
|
|
18
|
+
}
|
package/src/platform/types.ts
CHANGED
|
@@ -24,12 +24,6 @@ export interface SurfaceSpec {
|
|
|
24
24
|
readonly fill?: boolean;
|
|
25
25
|
/** The height to start at (a remembered height, so a frame mounting again doesn't jump). */
|
|
26
26
|
readonly initialHeightPx: number;
|
|
27
|
-
/**
|
|
28
|
-
* The frame holds a nested page's shell (P111): the host's config says so, never the frame. What
|
|
29
|
-
* the shell says of itself (`porthole/shell/state`) decides moves of focus into it and the
|
|
30
|
-
* gesture its page's calls need; nothing else in that namespace reaches the transport.
|
|
31
|
-
*/
|
|
32
|
-
readonly nested?: boolean;
|
|
33
27
|
}
|
|
34
28
|
|
|
35
29
|
/** One isolated frame. */
|
|
@@ -42,7 +36,7 @@ export interface Surface {
|
|
|
42
36
|
/**
|
|
43
37
|
* Whether the embedding page has transient user activation now (a gesture in the frame
|
|
44
38
|
* activates its ancestors), or undefined where the platform can't tell. The gesture gate reads
|
|
45
|
-
* it, and
|
|
39
|
+
* it (`copyText`'s by default, and any a host's config adds).
|
|
46
40
|
*/
|
|
47
41
|
userActivation(): boolean | undefined;
|
|
48
42
|
/**
|
|
@@ -53,22 +47,13 @@ export interface Surface {
|
|
|
53
47
|
*/
|
|
54
48
|
viewport?(): { readonly width: number; readonly height: number } | undefined;
|
|
55
49
|
/**
|
|
56
|
-
* Whether the embedding page's focus is in this frame now,
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
50
|
+
* Whether the embedding page's keyboard focus is in this frame now, as its document says;
|
|
51
|
+
* undefined, or absent, where the platform can't tell. The find shortcut reads it (P131: a
|
|
52
|
+
* frame that says the shortcut was pressed while the focus is elsewhere is not believed). No
|
|
53
|
+
* word on who put the focus there: a frame may take it by itself (P149).
|
|
60
54
|
*/
|
|
61
55
|
focused?(): boolean | undefined;
|
|
62
|
-
/**
|
|
63
|
-
* Each time the content moved the keyboard into its frame from one of the embedding page's text
|
|
64
|
-
* fields without the person (no press on the frame, no Tab) and the platform gave focus back
|
|
65
|
-
* (P109): whether the person was typing then (a key within the last second), and whether focus
|
|
66
|
-
* failed to go back (the frame kept it or took it again). Absent where the platform has no guard.
|
|
67
|
-
*/
|
|
68
|
-
onFocusTaken?(
|
|
69
|
-
listener: (take: { readonly typing: boolean; readonly failed: boolean }) => void,
|
|
70
|
-
): () => void;
|
|
71
|
-
/** The host moves focus into the frame itself: the guard takes it as the person's (P109). */
|
|
56
|
+
/** The host moves focus into the frame itself. */
|
|
72
57
|
focus?(): void;
|
|
73
58
|
/**
|
|
74
59
|
* The frame loaded a document other than the one it was given: the content navigated it. The
|
package/src/platform/web.ts
CHANGED
|
@@ -1,81 +1,8 @@
|
|
|
1
1
|
import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
|
|
2
2
|
import type { ColorScheme } from "../config/schema.ts";
|
|
3
|
-
import {
|
|
4
|
-
SHELL_BEAT_METHOD,
|
|
5
|
-
SHELL_FOCUS_METHOD,
|
|
6
|
-
SHELL_LOOK_METHOD,
|
|
7
|
-
SHELL_METHOD_PREFIX,
|
|
8
|
-
SHELL_STATE_METHOD,
|
|
9
|
-
} from "../isolation/types.ts";
|
|
10
3
|
import { postMessageTransport } from "../transport/post-message.ts";
|
|
11
|
-
import { focusGuard, type FocusGuard, type FocusTake } from "./focus-guard.ts";
|
|
12
|
-
import type { Transport } from "../transport/types.ts";
|
|
13
4
|
import type { DoorSurface, PlatformHost, Surface, SurfaceSpec } from "./types.ts";
|
|
14
5
|
|
|
15
|
-
/** A shell's own message (P111), by its namespace. */
|
|
16
|
-
const isShellWord = (data: unknown): data is { method: string; params?: unknown } =>
|
|
17
|
-
data !== null &&
|
|
18
|
-
typeof data === "object" &&
|
|
19
|
-
typeof (data as { method?: unknown }).method === "string" &&
|
|
20
|
-
(data as { method: string }).method.startsWith(SHELL_METHOD_PREFIX);
|
|
21
|
-
|
|
22
|
-
/**
|
|
23
|
-
* A nested page's transport (P111): the shell's state, checked, to the focus guard; the rest of
|
|
24
|
-
* the shell's namespace dropped; everything else as it came.
|
|
25
|
-
*/
|
|
26
|
-
function shellWords(opened: Transport, frame: HTMLIFrameElement, guard: FocusGuard): Transport {
|
|
27
|
-
const listeners = new Set<(message: unknown) => void>();
|
|
28
|
-
opened.listen((message) => {
|
|
29
|
-
if (!isShellWord(message)) {
|
|
30
|
-
for (const listener of listeners) {
|
|
31
|
-
listener(message);
|
|
32
|
-
}
|
|
33
|
-
return;
|
|
34
|
-
}
|
|
35
|
-
const params = message.params;
|
|
36
|
-
if (params === null || typeof params !== "object") {
|
|
37
|
-
return;
|
|
38
|
-
}
|
|
39
|
-
const { supported, ago, focused, gap, asked } = params as Record<string, unknown>;
|
|
40
|
-
const span = (value: unknown) =>
|
|
41
|
-
typeof value === "number" && Number.isFinite(value) && value >= 0;
|
|
42
|
-
if (message.method === SHELL_BEAT_METHOD) {
|
|
43
|
-
if (span(gap)) {
|
|
44
|
-
guard.beat(frame);
|
|
45
|
-
}
|
|
46
|
-
return;
|
|
47
|
-
}
|
|
48
|
-
if (
|
|
49
|
-
message.method !== SHELL_STATE_METHOD ||
|
|
50
|
-
typeof supported !== "boolean" ||
|
|
51
|
-
typeof focused !== "boolean" ||
|
|
52
|
-
!(ago === null || span(ago)) ||
|
|
53
|
-
!span(gap) ||
|
|
54
|
-
!(asked === undefined || (Number.isSafeInteger(asked) && (asked as number) >= 0))
|
|
55
|
-
) {
|
|
56
|
-
return;
|
|
57
|
-
}
|
|
58
|
-
guard.shell(frame, {
|
|
59
|
-
supported,
|
|
60
|
-
ago: ago as number | null,
|
|
61
|
-
focused,
|
|
62
|
-
gap: gap as number,
|
|
63
|
-
...(asked === undefined ? {} : { asked: asked as number }),
|
|
64
|
-
});
|
|
65
|
-
});
|
|
66
|
-
return {
|
|
67
|
-
send: (message) => opened.send(message),
|
|
68
|
-
listen(listener) {
|
|
69
|
-
listeners.add(listener);
|
|
70
|
-
return () => listeners.delete(listener);
|
|
71
|
-
},
|
|
72
|
-
close() {
|
|
73
|
-
listeners.clear();
|
|
74
|
-
opened.close();
|
|
75
|
-
},
|
|
76
|
-
};
|
|
77
|
-
}
|
|
78
|
-
|
|
79
6
|
/**
|
|
80
7
|
* The web platform: an `<iframe>` whose policy attributes are set before its document is given,
|
|
81
8
|
* talking over `postMessage`. Its first load is the document it was given; any later load is the
|
|
@@ -128,37 +55,10 @@ export const webPlatform: PlatformHost = {
|
|
|
128
55
|
container.append(frame);
|
|
129
56
|
|
|
130
57
|
const view = container.ownerDocument.defaultView ?? window;
|
|
131
|
-
// The focus guard (P109): a move of the keyboard into this frame from one of the page's text
|
|
132
|
-
// fields that the person didn't make is undone.
|
|
133
|
-
const guard = focusGuard(view);
|
|
134
|
-
const taken = new Set<(take: FocusTake) => void>();
|
|
135
|
-
const nested = spec.nested === true && spec.source.kind === "url";
|
|
136
58
|
// A frame is heard from its own window and its located origin alone: never the host's own
|
|
137
59
|
// origin (P125 removed P068's in-frame pages and the channel that heard them), so no page of
|
|
138
60
|
// the host's own can speak for a frame either.
|
|
139
|
-
const
|
|
140
|
-
const unguard = guard.add(
|
|
141
|
-
frame,
|
|
142
|
-
(take) => {
|
|
143
|
-
for (const listener of taken) {
|
|
144
|
-
listener(take);
|
|
145
|
-
}
|
|
146
|
-
},
|
|
147
|
-
{
|
|
148
|
-
nested,
|
|
149
|
-
// A nested page's shell is asked to look as the guard hears a move into its frame (P120).
|
|
150
|
-
...(nested
|
|
151
|
-
? {
|
|
152
|
-
ask: (n: number) =>
|
|
153
|
-
opened.send({ jsonrpc: "2.0", method: SHELL_LOOK_METHOD, params: { n } }),
|
|
154
|
-
}
|
|
155
|
-
: {}),
|
|
156
|
-
},
|
|
157
|
-
);
|
|
158
|
-
// A nested page's shell (P111): its own words go to the guard, by the frame's window and the
|
|
159
|
-
// content origin (the transport's checks); the page's pass on. The shell drops any page
|
|
160
|
-
// message in its namespace, so there none is the page's.
|
|
161
|
-
const transport = nested ? shellWords(opened, frame, guard) : opened;
|
|
61
|
+
const transport = postMessageTransport(() => frame.contentWindow, origin, view);
|
|
162
62
|
return {
|
|
163
63
|
transport,
|
|
164
64
|
element: frame,
|
|
@@ -186,20 +86,15 @@ export const webPlatform: PlatformHost = {
|
|
|
186
86
|
).userActivation;
|
|
187
87
|
return activation === undefined ? undefined : activation.isActive;
|
|
188
88
|
},
|
|
89
|
+
// Where the keyboard is, as the frame's own tree says it (its document's, or the shadow
|
|
90
|
+
// root's it is in): no more than that. A frame may take the focus by itself (0.16.0
|
|
91
|
+
// removed the guard that took it back, P149), so this is no word on who put it there.
|
|
189
92
|
focused() {
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
onFocusTaken(listener) {
|
|
193
|
-
taken.add(listener);
|
|
194
|
-
return () => taken.delete(listener);
|
|
93
|
+
const root = frame.getRootNode() as Partial<DocumentOrShadowRoot>;
|
|
94
|
+
return root.activeElement === frame;
|
|
195
95
|
},
|
|
196
96
|
focus() {
|
|
197
|
-
|
|
198
|
-
// A nested page (P136): the move stops at its shell on every engine, one way or another,
|
|
199
|
-
// and only the shell can pass it on. Only a move that landed: the shell asks no more of it.
|
|
200
|
-
if (nested && view.document.activeElement === frame) {
|
|
201
|
-
opened.send({ jsonrpc: "2.0", method: SHELL_FOCUS_METHOD });
|
|
202
|
-
}
|
|
97
|
+
frame.focus();
|
|
203
98
|
},
|
|
204
99
|
onLoad(listener) {
|
|
205
100
|
loaded.add(listener);
|
|
@@ -212,8 +107,6 @@ export const webPlatform: PlatformHost = {
|
|
|
212
107
|
destroy() {
|
|
213
108
|
navigated.clear();
|
|
214
109
|
loaded.clear();
|
|
215
|
-
taken.clear();
|
|
216
|
-
unguard();
|
|
217
110
|
transport.close();
|
|
218
111
|
frame.remove();
|
|
219
112
|
},
|
|
@@ -223,8 +116,7 @@ export const webPlatform: PlatformHost = {
|
|
|
223
116
|
* A served display's door (P125): hidden (no size, `visibility: hidden`, which still runs its
|
|
224
117
|
* script and fires its load on all three engines), out of focus and of the accessibility tree,
|
|
225
118
|
* sandboxed with scripts alone, no `allow`, no name. Nothing but its frame status is heard from
|
|
226
|
-
* it, from its window and the opaque origin alone; the
|
|
227
|
-
* never see it.
|
|
119
|
+
* it, from its window and the opaque origin alone; the bridge and annotations never see it.
|
|
228
120
|
*/
|
|
229
121
|
createDoor(container: HTMLElement, spec: { readonly url: string }): DoorSurface {
|
|
230
122
|
// oxlint-disable-next-line react/iframe-missing-sandbox -- set from the door's list, next
|
package/src/presets/presets.ts
CHANGED
|
@@ -56,8 +56,6 @@ export interface PresetOptions {
|
|
|
56
56
|
* be offered the runtime's own (`user`, `comments`, `artifact`, `assets`, `db`).
|
|
57
57
|
*/
|
|
58
58
|
readonly runtime?: RuntimeVersion;
|
|
59
|
-
/** Domain isolation, artifact pages: the page in an opaque child of Porthole's shell (P111). */
|
|
60
|
-
readonly nested?: true;
|
|
61
59
|
/**
|
|
62
60
|
* `own` (P128): an `<iframe>` of one of the page's own files (a relative `src`) or a `srcdoc`
|
|
63
61
|
* one loads and runs, in a realm of its own that the shell's hardening doesn't reach
|
|
@@ -249,7 +247,6 @@ function build(
|
|
|
249
247
|
...(options.storage === undefined ? {} : { storage: options.storage }),
|
|
250
248
|
...(options.errors === undefined ? {} : { errors: options.errors }),
|
|
251
249
|
...(options.runtime === undefined ? {} : { runtime: options.runtime }),
|
|
252
|
-
...(options.nested === undefined ? {} : { nested: options.nested }),
|
|
253
250
|
...(options.nestedFrames === undefined ? {} : { nestedFrames: options.nestedFrames }),
|
|
254
251
|
});
|
|
255
252
|
}
|
package/src/react/frame.tsx
CHANGED
|
@@ -656,12 +656,6 @@ export interface PortholeFrameProps {
|
|
|
656
656
|
readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
|
|
657
657
|
/** Too many declines: the display stops asking until it runs again. */
|
|
658
658
|
readonly onMuted?: () => void;
|
|
659
|
-
/**
|
|
660
|
-
* The content moved the keyboard into its frame from one of the page's text fields without the
|
|
661
|
-
* person, and focus went back (P109); `typing`: the person was typing on the page. A display
|
|
662
|
-
* that keeps doing it is stopped (`onContentError` says so).
|
|
663
|
-
*/
|
|
664
|
-
readonly onFocusTaken?: (taken: { readonly typing: boolean }) => void;
|
|
665
659
|
/**
|
|
666
660
|
* How the frame's first document went: loaded, blocked (and why), or a timeout. A host shows its
|
|
667
661
|
* own fallback (a url-mode app "Open in a new tab") on anything but loaded.
|
|
@@ -1067,9 +1061,6 @@ function Mount({
|
|
|
1067
1061
|
case "muted":
|
|
1068
1062
|
frame.onMuted?.();
|
|
1069
1063
|
return;
|
|
1070
|
-
case "focusTaken":
|
|
1071
|
-
frame.onFocusTaken?.(detail as DisplayEvents["focusTaken"]);
|
|
1072
|
-
return;
|
|
1073
1064
|
case "outcome":
|
|
1074
1065
|
frame.onOutcome?.(detail as DisplayEvents["outcome"]);
|
|
1075
1066
|
return;
|
|
@@ -1205,7 +1196,6 @@ function Mount({
|
|
|
1205
1196
|
"navigationBlocked",
|
|
1206
1197
|
"refused",
|
|
1207
1198
|
"muted",
|
|
1208
|
-
"focusTaken",
|
|
1209
1199
|
"outcome",
|
|
1210
1200
|
"annotation",
|
|
1211
1201
|
"findRequested",
|
package/src/runtime/contract.ts
CHANGED
|
@@ -51,8 +51,8 @@ export interface RuntimeMethod {
|
|
|
51
51
|
readonly watch?: true;
|
|
52
52
|
/**
|
|
53
53
|
* Gates of its own, over its host function's (after the review, P088): what changes the
|
|
54
|
-
* artifact for everyone needs the person's
|
|
55
|
-
*
|
|
54
|
+
* artifact for everyone needs the person's yes. A host's config may replace them
|
|
55
|
+
* (`CapabilityConfig.methodGates`).
|
|
56
56
|
*/
|
|
57
57
|
readonly gates?: readonly Gate[];
|
|
58
58
|
}
|
|
@@ -82,8 +82,8 @@ const method = (
|
|
|
82
82
|
...(extra.gates === undefined ? {} : { gates: extra.gates }),
|
|
83
83
|
});
|
|
84
84
|
|
|
85
|
-
/** What changes the artifact for everyone: the person's
|
|
86
|
-
const CHANGES: readonly Gate[] = ["
|
|
85
|
+
/** What changes the artifact for everyone: the person's yes, to its whole effect (no proof of a click since 0.16.0, P149). */
|
|
86
|
+
const CHANGES: readonly Gate[] = ["confirm"];
|
|
87
87
|
|
|
88
88
|
/** Contract 1's capabilities, by the name a page passes to `use`. */
|
|
89
89
|
export const RUNTIME_CAPABILITIES = {
|