@botiverse/porthole 0.12.0 → 0.14.0
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/dist/annotate/types.d.ts +32 -3
- package/dist/annotate/types.js +4 -0
- package/dist/annotate/validate.js +19 -2
- package/dist/bridge/bridge.d.ts +8 -1
- package/dist/bridge/bridge.js +7 -0
- package/dist/bridge/unseen.d.ts +8 -0
- package/dist/bridge/unseen.js +17 -0
- package/dist/check/files.js +14 -10
- package/dist/check/lint.js +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +29 -13
- package/dist/check/scroll.js +74 -18
- package/dist/compile/policy.d.ts +7 -0
- package/dist/compile/policy.js +13 -1
- package/dist/config/capabilities.d.ts +16 -3
- package/dist/config/capabilities.js +1 -0
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/validate.js +19 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +3 -1
- package/dist/guide/limits.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +2 -0
- package/dist/host/create-host.js +100 -3
- package/dist/host/pass-on.d.ts +15 -0
- package/dist/host/pass-on.js +65 -0
- package/dist/host/types.d.ts +37 -0
- package/dist/index.d.ts +5 -1
- package/dist/index.js +5 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/isolation/types.js +8 -0
- package/dist/platform/focus-guard.d.ts +212 -0
- package/dist/platform/focus-guard.js +620 -0
- package/dist/platform/types.d.ts +25 -0
- package/dist/platform/web.js +80 -2
- package/dist/presets/presets.d.ts +2 -0
- package/dist/presets/presets.js +1 -0
- package/dist/react/frame.d.ts +8 -0
- package/dist/react/frame.js +4 -0
- package/dist/runtime/requests.js +34 -12
- package/dist/runtime/types.generated.js +1 -1
- package/dist/server/files.js +19 -3
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +4 -0
- package/dist/server/nested.d.ts +37 -0
- package/dist/server/nested.js +70 -0
- package/dist/server/server.js +57 -7
- package/dist/shell/annotate.d.ts +1 -1
- package/dist/shell/annotate.js +157 -7
- package/dist/shell/frame.d.ts +45 -0
- package/dist/shell/frame.js +250 -0
- package/dist/shell/plan.js +2 -1
- package/dist/shell/runtime.js +49 -14
- package/docs/ADOPTING.md +140 -7
- package/docs/ARCHITECTURE.md +23 -0
- package/docs/DECISIONS.md +564 -5
- package/docs/DESIGN.md +18 -2
- package/docs/THREAT_MODEL.md +192 -30
- package/package.json +1 -1
- package/src/annotate/types.ts +28 -3
- package/src/annotate/validate.ts +23 -2
- package/src/bridge/bridge.ts +17 -1
- package/src/bridge/unseen.ts +24 -0
- package/src/check/files.ts +14 -10
- package/src/check/lint.ts +1 -1
- package/src/check/scroll.ts +106 -38
- package/src/compile/policy.ts +14 -1
- package/src/config/capabilities.ts +16 -3
- package/src/config/schema.ts +11 -0
- package/src/config/validate.ts +23 -0
- package/src/displays/displays.ts +3 -1
- package/src/guide/limits.ts +1 -1
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +105 -4
- package/src/host/pass-on.ts +73 -0
- package/src/host/types.ts +33 -0
- package/src/index.ts +5 -1
- package/src/isolation/types.ts +12 -0
- package/src/platform/focus-guard.ts +815 -0
- package/src/platform/types.ts +24 -0
- package/src/platform/web.ts +96 -2
- package/src/presets/presets.ts +3 -0
- package/src/react/frame.tsx +10 -0
- package/src/runtime/requests.ts +36 -14
- package/src/runtime/types.generated.ts +1 -1
- package/src/server/files.ts +19 -3
- package/src/server/index.ts +10 -0
- package/src/server/nested.ts +86 -0
- package/src/server/server.ts +65 -6
- package/src/shell/annotate.ts +157 -7
- package/src/shell/frame.ts +268 -0
- package/src/shell/plan.ts +2 -1
- package/src/shell/runtime.ts +49 -14
- package/types/runtime/v1/comments.d.ts +8 -4
package/src/check/scroll.ts
CHANGED
|
@@ -12,7 +12,9 @@ import { attributesOf } from "./markup.ts";
|
|
|
12
12
|
* - body with overflow-y hidden or clip, where html's overflow is visible (body's then becomes the
|
|
13
13
|
* viewport's) or body is one screen tall;
|
|
14
14
|
* - the root with overflow-y hidden or clip and one screen tall;
|
|
15
|
-
* - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing)
|
|
15
|
+
* - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing), and
|
|
16
|
+
* body fixed whatever its height, unless it scrolls itself (where html's overflow is visible,
|
|
17
|
+
* body's is the viewport's and body itself doesn't: P110);
|
|
16
18
|
* and nothing in the page's markup below body that scrolls itself: no element there with style=""
|
|
17
19
|
* or a Tailwind utility giving it overflow-y auto or scroll, or matched by a rule the check reads
|
|
18
20
|
* that does (a rule whose selector it can't read, or that matches nothing in the markup, doesn't
|
|
@@ -28,7 +30,8 @@ import { attributesOf } from "./markup.ts";
|
|
|
28
30
|
* and bottom set (`inset: 0`).
|
|
29
31
|
*
|
|
30
32
|
* What it reads: the page's `<style>` elements, the stylesheets it links that the caller finds
|
|
31
|
-
* (a version's own files) and what they `@import`, in document order; style="" on
|
|
33
|
+
* (a version's own files) and what they `@import`, in document order; style="" on body and the
|
|
34
|
+
* root (not html's: the shell drops it, P110); the
|
|
32
35
|
* class rules that match their classes; and, where the page loads Tailwind from its CDN, the few
|
|
33
36
|
* Tailwind utilities that hold a page (h-screen, overflow-hidden, fixed, inset-0…). Specificity,
|
|
34
37
|
* order, !important and cascade layers decide between rules, so a later override is seen.
|
|
@@ -43,7 +46,8 @@ import { attributesOf } from "./markup.ts";
|
|
|
43
46
|
*
|
|
44
47
|
* Bounded: each stylesheet is read once per page, as it streams (nothing parsed is kept past the
|
|
45
48
|
* rule it is in, a rule's selectors one at a time), at most `SHEETS` of them and `READ` bytes in
|
|
46
|
-
* all, its own `<style>` included; past that, the rest isn't read
|
|
49
|
+
* all, its own `<style>` included; past that, the rest isn't read, nor asked for, and a sheet is
|
|
50
|
+
* decoded only once its size is taken (P110). At most `MOST_LAYERS` layers a
|
|
47
51
|
* page, each named in at most `LONGEST_LAYER` characters: a new one past either isn't read. Each
|
|
48
52
|
* element keeps, per property, only each layer's winner so far, and a compound is matched against
|
|
49
53
|
* an element's classes (a set) in bounded work, so time and memory are linear in what it reads. A
|
|
@@ -57,19 +61,25 @@ import { attributesOf } from "./markup.ts";
|
|
|
57
61
|
* selector).
|
|
58
62
|
*/
|
|
59
63
|
|
|
60
|
-
/**
|
|
64
|
+
/**
|
|
65
|
+
* A stylesheet the page links, as the caller finds it from `from` (a path), or null: its path, the
|
|
66
|
+
* fewest characters it may hold (`least`: a string's length; as bytes, a third of them, less a
|
|
67
|
+
* BOM's), and its text (at least its first `SCANNED` characters), decoded only where the rule may
|
|
68
|
+
* read it (P110: one page linking 400 sheets decoded and kept all of them, though the rule reads at
|
|
69
|
+
* most `SHEETS`, `READ` characters in all).
|
|
70
|
+
*/
|
|
61
71
|
export type LinkedSheet = (
|
|
62
72
|
href: string,
|
|
63
73
|
from: string,
|
|
64
|
-
) => { readonly path: string; readonly text: string } | null;
|
|
74
|
+
) => { readonly path: string; readonly least: number; readonly text: () => string } | null;
|
|
65
75
|
|
|
66
76
|
export interface ScrollLock {
|
|
67
77
|
/** What to change, for the agent. */
|
|
68
78
|
readonly message: string;
|
|
69
79
|
/** The file the rule that holds it is in (the page's own `path`, or a stylesheet's). */
|
|
70
80
|
readonly path?: string;
|
|
71
|
-
/** Its line (1-based). */
|
|
72
|
-
readonly line
|
|
81
|
+
/** Its line (1-based); none where the page couldn't be checked (P110). */
|
|
82
|
+
readonly line?: number;
|
|
73
83
|
}
|
|
74
84
|
|
|
75
85
|
/** How much of one stylesheet is read: its first 2 MiB. */
|
|
@@ -575,7 +585,11 @@ function identAt(text: string, at: number): { value: string; end: number } | nul
|
|
|
575
585
|
if (code === "\\") {
|
|
576
586
|
const hex = /^[0-9a-f]{1,6}\s?/iu.exec(text.slice(index + 1, index + 8));
|
|
577
587
|
if (hex !== null) {
|
|
578
|
-
|
|
588
|
+
// CSS Syntax's "consume an escaped code point": 0, a surrogate or past U+10FFFF is U+FFFD
|
|
589
|
+
// (six hex digits reach 0xFFFFFF, which String.fromCodePoint throws on: P110).
|
|
590
|
+
const point = Number.parseInt(hex[0].trim(), 16);
|
|
591
|
+
const valid = point !== 0 && point <= 0x10ffff && (point < 0xd800 || point > 0xdfff);
|
|
592
|
+
value += String.fromCodePoint(valid ? point : 0xfffd);
|
|
579
593
|
index += 1 + hex[0].length;
|
|
580
594
|
} else if (index + 1 < text.length) {
|
|
581
595
|
value += text[index + 1];
|
|
@@ -875,8 +889,8 @@ const tooDeep = (name: string): string | null => {
|
|
|
875
889
|
return null;
|
|
876
890
|
};
|
|
877
891
|
|
|
878
|
-
/** A stylesheet found for the page, once: its path
|
|
879
|
-
type Found =
|
|
892
|
+
/** A stylesheet found for the page, once: its path, its fewest characters, its text when read. */
|
|
893
|
+
type Found = ReturnType<LinkedSheet>;
|
|
880
894
|
|
|
881
895
|
/** The cascade over the chain: each declaration that matches, then the one that wins. */
|
|
882
896
|
class Cascade {
|
|
@@ -979,18 +993,39 @@ class Cascade {
|
|
|
979
993
|
return true;
|
|
980
994
|
}
|
|
981
995
|
|
|
982
|
-
/**
|
|
983
|
-
|
|
996
|
+
/**
|
|
997
|
+
* Whether nothing more may be read for this page: `SHEETS` read, `READ` spent, or the version's
|
|
998
|
+
* budget. Then no sheet is asked for (P110).
|
|
999
|
+
*/
|
|
1000
|
+
full(): boolean {
|
|
1001
|
+
return this.read.size >= SHEETS || this.bytes >= READ || this.budget.spent;
|
|
1002
|
+
}
|
|
1003
|
+
|
|
1004
|
+
/**
|
|
1005
|
+
* A stylesheet's first `SCANNED` characters, if it may still be read for this page (once, within
|
|
1006
|
+
* the budget), else null. The caps count characters, whatever the caller gives: where even its
|
|
1007
|
+
* fewest are past what's left, it is refused before it is decoded (past the version's budget,
|
|
1008
|
+
* spent); else it is decoded, cut, and charged what it holds, or dropped if that doesn't fit.
|
|
1009
|
+
*/
|
|
1010
|
+
take(found: Found): string | null {
|
|
984
1011
|
if (found === null || this.read.has(found.path) || this.read.size >= SHEETS) {
|
|
985
|
-
return
|
|
1012
|
+
return null;
|
|
986
1013
|
}
|
|
987
|
-
const
|
|
988
|
-
if (this.bytes +
|
|
989
|
-
return
|
|
1014
|
+
const least = Math.min(found.least, SCANNED);
|
|
1015
|
+
if (this.bytes + least > READ) {
|
|
1016
|
+
return null;
|
|
1017
|
+
}
|
|
1018
|
+
if (this.budget.spent || least > this.budget.bytes) {
|
|
1019
|
+
this.budget.spent = true;
|
|
1020
|
+
return null;
|
|
1021
|
+
}
|
|
1022
|
+
const text = found.text().slice(0, SCANNED);
|
|
1023
|
+
if (this.bytes + text.length > READ || !this.spend(text.length)) {
|
|
1024
|
+
return null;
|
|
990
1025
|
}
|
|
991
1026
|
this.read.add(found.path);
|
|
992
|
-
this.bytes +=
|
|
993
|
-
return
|
|
1027
|
+
this.bytes += text.length;
|
|
1028
|
+
return text;
|
|
994
1029
|
}
|
|
995
1030
|
|
|
996
1031
|
/**
|
|
@@ -1146,12 +1181,19 @@ class Cascade {
|
|
|
1146
1181
|
take(to);
|
|
1147
1182
|
}
|
|
1148
1183
|
|
|
1149
|
-
/**
|
|
1150
|
-
|
|
1151
|
-
|
|
1184
|
+
/**
|
|
1185
|
+
* A stylesheet the page links or a sheet imports (`href`, from `from`), if it may still be read:
|
|
1186
|
+
* asked for only while the page may read more, decoded only once taken.
|
|
1187
|
+
*/
|
|
1188
|
+
file(href: string, from: string, layer: string | null) {
|
|
1189
|
+
if (this.full()) {
|
|
1190
|
+
return;
|
|
1191
|
+
}
|
|
1192
|
+
const found = this.find(href, from);
|
|
1193
|
+
const text = this.take(found);
|
|
1194
|
+
if (found === null || text === null) {
|
|
1152
1195
|
return;
|
|
1153
1196
|
}
|
|
1154
|
-
const text = found.text.slice(0, SCANNED);
|
|
1155
1197
|
this.sheet(withoutComments(text), 0, text.length, {
|
|
1156
1198
|
source: { path: found.path, text },
|
|
1157
1199
|
base: 0,
|
|
@@ -1311,7 +1353,7 @@ class Cascade {
|
|
|
1311
1353
|
return;
|
|
1312
1354
|
}
|
|
1313
1355
|
}
|
|
1314
|
-
this.file(
|
|
1356
|
+
this.file(href, context.from, layer);
|
|
1315
1357
|
}
|
|
1316
1358
|
}
|
|
1317
1359
|
|
|
@@ -1362,20 +1404,33 @@ interface Hold {
|
|
|
1362
1404
|
readonly at: Value;
|
|
1363
1405
|
}
|
|
1364
1406
|
|
|
1407
|
+
interface ScrollOptions {
|
|
1408
|
+
readonly noun: string;
|
|
1409
|
+
readonly path?: string;
|
|
1410
|
+
readonly sheet?: LinkedSheet;
|
|
1411
|
+
/** The version's, shared by its pages (`scrollBudget()`); else this page's own. */
|
|
1412
|
+
readonly budget?: ScrollBudget;
|
|
1413
|
+
}
|
|
1414
|
+
|
|
1365
1415
|
/**
|
|
1366
1416
|
* Whether `page`'s own styles hold it to one screen, and what to tell the agent; null where they
|
|
1367
1417
|
* don't (or where it can't tell). `sheet` finds what the page links (a version's own files).
|
|
1418
|
+
* Advisory, so it fails soft (P110): a throw in it is this page not checked, said as such (no
|
|
1419
|
+
* line), never a failed lint (a CSS escape past U+10FFFF threw out of `admitContent` and
|
|
1420
|
+
* `admitFiles` in 0.11).
|
|
1368
1421
|
*/
|
|
1369
|
-
export function scrollLock(
|
|
1370
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
}
|
|
1378
|
-
|
|
1422
|
+
export function scrollLock(page: string, options: ScrollOptions): ScrollLock | null {
|
|
1423
|
+
try {
|
|
1424
|
+
return readScrollLock(page, options);
|
|
1425
|
+
} catch {
|
|
1426
|
+
return {
|
|
1427
|
+
message: `The ${options.noun} wasn't checked for scroll lock: its styles couldn't be read. If it holds html, body or its root to one screen (overflow: hidden with height: 100% or 100vh, or position: fixed), let it scroll as a document.`,
|
|
1428
|
+
...(options.path === undefined ? {} : { path: options.path }),
|
|
1429
|
+
};
|
|
1430
|
+
}
|
|
1431
|
+
}
|
|
1432
|
+
|
|
1433
|
+
function readScrollLock(page: string, options: ScrollOptions): ScrollLock | null {
|
|
1379
1434
|
const shared = options.budget ?? { bytes: Infinity, steps: Infinity, spent: false };
|
|
1380
1435
|
if (shared.spent) {
|
|
1381
1436
|
return null;
|
|
@@ -1400,7 +1455,9 @@ export function scrollLock(
|
|
|
1400
1455
|
};
|
|
1401
1456
|
};
|
|
1402
1457
|
const chain: Node[] = [
|
|
1403
|
-
|
|
1458
|
+
// Not html's style="": the shell imports a page's html attributes but that one
|
|
1459
|
+
// (`renderDocument`), so it never applies in Porthole's frame (P110).
|
|
1460
|
+
{ ...nodeOf(scanned.html, "html", "html", false), style: null },
|
|
1404
1461
|
nodeOf(scanned.body, "body", "body", false),
|
|
1405
1462
|
];
|
|
1406
1463
|
const rootTag =
|
|
@@ -1461,7 +1518,7 @@ export function scrollLock(
|
|
|
1461
1518
|
) {
|
|
1462
1519
|
continue;
|
|
1463
1520
|
}
|
|
1464
|
-
cascade.file(
|
|
1521
|
+
cascade.file(href, from, null);
|
|
1465
1522
|
}
|
|
1466
1523
|
for (const node of chain) {
|
|
1467
1524
|
if (node.style !== null) {
|
|
@@ -1604,7 +1661,10 @@ export function scrollLock(
|
|
|
1604
1661
|
}
|
|
1605
1662
|
const height = tall("height");
|
|
1606
1663
|
const maxHeight = tall("max-height");
|
|
1607
|
-
|
|
1664
|
+
// A fixed body holds the page whatever its height (P110): a fixed box adds nothing to what the
|
|
1665
|
+
// frame scrolls, so `body { position: fixed; top: 0 }`, the scroll-lock libraries' way, does.
|
|
1666
|
+
const fixedBody = index === 1 && position?.value === "fixed";
|
|
1667
|
+
if (positioned && position !== undefined && (spanned || height || maxHeight || fixedBody)) {
|
|
1608
1668
|
shown.unshift(position);
|
|
1609
1669
|
}
|
|
1610
1670
|
states.push({ screen: height || maxHeight || spanned, shown, position: position?.value ?? "" });
|
|
@@ -1628,11 +1688,16 @@ export function scrollLock(
|
|
|
1628
1688
|
return found !== undefined && !CONTENT_HEIGHT.test(found) && !PARENT.test(found);
|
|
1629
1689
|
});
|
|
1630
1690
|
};
|
|
1691
|
+
// An element's own overflow-y: body's is the viewport's where html's overflow is visible, and
|
|
1692
|
+
// body's own is then visible (P110: `body { position: fixed; inset: 0; overflow: auto }` doesn't
|
|
1693
|
+
// scroll itself, the viewport takes its auto).
|
|
1694
|
+
const ownOverflowY = (index: number, node: Node): string =>
|
|
1695
|
+
index === 1 && htmlVisible ? "visible" : overflowY(node);
|
|
1631
1696
|
const scrollBox = (index: number): boolean => {
|
|
1632
1697
|
const node = chain[index];
|
|
1633
1698
|
return (
|
|
1634
1699
|
node !== undefined &&
|
|
1635
|
-
SCROLLS.has(
|
|
1700
|
+
SCROLLS.has(ownOverflowY(index, node)) &&
|
|
1636
1701
|
((states[index]?.screen ?? false) || unread(index))
|
|
1637
1702
|
);
|
|
1638
1703
|
};
|
|
@@ -1649,7 +1714,10 @@ export function scrollLock(
|
|
|
1649
1714
|
const overflow = value(node, "overflow-y");
|
|
1650
1715
|
const clipped =
|
|
1651
1716
|
clips && (index === 0 ? true : index === 1 ? state.screen || htmlVisible : state.screen);
|
|
1652
|
-
const fixed =
|
|
1717
|
+
const fixed =
|
|
1718
|
+
state.position === "fixed" &&
|
|
1719
|
+
(state.screen || index === 1) &&
|
|
1720
|
+
!SCROLLS.has(ownOverflowY(index, node));
|
|
1653
1721
|
if (!clipped && !fixed) {
|
|
1654
1722
|
continue;
|
|
1655
1723
|
}
|
package/src/compile/policy.ts
CHANGED
|
@@ -217,6 +217,8 @@ export function sandboxTokens(config: PortholeConfig): string[] {
|
|
|
217
217
|
case "opaque":
|
|
218
218
|
return ["allow-scripts"];
|
|
219
219
|
case "domain":
|
|
220
|
+
// Nested (P111), this frame holds Porthole's shell, on the content origin, and the page is
|
|
221
|
+
// the shell's child (`PAGE_SANDBOX_TOKENS`).
|
|
220
222
|
return ["allow-scripts", "allow-same-origin"];
|
|
221
223
|
case "external":
|
|
222
224
|
// The host may add a documented few (popups, modals, downloads), never top navigation.
|
|
@@ -235,9 +237,20 @@ export function sandboxTokens(config: PortholeConfig): string[] {
|
|
|
235
237
|
* own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
|
|
236
238
|
*/
|
|
237
239
|
export function servedSandboxDirective(config: PortholeConfig): CspDirective | null {
|
|
238
|
-
|
|
240
|
+
if (config.isolation !== "domain") {
|
|
241
|
+
return null;
|
|
242
|
+
}
|
|
243
|
+
return ["sandbox", ...(config.nested === true ? PAGE_SANDBOX_TOKENS : sandboxTokens(config))];
|
|
239
244
|
}
|
|
240
245
|
|
|
246
|
+
/**
|
|
247
|
+
* A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
|
|
248
|
+
* header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
|
|
249
|
+
* only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
|
|
250
|
+
* so the shell's realm (a test holds every sandbox Porthole writes to this).
|
|
251
|
+
*/
|
|
252
|
+
export const PAGE_SANDBOX_TOKENS: readonly string[] = ["allow-scripts"];
|
|
253
|
+
|
|
241
254
|
/** A served page's CSP header: the page's directives, then its sandbox (P099). */
|
|
242
255
|
export function servedDocumentCsp(
|
|
243
256
|
config: PortholeConfig,
|
|
@@ -45,9 +45,14 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
|
45
45
|
/**
|
|
46
46
|
* What must hold before a call reaches the host's handler. A capability's gates all apply.
|
|
47
47
|
*
|
|
48
|
-
* - `user-activation`: the call follows a real user gesture
|
|
49
|
-
*
|
|
50
|
-
*
|
|
48
|
+
* - `user-activation`: the call follows a real user gesture. The shell refuses a call without one
|
|
49
|
+
* in its frame, but that check is the page's own (a page posts the call itself and skips it).
|
|
50
|
+
* The host checks its own page's transient activation, which a gesture in a child frame
|
|
51
|
+
* propagates to, and which lasts 5 s after any gesture anywhere on the host's page: a click on
|
|
52
|
+
* the host's own UI, or the person typing in its own composer, counts. So it stops calls made on
|
|
53
|
+
* load, or on a timer while nobody does anything; it is not proof that the gesture was in this
|
|
54
|
+
* frame, nor of intent. Where a capability needs that (`comments`, P109: its draft goes into
|
|
55
|
+
* the person's composer), the host also asks that its page's focus be in the calling frame.
|
|
51
56
|
* - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
|
|
52
57
|
* goes only if they accept. No `confirm` function means the call is refused (fail closed).
|
|
53
58
|
* - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
|
|
@@ -82,6 +87,13 @@ export interface CapabilitySpec {
|
|
|
82
87
|
* Absent for what the shell does by itself (sizes, errors, annotations).
|
|
83
88
|
*/
|
|
84
89
|
readonly request?: { readonly method: string; readonly sdk?: string };
|
|
90
|
+
/**
|
|
91
|
+
* Its `user-activation` gate also needs the person in the calling frame (P109): the host page's
|
|
92
|
+
* focus in that frame, which a press on it or a Tab into it gives and the focus guard keeps from
|
|
93
|
+
* a frame's own `focus()`. Activation alone lasts 5 s after any gesture on the host's page,
|
|
94
|
+
* typing in its own composer included.
|
|
95
|
+
*/
|
|
96
|
+
readonly inFrame?: true;
|
|
85
97
|
}
|
|
86
98
|
|
|
87
99
|
const rate = (perMinute: number): Gate => ({ rateLimit: { perMinute } });
|
|
@@ -170,6 +182,7 @@ export const CAPABILITIES = {
|
|
|
170
182
|
defaultGates: ["user-activation", rate(30)],
|
|
171
183
|
served: "handler",
|
|
172
184
|
request: { method: "porthole/call" },
|
|
185
|
+
inFrame: true,
|
|
173
186
|
},
|
|
174
187
|
/** This artifact's current version, and a new version of it, base-checked (P088). */
|
|
175
188
|
artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
|
package/src/config/schema.ts
CHANGED
|
@@ -258,6 +258,17 @@ export interface PortholeConfig {
|
|
|
258
258
|
* `db`). Absent: 0.6's frames, globals and manual, exactly.
|
|
259
259
|
*/
|
|
260
260
|
readonly runtime?: RuntimeVersion;
|
|
261
|
+
/**
|
|
262
|
+
* Domain isolation, artifact pages (P111): the address the host frames serves Porthole's shell
|
|
263
|
+
* alone, a document of Porthole's own with no content in it, and the page runs in a child frame
|
|
264
|
+
* of the shell's, sandboxed without `allow-same-origin` (an opaque origin), served from the same
|
|
265
|
+
* origin at its files' sealed address. The shell is then a realm the page can't reach, above the
|
|
266
|
+
* page's frame: it relays the page's messages, and tells the host when its own transient
|
|
267
|
+
* activation turns on (a press in the page activates its ancestors only), which is how the host
|
|
268
|
+
* knows the person, not the page, moved the keyboard into the frame or opened a comment. The
|
|
269
|
+
* page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
|
|
270
|
+
*/
|
|
271
|
+
readonly nested?: true;
|
|
261
272
|
}
|
|
262
273
|
|
|
263
274
|
export interface StorageConfig {
|
package/src/config/validate.ts
CHANGED
|
@@ -324,6 +324,7 @@ export function validateConfig(
|
|
|
324
324
|
"storage",
|
|
325
325
|
"errors",
|
|
326
326
|
"runtime",
|
|
327
|
+
"nested",
|
|
327
328
|
],
|
|
328
329
|
"config",
|
|
329
330
|
);
|
|
@@ -687,6 +688,28 @@ export function validateConfig(
|
|
|
687
688
|
}
|
|
688
689
|
}
|
|
689
690
|
|
|
691
|
+
if (config.nested !== undefined) {
|
|
692
|
+
if (config.nested !== true) {
|
|
693
|
+
fail("config.nested", "must be true, or left out");
|
|
694
|
+
}
|
|
695
|
+
if (config.isolation !== "domain" || config.mode !== "artifact") {
|
|
696
|
+
fail("config.nested", "nests artifact pages served on their own origin (domain isolation)");
|
|
697
|
+
}
|
|
698
|
+
// The page's origin is opaque (P111): nothing of the content origin's own is its.
|
|
699
|
+
if (config.storage !== undefined) {
|
|
700
|
+
fail("config.nested", "a nested page keeps no storage: drop config.storage");
|
|
701
|
+
}
|
|
702
|
+
if (capabilities.assets !== undefined) {
|
|
703
|
+
fail(
|
|
704
|
+
"config.nested",
|
|
705
|
+
"a nested page can't load its asset library (/_blob/) yet: drop assets",
|
|
706
|
+
);
|
|
707
|
+
}
|
|
708
|
+
if (isObject(config.egress) && config.egress.libraries === true) {
|
|
709
|
+
fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
|
|
710
|
+
}
|
|
711
|
+
}
|
|
712
|
+
|
|
690
713
|
if (config.errors !== undefined) {
|
|
691
714
|
if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
|
|
692
715
|
fail("config.errors", 'must be "agent", "host" or "none"');
|
package/src/displays/displays.ts
CHANGED
|
@@ -93,9 +93,11 @@ export function defineDisplays<N extends string>(
|
|
|
93
93
|
return presets.url({ ...kind.options, contentOrigins: [source] });
|
|
94
94
|
}
|
|
95
95
|
const options = kind.options ?? {};
|
|
96
|
+
// Nesting (P111) is a served page's: an opaque frame has nothing to nest.
|
|
97
|
+
const { nested: _nested, ...opaque } = options;
|
|
96
98
|
return presets[kind.preset](
|
|
97
99
|
source === null
|
|
98
|
-
?
|
|
100
|
+
? opaque
|
|
99
101
|
: { ...options, ...kind.served, isolation: "domain", contentOrigins: [source] },
|
|
100
102
|
);
|
|
101
103
|
};
|
package/src/guide/limits.ts
CHANGED
|
@@ -196,7 +196,7 @@ export function manualLimits(config: PortholeConfig, network: string): ManualLim
|
|
|
196
196
|
);
|
|
197
197
|
add(
|
|
198
198
|
"storage",
|
|
199
|
-
config.isolation === "opaque"
|
|
199
|
+
config.isolation === "opaque" || config.nested === true
|
|
200
200
|
? `State isn't saved: localStorage works but lasts only while the ${it} is on screen, and a reload or another device starts fresh. Keep what matters in the ${it}'s code.`
|
|
201
201
|
: config.storage?.scope !== undefined
|
|
202
202
|
? `localStorage is kept for ${config.storage.scope}, in this browser; another browser or device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`
|
package/src/guide/runtime.ts
CHANGED
|
@@ -61,7 +61,7 @@ const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, stri
|
|
|
61
61
|
const WHAT: Readonly<Partial<Record<CapabilityName, (config: PortholeConfig) => string>>> = {
|
|
62
62
|
user: () => "who is viewing: { id, name, level }, as the app says",
|
|
63
63
|
comments: () =>
|
|
64
|
-
"opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width, bidi or tag characters; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. True if it opened. Write-only: a page never reads comments, and never posts one",
|
|
64
|
+
"opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. Call it from a click in the page. True if it opened. Write-only: a page never reads comments, and never posts one",
|
|
65
65
|
copyText: () =>
|
|
66
66
|
`copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied; nothing else in the page can write the clipboard. True if copied`,
|
|
67
67
|
openLink: () =>
|