@botiverse/porthole 0.14.3 → 0.14.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/CHANGELOG.md +77 -0
  2. package/dist/check/page-source.js +1 -1
  3. package/dist/conformance/harness-source.js +1 -1
  4. package/dist/host/create-host.js +2 -0
  5. package/dist/host/locate.d.ts +1 -1
  6. package/dist/host/locate.js +2 -2
  7. package/dist/host/outcome.d.ts +4 -0
  8. package/dist/host/outcome.js +43 -0
  9. package/dist/host/types.d.ts +12 -4
  10. package/dist/isolation/served.d.ts +17 -1
  11. package/dist/isolation/served.js +24 -1
  12. package/dist/isolation/types.d.ts +5 -0
  13. package/dist/isolation/types.js +5 -0
  14. package/dist/platform/focus-guard.d.ts +40 -0
  15. package/dist/platform/focus-guard.js +176 -32
  16. package/dist/platform/web.js +24 -9
  17. package/dist/react/frame.d.ts +2 -1
  18. package/dist/server/files.js +7 -7
  19. package/dist/server/index.d.ts +1 -1
  20. package/dist/server/index.js +1 -1
  21. package/dist/server/nested.d.ts +13 -7
  22. package/dist/server/nested.js +31 -9
  23. package/dist/server/server.js +5 -2
  24. package/dist/shell/frame.d.ts +5 -2
  25. package/dist/shell/frame.js +41 -18
  26. package/docs/ADOPTING.md +37 -14
  27. package/docs/ARCHITECTURE.md +5 -1
  28. package/docs/DECISIONS.md +404 -2
  29. package/docs/DESIGN.md +11 -4
  30. package/docs/THREAT_MODEL.md +116 -32
  31. package/package.json +1 -1
  32. package/src/host/create-host.ts +2 -0
  33. package/src/host/locate.ts +2 -2
  34. package/src/host/outcome.ts +49 -0
  35. package/src/host/types.ts +12 -4
  36. package/src/isolation/served.ts +29 -0
  37. package/src/isolation/types.ts +6 -0
  38. package/src/platform/focus-guard.ts +218 -34
  39. package/src/platform/web.ts +29 -12
  40. package/src/react/frame.tsx +2 -1
  41. package/src/server/files.ts +5 -6
  42. package/src/server/index.ts +1 -0
  43. package/src/server/nested.ts +44 -12
  44. package/src/server/server.ts +5 -4
  45. package/src/shell/frame.ts +43 -18
@@ -514,6 +514,8 @@ export function createHost(config, options = {}) {
514
514
  speaks,
515
515
  timeoutMs: config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS,
516
516
  onOutcome: (outcome) => emit("outcome", outcome),
517
+ // A frame status from the content (P124): never shown, the host's to hear.
518
+ refused: (message) => hostError(message, "frame-status"),
517
519
  });
518
520
  outcomeWatch = watch;
