@botiverse/porthole 0.15.2 → 0.15.3
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 +31 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/isolation/served.d.ts +5 -0
- package/dist/isolation/served.js +10 -3
- package/dist/isolation/types.d.ts +6 -0
- package/dist/isolation/types.js +6 -0
- package/dist/platform/focus-guard.d.ts +36 -0
- package/dist/platform/focus-guard.js +82 -8
- package/dist/platform/web.js +10 -2
- package/dist/server/nested.js +2 -1
- package/dist/server/pages.d.ts +9 -2
- package/dist/server/pages.js +28 -8
- package/dist/shell/frame.d.ts +1 -1
- package/dist/shell/frame.js +72 -3
- package/dist/shell/plan.d.ts +5 -0
- package/dist/shell/plan.js +2 -0
- package/dist/shell/runtime.js +259 -0
- package/docs/ADOPTING.md +5 -2
- package/docs/DECISIONS.md +183 -1
- package/docs/DESIGN.md +15 -1
- package/docs/THREAT_MODEL.md +31 -6
- package/package.json +1 -1
- package/src/isolation/served.ts +12 -3
- package/src/isolation/types.ts +7 -0
- package/src/platform/focus-guard.ts +126 -11
- package/src/platform/web.ts +15 -2
- package/src/server/nested.ts +2 -1
- package/src/server/pages.ts +38 -12
- package/src/shell/frame.ts +76 -3
- package/src/shell/plan.ts +7 -0
- package/src/shell/runtime.ts +259 -0
package/dist/shell/runtime.js
CHANGED
|
@@ -926,9 +926,14 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
926
926
|
const noRewrite = function () {
|
|
927
927
|
throw new Error("document.open and document.write aren't available here: build the page with DOM methods");
|
|
928
928
|
};
|
|
929
|
+
const unfixedBeforeRewrite = unfixed.length;
|
|
929
930
|
for (const name of ["open", "write", "writeln"]) {
|
|
930
931
|
lock(Document.prototype, name, noRewrite);
|
|
931
932
|
}
|
|
933
|
+
// Whether all three are fixed in place. The press port rests on it (P148): document.open() takes
|
|
934
|
+
// every listener off the window, the runtime's among them, and a document opened and closed
|
|
935
|
+
// again loads again, so content that could call it would hear a port before the runtime did.
|
|
936
|
+
const rewriteFixed = unfixed.length === unfixedBeforeRewrite;
|
|
932
937
|
|
|
933
938
|
// Some engines act on a hint the moment its element is connected or changed (WebKit opens a
|
|
934
939
|
// preconnect then, outside the CSP), before the observer's microtask. So every way to connect a
|
|
@@ -1392,6 +1397,254 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1392
1397
|
]);
|
|
1393
1398
|
}
|
|
1394
1399
|
|
|
1400
|
+
// A nested page's real presses, told to its shell (P148). The shell sees a press in the page only
|
|
1401
|
+
// as its own activation turning on, and a press within 5 s of the last gesture turns nothing on
|
|
1402
|
+
// (P111): to the host that reads as a button that does nothing. So the runtime, which runs before
|
|
1403
|
+
// any content and hears the browser's own events first, tells the shell each one, over a
|
|
1404
|
+
// MessagePort the shell sends at each load of the page's frame. What keeps that the runtime's
|
|
1405
|
+
// word and never the content's:
|
|
1406
|
+
// - the port: taken here, by the first listener there is (on window, capturing), from the first
|
|
1407
|
+
// message that is the browser's own (isTrusted), from the parent read now, that names the
|
|
1408
|
+
// method and carries exactly one port. The event goes no further. Every other event of that
|
|
1409
|
+
// name is stopped too, so content never hears one, and one that fails a check doesn't use up
|
|
1410
|
+
// the one port. The port is in this closure alone: no content holds it or can post on it. No
|
|
1411
|
+
// second port is taken: the shell's next one (it sends one at every load of the frame, and
|
|
1412
|
+
// WebKit fires a load for a navigation within the document) is answered on the first, that
|
|
1413
|
+
// this document is still here;
|
|
1414
|
+
// - the press: only the browser's own events (isTrusted), read through the platform's getters
|
|
1415
|
+
// kept now. A mouse on its way down; a finger or a pen on its way up (one that scrolls ends in
|
|
1416
|
+
// pointercancel: HTML's own rule for what activates); Enter or Space, not held down, on a
|
|
1417
|
+
// native control that isn't editable (a link takes Enter alone), by its tag and type, never
|
|
1418
|
+
// its role, which is the content's word; a click on such a control (an assistive technology's
|
|
1419
|
+
// activation is a click alone), but not the click a form gives its submit button when Enter is
|
|
1420
|
+
// pressed in another of its fields, which is typing, nor any click while a key is down;
|
|
1421
|
+
// - what is told: nothing but that there was one. No place, no target, no time.
|
|
1422
|
+
// After a press is told, what the page's calls say to its host (send, below) waits for the
|
|
1423
|
+
// shell's word that it has the press (it tells the host before it answers), so a call made in
|
|
1424
|
+
// the press's own handler never arrives ahead of it; a shell that doesn't answer in 250 ms
|
|
1425
|
+
// holds nothing back.
|
|
1426
|
+
// None of it is installed unless all of it can be (a built-in missing, or document.open, write
|
|
1427
|
+
// or writeln not fixed in place above): the page then tells no press, and the host has the
|
|
1428
|
+
// shell's activation alone, as before.
|
|
1429
|
+
let pressHeld = null;
|
|
1430
|
+
const pressParent = window.parent;
|
|
1431
|
+
if (plan.press === true && !hostless && pressParent !== window && rewriteFixed) {
|
|
1432
|
+
const messageProto = typeof MessageEvent === "function" ? MessageEvent.prototype : null;
|
|
1433
|
+
const messageSourceOf = getterOf(messageProto, "source");
|
|
1434
|
+
const messageDataOf = getterOf(messageProto, "data");
|
|
1435
|
+
const messagePortsOf = getterOf(messageProto, "ports");
|
|
1436
|
+
const stopNow = Event.prototype.stopImmediatePropagation;
|
|
1437
|
+
const portProto = typeof MessagePort === "function" ? MessagePort.prototype : null;
|
|
1438
|
+
const portPost = portProto === null ? null : portProto.postMessage;
|
|
1439
|
+
const portStart = portProto === null ? null : portProto.start;
|
|
1440
|
+
const eventTargetOf = getterOf(Event.prototype, "target");
|
|
1441
|
+
const pointerTypeOf = getterOf(typeof PointerEvent === "function" ? PointerEvent.prototype : null, "pointerType");
|
|
1442
|
+
const keyProto = typeof KeyboardEvent === "function" ? KeyboardEvent.prototype : null;
|
|
1443
|
+
const keyOf = getterOf(keyProto, "key");
|
|
1444
|
+
const repeatOf = getterOf(keyProto, "repeat");
|
|
1445
|
+
const editableOf = getterOf(HTMLElement.prototype, "isContentEditable");
|
|
1446
|
+
const designModeOf = getterOf(Document.prototype, "designMode");
|
|
1447
|
+
const activeOf = getterOf(Document.prototype, "activeElement");
|
|
1448
|
+
const controlTypeOf = getterOf(HTMLInputElement.prototype, "type");
|
|
1449
|
+
// Each control's form through its own getter: a field tied to a form by its form attribute is
|
|
1450
|
+
// not inside that form's element.
|
|
1451
|
+
const formGetters = bare(null);
|
|
1452
|
+
formGetters.button = getterOf(HTMLButtonElement.prototype, "form");
|
|
1453
|
+
formGetters.input = getterOf(HTMLInputElement.prototype, "form");
|
|
1454
|
+
formGetters.select = getterOf(HTMLSelectElement.prototype, "form");
|
|
1455
|
+
formGetters.textarea = getterOf(HTMLTextAreaElement.prototype, "form");
|
|
1456
|
+
const pressLater = setTimeout;
|
|
1457
|
+
const pressNoLater = clearTimeout;
|
|
1458
|
+
const pressListen = EventTarget.prototype.addEventListener;
|
|
1459
|
+
const all =
|
|
1460
|
+
messageSourceOf !== null && messageDataOf !== null && messagePortsOf !== null &&
|
|
1461
|
+
typeof stopNow === "function" && typeof portPost === "function" && typeof portStart === "function" &&
|
|
1462
|
+
eventTargetOf !== null && pointerTypeOf !== null && keyOf !== null && repeatOf !== null &&
|
|
1463
|
+
editableOf !== null && designModeOf !== null && activeOf !== null && controlTypeOf !== null &&
|
|
1464
|
+
formGetters.button !== null && formGetters.input !== null && formGetters.select !== null && formGetters.textarea !== null &&
|
|
1465
|
+
localNameOf !== null && namespaceOf !== null && nodeTypeOf !== null;
|
|
1466
|
+
if (all) {
|
|
1467
|
+
let port = null;
|
|
1468
|
+
// How many presses the shell hasn't answered yet, and the timer that stops waiting for it.
|
|
1469
|
+
let unanswered = 0;
|
|
1470
|
+
let giveUp = 0;
|
|
1471
|
+
const release = () => {
|
|
1472
|
+
unanswered = 0;
|
|
1473
|
+
callOf(pressNoLater, window, [giveUp]);
|
|
1474
|
+
const held = pressHeld;
|
|
1475
|
+
pressHeld = null;
|
|
1476
|
+
if (held !== null) {
|
|
1477
|
+
for (let i = 0; i < held.length; i += 1) {
|
|
1478
|
+
post(held[i]);
|
|
1479
|
+
}
|
|
1480
|
+
}
|
|
1481
|
+
};
|
|
1482
|
+
const tellPress = () => {
|
|
1483
|
+
if (port === null) {
|
|
1484
|
+
return;
|
|
1485
|
+
}
|
|
1486
|
+
try {
|
|
1487
|
+
callOf(portPost, port, [0]);
|
|
1488
|
+
} catch (_) {
|
|
1489
|
+
return;
|
|
1490
|
+
}
|
|
1491
|
+
unanswered += 1;
|
|
1492
|
+
if (pressHeld === null) {
|
|
1493
|
+
pressHeld = [];
|
|
1494
|
+
}
|
|
1495
|
+
callOf(pressNoLater, window, [giveUp]);
|
|
1496
|
+
giveUp = callOf(pressLater, window, [release, 250]);
|
|
1497
|
+
};
|
|
1498
|
+
callOf(pressListen, window, [
|
|
1499
|
+
"message",
|
|
1500
|
+
(event) => {
|
|
1501
|
+
let named = false;
|
|
1502
|
+
try {
|
|
1503
|
+
const data = callOf(messageDataOf, event, []);
|
|
1504
|
+
named = data !== null && typeof data === "object" && data.method === "porthole/shell/press-port";
|
|
1505
|
+
} catch (_) {}
|
|
1506
|
+
if (!named) {
|
|
1507
|
+
return;
|
|
1508
|
+
}
|
|
1509
|
+
callOf(stopNow, event, []);
|
|
1510
|
+
if (event.isTrusted !== true) {
|
|
1511
|
+
return;
|
|
1512
|
+
}
|
|
1513
|
+
try {
|
|
1514
|
+
const ports = callOf(messagePortsOf, event, []);
|
|
1515
|
+
if (callOf(messageSourceOf, event, []) !== pressParent || ports === null || ports.length !== 1) {
|
|
1516
|
+
return;
|
|
1517
|
+
}
|
|
1518
|
+
// Only the first is ever taken. A later one is the shell's for a load that left this
|
|
1519
|
+
// document where it was (WebKit's, for a navigation within it, P142): told, on the
|
|
1520
|
+
// port held, that this document is still here, so the shell goes on hearing that one.
|
|
1521
|
+
if (port !== null) {
|
|
1522
|
+
callOf(portPost, port, [1]);
|
|
1523
|
+
return;
|
|
1524
|
+
}
|
|
1525
|
+
const taken = ports[0];
|
|
1526
|
+
// The shell's answer to a press: it has it, and has told the host.
|
|
1527
|
+
callOf(pressListen, taken, [
|
|
1528
|
+
"message",
|
|
1529
|
+
() => {
|
|
1530
|
+
unanswered -= 1;
|
|
1531
|
+
if (unanswered <= 0) {
|
|
1532
|
+
release();
|
|
1533
|
+
}
|
|
1534
|
+
},
|
|
1535
|
+
]);
|
|
1536
|
+
callOf(portStart, taken, []);
|
|
1537
|
+
port = taken;
|
|
1538
|
+
} catch (_) {}
|
|
1539
|
+
},
|
|
1540
|
+
true,
|
|
1541
|
+
]);
|
|
1542
|
+
// A native control a key or a click presses: "both" (Enter and Space), "enter" (a link), or
|
|
1543
|
+
// "" for anything else, an editable one included. By the kept getters: the tag and the type,
|
|
1544
|
+
// never an attribute the content writes to say what it is.
|
|
1545
|
+
const controlOf = (node) => {
|
|
1546
|
+
if (typeOf(node) !== 1 || callOf(namespaceOf, node, []) !== XHTML) {
|
|
1547
|
+
return "";
|
|
1548
|
+
}
|
|
1549
|
+
const name = callOf(localNameOf, node, []);
|
|
1550
|
+
let kind = "";
|
|
1551
|
+
if (name === "button" || name === "summary") {
|
|
1552
|
+
kind = "both";
|
|
1553
|
+
} else if (name === "input") {
|
|
1554
|
+
const type = callOf(controlTypeOf, node, []);
|
|
1555
|
+
kind = type === "button" || type === "submit" || type === "reset" ? "both" : "";
|
|
1556
|
+
} else if (name === "a") {
|
|
1557
|
+
kind = callOf(hasAttributeIn, node, ["href"]) === true ? "enter" : "";
|
|
1558
|
+
}
|
|
1559
|
+
return kind !== "" && callOf(editableOf, node, []) !== true ? kind : "";
|
|
1560
|
+
};
|
|
1561
|
+
const formOf = (node) => {
|
|
1562
|
+
if (typeOf(node) !== 1 || callOf(namespaceOf, node, []) !== XHTML) {
|
|
1563
|
+
return null;
|
|
1564
|
+
}
|
|
1565
|
+
const getter = formGetters[callOf(localNameOf, node, [])];
|
|
1566
|
+
return typeof getter === "function" ? callOf(getter, node, []) : null;
|
|
1567
|
+
};
|
|
1568
|
+
// The browser's own event: nothing a page dispatches is a press.
|
|
1569
|
+
const real = (event) => event.isTrusted === true;
|
|
1570
|
+
// Whether a key is down: from the browser's own keydown to its keyup, or the next press of
|
|
1571
|
+
// a pointer. No click in that time is a press. The key's own press was judged as it went
|
|
1572
|
+
// down, where it went down: content that moves the focus to its button inside the keydown
|
|
1573
|
+
// of an Enter typed in a text field gets that button a click of the browser's own, and a
|
|
1574
|
+
// held key's repeats give a button one each. An assistive technology's click comes with no
|
|
1575
|
+
// key down.
|
|
1576
|
+
let keyDown = false;
|
|
1577
|
+
const pointed = (down) => (event) => {
|
|
1578
|
+
if (!real(event)) {
|
|
1579
|
+
return;
|
|
1580
|
+
}
|
|
1581
|
+
keyDown = false;
|
|
1582
|
+
try {
|
|
1583
|
+
if ((callOf(pointerTypeOf, event, []) === "mouse") === down) {
|
|
1584
|
+
tellPress();
|
|
1585
|
+
}
|
|
1586
|
+
} catch (_) {}
|
|
1587
|
+
};
|
|
1588
|
+
callOf(pressListen, window, ["pointerdown", pointed(true), true]);
|
|
1589
|
+
callOf(pressListen, window, ["pointerup", pointed(false), true]);
|
|
1590
|
+
callOf(pressListen, window, [
|
|
1591
|
+
"keyup",
|
|
1592
|
+
(event) => {
|
|
1593
|
+
if (real(event)) {
|
|
1594
|
+
keyDown = false;
|
|
1595
|
+
}
|
|
1596
|
+
},
|
|
1597
|
+
true,
|
|
1598
|
+
]);
|
|
1599
|
+
callOf(pressListen, window, [
|
|
1600
|
+
"keydown",
|
|
1601
|
+
(event) => {
|
|
1602
|
+
if (!real(event)) {
|
|
1603
|
+
return;
|
|
1604
|
+
}
|
|
1605
|
+
keyDown = true;
|
|
1606
|
+
try {
|
|
1607
|
+
// A key held down goes on being the key it was when it went down, wherever the focus
|
|
1608
|
+
// has moved since: its repeats are no press.
|
|
1609
|
+
const key = callOf(keyOf, event, []);
|
|
1610
|
+
if ((key !== "Enter" && key !== " ") || callOf(repeatOf, event, []) === true || callOf(designModeOf, document, []) === "on") {
|
|
1611
|
+
return;
|
|
1612
|
+
}
|
|
1613
|
+
const kind = controlOf(callOf(eventTargetOf, event, []));
|
|
1614
|
+
if (kind === "both" || (kind === "enter" && key === "Enter")) {
|
|
1615
|
+
tellPress();
|
|
1616
|
+
}
|
|
1617
|
+
} catch (_) {}
|
|
1618
|
+
},
|
|
1619
|
+
true,
|
|
1620
|
+
]);
|
|
1621
|
+
callOf(pressListen, window, [
|
|
1622
|
+
"click",
|
|
1623
|
+
(event) => {
|
|
1624
|
+
if (!real(event)) {
|
|
1625
|
+
return;
|
|
1626
|
+
}
|
|
1627
|
+
try {
|
|
1628
|
+
const target = callOf(eventTargetOf, event, []);
|
|
1629
|
+
if (keyDown || controlOf(target) === "") {
|
|
1630
|
+
return;
|
|
1631
|
+
}
|
|
1632
|
+
// A form's own click on its submit button, for Enter in another of its fields.
|
|
1633
|
+
const active = callOf(activeOf, document, []);
|
|
1634
|
+
if (active !== null && active !== target) {
|
|
1635
|
+
const form = formOf(target);
|
|
1636
|
+
if (form !== null && form === formOf(active)) {
|
|
1637
|
+
return;
|
|
1638
|
+
}
|
|
1639
|
+
}
|
|
1640
|
+
tellPress();
|
|
1641
|
+
} catch (_) {}
|
|
1642
|
+
},
|
|
1643
|
+
true,
|
|
1644
|
+
]);
|
|
1645
|
+
}
|
|
1646
|
+
}
|
|
1647
|
+
|
|
1395
1648
|
// The clipboard is the host's to write (P051): content can neither write nor read it. A copy
|
|
1396
1649
|
// the person makes (their keys, their menu) copies their selection as the browser makes it: no
|
|
1397
1650
|
// copy or cut listener of the content's runs, so none can swap what goes on the clipboard.
|
|
@@ -1610,8 +1863,14 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1610
1863
|
window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
|
|
1611
1864
|
}
|
|
1612
1865
|
};
|
|
1866
|
+
// After a press was told to the shell (P148), what the shell's protocol says next (a call, an
|
|
1867
|
+
// answer) waits for the shell to have the press: posted by the release above, through post.
|
|
1613
1868
|
const send = (message) => {
|
|
1614
1869
|
if (plan.protocol === "shell") {
|
|
1870
|
+
if (pressHeld !== null) {
|
|
1871
|
+
pressHeld[pressHeld.length] = message;
|
|
1872
|
+
return;
|
|
1873
|
+
}
|
|
1615
1874
|
post(message);
|
|
1616
1875
|
}
|
|
1617
1876
|
};
|
package/docs/ADOPTING.md
CHANGED
|
@@ -683,8 +683,11 @@ focusField(composer.textarea); // Firefox ignores a plain focus() while a fighti
|
|
|
683
683
|
frame there is out of process: your page sees no press in it, so a person's click into the
|
|
684
684
|
page's field is taken back. A nested page's shell sees it: a move into the frame is the
|
|
685
685
|
person's if the shell's activation turned on within the last second and you saw no press or key
|
|
686
|
-
of your own since. A second press in the page within 5 s of the last turns nothing on
|
|
687
|
-
|
|
686
|
+
of your own since. A second press in the page within 5 s of the last turns nothing on; from
|
|
687
|
+
0.15.3 the page's runtime tells its shell each real press (P148), so the person's next press in
|
|
688
|
+
the page counts as the first did, after they went back to your composer too. Nothing for you to
|
|
689
|
+
do but run 0.15.3 on both sides (your page, and whatever serves the content origins): an older
|
|
690
|
+
side ignores what the newer says, and the 5 s stay until both are new. A
|
|
688
691
|
nested page that takes the keyboard back as the guard returns it is fought as any page is, and
|
|
689
692
|
stopped (P120). A move into the page within 250 ms of the person's key on your page is taken
|
|
690
693
|
back on every engine (no hand presses that fast after typing, P122); on full Chromium a key the
|
package/docs/DECISIONS.md
CHANGED
|
@@ -5845,7 +5845,7 @@ that throws gives the "wasn't checked" warning; `admitFiles` with `\ffffff` in a
|
|
|
5845
5845
|
**Revisit when** a page's own document is ever shown outside the shell (then quirks mode is real),
|
|
5846
5846
|
or an engine starts counting fixed boxes in what the viewport scrolls.
|
|
5847
5847
|
|
|
5848
|
-
## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` · Accepted
|
|
5848
|
+
## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` · Accepted; amended by P148
|
|
5849
5849
|
|
|
5850
5850
|
**Context.** P109's focus guard and `comments.open`'s gate ask whether the person, not the page,
|
|
5851
5851
|
moved the keyboard into a frame or clicked in it. In full Chromium a cross-site frame is out of
|
|
@@ -9158,6 +9158,20 @@ each fail exactly their probe on all three. The old spec with its document in tw
|
|
|
9158
9158
|
route (then it needs its own entry, never `access`), or a browser stops exposing
|
|
9159
9159
|
`ancestorOrigins` to a framed page.
|
|
9160
9160
|
|
|
9161
|
+
**Amended in 0.15.3, after the audit of 0.15.1 (N1): the helpers that take host origins check
|
|
9162
|
+
them.** Decision 4 says every helper that takes host origins or `framedBy` throws on a bad one.
|
|
9163
|
+
For `framedBy` that held (`ancestorsOf`). For host origins it held in `createServer`, the host kit
|
|
9164
|
+
and `frameShellScript`, and not in four helpers a content Worker of a host's own calls itself:
|
|
9165
|
+
`statusPage`, `doorResponse`, `doorStatusResponse` and `nestedShellCsp` took `hostOrigins` as they
|
|
9166
|
+
came, so `https://app.example:0` passed and `"https://a; script-src *"` went into the
|
|
9167
|
+
`Content-Security-Policy` header as written. What they are given is the host's own configuration,
|
|
9168
|
+
not content's, so nothing reached them that a host didn't write; the claim was wrong, and a header
|
|
9169
|
+
built from an unchecked string is not something to leave. Each now runs `hostOriginProblem` over
|
|
9170
|
+
every origin and throws a `TypeError` naming itself (`doorResponse: hostOrigins: …`), with
|
|
9171
|
+
`frameAncestors` given or not; an embed's status pages name no host and check none. And the
|
|
9172
|
+
exported `isHostOrigin` now says no to what `hostOriginProblem` refuses (`:0`, a port past 65535 or
|
|
9173
|
+
with a leading zero, a host the URL parser rewrites): it tested the shape alone. `test/origins.test.ts`.
|
|
9174
|
+
|
|
9161
9175
|
## P146 · 2026-11-10 · CI's full set runs before a release, not on every push · Accepted
|
|
9162
9176
|
|
|
9163
9177
|
Amends P096 (its decision 4: what a push runs; its decision 6: the shards run by hand) and P097
|
|
@@ -9342,3 +9356,171 @@ P132's reports (through the root's box; here through `scrollTop`, the number the
|
|
|
9342
9356
|
would then be no better than the event, and no worse); a host needs marks in the page's own
|
|
9343
9357
|
scrollers to ride too (a timeline per scroller, named from the mark's nearest one); or decision 6's
|
|
9344
9358
|
case is reported.
|
|
9359
|
+
|
|
9360
|
+
## P148 · 2026-11-11 · A nested page's real presses, told to its shell over a port no content holds · Accepted
|
|
9361
|
+
|
|
9362
|
+
Amends P111 (its "Rejected", and item 4 of its "Threat it re-opens"). From Raft (xxchan,
|
|
9363
|
+
2026-11-11): a page's own button that calls `comments.open`; the host answers with a dialog; the
|
|
9364
|
+
person cancels it and presses the button again, and nothing happens ("This needs a click"), nor at
|
|
9365
|
+
the next press; some seconds later it works. Raft's pages are served, not nested: in full Chromium
|
|
9366
|
+
the host's page sees no press in their frame, and a press there counts only once the host's page
|
|
9367
|
+
has had no gesture of its own for 5 s (P109). ADOPTING's answer is to nest such pages (P111). But a
|
|
9368
|
+
nested page had the same dead button, for the 5 s after any gesture (below), so nesting was no
|
|
9369
|
+
answer to this report until that was closed. This decision closes it; it changes nothing for a
|
|
9370
|
+
page that isn't nested. Designed on one page first, attacked by Ferryman before any code (his
|
|
9371
|
+
findings are items 2, 4 and 5 below), accepted by the CTO with the bounds of item 1.
|
|
9372
|
+
|
|
9373
|
+
**Context.** P111 takes "the person is in this frame" from the shell's own transient activation
|
|
9374
|
+
turning on: within the last second, with no trusted press or key on the host's page since. An
|
|
9375
|
+
activation stays on for about 5 s, so a press in the page within 5 s of the last gesture turns
|
|
9376
|
+
nothing on, and a press in the page within 5 s of a press on the host's page can't be told from
|
|
9377
|
+
the page borrowing the host's. P111 accepted that. In use it is a button that does nothing:
|
|
9378
|
+
`leak/served/nested-press.spec.ts`'s first case, run against 0.15.2, has a press one second after
|
|
9379
|
+
a press on the host's page refused on full Chromium and on Firefox (the headless shell and WebKit
|
|
9380
|
+
show the host's page the press on the frame itself, and pass).
|
|
9381
|
+
|
|
9382
|
+
P111 rejected "the page's runtime reporting its own gestures (the page's word, in the page's
|
|
9383
|
+
realm)": the runtime and the content share a document, and whatever the runtime posts to the
|
|
9384
|
+
shell, the content can post from the same window. That holds for a message to a window. It doesn't
|
|
9385
|
+
for a `MessagePort` only the runtime holds, carrying an event only the browser makes.
|
|
9386
|
+
|
|
9387
|
+
**Decision.**
|
|
9388
|
+
1. **A port per load, from the shell.** At each `load` of its page's frame the shell makes a
|
|
9389
|
+
`MessageChannel`, keeps one end and posts the other to the page (`porthole/shell/press-port`,
|
|
9390
|
+
in the shell's own namespace, which it passes neither way). It hears only the port of the
|
|
9391
|
+
frame's last load, and forgets what it heard of a press before that load.
|
|
9392
|
+
2. **The runtime takes it before any content runs, and no content ever holds it.** The first
|
|
9393
|
+
listener there is (on `window`, capturing) takes the port from the first message that is the
|
|
9394
|
+
browser's own (`isTrusted`), from the parent read at the runtime's start, naming the method,
|
|
9395
|
+
with exactly one port, and stops the event there. Every other event of that name is stopped
|
|
9396
|
+
too. One that fails a check doesn't use up the one port (a page that dispatches a
|
|
9397
|
+
`MessageEvent` of its own before the shell's arrives would otherwise have the real port dropped:
|
|
9398
|
+
no press forged, but the feature silently off). The port lives in the runtime's closure.
|
|
9399
|
+
Two walls this rests on, both already there, now named as its preconditions:
|
|
9400
|
+
`document.open()` takes every listener off a window, the runtime's among them, and a document
|
|
9401
|
+
opened and closed again fires the frame's `load` again (measured on Chromium 153 and Firefox
|
|
9402
|
+
155, and WebKit here): the runtime's lock on `Document.prototype.open`, `write` and `writeln`
|
|
9403
|
+
(there for declarative shadow DOM) is what keeps a page from hearing the port in the runtime's
|
|
9404
|
+
place; and a nested page is `sandbox="allow-scripts"`, so every frame of its own is another
|
|
9405
|
+
opaque origin, with no unlocked `open` to borrow. If the lock on any of the three couldn't be
|
|
9406
|
+
fixed in place, or any built-in this uses is missing, or the plan names no host, **none of it is
|
|
9407
|
+
installed**: no port is taken and no press is told, and the host has the shell's activation
|
|
9408
|
+
alone, as before.
|
|
9409
|
+
3. **What is told is that there was a press, and nothing else**: no place, no target, no time. The
|
|
9410
|
+
shell notes when it heard it, on its own clock, and tells the host in its state (`pressed`: how
|
|
9411
|
+
long ago; `presses`: how many it has heard, so the host knows a new one).
|
|
9412
|
+
4. **What a press is** (every one the browser's own event, read through getters kept before
|
|
9413
|
+
content ran):
|
|
9414
|
+
- a mouse going down (`pointerdown`, `pointerType` `mouse`);
|
|
9415
|
+
- a finger or a pen coming up (`pointerup`, any other `pointerType`). A finger that scrolls goes
|
|
9416
|
+
down too and ends in `pointercancel`: counted as it lands, scrolling the page would open the
|
|
9417
|
+
gate for a second. This is HTML's own list of what activates;
|
|
9418
|
+
- Enter or Space going down, not a repeat of a held key, on a native control that isn't
|
|
9419
|
+
editable: `button`, `summary`, `input` of type button, submit or reset; Enter alone on
|
|
9420
|
+
`a[href]`. By tag and type, never `role`, which is the content's word: `role="button"` on a
|
|
9421
|
+
text field (or on a custom element around one) would make every space typed there a press,
|
|
9422
|
+
and P120's "typing is no press" would be the content's to decide. A custom element is never
|
|
9423
|
+
one, so the focus inside its shadow tree, open or closed, tells nothing;
|
|
9424
|
+
- a click on such a control (an assistive technology activates a button with a click alone),
|
|
9425
|
+
but none while a key is down (from the browser's own `keydown` to its `keyup`, or the next
|
|
9426
|
+
press of a pointer): the key's own press was judged as it went down, where it went down.
|
|
9427
|
+
Without that, content that moves the focus to its button inside the `keydown` of an Enter
|
|
9428
|
+
typed in a text field gets the button a click of the browser's own, the focus on it
|
|
9429
|
+
(Ferryman, on the code: measured on Chromium 153 and Firefox 155, and WebKit here); and a
|
|
9430
|
+
held key's repeats give a button a click each. Behind it, not the click a form gives its
|
|
9431
|
+
submit button for Enter in another of its controls (the two forms read through each
|
|
9432
|
+
control's own `form`: a field tied by its `form` attribute is not inside the form's
|
|
9433
|
+
element).
|
|
9434
|
+
5. **The host judges a press told exactly as an activation that turned on.** For a second
|
|
9435
|
+
(`SHELL_GESTURE_MS`), a move of focus into the frame, or a `comments.open`, is the person's,
|
|
9436
|
+
**with no trusted press or key on the host's page since** (the design page had this signal
|
|
9437
|
+
need no quiet host; it keeps one, which costs the case this is for nothing: the dialog's
|
|
9438
|
+
Cancel is before the press). And, as for an activation: not a press told in a fight over a
|
|
9439
|
+
text field (P120), not one within 250 ms of the person's key on the host's page (P122), not
|
|
9440
|
+
one told within a second of their typing with the pointer elsewhere, where the host's page
|
|
9441
|
+
sees the pointer (P120), and not one told in or just after a stall of the shell (below). A
|
|
9442
|
+
press told while the focus is already in the frame makes the frame the person's from there on,
|
|
9443
|
+
as a move they made into it does.
|
|
9444
|
+
6. **A stalled shell.** The shell notes a press when it hears it. Where the page shares the
|
|
9445
|
+
shell's thread, a page that holds it from its own click handler makes that as late as it
|
|
9446
|
+
likes, past the person going back to the host's page (P111, after its review). An activation
|
|
9447
|
+
seen after a stall is uncertain because the look that sees it turn on is the first look after
|
|
9448
|
+
the stall, and says its gap. A press is another message: when the page lets go, the shell's own
|
|
9449
|
+
timer may run first and say the stall, and the press follow a moment later with no gap of its
|
|
9450
|
+
own (seen on the first cut of this decision: `leak/served/nested-stall.spec.ts` failed on
|
|
9451
|
+
Chromium with frames in process). So the host notes when the shell was last seen to have
|
|
9452
|
+
stalled (a report or a heartbeat after more than `SHELL_STALL_MS` of silence, or a report that
|
|
9453
|
+
says such a gap), and a press told within `SHELL_AFTER_STALL_MS` (500 ms) of that is no one's.
|
|
9454
|
+
7. **What the page says next follows the press.** A call made in the press's own handler (a tap's
|
|
9455
|
+
click, a key's click) leaves the page a moment after the press does, on another channel, and
|
|
9456
|
+
could arrive first. After it tells a press, the runtime holds what it posts to its host until
|
|
9457
|
+
the shell answers on the port, which the shell does only after it has told the host; 250 ms
|
|
9458
|
+
without an answer and it holds nothing back. Content that posts past the runtime orders its
|
|
9459
|
+
own messages, at its own cost.
|
|
9460
|
+
8. **A load that isn't a new document.** WebKit fires the frame's `load` for a navigation within
|
|
9461
|
+
the document (P142). The shell then sends a second port to a runtime that takes only one, and
|
|
9462
|
+
would hear the first no more. That runtime answers the second port on the first (`1`: this
|
|
9463
|
+
document is still here), which only it can, and the shell goes back to the first and shuts the
|
|
9464
|
+
new one. A new document's runtime never has the port before.
|
|
9465
|
+
9. **Nested pages only** (`plan.press`, from `nested: true`). A served, opaque or proxied page's
|
|
9466
|
+
runtime carries the code and installs none of it; their plans are as before.
|
|
9467
|
+
|
|
9468
|
+
**Why the rejected alternative holds now.** What P111 feared was the content speaking as the
|
|
9469
|
+
runtime. It can't post on a port it never holds (2), and can't make the runtime post for an event
|
|
9470
|
+
it made up (4: `isTrusted` is an own, unforgeable property of each event; nothing else it could
|
|
9471
|
+
shape decides, since the tag, type, key, repeat, pointer type, target and form are read through
|
|
9472
|
+
getters taken before it ran). The runtime's word here stands where its other walls do (the
|
|
9473
|
+
navigation guard, P129, P130): its code runs first and calls only what it kept.
|
|
9474
|
+
|
|
9475
|
+
**What it does not say.** Which element was pressed, or that the press was meant for the call
|
|
9476
|
+
that follows. That is the activation rule's own limit. Content can put the focus on its own
|
|
9477
|
+
button and wait for the person's Enter meant for something else: with the shell's activation off
|
|
9478
|
+
that already passed for a gesture (P111, P120's residual); now it does within 5 s of the last
|
|
9479
|
+
gesture too, under the same rules of item 5.
|
|
9480
|
+
|
|
9481
|
+
**Threat.** One message more from the shell to the page (a port, nothing in it), two content-free
|
|
9482
|
+
values on that port, and two numbers more in the shell's state. No secret is in any of them. The
|
|
9483
|
+
gate P111 keeps shut for 5 s after any gesture now opens for a second after a real press in the
|
|
9484
|
+
page: the case P111's "Threat it re-opens" (4) accepted as a loss is the one given back. A page
|
|
9485
|
+
that could take the port could tell presses that never were, and with the person active on the
|
|
9486
|
+
host's page within 5 s open a comment composer or keep the keyboard: items 2 and 4 are what
|
|
9487
|
+
stands in the way, each with a control that takes it out.
|
|
9488
|
+
|
|
9489
|
+
**Residual.** A key on a control that isn't native (a `div` with `role="button"`, a custom
|
|
9490
|
+
element) tells nothing: the 5 s of P111 stay for it. So they do on an engine where the runtime
|
|
9491
|
+
can't install all of this (one without `PointerEvent`, say): nothing is told there. A press within 500 ms
|
|
9492
|
+
of a stall of the shell is dropped, a slow page's own included. The shell's stamp is when it
|
|
9493
|
+
heard the press, a message's time after it was made: a press on the host's page within that time
|
|
9494
|
+
of a press in the page reads as before it.
|
|
9495
|
+
|
|
9496
|
+
**Tested.** `test/nested.test.ts` (the shell's script in a stub page): one port per load; a press
|
|
9497
|
+
is told to the host before it is answered; anything else on the port is none; a new load's port
|
|
9498
|
+
replaces the last and forgets its press; "still here" restores the port before; the plan asks
|
|
9499
|
+
only a nested page; `shellPress`, `shellSaw` and `personMoved` on a press told.
|
|
9500
|
+
`leak/served/nested-press.spec.ts`, real input only, on full Chromium, the headless shell, WebKit
|
|
9501
|
+
and Firefox: a second and a third press after presses on the host's page open `comments` (refused
|
|
9502
|
+
before this decision on full Chromium and Firefox); Enter on the page's button, its call made in the key's
|
|
9503
|
+
own click, is allowed (not Firefox, where a page's own `focus()` puts no key on its button); a
|
|
9504
|
+
page's `focus()` 700 ms after a second press, the person back in the host's composer, is taken
|
|
9505
|
+
back; every event a page can dispatch tells nothing; typing in a text field, one with
|
|
9506
|
+
`role="button"`, one in a custom element with that role, and an editable button tells nothing; a
|
|
9507
|
+
held key is one press; Enter typed in a field tells none though the page moves the focus to its
|
|
9508
|
+
button as the key goes down, and none though a form clicks its button for it; a
|
|
9509
|
+
finger that scrolls tells none and a tap one (Chromium, the only engine a test can drag a finger
|
|
9510
|
+
on); content's first listener hears no port; a port message content sends itself first is not
|
|
9511
|
+
taken and takes no place (Firefox makes no such event); a page can't open its document again,
|
|
9512
|
+
at a later moment or as soon as it runs; a press after a link within the document is heard; the
|
|
9513
|
+
host's rule on a press told after a stall.
|
|
9514
|
+
Negative controls, each failing its probe on every engine it names: `press-untrusted`,
|
|
9515
|
+
`press-role`, `press-editable`, `press-repeat`, `press-key-click`, `press-submit` (behind
|
|
9516
|
+
`press-key-click`: it fails its probe with both out), `press-touch-down` (Chromium),
|
|
9517
|
+
`press-port-heard`, `press-port-forged` (Chromium, WebKit), `press-open-lock`,
|
|
9518
|
+
`press-still-here` (WebKit), `press-host-input`, and `shell-stall` (now this rule's too). No
|
|
9519
|
+
control for item 7 (an order between two channels: with the hold out it is lost only sometimes),
|
|
9520
|
+
nor for "only the last load's port" (nothing of a document outlives it to speak on the port it
|
|
9521
|
+
held: a second wall behind item 2, held by the unit test).
|
|
9522
|
+
|
|
9523
|
+
**Revisit when** an engine shows the host's page a press in an out-of-process frame (P111's own
|
|
9524
|
+
condition: this and the activation rule could then both go); a host reports the residual for
|
|
9525
|
+
controls that aren't native (then a rule for `role` that typing can't satisfy); or the 500 ms
|
|
9526
|
+
after a stall drops presses people notice.
|
package/docs/DESIGN.md
CHANGED
|
@@ -1009,6 +1009,7 @@ for that to lapse and click with raw input.
|
|
|
1009
1009
|
| The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
|
|
1010
1010
|
| The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
|
|
1011
1011
|
| A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows), asking the shell to look as it hears the move; where the host's page sees the pointer over its frames, not with the pointer elsewhere within a second of typing; in a fight over a text field, a frame that takes focus again is judged without the shell and taken back at once, counted (P120); no press within 250 ms of the person's key on the host's page (P122) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three); `pointer-rule` (P120's pointer rule out) → "an activation that came as the person typed…" (all three); `key-press` (P122's 250 ms out) → "an activation that turned on within 250 ms of the person's key…" (all three); `nested-fight` (a frame that takes focus back in a fight let be) → "a page that holds the keyboard from its load…" (Firefox); `leak/served/nested-keyboard.spec.ts` (a page that takes the keyboard as the person types: a race, no control's probe) |
|
|
1012
|
+
| A nested page's real presses, told to its shell (P148) | the shell sends its page a `MessagePort` at each load and hears only the last load's; the page's runtime takes it before content runs (the first listener, capturing; the browser's own message, from the parent read at start, exactly one port; the event stopped) and tells on it only the browser's own events: a mouse down, a finger or pen up, Enter or Space not held on a native control that isn't editable (by tag and type, never `role`), a click on one, but none while a key is down nor a form's own for Enter in a field; installed only under a nested page's plan and only if `document.open`, `write` and `writeln` are fixed shut; the host takes a press told as an activation that turned on (a second, no press or key on its page since, P120's and P122's rules, not within 500 ms of a stall of the shell) | `test/nested.test.ts` "the page's real presses, told to the shell over a port"; `leak/served/nested-press.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `press-untrusted`, `press-role`, `press-editable`, `press-repeat`, `press-key-click`, `press-submit` (with `press-key-click`), `press-touch-down` (Chromium), `press-port-heard`, `press-port-forged` (Chromium, WebKit), `press-open-lock`, `press-still-here` (WebKit), `press-host-input`, `shell-stall` |
|
|
1012
1013
|
| A nested page's shell passes the focus on at the host's word (P136) | `display.focus()` sends `porthole/shell/focus`, only a move that landed; the shell acts only while the focus is on its own document, blurring its frame first, and a page's message in its namespace never reaches that code | `test/nested.test.ts` "the host's word that it moved the focus into a nested page's frame"; `leak/served/nested.spec.ts`: "a page that had the focus gets it back by the host's own move…", "a page that never had the focus…", "a second host's move into a page it just handed the focus to…", "the host's move into a page that holds the focus…", "the host's move from its own text field…", "the host's move takes no keyboard…", "the host's move from inside a key's own handler…" (`test.fail` on Firefox) | `shell-focus-held` |
|
|
1013
1014
|
| A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket; outside `/server` too (P121), `createHost` refuses a nested page located on any other label, the shell runs on no other origin, and `nestedShellResponse` and `frameShellScript` refuse one; `nestedFileCsp` is the page's and its files' CSP for `/server` and a Worker of a host's own | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"; `test/nested.test.ts` "… (P121)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell; `[nested-label]`: a nested page located on its scope's label is refused, no frame made) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label,nested-host-label,nested-shell-origin` (the shell on the scope's label, the host's and the shell's checks out) → `[nested-siblings]`, `[nested-label]` (all three); `nested-host-label` (the host's check out) → `[nested-label]` (all three) |
|
|
1014
1015
|
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
@@ -1637,7 +1638,20 @@ control the tables above name to the registry):
|
|
|
1637
1638
|
| `nested-shell-origin` | `served/nested-siblings.spec.ts` | nothing | — | the host's mount refuses a shell located on any other label first, and /server serves none there (`shell-label,nested-host-label,nested-shell-origin`) |
|
|
1638
1639
|
| `file-sandbox` | `served/nested.spec.ts` | `a page's SVG or XML file opened on a tab of its own is an opaque origin, and its script touches nothing of the shell's (P111, after its review)` | — | — |
|
|
1639
1640
|
| `nested-fight` | `served/nested.spec.ts` | nothing | Firefox: `a page that holds the keyboard from its load and takes it back on its own blur gets none of what the person types in the host's composer, and is stopped (P120)` | no probe can see it on Chromium and WebKit: a page can't take focus back from its own blur there, so no fight has a frame take focus again (measured) |
|
|
1640
|
-
| `shell-stall` | `served/nested.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)` | — | — |
|
|
1641
|
+
| `shell-stall` | `served/nested.spec.ts`, `served/nested-press.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)`, `a press a shell tells after a stall is no one's (P148)` | — | — |
|
|
1642
|
+
| `press-untrusted` | `served/nested-press.spec.ts` | `a press the page makes up is none: a dispatched pointer, key or click tells the shell nothing (P148)` | — | — |
|
|
1643
|
+
| `press-role` | `served/nested-press.spec.ts` | `typing is no press, whatever the content calls the field: a role of button, a custom element's, an editable button (P148)` | — | — |
|
|
1644
|
+
| `press-editable` | `served/nested-press.spec.ts` | `typing is no press, whatever the content calls the field: a role of button, a custom element's, an editable button (P148)` | — | — |
|
|
1645
|
+
| `press-repeat` | `served/nested-press.spec.ts` | `a key held down is one press, however long it repeats (P148)` | — | — |
|
|
1646
|
+
| `press-key-click` | `served/nested-press.spec.ts` | `Enter typed in a text field is no press, though the page moves the focus to its button as the key goes down (P148)`, `a key held down is one press, however long it repeats (P148)` | — | — |
|
|
1647
|
+
| `press-submit` | `served/nested-press.spec.ts` | nothing | — | a key is down while a form clicks its submit button for an Enter, and no click is a press then: that rule refuses the click first (`press-key-click,press-submit`) |
|
|
1648
|
+
| `press-key-click,press-submit` | `served/nested-press.spec.ts` | `Enter typed in a text field is no press, though the page moves the focus to its button as the key goes down (P148)`, `a key held down is one press, however long it repeats (P148)`, `Enter in a form's text field is no press, though the form clicks its submit button (P148)` | — | — |
|
|
1649
|
+
| `press-touch-down` | `served/nested-press.spec.ts` | nothing | Chromium: `a finger that scrolls the page is no press; a tap is (P148)` | no probe can drive a finger's drag on WebKit and Firefox: a test has a tap there and no touch scroll |
|
|
1650
|
+
| `press-port-heard` | `served/nested-press.spec.ts` | `the shell's port is the runtime's alone: content's first listener hears no message that carries one (P148)` | — | — |
|
|
1651
|
+
| `press-port-forged` | `served/nested-press.spec.ts` | nothing | Chromium, WebKit: `a port message content sends itself first is not taken, and takes no place: the person's press still reaches the shell (P148)` | no probe can make the event on Firefox: its MessageEvent constructor takes no window of another origin as a source (measured), and the runtime takes a port from its parent's alone |
|
|
1652
|
+
| `press-open-lock` | `served/nested-press.spec.ts` | `a page can't open its document again to hear the port the shell sends at the next load (P148)`, `nor as soon as it runs, to hear the first port in the runtime's place (P148)` | — | — |
|
|
1653
|
+
| `press-still-here` | `served/nested-press.spec.ts` | nothing | WebKit: `a press after a link within the document is heard: the load WebKit fires for it leaves the first port the one (P148)` | no probe can see it on Chromium and Firefox: they fire no load for a navigation within the document (measured), so the shell sends no second port |
|
|
1654
|
+
| `press-host-input` | `served/nested-press.spec.ts` | `a page's focus() just after a second press in it, the person gone back to the host's composer, is taken back (P148)` | — | — |
|
|
1641
1655
|
| `shell-host-input` | `served/nested.spec.ts` | `a page's focus() just after the person pressed it and went back to the host's composer is taken back` | — | — |
|
|
1642
1656
|
| `key-press` | `served/nested-key.spec.ts` | `an activation that turned on within 250 ms of the person's key on the host's page is no gesture, where the pointer is never seen too (P122)` | — | — |
|
|
1643
1657
|
| `pointer-rule` | `served/nested.spec.ts` | `an activation that came as the person typed, the pointer elsewhere, is no gesture a second on either (P120, after its review)` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.15.
|
|
8
|
+
**Status.** This describes Porthole 0.15.3 (2026-11-11). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -74,6 +74,18 @@ placed down the document and moved by a scroll-driven animation in the layer's c
|
|
|
74
74
|
so they no longer trail the text for the frames before the scroll event is heard. No message and
|
|
75
75
|
no reading is added (the scroll offset was read already, P132), and the layer still adds nothing to
|
|
76
76
|
what a page can scroll. No wall moves.
|
|
77
|
+
0.15.3: P148, a nested page's real presses: the page's runtime tells its shell each press the
|
|
78
|
+
browser itself made (a mouse down, a finger up, Enter or Space on a native control, a click on
|
|
79
|
+
one), over a `MessagePort` the shell sends at each load and the runtime takes before any content
|
|
80
|
+
runs; the shell tells the host when it heard the last, and the host takes it as it takes the
|
|
81
|
+
shell's activation turning on (§7 "The keyboard"). It gives back what P111 accepted as a loss: a
|
|
82
|
+
press in the page within 5 s of the last gesture. It rests on the runtime's lock on
|
|
83
|
+
`document.open` and on a nested page's frames being opaque, and is not installed where either
|
|
84
|
+
fails. The nested shell's script and the served shell runtime change (their pins, P144 and P145).
|
|
85
|
+
Also in 0.15.3, after the audit of 0.15.1: the four helpers a content Worker of a host's own calls
|
|
86
|
+
with host origins (`statusPage`, `doorResponse`, `doorStatusResponse`, `nestedShellCsp`) check
|
|
87
|
+
each one and throw on a bad one, as P145 said they did; the origins are the host's own
|
|
88
|
+
configuration, never content's.
|
|
77
89
|
|
|
78
90
|
## 1. Two layers
|
|
79
91
|
|
|
@@ -1177,11 +1189,24 @@ unposted words beside the frame and tell the page when.
|
|
|
1177
1189
|
blur), and its `comments.open` on a key it got reaches no handler on Firefox and full Chromium
|
|
1178
1190
|
(on Chromium with frames in process it can: below); what a page says in the shell's name, to its
|
|
1179
1191
|
parent or to the host's window, moves nothing (negative controls `shell-namespace`,
|
|
1180
|
-
`shell-host-input`, `pointer-rule`, `nested-fight`).
|
|
1181
|
-
|
|
1182
|
-
|
|
1183
|
-
|
|
1184
|
-
|
|
1192
|
+
`shell-host-input`, `pointer-rule`, `nested-fight`). A press in the page within 5 s of the last
|
|
1193
|
+
gesture turns no activation on; the page's runtime tells the shell each real press instead
|
|
1194
|
+
(P148), over a port no content holds, and the host takes a press told as it takes an activation
|
|
1195
|
+
turning on: for a second, with no press or key on the host's page since, not in a fight, not
|
|
1196
|
+
within 250 ms of the person's key, not within 500 ms of a stall of the shell. A press is the
|
|
1197
|
+
browser's own event alone (a mouse down; a finger or pen up, so a scroll is none; Enter or Space,
|
|
1198
|
+
not held, on a native control that isn't editable, by its tag and never its `role`; a click on
|
|
1199
|
+
one, but none while a key is down, nor a form's own for Enter in a field); nothing a page
|
|
1200
|
+
dispatches is one, and
|
|
1201
|
+
nothing a page does gets it the port (`leak/served/nested-press.spec.ts`; negative controls
|
|
1202
|
+
`press-untrusted`, `press-role`, `press-editable`, `press-repeat`, `press-key-click`,
|
|
1203
|
+
`press-submit`,
|
|
1204
|
+
`press-touch-down`, `press-port-heard`, `press-port-forged`, `press-open-lock`,
|
|
1205
|
+
`press-still-here`, `press-host-input`). *What doesn't*: a key on a control that isn't native
|
|
1206
|
+
(a `div` with `role="button"`) tells nothing, so a move into the page by it within 5 s of the
|
|
1207
|
+
last gesture is still taken back, until they Tab in; so is any press where the runtime couldn't
|
|
1208
|
+
install its part; the page gets the keys typed while a move waits for the shell's word, or
|
|
1209
|
+
before focus is back. No press of the person's comes within 250 ms of a key they typed on the host's page (a
|
|
1185
1210
|
hand goes from the keys to the pointer first): a move into the frame, or the shell's activation
|
|
1186
1211
|
turning on, that soon is their next key landing in the page, and is taken back, on every engine
|
|
1187
1212
|
(P122, after CI saw full Chromium let such a page keep the keyboard: its key outran the shell's
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.15.
|
|
3
|
+
"version": "0.15.3",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|