@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.
- package/CHANGELOG.md +77 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +2 -0
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +4 -0
- package/dist/host/outcome.js +43 -0
- package/dist/host/types.d.ts +12 -4
- package/dist/isolation/served.d.ts +17 -1
- package/dist/isolation/served.js +24 -1
- package/dist/isolation/types.d.ts +5 -0
- package/dist/isolation/types.js +5 -0
- package/dist/platform/focus-guard.d.ts +40 -0
- package/dist/platform/focus-guard.js +176 -32
- package/dist/platform/web.js +24 -9
- package/dist/react/frame.d.ts +2 -1
- package/dist/server/files.js +7 -7
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +1 -1
- package/dist/server/nested.d.ts +13 -7
- package/dist/server/nested.js +31 -9
- package/dist/server/server.js +5 -2
- package/dist/shell/frame.d.ts +5 -2
- package/dist/shell/frame.js +41 -18
- package/docs/ADOPTING.md +37 -14
- package/docs/ARCHITECTURE.md +5 -1
- package/docs/DECISIONS.md +404 -2
- package/docs/DESIGN.md +11 -4
- package/docs/THREAT_MODEL.md +116 -32
- package/package.json +1 -1
- package/src/host/create-host.ts +2 -0
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +49 -0
- package/src/host/types.ts +12 -4
- package/src/isolation/served.ts +29 -0
- package/src/isolation/types.ts +6 -0
- package/src/platform/focus-guard.ts +218 -34
- package/src/platform/web.ts +29 -12
- package/src/react/frame.tsx +2 -1
- package/src/server/files.ts +5 -6
- package/src/server/index.ts +1 -0
- package/src/server/nested.ts +44 -12
- package/src/server/server.ts +5 -4
- package/src/shell/frame.ts +43 -18
package/src/server/nested.ts
CHANGED
|
@@ -1,9 +1,18 @@
|
|
|
1
1
|
import type { CompiledConfig } from "../compile/compile.ts";
|
|
2
|
-
import {
|
|
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
|
package/src/server/server.ts
CHANGED
|
@@ -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
|
);
|
package/src/shell/frame.ts
CHANGED
|
@@ -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)
|
|
22
|
-
*
|
|
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
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
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,
|