519
521
  if (!speaks) {
@@ -3,6 +3,6 @@ import type { FrameSource, InstanceLocator, InstanceRef } from "../isolation/typ
3
3
  /**
4
4
  * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
5
5
  * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
6
- * own site) before any frame is made.
6
+ * own site; a nested page's on a shell's own label, P121) before any frame is made.
7
7
  */
8
8
  export declare function locateServed(locator: InstanceLocator, instance: InstanceRef, config: PortholeConfig, hostOrigin: string, signal?: AbortSignal): Promise<FrameSource>;
@@ -3,11 +3,11 @@ import { parseViewer } from "../runtime/levels.js";
3
3
  /**
4
4
  * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
5
5
  * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
6
- * own site) before any frame is made.
6
+ * own site; a nested page's on a shell's own label, P121) before any frame is made.
7
7
  */
8
8
  export async function locateServed(locator, instance, config, hostOrigin, signal) {
9
9
  const location = await locator.locate(instance, signal);
10
- checkFrameLocation(location, config.contentOrigins, hostOrigin);
10
+ checkFrameLocation(location, config.contentOrigins, hostOrigin, config.nested === true);
11
11
  // The host's access, as its backend answered (P087): a viewer that doesn't parse is the host's
12
12
  // error, never no viewer (after the review: a mount's own would take its place).
13
13
  const viewer = location.viewer === undefined ? null : parseViewer(location.viewer);
@@ -9,6 +9,8 @@ interface FrameStatus {
9
9
  }
10
10
  /** A frame-status message, or null for anything else. */
11
11
  export declare function parseFrameStatus(data: unknown): FrameStatus | null;
12
+ /** What the host is told of a frame status it didn't take (P124). */
13
+ export declare const UNTRUSTED_FRAME_STATUS = "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
12
14
  export interface OutcomeWatch {
13
15
  /** The frame finished its handshake. */
14
16
  initialized(): void;
@@ -21,5 +23,7 @@ export declare function watchOutcome(options: {
21
23
  readonly speaks: boolean;
22
24
  readonly timeoutMs: number;
23
25
  readonly onOutcome: (outcome: FrameOutcome) => void;
26
+ /** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
27
+ readonly refused?: (message: string) => void;
24
28
  }): OutcomeWatch;
25
29
  export {};
@@ -12,6 +12,27 @@ import { FRAME_STATUS_METHOD } from "../isolation/types.js";
12
12
  * - an app from a host's own gateway is loaded on its first load, unless its page says it is
13
13
  * blocked (the gateway may send the same message);
14
14
  * - nothing settled in `timeoutMs`: a timeout.
15
+ *
16
+ * Who may say how loading went (P124). A frame status is taken only from a document of Porthole's
17
+ * server, a host's gateway or the host's own pages, never from content: its words draw the host's
18
+ * fallback, in Porthole's wording, with a link. Nothing in a message tells who sent it (a page
19
+ * that shares the frame's window and origin can send the same bytes), so the host goes by what
20
+ * content can't change: where the frame's documents come from, and in what order they speak.
21
+ *
22
+ * - An opaque frame's only document is the host's own shell, with the content in it: no page of
23
+ * Porthole's server ever loads there, so its every frame status is the content's.
24
+ * - A frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell)
25
+ * says Porthole's own word first in every document that holds content, before any of the
26
+ * content's code runs: the shell's hello, the proxy's ready (a nested page's own runtime's hello
27
+ * reaches the host before anything its page says, through its shell). A status page says
28
+ * nothing but its frame status. So a frame status is taken only before anything else was heard
29
+ * from the frame in this run: from its first document, which then was a page of Porthole's.
30
+ * After that, it came from the content (or from a later document, which in a display without
31
+ * files starts the display again, whose first document then says how it went).
32
+ * - A url-mode app has no shell to speak first, and shares its origin with the entry page and the
33
+ * status pages: its frame status is taken as before, the app's word (THREAT_MODEL S6).
34
+ *
35
+ * A frame status not taken is dropped, and told once a run to the host (`refused`).
15
36
  */
16
37
  /** How long after a load the frame's word may still arrive. */
17
38
  const SETTLE_MS = 400;
@@ -58,12 +79,21 @@ export function parseFrameStatus(data) {
58
79
  : {}),
59
80
  };
60
81
  }
82
+ /** Whether a message names the frame-status method, well formed or not. */
83
+ const namesFrameStatus = (data) => data !== null &&
84
+ typeof data === "object" &&
85
+ data.method === FRAME_STATUS_METHOD;
86
+ /** What the host is told of a frame status it didn't take (P124). */
87
+ export const UNTRUSTED_FRAME_STATUS = "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
61
88
  export function watchOutcome(options) {
62
89
  const { surface, source, speaks } = options;
63
90
  const reports = source.kind === "url" && source.reports === true;
64
91
  // The first outcome; after a load, only a later block (a status page, access revoked) is told.
65
92
  let decided = null;
66
93
  let heard = false;
94
+ // Whether the frame said anything but a frame status in this run (P124).
95
+ let spoke = false;
96
+ let told = false;
67
97
  let entering = false;
68
98
  let loads = 0;
69
99
  const timers = new Set();
@@ -96,8 +126,21 @@ export function watchOutcome(options) {
96
126
  options.onOutcome(outcome);
97
127
  }
98
128
  };
129
+ // Whether a frame status may be the word of a page of Porthole's (P124, above).
130
+ const mayBePorthole = () => source.kind === "url" && (!speaks || !spoke);
99
131
  const unlisten = surface.transport.listen((data) => {
100
132
  heard = true;
133
+ if (!namesFrameStatus(data)) {
134
+ spoke = true;
135
+ return;
136
+ }
137
+ if (!mayBePorthole()) {
138
+ if (!told) {
139
+ told = true;
140
+ options.refused?.(UNTRUSTED_FRAME_STATUS);
141
+ }
142
+ return;
143
+ }
101
144
  const status = parseFrameStatus(data);
102
145
  if (status?.state === "entering") {
103
146
  entering = true;
@@ -117,7 +117,13 @@ export type HostErrorKind =
117
117
  /** A display couldn't be made (the React binding: a bad config, a missing handler). */
118
118
  | "mount"
119
119
  /** An annotation call was refused (an invalid mark, an unknown id). */
120
- | "annotations";
120
+ | "annotations"
121
+ /**
122
+ * A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
123
+ * from the frame's content, not from a page of Porthole's server (P124): never shown, never an
124
+ * outcome. Told once a run.
125
+ */
126
+ | "frame-status";
121
127
  /** What a display reports, by event name. */
122
128
  /** Why a display's frame showed nothing of its content (`FrameOutcome`). */
123
129
  export type FrameBlock =
@@ -138,9 +144,11 @@ export type FrameBlock =
138
144
  /**
139
145
  * How a display's document went: it loaded (a shell or view finished its handshake; a url-mode
140
146
  * app's document loaded), it was blocked (and why), or nothing settled in
141
- * `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if the frame shows a status page
142
- * after it loaded (access revoked mid-session). A host shows its own fallback ("Open in a new
143
- * tab") on anything but loaded.
147
+ * `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if a url-mode app's frame shows a
148
+ * status page after it loaded (access revoked mid-session). A host shows its own fallback ("Open in
149
+ * a new tab") on anything but loaded. A `blocked` is the word of a page of Porthole's server (or a
150
+ * host's gateway, or its own pages), never of a frame's content, except a url-mode app's (P124):
151
+ * in a frame that speaks, only its run's first document says it; an opaque frame never does.
144
152
  */
145
153
  export type FrameOutcome = {
146
154
  readonly state: "loaded";
@@ -6,6 +6,20 @@ interface ParsedOrigin {
6
6
  }
7
7
  /** `scheme://host[:port]`, lowercase, nothing else; null for anything that isn't exactly that. */
8
8
  export declare function parseOrigin(origin: string): ParsedOrigin | null;
9
+ /**
10
+ * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
11
+ * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
12
+ */
13
+ export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
14
+ /** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
15
+ export declare const isNestedLabel: (label: string) => boolean;
16
+ /**
17
+ * Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
18
+ * The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
19
+ * each refuse any other origin, so a content Worker of a host's own can't put it beside other
20
+ * content by mistake.
21
+ */
22
+ export declare function onNestedLabel(origin: string): boolean;
9
23
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
10
24
  export declare function isExactOrigin(origin: unknown): origin is string;
11
25
  export declare function isHostOrigin(origin: unknown): origin is string;
@@ -31,5 +45,7 @@ export declare function originMatchesSource(origin: string, source: string): boo
31
45
  * names, and it is not of the host's own site (a same-site frame with `allow-same-origin` could
32
46
  * reach cookies and storage the host shares with its site).
33
47
  */
34
- export declare function checkFrameLocation(location: FrameLocation, contentOrigins: readonly string[], hostOrigin: string): void;
48
+ export declare function checkFrameLocation(location: FrameLocation, contentOrigins: readonly string[], hostOrigin: string,
49
+ /** The config nests its pages (P111): the location must be on a shell's own label (P121). */
50
+ nested?: boolean): void;
35
51
  export {};
@@ -15,6 +15,24 @@ export function parseOrigin(origin) {
15
15
  const [, scheme = "", host = "", port] = match;
16
16
  return { scheme, host, port: port ?? DEFAULT_PORTS[scheme] ?? "" };
17
17
  }
18
+ /**
19
+ * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
20
+ * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
21
+ */
22
+ export const PORTHOLE_LABEL_PREFIX = "porthole-";
23
+ const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
24
+ /** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
25
+ export const isNestedLabel = (label) => NESTED_LABEL.test(label);
26
+ /**
27
+ * Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
28
+ * The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
29
+ * each refuse any other origin, so a content Worker of a host's own can't put it beside other
30
+ * content by mistake.
31
+ */
32
+ export function onNestedLabel(origin) {
33
+ const parsed = parseOrigin(origin);
34
+ return parsed !== null && isNestedLabel(parsed.host.split(".")[0] ?? "");
35
+ }
18
36
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
19
37
  export function isExactOrigin(origin) {
20
38
  return typeof origin === "string" && parseOrigin(origin) !== null;
@@ -95,7 +113,9 @@ export function originMatchesSource(origin, source) {
95
113
  * names, and it is not of the host's own site (a same-site frame with `allow-same-origin` could
96
114
  * reach cookies and storage the host shares with its site).
97
115
  */
98
- export function checkFrameLocation(location, contentOrigins, hostOrigin) {
116
+ export function checkFrameLocation(location, contentOrigins, hostOrigin,
117
+ /** The config nests its pages (P111): the location must be on a shell's own label (P121). */
118
+ nested = false) {
99
119
  const origin = parseOrigin(location.origin);
100
120
  let url;
101
121
  try {
@@ -112,6 +132,9 @@ export function checkFrameLocation(location, contentOrigins, hostOrigin) {
112
132
  if (!contentOrigins.some((source) => originMatchesSource(location.origin, source))) {
113
133
  throw new TypeError(`The located origin ${location.origin} is not one of the config's content origins`);
114
134
  }
135
+ if (nested && !onNestedLabel(location.origin)) {
136
+ throw new TypeError(`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`);
137
+ }
115
138
  const host = parseOrigin(hostOrigin);
116
139
  if (host !== null && maybeSameSite(origin.host, host.host)) {
117
140
  throw new TypeError(`The located origin ${location.origin} may be the same site as the host (${hostOrigin}): content must be served from a registrable domain the host uses for nothing else`);
@@ -83,6 +83,11 @@ export declare const FRAME_STATUS_METHOD = "porthole/notifications/frame-status"
83
83
  export declare const SHELL_STATE_METHOD = "porthole/shell/state";
84
84
  /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
85
85
  export declare const SHELL_BEAT_METHOD = "porthole/shell/beat";
86
+ /**
87
+ * The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
88
+ * that names the ask (`asked`). The host asks as it hears focus move into the frame.
89
+ */
90
+ export declare const SHELL_LOOK_METHOD = "porthole/shell/look";
86
91
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
87
92
  export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
88
93
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -4,6 +4,11 @@ export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
4
4
  export const SHELL_STATE_METHOD = "porthole/shell/state";
5
5
  /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
6
6
  export const SHELL_BEAT_METHOD = "porthole/shell/beat";
7
+ /**
8
+ * The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
9
+ * that names the ask (`asked`). The host asks as it hears focus move into the frame.
10
+ */
11
+ export const SHELL_LOOK_METHOD = "porthole/shell/look";
7
12
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
8
13
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
9
14
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -18,6 +18,15 @@
18
18
  * frame again (the review of the guard, GK-1): the guard keeps watching after each take-back and
19
19
  * counts one that didn't hold. Every engine keeps a gesture's transient activation for 5 s
20
20
  * (measured: 5.04 to 5.10 s).
21
+ *
22
+ * A nested page's shell (P111) says when its activation turned on, which a press in the page does,
23
+ * and so does a key the person typed into it: one meant for the host's composer, after the page took
24
+ * the keyboard and before the guard took it back (the audit of P111's guard, NG-1). Neither the
25
+ * shell nor the host's page can tell the two apart from the activation (the shell gets no event as
26
+ * focus comes into its child, measured), so (P120): in a fight over a text field the shell's word
27
+ * isn't asked; a wait on a move from a text field doesn't end with the frame holding focus unjudged;
28
+ * and where the host's page sees the pointer over its frames, an activation while it isn't over the
29
+ * frame and the person was typing is no press.
21
30
  */
22
31
  /** How long the person's Tab counts as moving focus (the move follows its keydown at once). */
23
32
  export declare const TAB_MS = 1000;
@@ -28,6 +37,16 @@ export declare const TAB_MS = 1000;
28
37
  export declare const ACTIVATION_SPAN_MS = 5000;
29
38
  /** The person is typing: a key on the host's page within this long. */
30
39
  export declare const TYPING_MS = 1000;
40
+ /**
41
+ * No press of the person's lands on a frame this soon after a key they typed on the host's page
42
+ * (P122): a hand on the keys doesn't reach the pointer and press that fast (the Keystroke-Level
43
+ * Model gives 400 ms to the hand's move from the keys to the mouse alone; Card, Moran and Newell,
44
+ * 1980). A move into a nested page's frame, or its shell's activation turning on, within this long
45
+ * is the person's next key landing in the page, which turns its activation on as a press does.
46
+ * Where neither the host's page nor the shell sees the pointer (full Chromium), it holds a page that
47
+ * takes the keyboard while the person types even when their key outruns the shell's answer.
48
+ */
49
+ export declare const KEY_PRESS_MS = 250;
31
50
  /**
32
51
  * After a take-back, the guard keeps watching (each animation frame) until focus has stayed in the
33
52
  * text field this long: a page that takes it again at once (on its own blur, which the take-back
@@ -98,6 +117,12 @@ export interface ShellWord {
98
117
  readonly focusedAt: number;
99
118
  /** Its activation turned on while it was stalled: uncertain until it goes off (`SHELL_STALL_MS`). */
100
119
  readonly uncertain?: boolean;
120
+ /**
121
+ * Its activation turned on within `TYPING_MS` of the person's typing on the host's page, the
122
+ * pointer not come over the frame since (`pressPossible`, judged as it turned on): where the
123
+ * host's page sees the pointer, their key landing in the page, no press (P120).
124
+ */
125
+ readonly keyed?: boolean;
101
126
  }
102
127
  /** One move of the keyboard the guard undid. */
103
128
  export interface FocusTake {
@@ -142,6 +167,8 @@ export interface FocusMove {
142
167
  readonly shell?: {
143
168
  readonly word: ShellWord;
144
169
  readonly hostInputAt: number;
170
+ /** The host's page sees the pointer over its frames on this engine (`pressPossible`, P120). */
171
+ readonly pointerShown?: boolean;
145
172
  };
146
173
  }
147
174
  /**
@@ -167,6 +194,15 @@ export declare function personMoved(move: FocusMove): boolean;
167
194
  * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key.
168
195
  */
169
196
  export declare function shellGesture(word: ShellWord, hostInputAt: number, now: number): boolean;
197
+ /**
198
+ * Whether the person could have pressed the frame just before `at` (P120): a nested page's shell
199
+ * says its activation turned on, which a key typed into the page does as well as a press. Where the
200
+ * host's page sees the pointer over its frames (`shown`: Firefox; Chromium and WebKit where the frame
201
+ * is in their process, not full Chromium), a press needs the pointer over the frame, come over it
202
+ * since the person last typed on the host's page; within `TYPING_MS` of that typing, an activation
203
+ * with the pointer elsewhere is their keys landing in the page. Anywhere else it may be a press.
204
+ */
205
+ export declare function pressPossible(shown: boolean, over: boolean, overSince: number, typedAt: number, at: number): boolean;
170
206
  /** Whether `element` takes the person's typed text: a text field, a text area, an editable region. */
171
207
  export declare function takesText(element: Element | null): element is HTMLElement;
172
208
  /** One page's guard, shared by every display's frame on it. */
@@ -177,6 +213,8 @@ export interface FocusGuard {
177
213
  */
178
214
  add(frame: HTMLIFrameElement, taken: (take: FocusTake) => void, options?: {
179
215
  readonly nested?: boolean;
216
+ /** Asks a nested page's shell to look now (P120); it answers with a report naming `n`. */
217
+ readonly ask?: (n: number) => void;
180
218
  }): () => void;
181
219
  /** What a nested page's shell said (P111): its activation, its focus. */
182
220
  shell(frame: HTMLIFrameElement, said: {
@@ -185,6 +223,8 @@ export interface FocusGuard {
185
223
  readonly focused: boolean;
186
224
  /** How long the shell went without a look before this one (its own clock). */
187
225
  readonly gap: number;
226
+ /** The ask this report answers (P120), if it answers one. */
227
+ readonly asked?: number;
188
228
  }): void;
189
229
  /** A nested page's shell's heartbeat (P111): it is looking. */
190
230
  beat(frame: HTMLIFrameElement): void;