@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
@@ -1,9 +1,18 @@
1
1
  import type { CompiledConfig } from "../compile/compile.ts";
2
- import { servedPermissionsPolicy, serializeCsp, type CspDirective } from "../compile/policy.ts";
2
+ import {
3
+ INERT_FILE_CSP,
4
+ PAGE_SANDBOX_TOKENS,
5
+ servedPermissionsPolicy,
6
+ serializeCsp,
7
+ type CspDirective,
8
+ } from "../compile/policy.ts";
3
9
  import { frameShellDocument, frameShellScript, type FrameShellOptions } from "../shell/frame.ts";
10
+ import { onNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
4
11
  import { sha256, utf8 } from "./crypto.ts";
5
12
  import { base32 } from "./keys.ts";
6
13
 
14
+ export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
15
+
7
16
  /**
8
17
  * A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
9
18
  * `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
@@ -16,14 +25,6 @@ import { base32 } from "./keys.ts";
16
25
  * address.
17
26
  */
18
27
 
19
- /**
20
- * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
21
- * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
22
- */
23
- export const PORTHOLE_LABEL_PREFIX = "porthole-";
24
-
25
- const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
26
-
27
28
  /**
28
29
  * The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
29
30
  * base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
@@ -37,9 +38,6 @@ export function nestedLabelOf(label: string): string {
37
38
  return `${PORTHOLE_LABEL_PREFIX}${base32(sha256(utf8(`porthole/nested/${label}`)).subarray(0, 15))}`;
38
39
  }
39
40
 
40
- /** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
41
- export const isNestedLabel = (label: string): boolean => NESTED_LABEL.test(label);
42
-
43
41
  /** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
44
42
  export const NESTED_FILES_PREFIX = "/__porthole/f/";
45
43
 
@@ -77,6 +75,16 @@ export function nestedShellResponse(
77
75
  compiled: CompiledConfig,
78
76
  options: FrameShellOptions & { readonly origin: string; readonly method?: string },
79
77
  ): Response {
78
+ // On the shell's own label alone (P114), its page on that origin (P121): a content Worker of a
79
+ // host's own that would serve it beside other content is refused here, not left to its routes.
80
+ if (!onNestedLabel(options.origin)) {
81
+ throw new TypeError(
82
+ `nestedShellResponse: origin ${options.origin} isn't on a nested page's own label (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf)`,
83
+ );
84
+ }
85
+ if (new URL(options.page).origin !== options.origin) {
86
+ throw new TypeError("nestedShellResponse: page is on the shell's own origin");
87
+ }
80
88
  const script = frameShellScript(options);
81
89
  const headers = new Headers({
82
90
  "content-type": "text/html; charset=utf-8",
@@ -104,6 +112,30 @@ export function nestedShellResponse(
104
112
  export const nestedAncestors = (origin: string, frameAncestors: string): string =>
105
113
  `${origin} ${frameAncestors}`;
106
114
 
115
+ /**
116
+ * A nested page's answer's CSP below its sealed prefix, by what it is (P111; the one source for
117
+ * `/server` and a content Worker of a host's own, P121): a page its directives and
118
+ * `sandbox allow-scripts`, so it is an opaque origin in the shell's child and on a tab of its own
119
+ * (never `allow-same-origin`, which would give it the shell's origin and realm); a script its
120
+ * directives and `sandbox` (a worker's policy is its script's; opened on its own it runs nothing on
121
+ * the shell's origin); any other file nothing at all. `directives` are the page's: the compiled
122
+ * config's, its files' prefix opened (`fileSetCspDirectives(compiled.cspDirectives, source)`) for
123
+ * a page of a file set. Then who may frame it: `frame-ancestors` (`nestedAncestors`).
124
+ */
125
+ export function nestedFileCsp(
126
+ role: "page" | "script" | "file",
127
+ directives: readonly CspDirective[],
128
+ ): string {
129
+ switch (role) {
130
+ case "page":
131
+ return serializeCsp([...directives, ["sandbox", ...PAGE_SANDBOX_TOKENS]]);
132
+ case "script":
133
+ return serializeCsp([...directives, ["sandbox"]]);
134
+ case "file":
135
+ return INERT_FILE_CSP;
136
+ }
137
+ }
138
+
107
139
  /**
108
140
  * What a nested page's files (not its pages) carry beyond a served file's (P111): its page's
109
141
  * origin is opaque, so a same-origin resource policy would refuse its own images and scripts, and
@@ -18,6 +18,7 @@ import {
18
18
  isNestedLabel,
19
19
  nestedAncestors,
20
20
  nestedLabelOf,
21
+ nestedFileCsp,
21
22
  nestedShellResponse,
22
23
  PORTHOLE_LABEL_PREFIX,
23
24
  } from "./nested.ts";
@@ -1199,11 +1200,11 @@ export function createServer(options: ServerOptions): PortholeServer {
1199
1200
  // A page that may use its artifact's assets loads them from its own origin (P089); every
1200
1201
  // served page carries its frame's sandbox, a tab of its own included (P099).
1201
1202
  const { config, cspDirectives } = served.compiled;
1203
+ const directives = served.assets
1204
+ ? assetCspDirectives(config, cspDirectives, access.origin)
1205
+ : cspDirectives;
1202
1206
  const headers = documentHeaders(
1203
- servedDocumentCsp(
1204
- config,
1205
- served.assets ? assetCspDirectives(config, cspDirectives, access.origin) : cspDirectives,
1206
- ),
1207
+ nested ? nestedFileCsp("page", directives) : servedDocumentCsp(config, directives),
1207
1208
  servedPermissionsPolicy(config),
1208
1209
  ancestors,
1209
1210
  );
@@ -1,5 +1,5 @@
1
1
  import { PAGE_SANDBOX_TOKENS } from "../compile/policy.ts";
2
- import { hostOriginProblem } from "../isolation/served.ts";
2
+ import { hostOriginProblem, onNestedLabel } from "../isolation/served.ts";
3
3
 
4
4
  /**
5
5
  * Porthole's shell for a nested page (P111): the whole document at the address the host frames,
@@ -18,8 +18,11 @@ import { hostOriginProblem } from "../isolation/served.ts";
18
18
  * shell (activation goes up, never down), so the shell's activation turning on is a press or
19
19
  * key of the person's in this page. It is read at every animation frame, on its window's focus
20
20
  * and blur, and before each message of the page's is passed on (a call made in a click's handler
21
- * arrives after the state that says so). What it can't see: a gesture while its activation is
22
- * already on (within 5 s of the last one) turns nothing on;
21
+ * arrives after the state that says so), and at once when the host asks (`porthole/shell/look`,
22
+ * P120: the host heard focus move into the frame, and a key the person types into the page
23
+ * before the shell's next frame would turn its activation on as a press does). What it can't
24
+ * see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
25
+ * on;
23
26
  * - renews the page's sealed files' address before it ends, and gives the page the new one
24
27
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
25
28
  * are), so only the shell, on that origin, may renew it (P083);
@@ -32,6 +35,12 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
32
35
  const plan = __PLAN__;
33
36
  const PREFIX = "porthole/shell/";
34
37
  const own = location.origin;
38
+ // A nested page's shell runs on a label of its own alone (P114, P121): on any other origin (its
39
+ // scope's, where other displays run content with allow-same-origin) it frames nothing and says
40
+ // nothing.
41
+ if (!/^porthole-[a-z2-7]{24}\./.test(location.hostname + ".")) {
42
+ return;
43
+ }
35
44
  let page = null;
36
45
  try {
37
46
  page = new URL(plan.page);
@@ -96,21 +105,22 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
96
105
  let focused = false;
97
106
  let lookedAt = performance.now();
98
107
  let toldAt = 0;
99
- const tell = (gap) => {
108
+ const tell = (gap, asked) => {
100
109
  toldAt = performance.now();
101
- toHost({
102
- jsonrpc: "2.0",
103
- method: PREFIX + "state",
104
- params: {
105
- supported: activation !== undefined,
106
- active,
107
- ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
108
- focused,
109
- gap: Math.max(0, Math.round(gap)),
110
- },
111
- });
110
+ const params = {
111
+ supported: activation !== undefined,
112
+ active,
113
+ ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
114
+ focused,
115
+ gap: Math.max(0, Math.round(gap)),
116
+ };
117
+ // The answer to the host's ask (P120), by its number.
118
+ if (asked !== undefined) {
119
+ params.asked = asked;
120
+ }
121
+ toHost({ jsonrpc: "2.0", method: PREFIX + "state", params });
112
122
  };
113
- const look = () => {
123
+ const look = (asked) => {
114
124
  const now = performance.now();
115
125
  const gap = now - lookedAt;
116
126
  lookedAt = now;
@@ -128,8 +138,8 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
128
138
  focused = inside;
129
139
  changed = true;
130
140
  }
131
- if (changed) {
132
- tell(gap);
141
+ if (changed || typeof asked === "number") {
142
+ tell(gap, typeof asked === "number" ? asked : undefined);
133
143
  } else if (now - toldAt >= 50) {
134
144
  // The heartbeat: the host knows the shell was looking, every 50 ms.
135
145
  toldAt = now;
@@ -167,6 +177,15 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
167
177
  return;
168
178
  }
169
179
  if (framed && source === window.parent && plan.origins.indexOf(event.origin) !== -1) {
180
+ const data = event.data;
181
+ // The host's words to the shell are never the page's to hear (P120): its ask to look now.
182
+ if (data !== null && typeof data === "object" && typeof data.method === "string" && data.method.indexOf(PREFIX) === 0) {
183
+ const n = data.params !== null && typeof data.params === "object" ? data.params.n : undefined;
184
+ if (data.method === PREFIX + "look" && typeof n === "number" && n >= 0 && Math.floor(n) === n) {
185
+ look(n);
186
+ }
187
+ return;
188
+ }
170
189
  const child = frame.contentWindow;
171
190
  if (child !== null) {
172
191
  child.postMessage(event.data, "*");
@@ -237,6 +256,12 @@ export function frameShellScript(options: FrameShellOptions): string {
237
256
  if (!page.pathname.startsWith("/__porthole/f/") || page.hash !== "") {
238
257
  throw new TypeError("frameShellScript: page is under /__porthole/f/, with no fragment");
239
258
  }
259
+ // The shell runs on a nested page's own label alone (P114), and its page is on its origin.
260
+ if (!onNestedLabel(page.origin)) {
261
+ throw new TypeError(
262
+ "frameShellScript: page is on a nested page's own label (porthole-<24 base32>, nestedLabelOf)",
263
+ );
264
+ }
240
265
  return FRAME_SHELL_RUNTIME.replace("__PLAN__", () =>
241
266
  scriptJson({
242
267
  origins: options.origins,