@botiverse/porthole 0.14.3 → 0.14.4
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 +59 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- 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/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 +32 -14
- package/docs/ARCHITECTURE.md +5 -1
- package/docs/DECISIONS.md +312 -2
- package/docs/DESIGN.md +8 -3
- package/docs/THREAT_MODEL.md +85 -30
- package/package.json +1 -1
- package/src/host/locate.ts +2 -2
- 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/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/dist/platform/web.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { FRAME_STATUS_METHOD, SHELL_BEAT_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
|
|
1
|
+
import { FRAME_STATUS_METHOD, SHELL_BEAT_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
|
|
2
2
|
import { postMessageTransport } from "../transport/post-message.js";
|
|
3
3
|
import { focusGuard } from "./focus-guard.js";
|
|
4
4
|
/** A frame-status message (`porthole/notifications/frame-status`), by its method alone. */
|
|
@@ -28,7 +28,7 @@ function shellWords(opened, frame, guard) {
|
|
|
28
28
|
if (params === null || typeof params !== "object") {
|
|
29
29
|
return;
|
|
30
30
|
}
|
|
31
|
-
const { supported, ago, focused, gap } = params;
|
|
31
|
+
const { supported, ago, focused, gap, asked } = params;
|
|
32
32
|
const span = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
|
|
33
33
|
if (message.method === SHELL_BEAT_METHOD) {
|
|
34
34
|
if (span(gap)) {
|
|
@@ -40,10 +40,17 @@ function shellWords(opened, frame, guard) {
|
|
|
40
40
|
typeof supported !== "boolean" ||
|
|
41
41
|
typeof focused !== "boolean" ||
|
|
42
42
|
!(ago === null || span(ago)) ||
|
|
43
|
-
!span(gap)
|
|
43
|
+
!span(gap) ||
|
|
44
|
+
!(asked === undefined || (Number.isSafeInteger(asked) && asked >= 0))) {
|
|
44
45
|
return;
|
|
45
46
|
}
|
|
46
|
-
guard.shell(frame, {
|
|
47
|
+
guard.shell(frame, {
|
|
48
|
+
supported,
|
|
49
|
+
ago: ago,
|
|
50
|
+
focused,
|
|
51
|
+
gap: gap,
|
|
52
|
+
...(asked === undefined ? {} : { asked: asked }),
|
|
53
|
+
});
|
|
47
54
|
});
|
|
48
55
|
return {
|
|
49
56
|
send: (message) => opened.send(message),
|
|
@@ -113,17 +120,25 @@ export const webPlatform = {
|
|
|
113
120
|
const guard = focusGuard(view);
|
|
114
121
|
const taken = new Set();
|
|
115
122
|
const nested = spec.nested === true && spec.source.kind === "url";
|
|
116
|
-
const unguard = guard.add(frame, (take) => {
|
|
117
|
-
for (const listener of taken) {
|
|
118
|
-
listener(take);
|
|
119
|
-
}
|
|
120
|
-
}, { nested });
|
|
121
123
|
// A served frame may pass through the host's own pages (a redirect entry's, P068): what they
|
|
122
124
|
// say of the frame's status is heard too, and nothing else from there.
|
|
123
125
|
const own = view.origin;
|
|
124
126
|
const opened = postMessageTransport(() => frame.contentWindow, origin, view, origin === "null" || own === "null" || own === origin
|
|
125
127
|
? undefined
|
|
126
128
|
: { origin: own, accept: isFrameStatus });
|
|
129
|
+
const unguard = guard.add(frame, (take) => {
|
|
130
|
+
for (const listener of taken) {
|
|
131
|
+
listener(take);
|
|
132
|
+
}
|
|
133
|
+
}, {
|
|
134
|
+
nested,
|
|
135
|
+
// A nested page's shell is asked to look as the guard hears a move into its frame (P120).
|
|
136
|
+
...(nested
|
|
137
|
+
? {
|
|
138
|
+
ask: (n) => opened.send({ jsonrpc: "2.0", method: SHELL_LOOK_METHOD, params: { n } }),
|
|
139
|
+
}
|
|
140
|
+
: {}),
|
|
141
|
+
});
|
|
127
142
|
// A nested page's shell (P111): its own words go to the guard, by the frame's window and the
|
|
128
143
|
// content origin (the transport's checks); the page's pass on. The shell drops any page
|
|
129
144
|
// message in its namespace, so there none is the page's.
|
package/dist/server/files.js
CHANGED
|
@@ -3,7 +3,7 @@ import { DEFAULT_ENTRY, lookupFile, requestFilePath } from "../files/paths.js";
|
|
|
3
3
|
import { fileTypeOf } from "../files/types.js";
|
|
4
4
|
import { isCodeAsset } from "../runtime/requests.js";
|
|
5
5
|
import { sha256, utf8 } from "./crypto.js";
|
|
6
|
-
import { NESTED_FILE_HEADERS } from "./nested.js";
|
|
6
|
+
import { NESTED_FILE_HEADERS, nestedFileCsp } from "./nested.js";
|
|
7
7
|
const HEX = /^[0-9a-f]{64}$/u;
|
|
8
8
|
const YEAR = 31_536_000;
|
|
9
9
|
const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
@@ -174,12 +174,12 @@ export async function serveFile(serving) {
|
|
|
174
174
|
// sandbox, so none opened as a document on its own (a tab, "open image in new tab") runs on that
|
|
175
175
|
// origin. Pages run their scripts, opaque; anything else runs nothing (a file's is inert already,
|
|
176
176
|
// a script's gets one too).
|
|
177
|
-
const csp =
|
|
178
|
-
?
|
|
179
|
-
: role === "
|
|
180
|
-
?
|
|
181
|
-
:
|
|
182
|
-
?
|
|
177
|
+
const csp = nested
|
|
178
|
+
? nestedFileCsp(role, directives)
|
|
179
|
+
: role === "file"
|
|
180
|
+
? INERT_FILE_CSP
|
|
181
|
+
: role === "page"
|
|
182
|
+
? servedDocumentCsp(serving.compiled.config, directives)
|
|
183
183
|
: serializeCsp(directives);
|
|
184
184
|
const headers = new Headers({
|
|
185
185
|
"content-type": type,
|
package/dist/server/index.d.ts
CHANGED
|
@@ -37,7 +37,7 @@ export { createContentHost, HEALTH_PATH, ISSUE_BODY_BYTES, type ContentHealthVie
|
|
|
37
37
|
export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDomainInfo, type ContentDomainProblem, } from "./domain.ts";
|
|
38
38
|
export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
|
|
39
39
|
export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
40
|
-
export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.ts";
|
|
40
|
+
export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedFileCsp, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.ts";
|
|
41
41
|
export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
|
|
42
42
|
export { conformancePage } from "../conformance/page.ts";
|
|
43
43
|
export type { PortholeConfig } from "../config/schema.ts";
|
package/dist/server/index.js
CHANGED
|
@@ -41,7 +41,7 @@ export { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
|
41
41
|
// sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
|
|
42
42
|
// config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
|
|
43
43
|
// pages").
|
|
44
|
-
export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
|
|
44
|
+
export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedFileCsp, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
|
|
45
45
|
export { isHostLabel, prefixedName } from "./naming.js";
|
|
46
46
|
// The page an app serves in conformance test mode (P071).
|
|
47
47
|
export { conformancePage } from "../conformance/page.js";
|
package/dist/server/nested.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import type { CompiledConfig } from "../compile/compile.ts";
|
|
2
|
+
import { type CspDirective } from "../compile/policy.ts";
|
|
2
3
|
import { type FrameShellOptions } from "../shell/frame.ts";
|
|
4
|
+
export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
|
|
3
5
|
/**
|
|
4
6
|
* A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
|
|
5
7
|
* `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
|
|
@@ -11,11 +13,6 @@ import { type FrameShellOptions } from "../shell/frame.ts";
|
|
|
11
13
|
* `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
|
|
12
14
|
* address.
|
|
13
15
|
*/
|
|
14
|
-
/**
|
|
15
|
-
* The start of every label Porthole serves for itself on a content domain (P114): no host's naming
|
|
16
|
-
* may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
|
|
17
|
-
*/
|
|
18
|
-
export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
|
|
19
16
|
/**
|
|
20
17
|
* The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
|
|
21
18
|
* base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
|
|
@@ -26,8 +23,6 @@ export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
|
|
|
26
23
|
* serves its nested pages on it too.
|
|
27
24
|
*/
|
|
28
25
|
export declare function nestedLabelOf(label: string): string;
|
|
29
|
-
/** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
|
|
30
|
-
export declare const isNestedLabel: (label: string) => boolean;
|
|
31
26
|
/** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
|
|
32
27
|
export declare const NESTED_FILES_PREFIX = "/__porthole/f/";
|
|
33
28
|
/**
|
|
@@ -50,6 +45,17 @@ export declare function nestedShellResponse(compiled: CompiledConfig, options: F
|
|
|
50
45
|
* above it, the host origins (`frame-ancestors` names every ancestor).
|
|
51
46
|
*/
|
|
52
47
|
export declare const nestedAncestors: (origin: string, frameAncestors: string) => string;
|
|
48
|
+
/**
|
|
49
|
+
* A nested page's answer's CSP below its sealed prefix, by what it is (P111; the one source for
|
|
50
|
+
* `/server` and a content Worker of a host's own, P121): a page its directives and
|
|
51
|
+
* `sandbox allow-scripts`, so it is an opaque origin in the shell's child and on a tab of its own
|
|
52
|
+
* (never `allow-same-origin`, which would give it the shell's origin and realm); a script its
|
|
53
|
+
* directives and `sandbox` (a worker's policy is its script's; opened on its own it runs nothing on
|
|
54
|
+
* the shell's origin); any other file nothing at all. `directives` are the page's: the compiled
|
|
55
|
+
* config's, its files' prefix opened (`fileSetCspDirectives(compiled.cspDirectives, source)`) for
|
|
56
|
+
* a page of a file set. Then who may frame it: `frame-ancestors` (`nestedAncestors`).
|
|
57
|
+
*/
|
|
58
|
+
export declare function nestedFileCsp(role: "page" | "script" | "file", directives: readonly CspDirective[]): string;
|
|
53
59
|
/**
|
|
54
60
|
* What a nested page's files (not its pages) carry beyond a served file's (P111): its page's
|
|
55
61
|
* origin is opaque, so a same-origin resource policy would refuse its own images and scripts, and
|
package/dist/server/nested.js
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
import { servedPermissionsPolicy, serializeCsp } from "../compile/policy.js";
|
|
1
|
+
import { INERT_FILE_CSP, PAGE_SANDBOX_TOKENS, servedPermissionsPolicy, serializeCsp, } from "../compile/policy.js";
|
|
2
2
|
import { frameShellDocument, frameShellScript } from "../shell/frame.js";
|
|
3
|
+
import { onNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.js";
|
|
3
4
|
import { sha256, utf8 } from "./crypto.js";
|
|
4
5
|
import { base32 } from "./keys.js";
|
|
6
|
+
export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.js";
|
|
5
7
|
/**
|
|
6
8
|
* A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
|
|
7
9
|
* `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
|
|
@@ -13,12 +15,6 @@ import { base32 } from "./keys.js";
|
|
|
13
15
|
* `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
|
|
14
16
|
* address.
|
|
15
17
|
*/
|
|
16
|
-
/**
|
|
17
|
-
* The start of every label Porthole serves for itself on a content domain (P114): no host's naming
|
|
18
|
-
* may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
|
|
19
|
-
*/
|
|
20
|
-
export const PORTHOLE_LABEL_PREFIX = "porthole-";
|
|
21
|
-
const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
|
|
22
18
|
/**
|
|
23
19
|
* The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
|
|
24
20
|
* base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
|
|
@@ -31,8 +27,6 @@ const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
|
|
|
31
27
|
export function nestedLabelOf(label) {
|
|
32
28
|
return `${PORTHOLE_LABEL_PREFIX}${base32(sha256(utf8(`porthole/nested/${label}`)).subarray(0, 15))}`;
|
|
33
29
|
}
|
|
34
|
-
/** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
|
|
35
|
-
export const isNestedLabel = (label) => NESTED_LABEL.test(label);
|
|
36
30
|
/** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
|
|
37
31
|
export const NESTED_FILES_PREFIX = "/__porthole/f/";
|
|
38
32
|
const base64 = (bytes) => btoa(String.fromCharCode(...bytes));
|
|
@@ -60,6 +54,14 @@ export function nestedShellCsp(script, origin, hostOrigins) {
|
|
|
60
54
|
* stored (it carries the page's sealed address), its page at `options.page`.
|
|
61
55
|
*/
|
|
62
56
|
export function nestedShellResponse(compiled, options) {
|
|
57
|
+
// On the shell's own label alone (P114), its page on that origin (P121): a content Worker of a
|
|
58
|
+
// host's own that would serve it beside other content is refused here, not left to its routes.
|
|
59
|
+
if (!onNestedLabel(options.origin)) {
|
|
60
|
+
throw new TypeError(`nestedShellResponse: origin ${options.origin} isn't on a nested page's own label (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf)`);
|
|
61
|
+
}
|
|
62
|
+
if (new URL(options.page).origin !== options.origin) {
|
|
63
|
+
throw new TypeError("nestedShellResponse: page is on the shell's own origin");
|
|
64
|
+
}
|
|
63
65
|
const script = frameShellScript(options);
|
|
64
66
|
const headers = new Headers({
|
|
65
67
|
"content-type": "text/html; charset=utf-8",
|
|
@@ -84,6 +86,26 @@ export function nestedShellResponse(compiled, options) {
|
|
|
84
86
|
* above it, the host origins (`frame-ancestors` names every ancestor).
|
|
85
87
|
*/
|
|
86
88
|
export const nestedAncestors = (origin, frameAncestors) => `${origin} ${frameAncestors}`;
|
|
89
|
+
/**
|
|
90
|
+
* A nested page's answer's CSP below its sealed prefix, by what it is (P111; the one source for
|
|
91
|
+
* `/server` and a content Worker of a host's own, P121): a page its directives and
|
|
92
|
+
* `sandbox allow-scripts`, so it is an opaque origin in the shell's child and on a tab of its own
|
|
93
|
+
* (never `allow-same-origin`, which would give it the shell's origin and realm); a script its
|
|
94
|
+
* directives and `sandbox` (a worker's policy is its script's; opened on its own it runs nothing on
|
|
95
|
+
* the shell's origin); any other file nothing at all. `directives` are the page's: the compiled
|
|
96
|
+
* config's, its files' prefix opened (`fileSetCspDirectives(compiled.cspDirectives, source)`) for
|
|
97
|
+
* a page of a file set. Then who may frame it: `frame-ancestors` (`nestedAncestors`).
|
|
98
|
+
*/
|
|
99
|
+
export function nestedFileCsp(role, directives) {
|
|
100
|
+
switch (role) {
|
|
101
|
+
case "page":
|
|
102
|
+
return serializeCsp([...directives, ["sandbox", ...PAGE_SANDBOX_TOKENS]]);
|
|
103
|
+
case "script":
|
|
104
|
+
return serializeCsp([...directives, ["sandbox"]]);
|
|
105
|
+
case "file":
|
|
106
|
+
return INERT_FILE_CSP;
|
|
107
|
+
}
|
|
108
|
+
}
|
|
87
109
|
/**
|
|
88
110
|
* What a nested page's files (not its pages) carry beyond a served file's (P111): its page's
|
|
89
111
|
* origin is opaque, so a same-origin resource policy would refuse its own images and scripts, and
|
package/dist/server/server.js
CHANGED
|
@@ -7,7 +7,7 @@ import { isHostLabel, reservedLabels } from "./naming.js";
|
|
|
7
7
|
import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
|
|
8
8
|
import { libraryFile } from "./libraries.js";
|
|
9
9
|
import { isNavigation, ownLoad, serveAsset, serveFile } from "./files.js";
|
|
10
|
-
import { isNestedLabel, nestedAncestors, nestedLabelOf, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
|
|
10
|
+
import { isNestedLabel, nestedAncestors, nestedLabelOf, nestedFileCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
|
|
11
11
|
import { DEFAULT_ENTRY } from "../files/paths.js";
|
|
12
12
|
import { isPortholeCookie, setsPortholeCookie } from "./proxy.js";
|
|
13
13
|
import { assetCodeRuns, assetCspDirectives, INERT_FILE_CSP, servedDocumentCsp, servedPermissionsPolicy, } from "../compile/policy.js";
|
|
@@ -966,7 +966,10 @@ export function createServer(options) {
|
|
|
966
966
|
// A page that may use its artifact's assets loads them from its own origin (P089); every
|
|
967
967
|
// served page carries its frame's sandbox, a tab of its own included (P099).
|
|
968
968
|
const { config, cspDirectives } = served.compiled;
|
|
969
|
-
const
|
|
969
|
+
const directives = served.assets
|
|
970
|
+
? assetCspDirectives(config, cspDirectives, access.origin)
|
|
971
|
+
: cspDirectives;
|
|
972
|
+
const headers = documentHeaders(nested ? nestedFileCsp("page", directives) : servedDocumentCsp(config, directives), servedPermissionsPolicy(config), ancestors);
|
|
970
973
|
if (cookie !== null) {
|
|
971
974
|
headers.set("set-cookie", cookie);
|
|
972
975
|
}
|
package/dist/shell/frame.d.ts
CHANGED
|
@@ -15,8 +15,11 @@
|
|
|
15
15
|
* shell (activation goes up, never down), so the shell's activation turning on is a press or
|
|
16
16
|
* key of the person's in this page. It is read at every animation frame, on its window's focus
|
|
17
17
|
* and blur, and before each message of the page's is passed on (a call made in a click's handler
|
|
18
|
-
* arrives after the state that says so)
|
|
19
|
-
*
|
|
18
|
+
* arrives after the state that says so), and at once when the host asks (`porthole/shell/look`,
|
|
19
|
+
* P120: the host heard focus move into the frame, and a key the person types into the page
|
|
20
|
+
* before the shell's next frame would turn its activation on as a press does). What it can't
|
|
21
|
+
* see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
|
|
22
|
+
* on;
|
|
20
23
|
* - renews the page's sealed files' address before it ends, and gives the page the new one
|
|
21
24
|
* (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
|
|
22
25
|
* are), so only the shell, on that origin, may renew it (P083);
|
package/dist/shell/frame.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { PAGE_SANDBOX_TOKENS } from "../compile/policy.js";
|
|
2
|
-
import { hostOriginProblem } from "../isolation/served.js";
|
|
2
|
+
import { hostOriginProblem, onNestedLabel } from "../isolation/served.js";
|
|
3
3
|
/**
|
|
4
4
|
* Porthole's shell for a nested page (P111): the whole document at the address the host frames,
|
|
5
5
|
* with no content in it. It frames the page (the same origin's sealed files' address) in a child
|
|
@@ -17,8 +17,11 @@ import { hostOriginProblem } from "../isolation/served.js";
|
|
|
17
17
|
* shell (activation goes up, never down), so the shell's activation turning on is a press or
|
|
18
18
|
* key of the person's in this page. It is read at every animation frame, on its window's focus
|
|
19
19
|
* and blur, and before each message of the page's is passed on (a call made in a click's handler
|
|
20
|
-
* arrives after the state that says so)
|
|
21
|
-
*
|
|
20
|
+
* arrives after the state that says so), and at once when the host asks (`porthole/shell/look`,
|
|
21
|
+
* P120: the host heard focus move into the frame, and a key the person types into the page
|
|
22
|
+
* before the shell's next frame would turn its activation on as a press does). What it can't
|
|
23
|
+
* see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
|
|
24
|
+
* on;
|
|
22
25
|
* - renews the page's sealed files' address before it ends, and gives the page the new one
|
|
23
26
|
* (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
|
|
24
27
|
* are), so only the shell, on that origin, may renew it (P083);
|
|
@@ -31,6 +34,12 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
31
34
|
const plan = __PLAN__;
|
|
32
35
|
const PREFIX = "porthole/shell/";
|
|
33
36
|
const own = location.origin;
|
|
37
|
+
// A nested page's shell runs on a label of its own alone (P114, P121): on any other origin (its
|
|
38
|
+
// scope's, where other displays run content with allow-same-origin) it frames nothing and says
|
|
39
|
+
// nothing.
|
|
40
|
+
if (!/^porthole-[a-z2-7]{24}\./.test(location.hostname + ".")) {
|
|
41
|
+
return;
|
|
42
|
+
}
|
|
34
43
|
let page = null;
|
|
35
44
|
try {
|
|
36
45
|
page = new URL(plan.page);
|
|
@@ -95,21 +104,22 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
95
104
|
let focused = false;
|
|
96
105
|
let lookedAt = performance.now();
|
|
97
106
|
let toldAt = 0;
|
|
98
|
-
const tell = (gap) => {
|
|
107
|
+
const tell = (gap, asked) => {
|
|
99
108
|
toldAt = performance.now();
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
}
|
|
109
|
+
const params = {
|
|
110
|
+
supported: activation !== undefined,
|
|
111
|
+
active,
|
|
112
|
+
ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
|
|
113
|
+
focused,
|
|
114
|
+
gap: Math.max(0, Math.round(gap)),
|
|
115
|
+
};
|
|
116
|
+
// The answer to the host's ask (P120), by its number.
|
|
117
|
+
if (asked !== undefined) {
|
|
118
|
+
params.asked = asked;
|
|
119
|
+
}
|
|
120
|
+
toHost({ jsonrpc: "2.0", method: PREFIX + "state", params });
|
|
111
121
|
};
|
|
112
|
-
const look = () => {
|
|
122
|
+
const look = (asked) => {
|
|
113
123
|
const now = performance.now();
|
|
114
124
|
const gap = now - lookedAt;
|
|
115
125
|
lookedAt = now;
|
|
@@ -127,8 +137,8 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
127
137
|
focused = inside;
|
|
128
138
|
changed = true;
|
|
129
139
|
}
|
|
130
|
-
if (changed) {
|
|
131
|
-
tell(gap);
|
|
140
|
+
if (changed || typeof asked === "number") {
|
|
141
|
+
tell(gap, typeof asked === "number" ? asked : undefined);
|
|
132
142
|
} else if (now - toldAt >= 50) {
|
|
133
143
|
// The heartbeat: the host knows the shell was looking, every 50 ms.
|
|
134
144
|
toldAt = now;
|
|
@@ -166,6 +176,15 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
166
176
|
return;
|
|
167
177
|
}
|
|
168
178
|
if (framed && source === window.parent && plan.origins.indexOf(event.origin) !== -1) {
|
|
179
|
+
const data = event.data;
|
|
180
|
+
// The host's words to the shell are never the page's to hear (P120): its ask to look now.
|
|
181
|
+
if (data !== null && typeof data === "object" && typeof data.method === "string" && data.method.indexOf(PREFIX) === 0) {
|
|
182
|
+
const n = data.params !== null && typeof data.params === "object" ? data.params.n : undefined;
|
|
183
|
+
if (data.method === PREFIX + "look" && typeof n === "number" && n >= 0 && Math.floor(n) === n) {
|
|
184
|
+
look(n);
|
|
185
|
+
}
|
|
186
|
+
return;
|
|
187
|
+
}
|
|
169
188
|
const child = frame.contentWindow;
|
|
170
189
|
if (child !== null) {
|
|
171
190
|
child.postMessage(event.data, "*");
|
|
@@ -222,6 +241,10 @@ export function frameShellScript(options) {
|
|
|
222
241
|
if (!page.pathname.startsWith("/__porthole/f/") || page.hash !== "") {
|
|
223
242
|
throw new TypeError("frameShellScript: page is under /__porthole/f/, with no fragment");
|
|
224
243
|
}
|
|
244
|
+
// The shell runs on a nested page's own label alone (P114), and its page is on its origin.
|
|
245
|
+
if (!onNestedLabel(page.origin)) {
|
|
246
|
+
throw new TypeError("frameShellScript: page is on a nested page's own label (porthole-<24 base32>, nestedLabelOf)");
|
|
247
|
+
}
|
|
225
248
|
return FRAME_SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({
|
|
226
249
|
origins: options.origins,
|
|
227
250
|
page: page.href,
|
package/docs/ADOPTING.md
CHANGED
|
@@ -267,14 +267,20 @@ display.on("annotation", (report) => {
|
|
|
267
267
|
if (report.type === "activated") bubble.openBeside(frame, report.rect, report.id);
|
|
268
268
|
if (report.type === "anchored") bubble.follow(report.results);
|
|
269
269
|
});
|
|
270
|
-
// The
|
|
271
|
-
|
|
270
|
+
// The composer closed, whatever came of it (posted, a draft added, dismissed): take the selection,
|
|
271
|
+
// and its highlight, away. The page sees the clear: never clear only when a draft is added.
|
|
272
|
+
composer.onClose(() => display.annotations.clearSelection());
|
|
272
273
|
```
|
|
273
274
|
|
|
274
|
-
- **Clear the selection
|
|
275
|
-
selection, and the highlight the browser leaves on it (gray while focus
|
|
276
|
-
stay until something clears them; the person's next click in the page
|
|
277
|
-
when your composer is done with it.
|
|
275
|
+
- **Clear the selection when the composer closes, every time** (`annotations.clearSelection()`,
|
|
276
|
+
P115): the page's text selection, and the highlight the browser leaves on it (gray while focus
|
|
277
|
+
is in your composer), stay until something clears them; the person's next click in the page
|
|
278
|
+
would, and this does it when your composer is done with it. The page sees the clear (the
|
|
279
|
+
message, and a `selectionchange` with no press of its own), so it learns when the person was
|
|
280
|
+
done with its words (P121): clear on every close, kept or dismissed, or as the composer opens
|
|
281
|
+
(which tells it nothing `selected` and its blur didn't), or leave it to their next click; never
|
|
282
|
+
only when a draft is added, which tells the page that a draft exists there, and when. Above all
|
|
283
|
+
for a page `mayPassOn` says to keep drafts from (below). No `unselected` follows it (you know), and nothing else
|
|
278
284
|
changes: your marks and drafts, the mode (`start`) and a followed mark stay. With nothing
|
|
279
285
|
selected it does nothing; it is never sent to a frame that runs later (a reload has no selection
|
|
280
286
|
to clear). Like `start` and `show`, only where the config declares `annotate`. The shell is your
|
|
@@ -293,10 +299,12 @@ composer.onDone(() => display.annotations.clearSelection());
|
|
|
293
299
|
annotating={commenting ? { elements: false, text: true } : null}
|
|
294
300
|
annotations={marks} trackedAnnotation={openCard?.markId ?? null}
|
|
295
301
|
onAnnotation={(report) => {
|
|
296
|
-
|
|
302
|
+
// The page moves its mark, and so the card, at will: armed again as it moves (§6, P121).
|
|
303
|
+
if (report.type === "tracked" && card.moveBeside(report.rect) > 4) cardGuard.placed();
|
|
297
304
|
if (report.type === "selected") composer.openBeside(report.rect, report.anchor);
|
|
298
305
|
}} />
|
|
299
|
-
|
|
306
|
+
// cardGuard = guardPresses(card.element) (below); moveBeside answers how far it moved, in px.
|
|
307
|
+
composer.onClose(() => frame.current?.clearSelection()); // every close, kept or dismissed
|
|
300
308
|
```
|
|
301
309
|
|
|
302
310
|
- **Ids say nothing, and a count only where the page may know it**: the content reads every
|
|
@@ -323,7 +331,9 @@ composer.onDone(() => display.annotations.clearSelection());
|
|
|
323
331
|
library CDNs (whose paths only their operators read); show such a page no draft marks.
|
|
324
332
|
- **The content chooses when your view opens and where** (it can post `activated` for a mark you
|
|
325
333
|
show on the person's own press in the content, under their pointer, P105), so a view that a
|
|
326
|
-
report opens or moves
|
|
334
|
+
report opens or moves (a card that follows a `tracked` mark included, each time it moves more
|
|
335
|
+
than a few px: the page moves it at will, up to 60 times a second) takes no press of any kind
|
|
336
|
+
for 500 ms after it appears or moves (no
|
|
327
337
|
`pointerdown`, `pointerup`, `click` or key: menu triggers act on a press, and menu items click
|
|
328
338
|
themselves on a release), ignores a press that began before that, opens beside the frame rather
|
|
329
339
|
than over `rect` where the layout allows, takes no focus, and has nothing one click away that
|
|
@@ -417,7 +427,12 @@ focusField(composer.textarea); // Firefox ignores a plain focus() while a fighti
|
|
|
417
427
|
page's field is taken back. A nested page's shell sees it: a move into the frame is the
|
|
418
428
|
person's if the shell's activation turned on within the last second and you saw no press or key
|
|
419
429
|
of your own since. A second press in the page within 5 s of the last turns nothing on: after the
|
|
420
|
-
person went back to your composer, their next move in is taken back until then, or a Tab.
|
|
430
|
+
person went back to your composer, their next move in is taken back until then, or a Tab. A
|
|
431
|
+
nested page that takes the keyboard back as the guard returns it is fought as any page is, and
|
|
432
|
+
stopped (P120). A move into the page within 250 ms of the person's key on your page is taken
|
|
433
|
+
back on every engine (no hand presses that fast after typing, P122); on full Chromium a key the
|
|
434
|
+
person types into the page just as it takes the keyboard, slower than that, can still pass for a
|
|
435
|
+
press (THREAT_MODEL §7).
|
|
421
436
|
|
|
422
437
|
## 4. Served pages: the host kit
|
|
423
438
|
|
|
@@ -611,7 +626,7 @@ and Porthole's libraries (`egress.libraries`); the config refuses them.
|
|
|
611
626
|
|
|
612
627
|
What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
|
|
613
628
|
own answers the same, with the helpers `/server` exports: `nestedLabelOf`, `nestedShellResponse`,
|
|
614
|
-
`NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
|
|
629
|
+
`nestedFileCsp`, `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
|
|
615
630
|
`https://<nestedLabelOf(label)>.<content domain>`, where `label` is the scope's label (the one its
|
|
616
631
|
other displays are served on); `<token>` is the access in the path (Porthole's sealed session, or a
|
|
617
632
|
signed token of your own: the shell only needs addresses under the prefix). Your frame location
|
|
@@ -620,13 +635,16 @@ for a nested page is on `<origin>`.
|
|
|
620
635
|
**The rule** (P114): `<origin>` answers the four rows below and Porthole's status pages, nothing
|
|
621
636
|
else (no other display, no clean address, no asset, no app), and the scope's label never answers a
|
|
622
637
|
nested page's shell, page or files. That is what keeps the shell's realm (its word to your page,
|
|
623
|
-
the page's sealed address) out of every other display's reach.
|
|
638
|
+
the page's sealed address) out of every other display's reach. Porthole holds the shell to that
|
|
639
|
+
label (P121): `createHost` refuses a nested page located anywhere else (a host error, `locate`, and
|
|
640
|
+
no frame), `nestedShellResponse` throws for another origin, and the shell runs nowhere else. That
|
|
641
|
+
`<origin>` answers nothing but these is yours to hold: Porthole can't see your Worker's routes.
|
|
624
642
|
|
|
625
643
|
| Request | Answer |
|
|
626
644
|
| --- | --- |
|
|
627
645
|
| `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
|
|
628
|
-
| `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy
|
|
629
|
-
| `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin
|
|
646
|
+
| `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy`: `nestedFileCsp("page", fileSetCspDirectives(compiled.cspDirectives, "<origin>/__porthole/f/"))` then `; frame-ancestors ` and `nestedAncestors("<origin>", "<host origins>")`: the page's directives, its files' prefix opened, and `sandbox allow-scripts` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
|
|
647
|
+
| `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin` (`nestedFileCsp(fileTypeOf(path).role, directives)`, then the `frame-ancestors` above): a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
|
|
630
648
|
| `<origin>/__porthole/f/<token>/__porthole/renew` | Only the shell's own fetch (`Sec-Fetch-Site: same-origin`, not a navigation): `{ "base": "<origin>/__porthole/f/<new token>/", "expires": <epoch ms> }`, `no-store`; anything else 403. The shell renews 5 minutes before `expires` and moves the page to the new base. |
|
|
631
649
|
| A token that ended, under the prefix | Porthole's status page (`401`, reason `session`), `frame-ancestors <origin> <host origins>`: it tells the shell, which tells your page (`outcome` blocked). |
|
|
632
650
|
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -214,6 +214,7 @@ Host app Shell (its own origin) Page (opaque child)
|
|
|
214
214
|
│◄── the page's messages ──────│◄── postMessage (by source) ───│
|
|
215
215
|
│── the host's messages ──────►│── postMessage ───────────────►│
|
|
216
216
|
│◄── porthole/shell/state ─────│ its own activation, its focus │
|
|
217
|
+
│── porthole/shell/look ──────►│ look now (as a move is heard) │
|
|
217
218
|
```
|
|
218
219
|
|
|
219
220
|
### URL frame
|
|
@@ -292,7 +293,10 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
|
|
|
292
293
|
transient activation, which only a press or key in the page turns on, and whether
|
|
293
294
|
focus is in it), and the host, which knows the frame is nested from its config
|
|
294
295
|
only, uses it to tell the person's gesture from the page's (the focus guard,
|
|
295
|
-
`comments.open`).
|
|
296
|
+
`comments.open`). The host's own words in that namespace (its ask to look, P120)
|
|
297
|
+
go to the shell alone. A key and a press look the same in that word, so the host
|
|
298
|
+
doesn't ask it while it fights a frame for the keyboard (P120). Everything else
|
|
299
|
+
the page says is still the content's word.
|
|
296
300
|
|
|
297
301
|
5. **Host's decision ↔ content domain.** Authentication and authorization
|
|
298
302
|
*policy* are the host's; carrying the host's decision safely onto the content
|