@botiverse/porthole 0.14.2 → 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 +75 -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/annotate.d.ts +9 -0
- package/dist/shell/annotate.js +73 -8
- 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 +385 -2
- package/docs/DESIGN.md +18 -6
- package/docs/THREAT_MODEL.md +91 -31
- 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/annotate.ts +74 -8
- 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/annotate.d.ts
CHANGED
|
@@ -1,3 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which marker a press on the shell's layer is for (P119), spliced into the runtime: the index of
|
|
3
|
+
* `count` boxes (`boxAt(i)`, the markers' own boxes in the viewport, the last drawn on top), or -1.
|
|
4
|
+
* A point on a marker's own box is that marker's (the topmost, as before). With `touch` (the last
|
|
5
|
+
* pointer a finger or a pen), a marker also takes the points of a 44 by 44 CSS px box centred on
|
|
6
|
+
* its own (its own size where it is larger): where those overlap, the marker whose own box's
|
|
7
|
+
* centre is nearest the point. No built-in is called (content may have patched them).
|
|
8
|
+
*/
|
|
9
|
+
export declare const MARKER_HIT: string;
|
|
1
10
|
/**
|
|
2
11
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
3
12
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
package/dist/shell/annotate.js
CHANGED
|
@@ -1,3 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which marker a press on the shell's layer is for (P119), spliced into the runtime: the index of
|
|
3
|
+
* `count` boxes (`boxAt(i)`, the markers' own boxes in the viewport, the last drawn on top), or -1.
|
|
4
|
+
* A point on a marker's own box is that marker's (the topmost, as before). With `touch` (the last
|
|
5
|
+
* pointer a finger or a pen), a marker also takes the points of a 44 by 44 CSS px box centred on
|
|
6
|
+
* its own (its own size where it is larger): where those overlap, the marker whose own box's
|
|
7
|
+
* centre is nearest the point. No built-in is called (content may have patched them).
|
|
8
|
+
*/
|
|
9
|
+
export const MARKER_HIT = String.raw `(count, boxAt, x, y, touch) => {
|
|
10
|
+
const TARGET = 44;
|
|
11
|
+
let best = -1;
|
|
12
|
+
let nearest = 0;
|
|
13
|
+
for (let i = count - 1; i >= 0; i -= 1) {
|
|
14
|
+
const rect = boxAt(i);
|
|
15
|
+
if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
|
|
16
|
+
return i;
|
|
17
|
+
}
|
|
18
|
+
if (touch) {
|
|
19
|
+
const dx = x - (rect.x + rect.width / 2);
|
|
20
|
+
const dy = y - (rect.y + rect.height / 2);
|
|
21
|
+
const halfWidth = (rect.width > TARGET ? rect.width : TARGET) / 2;
|
|
22
|
+
const halfHeight = (rect.height > TARGET ? rect.height : TARGET) / 2;
|
|
23
|
+
if (dx >= -halfWidth && dx <= halfWidth && dy >= -halfHeight && dy <= halfHeight) {
|
|
24
|
+
const distance = dx * dx + dy * dy;
|
|
25
|
+
if (best === -1 || distance < nearest) {
|
|
26
|
+
best = i;
|
|
27
|
+
nearest = distance;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
return best;
|
|
33
|
+
}`;
|
|
1
34
|
/**
|
|
2
35
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
3
36
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
@@ -376,7 +409,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
376
409
|
// layer inherits from the page could reach it, so each of those is set here). A draft
|
|
377
410
|
// (P107) is a comment not yet posted: its line is dashed (an element's outline too) and its
|
|
378
411
|
// marker hollow, a light bubble with a dashed edge and the glyph's outline, no number.
|
|
379
|
-
|
|
412
|
+
// While the last pointer was a finger or a pen (P119), each marker takes the pointer in a
|
|
413
|
+
// box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
|
|
414
|
+
// box, its border 1 px), so a tap a few px off still lands on the shell's layer.
|
|
415
|
+
const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
|
|
380
416
|
// Inline and important: the content's own style sheets can't hide, shrink or move it by
|
|
381
417
|
// accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
|
|
382
418
|
// content can still cover the layer, or move it with its ancestors, P104).
|
|
@@ -404,6 +440,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
404
440
|
// marker's node across draws, so a press that spans a redraw ends on the node it began on.
|
|
405
441
|
let markers = [];
|
|
406
442
|
const markerNodes = new Map();
|
|
443
|
+
// Whether the last pointer was a finger or a pen (P119): then each marker takes the pointer
|
|
444
|
+
// in a 44 px box around it (the markers' box has the class "touch"). Until a pointer is
|
|
445
|
+
// seen, whether the device has a coarse pointer at all (a phone, a tablet, a laptop with a
|
|
446
|
+
// touch screen): a mouse moves before it presses, and its first move turns it off.
|
|
447
|
+
const coarseQuery = typeof window.matchMedia === "function" ? window.matchMedia("(any-pointer: coarse)") : null;
|
|
448
|
+
let touch = coarseQuery !== null && coarseQuery.matches === true;
|
|
449
|
+
const markerHit = ${MARKER_HIT};
|
|
407
450
|
const MARKER_HEIGHT = 18;
|
|
408
451
|
const SVG = "http://www.w3.org/2000/svg";
|
|
409
452
|
const labelOf = (count) => (count === 0 ? "" : count > 99 ? "99+" : String(count));
|
|
@@ -714,6 +757,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
714
757
|
if (boxes.style.textContent !== STYLE) {
|
|
715
758
|
boxes.style.textContent = STYLE;
|
|
716
759
|
}
|
|
760
|
+
if (boxes.markers.className !== (touch ? "touch" : "")) {
|
|
761
|
+
boxes.markers.className = touch ? "touch" : "";
|
|
762
|
+
}
|
|
717
763
|
return boxes;
|
|
718
764
|
};
|
|
719
765
|
const draw = () => {
|
|
@@ -1118,14 +1164,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1118
1164
|
const rect = callOf(elementRect, element, []);
|
|
1119
1165
|
return { x: callOf(leftOf, rect, []), y: callOf(topOf, rect, []), width: callOf(widthOf, rect, []), height: callOf(heightOf, rect, []) };
|
|
1120
1166
|
};
|
|
1167
|
+
// The marker a press at (x, y) is for: on a marker's own box, that one; after a finger or a
|
|
1168
|
+
// pen, also within the 44 px box around one, the nearest (P119).
|
|
1121
1169
|
const markerAt = (x, y) => {
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
|
|
1125
|
-
return markers[i];
|
|
1126
|
-
}
|
|
1127
|
-
}
|
|
1128
|
-
return null;
|
|
1170
|
+
const at = markerHit(markers.length, (i) => markerBox(markers[i].element), x, y, touch);
|
|
1171
|
+
return at < 0 ? null : markers[at];
|
|
1129
1172
|
};
|
|
1130
1173
|
const isShown = (id) => {
|
|
1131
1174
|
for (let i = 0; i < marks.length; i += 1) {
|
|
@@ -1170,6 +1213,28 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1170
1213
|
const CANCELLED = { mousedown: 1, mouseup: 1, click: 1, dblclick: 1, auxclick: 1, contextmenu: 1 };
|
|
1171
1214
|
// The pointer on a marker (1), or leaving the layer for the content (0).
|
|
1172
1215
|
const HOVERS = { pointerover: 1, pointermove: 1, pointerout: 0, pointerleave: 0 };
|
|
1216
|
+
// Which pointer the person uses (P119), from each real one that goes down or moves, before
|
|
1217
|
+
// the marker's listener (which stops a press on the layer): a finger or a pen gives every
|
|
1218
|
+
// marker its 44 px box, a mouse takes it away. A mouse moves before it presses, so its press
|
|
1219
|
+
// is hit-tested on the markers' own boxes. Read through the platform's getter, kept now; an
|
|
1220
|
+
// event the page makes up (isTrusted is false) changes nothing.
|
|
1221
|
+
const pointerTypeOf = getterOf(typeof PointerEvent === "function" ? PointerEvent.prototype : null, "pointerType");
|
|
1222
|
+
const onPointer = (event) => {
|
|
1223
|
+
if (!event.isTrusted || pointerTypeOf === null) {
|
|
1224
|
+
return;
|
|
1225
|
+
}
|
|
1226
|
+
const kind = callOf(pointerTypeOf, event, []);
|
|
1227
|
+
const next = kind === "touch" || kind === "pen";
|
|
1228
|
+
if (next !== touch) {
|
|
1229
|
+
touch = next;
|
|
1230
|
+
if (boxes !== null) {
|
|
1231
|
+
boxes.markers.className = touch ? "touch" : "";
|
|
1232
|
+
}
|
|
1233
|
+
}
|
|
1234
|
+
};
|
|
1235
|
+
for (const type of ["pointerdown", "pointermove"]) {
|
|
1236
|
+
window.addEventListener(type, onPointer, true);
|
|
1237
|
+
}
|
|
1173
1238
|
for (const type of ["pointerdown", "pointerup", "pointercancel", "mousedown", "mouseup", "click", "dblclick", "auxclick", "contextmenu", "touchstart", "touchend", "touchcancel", "pointerover", "pointerout", "pointerenter", "pointerleave", "pointermove", "mouseover", "mouseout", "mouseenter", "mouseleave", "mousemove"]) {
|
|
1174
1239
|
window.addEventListener(type, onMarker, true);
|
|
1175
1240
|
}
|
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
|
|