@botiverse/porthole 0.8.0 → 0.10.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 +42 -4
- package/dist/annotate/types.js +6 -1
- package/dist/annotate/validate.d.ts +16 -1
- package/dist/annotate/validate.js +33 -3
- package/dist/bridge/bridge.js +1 -51
- package/dist/bridge/unseen.d.ts +18 -0
- package/dist/bridge/unseen.js +71 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/behavior.js +107 -68
- package/dist/conformance/clipboard.js +16 -14
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/limits.js +117 -64
- package/dist/conformance/probes.js +66 -49
- package/dist/conformance/served.js +66 -63
- package/dist/host/create-host.js +75 -3
- package/dist/platform/types.d.ts +12 -1
- package/dist/platform/web.js +8 -0
- package/dist/react/frame.d.ts +6 -2
- package/dist/shell/annotate.d.ts +10 -3
- package/dist/shell/annotate.js +610 -39
- package/docs/ADOPTING.md +76 -0
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +516 -1
- package/docs/DESIGN.md +178 -20
- package/docs/THREAT_MODEL.md +92 -9
- package/package.json +1 -1
- package/src/annotate/types.ts +39 -5
- package/src/annotate/validate.ts +39 -3
- package/src/bridge/bridge.ts +1 -60
- package/src/bridge/unseen.ts +82 -0
- package/src/conformance/behavior.ts +221 -69
- package/src/conformance/clipboard.ts +44 -14
- package/src/conformance/limits.ts +169 -76
- package/src/conformance/probes.ts +97 -49
- package/src/conformance/served.ts +112 -63
- package/src/host/create-host.ts +75 -3
- package/src/platform/types.ts +9 -1
- package/src/platform/web.ts +10 -0
- package/src/react/frame.tsx +6 -2
- package/src/shell/annotate.ts +610 -39
|
@@ -65,12 +65,18 @@ async function expectNoChild(
|
|
|
65
65
|
display: LaunchedDisplay,
|
|
66
66
|
udp: UdpOracle,
|
|
67
67
|
): Promise<Record<string, unknown>> {
|
|
68
|
-
|
|
68
|
+
// A document written over (`document.write`, once the shell's lock is gone) or navigated away
|
|
69
|
+
// is started again before it reports: that is the escape itself, the probe's verdict (P096).
|
|
70
|
+
const verdict = await context.result(display, 15_000).catch(async (error: unknown) => {
|
|
71
|
+
const restarts = (await display.events()).filter((event) => event.type === "navigated");
|
|
72
|
+
expect(restarts, "probe: the content's document was replaced before it reported").toEqual([]);
|
|
73
|
+
throw error;
|
|
74
|
+
});
|
|
69
75
|
await settle(1_000);
|
|
70
76
|
expect(verdict.error, "the attack itself failed").toBeUndefined();
|
|
71
|
-
expect(verdict.childRan ?? false, "a nested frame's script ran").toBe(false);
|
|
72
|
-
expect(verdict.frames ?? 0, "a nested frame is still in the tree").toBe(0);
|
|
73
|
-
expect(udp.packets(), "STUN packets reached the oracle").toBe(0);
|
|
77
|
+
expect(verdict.childRan ?? false, "probe: a nested frame's script ran").toBe(false);
|
|
78
|
+
expect(verdict.frames ?? 0, "probe: a nested frame is still in the tree").toBe(0);
|
|
79
|
+
expect(udp.packets(), "probe: STUN packets reached the oracle").toBe(0);
|
|
74
80
|
if (verdict.reached !== undefined || verdict.blocked !== undefined) {
|
|
75
81
|
context.measured(
|
|
76
82
|
`${context.engine}: a new frame's realm, in the task that added it, was ${verdict.blocked === undefined ? `reachable (RTCPeerConnection: ${JSON.stringify(verdict.reached)})` : `unreachable (${JSON.stringify(verdict.blocked)})`}`,
|
|
@@ -86,9 +92,14 @@ const childSetup = (stun: string) => `
|
|
|
86
92
|
const child = ${js(childDocument(stun))};
|
|
87
93
|
const makeFrame = () => { const f = document.createElement("iframe"); f.setAttribute("srcdoc", child); return f; };`;
|
|
88
94
|
|
|
89
|
-
/**
|
|
95
|
+
/**
|
|
96
|
+
* A navigated document's beacon to an allowed witness, heard only if that document ran: its first
|
|
97
|
+
* act, a real beacon, which the browser delivers even when the frame is removed a moment later (the
|
|
98
|
+
* display started again). A fetch at its end raced that restart: the embedder-csp control saw
|
|
99
|
+
* blob: and data: documents run only some of the time (P096).
|
|
100
|
+
*/
|
|
90
101
|
const witnessScript = (origin: string): string =>
|
|
91
|
-
`<script>fetch(${js(`${origin}/ran`)}).catch(() => {});</script>`;
|
|
102
|
+
`<script>navigator.sendBeacon(${js(`${origin}/ran`)}) || fetch(${js(`${origin}/ran`)}, { keepalive: true }).catch(() => {});</script>`;
|
|
92
103
|
|
|
93
104
|
/**
|
|
94
105
|
* A document the frame navigates to must never run: it would be a fresh realm without the shell's
|
|
@@ -97,7 +108,7 @@ const witnessScript = (origin: string): string =>
|
|
|
97
108
|
*/
|
|
98
109
|
function measureWitness(context: ProbeContext, witness: HttpOracle, scheme: string): void {
|
|
99
110
|
const ran = witness.requests().some((request) => request.path === "/ran");
|
|
100
|
-
expect(ran, `a ${scheme} document the frame navigated to ran`).toBe(false);
|
|
111
|
+
expect(ran, `probe: a ${scheme} document the frame navigated to ran`).toBe(false);
|
|
101
112
|
}
|
|
102
113
|
|
|
103
114
|
/** Every navigation attempt's verdict: nothing reached the oracle, and the content stayed or restarted. */
|
|
@@ -108,10 +119,10 @@ async function expectNoNavigation(
|
|
|
108
119
|
udp?: UdpOracle,
|
|
109
120
|
): Promise<void> {
|
|
110
121
|
await settle(1_500);
|
|
111
|
-
expect(canary.requests(), "the navigation reached the canary").toEqual([]);
|
|
112
|
-
expect(context.requestsTo(canary.origin), "the page requested the canary").toEqual([]);
|
|
122
|
+
expect(canary.requests(), "probe: the navigation reached the canary").toEqual([]);
|
|
123
|
+
expect(context.requestsTo(canary.origin), "probe: the page requested the canary").toEqual([]);
|
|
113
124
|
if (udp !== undefined) {
|
|
114
|
-
expect(udp.packets(), "a navigated document reached the STUN oracle").toBe(0);
|
|
125
|
+
expect(udp.packets(), "probe: a navigated document reached the STUN oracle").toBe(0);
|
|
115
126
|
}
|
|
116
127
|
const events = await display.events();
|
|
117
128
|
const restarts = events.filter((event) => event.type === "navigated").length;
|
|
@@ -124,7 +135,7 @@ async function expectNoNavigation(
|
|
|
124
135
|
const frame = await display.frame();
|
|
125
136
|
await expect(
|
|
126
137
|
frame.locator("#marker"),
|
|
127
|
-
"the frame lost its content without being started again",
|
|
138
|
+
"probe: the frame lost its content without being started again",
|
|
128
139
|
).toHaveCount(1);
|
|
129
140
|
context.measured(`${context.engine}: the frame kept its content`);
|
|
130
141
|
}
|
|
@@ -195,9 +206,9 @@ const escape = (id: string, title: string, code: string | ((canary: string) => s
|
|
|
195
206
|
});
|
|
196
207
|
const before = context.page.url();
|
|
197
208
|
await expectNoNavigation(context, display, canary);
|
|
198
|
-
expect(popups, "a popup opened").toEqual([]);
|
|
199
|
-
expect(downloads, "a download started").toEqual([]);
|
|
200
|
-
expect(context.page.url(), "the top page navigated").toBe(before);
|
|
209
|
+
expect(popups, "probe: a popup opened").toEqual([]);
|
|
210
|
+
expect(downloads, "probe: a download started").toEqual([]);
|
|
211
|
+
expect(context.page.url(), "probe: the top page navigated").toBe(before);
|
|
201
212
|
},
|
|
202
213
|
});
|
|
203
214
|
|
|
@@ -262,8 +273,8 @@ const hint = (id: string, make: (canary: string) => Hint): Probe => ({
|
|
|
262
273
|
});
|
|
263
274
|
await context.result(display, 15_000);
|
|
264
275
|
await settle(1_000);
|
|
265
|
-
expect(canary.requests(), "a hint fetched from the canary").toEqual([]);
|
|
266
|
-
expect(canary.connections(), "a hint opened a connection to the canary").toBe(0);
|
|
276
|
+
expect(canary.requests(), "probe: a hint fetched from the canary").toEqual([]);
|
|
277
|
+
expect(canary.connections(), "probe: a hint opened a connection to the canary").toBe(0);
|
|
267
278
|
},
|
|
268
279
|
});
|
|
269
280
|
|
|
@@ -327,9 +338,12 @@ const sdkProbe = (preset: "inline" | "artifact" | "mcp-app"): Probe => ({
|
|
|
327
338
|
document: page,
|
|
328
339
|
});
|
|
329
340
|
const verdict = await context.result(display, 20_000);
|
|
330
|
-
expect(verdict.error, "App.connect failed").toBeUndefined();
|
|
331
|
-
expect(verdict
|
|
332
|
-
|
|
341
|
+
expect(verdict.error, "probe: App.connect failed").toBeUndefined();
|
|
342
|
+
expect(verdict, "probe: the App SDK didn't connect with the host's theme").toMatchObject({
|
|
343
|
+
connected: true,
|
|
344
|
+
theme: "light",
|
|
345
|
+
});
|
|
346
|
+
expect(verdict.styles, "probe: the host context carried no theme variables").toBeGreaterThan(0);
|
|
333
347
|
},
|
|
334
348
|
});
|
|
335
349
|
|
|
@@ -354,7 +368,10 @@ export const PROBES: readonly Probe[] = [
|
|
|
354
368
|
config: inline(),
|
|
355
369
|
content: attack(`r.origin = window.origin;`),
|
|
356
370
|
});
|
|
357
|
-
expect(
|
|
371
|
+
expect(
|
|
372
|
+
(await context.result(display)).origin,
|
|
373
|
+
"probe: the content's origin isn't opaque",
|
|
374
|
+
).toBe("null");
|
|
358
375
|
},
|
|
359
376
|
},
|
|
360
377
|
{
|
|
@@ -371,7 +388,10 @@ export const PROBES: readonly Probe[] = [
|
|
|
371
388
|
try { window.sendPrompt = () => "replaced"; } catch (e) {}
|
|
372
389
|
r.replaced = window.sendPrompt !== original;`),
|
|
373
390
|
});
|
|
374
|
-
expect(
|
|
391
|
+
expect(
|
|
392
|
+
await context.result(display),
|
|
393
|
+
"probe: a global was defined without its capability, or replaced",
|
|
394
|
+
).toMatchObject({
|
|
375
395
|
sendPrompt: "function",
|
|
376
396
|
openLink: "undefined",
|
|
377
397
|
replaced: false,
|
|
@@ -393,7 +413,10 @@ export const PROBES: readonly Probe[] = [
|
|
|
393
413
|
r.accent = style.getPropertyValue("--color-accent").trim();
|
|
394
414
|
r.theme = document.documentElement.getAttribute("data-theme");`),
|
|
395
415
|
});
|
|
396
|
-
expect(
|
|
416
|
+
expect(
|
|
417
|
+
await context.result(display),
|
|
418
|
+
"probe: the declared theme wasn't applied",
|
|
419
|
+
).toMatchObject({
|
|
397
420
|
accent: resolveTheme(config.theme, "dark")["--color-accent"],
|
|
398
421
|
theme: "dark",
|
|
399
422
|
});
|
|
@@ -413,9 +436,15 @@ export const PROBES: readonly Probe[] = [
|
|
|
413
436
|
});
|
|
414
437
|
await context.result(display);
|
|
415
438
|
const frame = await display.frame();
|
|
416
|
-
await expect(
|
|
439
|
+
await expect(
|
|
440
|
+
frame.locator("body"),
|
|
441
|
+
"probe: the content didn't run exactly once",
|
|
442
|
+
).toHaveAttribute("data-ran", "1");
|
|
417
443
|
await settle(300);
|
|
418
|
-
await expect(frame.locator("body")
|
|
444
|
+
await expect(frame.locator("body"), "probe: the content ran again").toHaveAttribute(
|
|
445
|
+
"data-ran",
|
|
446
|
+
"1",
|
|
447
|
+
);
|
|
419
448
|
},
|
|
420
449
|
},
|
|
421
450
|
|
|
@@ -458,9 +487,9 @@ export const PROBES: readonly Probe[] = [
|
|
|
458
487
|
}
|
|
459
488
|
expect(verdict.allowed, "the allowed origin (the positive control)").toBe("oracle");
|
|
460
489
|
expect(allowed.requests().map((request) => request.path)).toContain("/allowed");
|
|
461
|
-
expect(canary.requests(), "requests reached the canary").toEqual([]);
|
|
462
|
-
expect(context.requestsTo(canary.origin)).toEqual([]);
|
|
463
|
-
expect(verdict).toMatchObject({
|
|
490
|
+
expect(canary.requests(), "probe: requests reached the canary").toEqual([]);
|
|
491
|
+
expect(context.requestsTo(canary.origin), "probe: the page requested the canary").toEqual([]);
|
|
492
|
+
expect(verdict, "probe: a channel to the canary wasn't blocked").toMatchObject({
|
|
464
493
|
fetch: "blocked",
|
|
465
494
|
xhr: "blocked",
|
|
466
495
|
websocket: "blocked",
|
|
@@ -512,9 +541,9 @@ export const PROBES: readonly Probe[] = [
|
|
|
512
541
|
context.inapplicable(INHERITED("img-src", allowed.origin));
|
|
513
542
|
}
|
|
514
543
|
expect(verdict.allowed, "the allowed image (the positive control)").toBe("loaded");
|
|
515
|
-
expect(canary.requests(), "resources loaded from the canary").toEqual([]);
|
|
516
|
-
expect(context.requestsTo(canary.origin)).toEqual([]);
|
|
517
|
-
expect(verdict.script).toBe("undefined");
|
|
544
|
+
expect(canary.requests(), "probe: resources loaded from the canary").toEqual([]);
|
|
545
|
+
expect(context.requestsTo(canary.origin), "probe: the page requested the canary").toEqual([]);
|
|
546
|
+
expect(verdict.script, "probe: a script from the canary ran").toBe("undefined");
|
|
518
547
|
},
|
|
519
548
|
},
|
|
520
549
|
|
|
@@ -545,14 +574,14 @@ export const PROBES: readonly Probe[] = [
|
|
|
545
574
|
});
|
|
546
575
|
const verdict = await context.result(display, 15_000);
|
|
547
576
|
await settle();
|
|
548
|
-
expect(verdict).toMatchObject({
|
|
577
|
+
expect(verdict, "probe: a WebRTC constructor was reachable or came back").toMatchObject({
|
|
549
578
|
names: [],
|
|
550
579
|
peer: "undefined",
|
|
551
580
|
prefixed: "undefined",
|
|
552
581
|
restored: "undefined",
|
|
553
582
|
});
|
|
554
|
-
expect(verdict.connected).toBeUndefined();
|
|
555
|
-
expect(udp.packets(), "STUN reached the oracle").toBe(0);
|
|
583
|
+
expect(verdict.connected, "probe: the content reached a peer connection").toBeUndefined();
|
|
584
|
+
expect(udp.packets(), "probe: STUN reached the oracle").toBe(0);
|
|
556
585
|
if (!sends) {
|
|
557
586
|
context.measured(
|
|
558
587
|
`${context.engine}: the STUN oracle has no positive control here; the constructors' absence is the evidence`,
|
|
@@ -781,7 +810,7 @@ export const PROBES: readonly Probe[] = [
|
|
|
781
810
|
context
|
|
782
811
|
.requestsTo(new URL(context.page.url()).origin)
|
|
783
812
|
.filter((url) => url.includes("/__probe/")),
|
|
784
|
-
"the frame navigated to the host's own origin",
|
|
813
|
+
"probe: the frame navigated to the host's own origin",
|
|
785
814
|
).toEqual([]);
|
|
786
815
|
},
|
|
787
816
|
},
|
|
@@ -793,7 +822,7 @@ export const PROBES: readonly Probe[] = [
|
|
|
793
822
|
const canary = await context.http();
|
|
794
823
|
const udp = await context.udp();
|
|
795
824
|
const witness = await context.http();
|
|
796
|
-
const page =
|
|
825
|
+
const page = `${witnessScript(witness.origin)}<p id="blob">blob</p>${childDocument(udp.stun)}`;
|
|
797
826
|
const display = await context.launch({
|
|
798
827
|
config: inline({ egress: { connect: [witness.origin] } }),
|
|
799
828
|
content: attack(`
|
|
@@ -812,7 +841,7 @@ export const PROBES: readonly Probe[] = [
|
|
|
812
841
|
const canary = await context.http();
|
|
813
842
|
const udp = await context.udp();
|
|
814
843
|
const witness = await context.http();
|
|
815
|
-
const page =
|
|
844
|
+
const page = `${witnessScript(witness.origin)}<p id="data">data</p>${childDocument(udp.stun)}`;
|
|
816
845
|
const display = await context.launch({
|
|
817
846
|
config: inline({ egress: { connect: [witness.origin] } }),
|
|
818
847
|
content: attack(`
|
|
@@ -900,9 +929,12 @@ export const PROBES: readonly Probe[] = [
|
|
|
900
929
|
});
|
|
901
930
|
const verdict = await context.result(display);
|
|
902
931
|
await settle();
|
|
903
|
-
expect(verdict
|
|
904
|
-
|
|
905
|
-
|
|
932
|
+
expect(verdict, "probe: a <base> took effect or a plugin element stayed").toMatchObject({
|
|
933
|
+
baseChanged: false,
|
|
934
|
+
plugins: 0,
|
|
935
|
+
});
|
|
936
|
+
expect(canary.requests(), "probe: requests reached the canary").toEqual([]);
|
|
937
|
+
expect(context.requestsTo(canary.origin), "probe: the page requested the canary").toEqual([]);
|
|
906
938
|
},
|
|
907
939
|
},
|
|
908
940
|
|
|
@@ -939,8 +971,11 @@ export const PROBES: readonly Probe[] = [
|
|
|
939
971
|
});
|
|
940
972
|
await context.result(display, 15_000);
|
|
941
973
|
await settle(1_000);
|
|
942
|
-
expect(canary.requests()).toEqual([]);
|
|
943
|
-
expect(
|
|
974
|
+
expect(canary.requests(), "probe: speculation rules fetched from the canary").toEqual([]);
|
|
975
|
+
expect(
|
|
976
|
+
canary.connections(),
|
|
977
|
+
"probe: speculation rules opened a connection to the canary",
|
|
978
|
+
).toBe(0);
|
|
944
979
|
},
|
|
945
980
|
},
|
|
946
981
|
|
|
@@ -971,8 +1006,11 @@ export const PROBES: readonly Probe[] = [
|
|
|
971
1006
|
localStorage.setItem("porthole-host-secret", "porthole-host-secret-value");
|
|
972
1007
|
});
|
|
973
1008
|
const verdict = await context.result(display);
|
|
974
|
-
expect(verdict.origin).toBe("null");
|
|
975
|
-
expect(
|
|
1009
|
+
expect(verdict.origin, "probe: the content's origin isn't opaque").toBe("null");
|
|
1010
|
+
expect(
|
|
1011
|
+
verdict,
|
|
1012
|
+
"probe: the content reached the host's document, storage or opener",
|
|
1013
|
+
).toMatchObject({
|
|
976
1014
|
parentDocument: "blocked",
|
|
977
1015
|
topDocument: "blocked",
|
|
978
1016
|
parentLocation: "blocked",
|
|
@@ -981,8 +1019,10 @@ export const PROBES: readonly Probe[] = [
|
|
|
981
1019
|
html: false,
|
|
982
1020
|
opener: true,
|
|
983
1021
|
});
|
|
984
|
-
expect(["blocked", ""]).toContain(
|
|
985
|
-
|
|
1022
|
+
expect(["blocked", ""], "probe: the content read the host's cookie").toContain(
|
|
1023
|
+
verdict.cookie,
|
|
1024
|
+
);
|
|
1025
|
+
expect(canary.requests(), "probe: requests reached the canary").toEqual([]);
|
|
986
1026
|
},
|
|
987
1027
|
},
|
|
988
1028
|
{
|
|
@@ -1011,10 +1051,15 @@ export const PROBES: readonly Probe[] = [
|
|
|
1011
1051
|
const verdict = await context.result(display);
|
|
1012
1052
|
await settle();
|
|
1013
1053
|
expect(verdict.siblings, "the probe found its sibling").toBeGreaterThan(0);
|
|
1014
|
-
expect(canary.requests()).toEqual([]);
|
|
1054
|
+
expect(canary.requests(), "probe: a sibling was navigated to the canary").toEqual([]);
|
|
1015
1055
|
const frame = await victim.frame();
|
|
1016
|
-
await expect(
|
|
1017
|
-
|
|
1056
|
+
await expect(
|
|
1057
|
+
frame.locator("#victim"),
|
|
1058
|
+
"probe: the other display lost its content",
|
|
1059
|
+
).toHaveText("victim");
|
|
1060
|
+
await expect(frame.locator("#hijacked"), "probe: the other display was driven").toHaveCount(
|
|
1061
|
+
0,
|
|
1062
|
+
);
|
|
1018
1063
|
},
|
|
1019
1064
|
},
|
|
1020
1065
|
|
|
@@ -1038,7 +1083,10 @@ export const PROBES: readonly Probe[] = [
|
|
|
1038
1083
|
});
|
|
1039
1084
|
await context.result(display, 15_000);
|
|
1040
1085
|
await settle();
|
|
1041
|
-
expect(
|
|
1086
|
+
expect(
|
|
1087
|
+
context.requestsTo(host).filter((url) => url.includes("/portholeProbe/")),
|
|
1088
|
+
"probe: something loaded from the embedding page's own origin",
|
|
1089
|
+
).toEqual([]);
|
|
1042
1090
|
},
|
|
1043
1091
|
},
|
|
1044
1092
|
...BEHAVIOR_PROBES,
|