@botiverse/porthole 0.9.0 → 0.12.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 +21 -7
- package/dist/annotate/validate.d.ts +18 -3
- package/dist/annotate/validate.js +29 -5
- 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/files.d.ts +2 -0
- package/dist/check/files.js +67 -50
- package/dist/check/lint.d.ts +8 -1
- package/dist/check/lint.js +18 -0
- package/dist/check/markup.d.ts +7 -0
- package/dist/check/markup.js +49 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +100 -0
- package/dist/check/scroll.js +1429 -0
- 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/runtime.js +6 -0
- package/dist/conformance/served.js +66 -63
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +46 -4
- package/dist/index.d.ts +1 -1
- package/dist/platform/types.d.ts +4 -2
- package/dist/react/frame.d.ts +2 -1
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +16 -1
- package/dist/runtime/types.generated.js +1 -1
- package/dist/shell/annotate.d.ts +6 -3
- package/dist/shell/annotate.js +474 -104
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +99 -1
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +764 -14
- package/docs/DESIGN.md +192 -42
- package/docs/THREAT_MODEL.md +109 -27
- package/package.json +1 -1
- package/src/annotate/types.ts +22 -7
- package/src/annotate/validate.ts +32 -6
- package/src/bridge/bridge.ts +1 -60
- package/src/bridge/unseen.ts +82 -0
- package/src/check/files.ts +68 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1757 -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/runtime.ts +9 -0
- package/src/conformance/served.ts +112 -63
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +50 -4
- package/src/index.ts +1 -0
- package/src/platform/types.ts +4 -2
- package/src/react/frame.tsx +2 -1
- package/src/runtime/requests.ts +23 -1
- package/src/runtime/types.generated.ts +1 -1
- package/src/shell/annotate.ts +474 -104
- package/src/shell/use.ts +9 -1
- package/types/runtime/v1/comments.d.ts +14 -4
|
@@ -224,8 +224,10 @@ export function servedTests(
|
|
|
224
224
|
const display = await showMode(page, mode, instance(`${mode}-origin`));
|
|
225
225
|
const frame = await display.frame();
|
|
226
226
|
const origin = await frame.evaluate(() => window.origin);
|
|
227
|
-
expect(origin).toBe(display.origin);
|
|
228
|
-
expect(origin).not.toBe(
|
|
227
|
+
expect(origin, "probe: content runs on its own origin").toBe(display.origin);
|
|
228
|
+
expect(origin, "probe: content runs on the host's origin").not.toBe(
|
|
229
|
+
new URL(page.url()).origin,
|
|
230
|
+
);
|
|
229
231
|
},
|
|
230
232
|
);
|
|
231
233
|
|
|
@@ -235,7 +237,10 @@ export function servedTests(
|
|
|
235
237
|
async ({ page }) => {
|
|
236
238
|
const display = await showMode(page, mode, instance(`${mode}-reach`));
|
|
237
239
|
await plantHostSecrets(page);
|
|
238
|
-
expect(
|
|
240
|
+
expect(
|
|
241
|
+
await reachIntoHost(await display.frame()),
|
|
242
|
+
"probe: content reached into the host",
|
|
243
|
+
).toEqual(CLOSED);
|
|
239
244
|
},
|
|
240
245
|
);
|
|
241
246
|
|
|
@@ -267,8 +272,11 @@ export function servedTests(
|
|
|
267
272
|
}, target);
|
|
268
273
|
await frame.click("#porthole-probe-top");
|
|
269
274
|
await page.waitForTimeout(SETTLE_MS);
|
|
270
|
-
expect(page.url()).toBe(before);
|
|
271
|
-
expect(
|
|
275
|
+
expect(page.url(), "probe: the host's page stays").toBe(before);
|
|
276
|
+
expect(
|
|
277
|
+
await host.canaryHits(`${mode}-top`),
|
|
278
|
+
"probe: the navigation reached the canary",
|
|
279
|
+
).toBe(0);
|
|
272
280
|
},
|
|
273
281
|
);
|
|
274
282
|
|
|
@@ -301,10 +309,16 @@ export function servedTests(
|
|
|
301
309
|
}, target);
|
|
302
310
|
await frame.click("#porthole-probe-popup");
|
|
303
311
|
await page.waitForTimeout(SETTLE_MS);
|
|
304
|
-
expect(programmatic).toBe(false);
|
|
305
|
-
expect(
|
|
306
|
-
|
|
307
|
-
|
|
312
|
+
expect(programmatic, "probe: a window opened on load").toBe(false);
|
|
313
|
+
expect(
|
|
314
|
+
await frame.evaluate(() => document.body.dataset.popup),
|
|
315
|
+
"probe: a window opened after a click",
|
|
316
|
+
).toBe("false");
|
|
317
|
+
expect(opened, "probe: a window opened").toHaveLength(0);
|
|
318
|
+
expect(
|
|
319
|
+
await host.canaryHits(`${mode}-popup`),
|
|
320
|
+
"probe: the popup reached the canary",
|
|
321
|
+
).toBe(0);
|
|
308
322
|
},
|
|
309
323
|
);
|
|
310
324
|
}
|
|
@@ -322,10 +336,14 @@ export function servedTests(
|
|
|
322
336
|
search: location.search,
|
|
323
337
|
hash: location.hash,
|
|
324
338
|
}));
|
|
325
|
-
expect(seen.origin).toBe(display.origin);
|
|
326
|
-
expect(seen.search).toMatch(
|
|
327
|
-
|
|
328
|
-
|
|
339
|
+
expect(seen.origin, "probe: the frame's address is on its own origin").toBe(display.origin);
|
|
340
|
+
expect(seen.search, "probe: the frame's address carries more than the ticket").toMatch(
|
|
341
|
+
/^(\?ticket=[^&]+)?$/u,
|
|
342
|
+
);
|
|
343
|
+
expect(seen.hash, "probe: the frame's address carries a fragment").toBe("");
|
|
344
|
+
expect(seen.origin, "probe: the frame's address is the host's origin").not.toBe(
|
|
345
|
+
new URL(page.url()).origin,
|
|
346
|
+
);
|
|
329
347
|
},
|
|
330
348
|
);
|
|
331
349
|
|
|
@@ -346,8 +364,11 @@ export function servedTests(
|
|
|
346
364
|
const other = await host.show(page, await host.shell("scope-b"), {
|
|
347
365
|
content: SHELL_CONTENT,
|
|
348
366
|
});
|
|
349
|
-
expect(other.origin).not.toBe(first.origin);
|
|
350
|
-
expect(
|
|
367
|
+
expect(other.origin, "probe: another scope shares the origin").not.toBe(first.origin);
|
|
368
|
+
expect(
|
|
369
|
+
await (await other.frame()).evaluate(() => localStorage.getItem("kept")),
|
|
370
|
+
"probe: another scope read the storage",
|
|
371
|
+
).toBeNull();
|
|
351
372
|
},
|
|
352
373
|
);
|
|
353
374
|
|
|
@@ -364,9 +385,10 @@ export function servedTests(
|
|
|
364
385
|
] as const) {
|
|
365
386
|
const frame = await display.frame();
|
|
366
387
|
await expect(frame.locator("#artifact")).toHaveText(`version ${version}`);
|
|
367
|
-
expect(
|
|
368
|
-
|
|
369
|
-
|
|
388
|
+
expect(
|
|
389
|
+
await frame.evaluate(() => document.documentElement.dataset.rtc),
|
|
390
|
+
"probe: the page ran before it was hardened",
|
|
391
|
+
).toBe("undefined");
|
|
370
392
|
}
|
|
371
393
|
},
|
|
372
394
|
);
|
|
@@ -383,8 +405,11 @@ export function servedTests(
|
|
|
383
405
|
try {
|
|
384
406
|
const other = await fresh.newPage();
|
|
385
407
|
const again = await other.goto(location.url);
|
|
386
|
-
expect(again?.status(), browserName).toBe(401);
|
|
387
|
-
expect(
|
|
408
|
+
expect(again?.status(), `probe: ${browserName}`).toBe(401);
|
|
409
|
+
expect(
|
|
410
|
+
await other.locator("#porthole-root").count(),
|
|
411
|
+
"probe: a used ticket showed content",
|
|
412
|
+
).toBe(0);
|
|
388
413
|
} finally {
|
|
389
414
|
await fresh.close();
|
|
390
415
|
}
|
|
@@ -428,10 +453,10 @@ export function servedTests(
|
|
|
428
453
|
(window as unknown as { portholeProbeStays?: boolean }).portholeProbeStays === true,
|
|
429
454
|
)
|
|
430
455
|
.catch(() => false);
|
|
431
|
-
expect(stays, "another content origin: the frame's document stays").toBe(true);
|
|
432
|
-
expect(new URL(frame.url()).origin, "another content origin").toBe(display.origin);
|
|
456
|
+
expect(stays, "probe: another content origin: the frame's document stays").toBe(true);
|
|
457
|
+
expect(new URL(frame.url()).origin, "probe: another content origin").toBe(display.origin);
|
|
433
458
|
await away(outside);
|
|
434
|
-
expect(await host.canaryHits("self-navigation"), "the outside site").toBe(0);
|
|
459
|
+
expect(await host.canaryHits("self-navigation"), "probe: the outside site").toBe(0);
|
|
435
460
|
},
|
|
436
461
|
);
|
|
437
462
|
|
|
@@ -518,15 +543,18 @@ export function servedTests(
|
|
|
518
543
|
}, target);
|
|
519
544
|
await press(page, "#porthole-probe-open");
|
|
520
545
|
await page.waitForTimeout(SETTLE_MS);
|
|
521
|
-
expect(programmatic, "on load").toBe(false);
|
|
522
|
-
expect(await page.evaluate(() => document.body.dataset.popup), "after a click").toBe(
|
|
546
|
+
expect(programmatic, "probe: on load").toBe(false);
|
|
547
|
+
expect(await page.evaluate(() => document.body.dataset.popup), "probe: after a click").toBe(
|
|
523
548
|
"false",
|
|
524
549
|
);
|
|
525
|
-
expect(["absent", "refused"], "picture-in-picture").toContain(
|
|
550
|
+
expect(["absent", "refused"], "probe: picture-in-picture").toContain(
|
|
526
551
|
await page.evaluate(() => document.body.dataset.pip),
|
|
527
552
|
);
|
|
528
|
-
expect(opened, "a window opened").toEqual([]);
|
|
529
|
-
expect(
|
|
553
|
+
expect(opened, "probe: a window opened").toEqual([]);
|
|
554
|
+
expect(
|
|
555
|
+
await host.canaryHits("tab-window-open"),
|
|
556
|
+
"probe: the window reached the canary",
|
|
557
|
+
).toBe(0);
|
|
530
558
|
},
|
|
531
559
|
);
|
|
532
560
|
|
|
@@ -580,12 +608,12 @@ export function servedTests(
|
|
|
580
608
|
}, urls);
|
|
581
609
|
await press(page, "#porthole-probe-escape");
|
|
582
610
|
await page.waitForTimeout(SETTLE_MS);
|
|
583
|
-
expect(opened, "a window opened").toEqual([]);
|
|
584
|
-
expect(downloads, "a download started").toEqual([]);
|
|
585
|
-
expect(dialogs, "a browser dialog showed").toEqual([]);
|
|
586
|
-
expect(new URL(page.url()).pathname, "the page stays").not.toMatch(/canary/u);
|
|
611
|
+
expect(opened, "probe: a window opened").toEqual([]);
|
|
612
|
+
expect(downloads, "probe: a download started").toEqual([]);
|
|
613
|
+
expect(dialogs, "probe: a browser dialog showed").toEqual([]);
|
|
614
|
+
expect(new URL(page.url()).pathname, "probe: the page stays").not.toMatch(/canary/u);
|
|
587
615
|
for (const kind of kinds) {
|
|
588
|
-
expect(await host.canaryHits(`tab-${kind}`), kind).toBe(0);
|
|
616
|
+
expect(await host.canaryHits(`tab-${kind}`), `probe: ${kind}`).toBe(0);
|
|
589
617
|
}
|
|
590
618
|
},
|
|
591
619
|
);
|
|
@@ -639,8 +667,11 @@ export function servedTests(
|
|
|
639
667
|
const away = await host.canary("tab-opener");
|
|
640
668
|
await clickAway(tab, `${away}?d=secret`, "opener");
|
|
641
669
|
await page.waitForTimeout(SETTLE_MS);
|
|
642
|
-
expect(page.url(), "the opener stays").toBe("about:blank");
|
|
643
|
-
expect(
|
|
670
|
+
expect(page.url(), "probe: the opener stays").toBe("about:blank");
|
|
671
|
+
expect(
|
|
672
|
+
await host.canaryHits("tab-opener"),
|
|
673
|
+
"probe: the opener's navigation reached the canary",
|
|
674
|
+
).toBe(0);
|
|
644
675
|
},
|
|
645
676
|
);
|
|
646
677
|
|
|
@@ -831,7 +862,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
831
862
|
}
|
|
832
863
|
expect(
|
|
833
864
|
tab.url(),
|
|
834
|
-
`a ${name === "blob" ? "blob: document" : "outside site"} by ${how}: the tab stays`,
|
|
865
|
+
`probe: a ${name === "blob" ? "blob: document" : "outside site"} by ${how}: the tab stays`,
|
|
835
866
|
).toBe(here);
|
|
836
867
|
await tab.close();
|
|
837
868
|
}
|
|
@@ -842,7 +873,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
842
873
|
ways.map(async (how) => [how, await host.canaryHits(`tab-nav-${how}`)] as const),
|
|
843
874
|
)
|
|
844
875
|
).filter(([, hits]) => hits > 0);
|
|
845
|
-
expect(heard, "the outside site heard these").toEqual([]);
|
|
876
|
+
expect(heard, "probe: the outside site heard these").toEqual([]);
|
|
846
877
|
},
|
|
847
878
|
);
|
|
848
879
|
|
|
@@ -924,7 +955,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
924
955
|
[how, canaries[how] ?? ""] as const,
|
|
925
956
|
);
|
|
926
957
|
await tab.waitForTimeout(SETTLE_MS);
|
|
927
|
-
expect(tab.url(),
|
|
958
|
+
expect(tab.url(), `probe: ${how}: the tab stays`).toBe(here);
|
|
928
959
|
await tab.close();
|
|
929
960
|
}
|
|
930
961
|
await page.waitForTimeout(SETTLE_MS);
|
|
@@ -933,7 +964,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
933
964
|
ways.map(async (how) => [how, await host.canaryHits(`tab-links-${how}`)] as const),
|
|
934
965
|
)
|
|
935
966
|
).filter(([, hits]) => hits > 0);
|
|
936
|
-
expect(heard, "the outside site heard these").toEqual([]);
|
|
967
|
+
expect(heard, "probe: the outside site heard these").toEqual([]);
|
|
937
968
|
// Still as before: a fragment link jumps; a link content cancels goes nowhere.
|
|
938
969
|
const tab = await freshTab();
|
|
939
970
|
await tab.evaluate(() => {
|
|
@@ -1037,11 +1068,11 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1037
1068
|
const said = JSON.parse(
|
|
1038
1069
|
await page.evaluate(() => document.body.dataset.devices ?? "{}"),
|
|
1039
1070
|
) as Record<string, string>;
|
|
1040
|
-
expect(said.location, "location").toBe("denied 1");
|
|
1071
|
+
expect(said.location, "probe: location").toBe("denied 1");
|
|
1041
1072
|
// No stream, however it is refused: a machine without a camera says NotFoundError even
|
|
1042
1073
|
// where the policy would refuse (measured: Chromium, the header alone).
|
|
1043
|
-
expect(said.media, "camera and microphone").not.toBe("granted");
|
|
1044
|
-
expect(["rejected", "absent"], "full screen").toContain(said.fullscreen);
|
|
1074
|
+
expect(said.media, "probe: camera and microphone").not.toBe("granted");
|
|
1075
|
+
expect(["rejected", "absent"], "probe: full screen").toContain(said.fullscreen);
|
|
1045
1076
|
if (warnings.length > 0) {
|
|
1046
1077
|
info?.annotations.push({
|
|
1047
1078
|
type: "measured",
|
|
@@ -1169,9 +1200,12 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1169
1200
|
document.body.append(button);
|
|
1170
1201
|
}, canary);
|
|
1171
1202
|
await press(page, "#porthole-probe-prompts");
|
|
1203
|
+
// A prompt the page may show waits for the person, and its report never comes: the
|
|
1204
|
+
// probe's verdict (P096), as much as one refused too late.
|
|
1172
1205
|
await expect
|
|
1173
1206
|
.poll(() => page.evaluate(() => document.body.dataset.prompts ?? ""), {
|
|
1174
1207
|
timeout: 10_000,
|
|
1208
|
+
message: "probe: a prompt was shown and waited, instead of being refused at once",
|
|
1175
1209
|
})
|
|
1176
1210
|
.not.toBe("");
|
|
1177
1211
|
const said = JSON.parse(
|
|
@@ -1179,17 +1213,17 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1179
1213
|
) as Record<string, string | boolean>;
|
|
1180
1214
|
const atOnce = (value: unknown) =>
|
|
1181
1215
|
value === "absent" || (typeof value === "string" && /^refused \w+ at once$/u.test(value));
|
|
1182
|
-
expect(atOnce(said.passkey), `a passkey: ${String(said.passkey)}`).toBe(true);
|
|
1183
|
-
expect(atOnce(said.payment), `a payment: ${String(said.payment)}`).toBe(true);
|
|
1184
|
-
expect(atOnce(said.share), `a share: ${String(said.share)}`).toBe(true);
|
|
1185
|
-
expect(atOnce(said.applePay), `Apple Pay: ${String(said.applePay)}`).toBe(true);
|
|
1216
|
+
expect(atOnce(said.passkey), `probe: a passkey: ${String(said.passkey)}`).toBe(true);
|
|
1217
|
+
expect(atOnce(said.payment), `probe: a payment: ${String(said.payment)}`).toBe(true);
|
|
1218
|
+
expect(atOnce(said.share), `probe: a share: ${String(said.share)}`).toBe(true);
|
|
1219
|
+
expect(atOnce(said.applePay), `probe: Apple Pay: ${String(said.applePay)}`).toBe(true);
|
|
1186
1220
|
expect(
|
|
1187
1221
|
said.video === "absent" || String(said.video).startsWith("refused"),
|
|
1188
|
-
`a video's full screen: ${String(said.video)}`,
|
|
1222
|
+
`probe: a video's full screen: ${String(said.video)}`,
|
|
1189
1223
|
).toBe(true);
|
|
1190
|
-
expect(said.shown, "a video in full screen").toBe(false);
|
|
1224
|
+
expect(said.shown, "probe: a video in full screen").toBe(false);
|
|
1191
1225
|
await page.waitForTimeout(SETTLE_MS);
|
|
1192
|
-
expect(await host.canaryHits("tab-payment"), "the payment method's address").toBe(0);
|
|
1226
|
+
expect(await host.canaryHits("tab-payment"), "probe: the payment method's address").toBe(0);
|
|
1193
1227
|
},
|
|
1194
1228
|
);
|
|
1195
1229
|
|
|
@@ -1215,8 +1249,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1215
1249
|
setTimeout(() => resolve(unreachable), 3_000),
|
|
1216
1250
|
),
|
|
1217
1251
|
]);
|
|
1218
|
-
expect(shown.root).toBe(false);
|
|
1219
|
-
expect(shown.origin).not.toBe(
|
|
1252
|
+
expect(shown.root, "probe: a foreign origin framed the content").toBe(false);
|
|
1253
|
+
expect(shown.origin, "probe: a foreign origin framed the content's origin").not.toBe(
|
|
1254
|
+
location.origin,
|
|
1255
|
+
);
|
|
1220
1256
|
}
|
|
1221
1257
|
},
|
|
1222
1258
|
);
|
|
@@ -1266,8 +1302,8 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1266
1302
|
return { fetched, policy: policies.find((policy) => /connect-src/u.test(policy)) ?? "" };
|
|
1267
1303
|
}, urls);
|
|
1268
1304
|
await page.waitForTimeout(SETTLE_MS);
|
|
1269
|
-
expect(seen.fetched).toBe("blocked");
|
|
1270
|
-
expect(seen.policy, "a CSP applied to the document").not.toBe("");
|
|
1305
|
+
expect(seen.fetched, "probe: the fetch got out").toBe("blocked");
|
|
1306
|
+
expect(seen.policy, "probe: a CSP applied to the document").not.toBe("");
|
|
1271
1307
|
const sources = new Map(
|
|
1272
1308
|
seen.policy
|
|
1273
1309
|
.split(";")
|
|
@@ -1276,10 +1312,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1276
1312
|
);
|
|
1277
1313
|
// What runs or talks never opens to any site (P059), whatever the config.
|
|
1278
1314
|
for (const name of ["script-src", "style-src", "connect-src", "frame-src", "default-src"]) {
|
|
1279
|
-
expect(sources.get(name) ?? [],
|
|
1315
|
+
expect(sources.get(name) ?? [], `probe: ${name} opens no scheme`).not.toContain("https:");
|
|
1280
1316
|
}
|
|
1281
1317
|
for (const kind of ["fetch", "script", "style", "frame"] as const) {
|
|
1282
|
-
expect(await host.canaryHits(`egress-${kind}`), kind).toBe(0);
|
|
1318
|
+
expect(await host.canaryHits(`egress-${kind}`), `probe: ${kind}`).toBe(0);
|
|
1283
1319
|
}
|
|
1284
1320
|
// Images and media: closed, unless the config opened them to any https site (P059);
|
|
1285
1321
|
// then, the canary being an https site, an image reaches it, as the config means.
|
|
@@ -1299,10 +1335,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1299
1335
|
"the image, as the config opens it",
|
|
1300
1336
|
).toBeGreaterThan(0);
|
|
1301
1337
|
} else {
|
|
1302
|
-
expect(await host.canaryHits("egress-img"), "img").toBe(0);
|
|
1338
|
+
expect(await host.canaryHits("egress-img"), "probe: img").toBe(0);
|
|
1303
1339
|
}
|
|
1304
1340
|
if (!https("media")) {
|
|
1305
|
-
expect(await host.canaryHits("egress-media"), "media").toBe(0);
|
|
1341
|
+
expect(await host.canaryHits("egress-media"), "probe: media").toBe(0);
|
|
1306
1342
|
}
|
|
1307
1343
|
},
|
|
1308
1344
|
);
|
|
@@ -1330,11 +1366,18 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1330
1366
|
await expect
|
|
1331
1367
|
.poll(async () => methodsOf(await display.received()))
|
|
1332
1368
|
.toContain(MCP_APPS_METHODS.initialize);
|
|
1333
|
-
await expect(
|
|
1369
|
+
await expect(
|
|
1370
|
+
frame.locator("html"),
|
|
1371
|
+
"probe: the view's undeclared fetch got out",
|
|
1372
|
+
).toHaveAttribute("data-fetch", "blocked");
|
|
1334
1373
|
expect(
|
|
1335
1374
|
await frame.evaluate(() => [window.origin, document.documentElement.dataset.rtc]),
|
|
1375
|
+
"probe: the view runs hardened on its own origin",
|
|
1336
1376
|
).toEqual([display.origin, "undefined"]);
|
|
1337
|
-
expect(
|
|
1377
|
+
expect(
|
|
1378
|
+
await host.canaryHits("proxy-undeclared"),
|
|
1379
|
+
"probe: the undeclared fetch reached the canary",
|
|
1380
|
+
).toBe(0);
|
|
1338
1381
|
},
|
|
1339
1382
|
);
|
|
1340
1383
|
|
|
@@ -1350,7 +1393,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1350
1393
|
resourceReady('<p id="view">Not from the host.</p>'),
|
|
1351
1394
|
);
|
|
1352
1395
|
await page.waitForTimeout(SETTLE_MS);
|
|
1353
|
-
expect(
|
|
1396
|
+
expect(
|
|
1397
|
+
await frame.locator("#view").count(),
|
|
1398
|
+
"probe: the proxy took a view not from its host",
|
|
1399
|
+
).toBe(0);
|
|
1354
1400
|
},
|
|
1355
1401
|
);
|
|
1356
1402
|
|
|
@@ -1383,9 +1429,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1383
1429
|
const other = await fresh.newPage();
|
|
1384
1430
|
const bare = await other.goto(`${location.origin}/`);
|
|
1385
1431
|
const away = new URL(other.url()).origin !== location.origin;
|
|
1386
|
-
expect(bare?.status() === 401 || away, `ended at ${other.url()}`).toBe(true);
|
|
1432
|
+
expect(bare?.status() === 401 || away, `probe: ended at ${other.url()}`).toBe(true);
|
|
1387
1433
|
expect(
|
|
1388
1434
|
await other.evaluate(() => document.documentElement.dataset.app ?? null),
|
|
1435
|
+
"probe: the app ran without its ticket's cookie",
|
|
1389
1436
|
).toBeNull();
|
|
1390
1437
|
} finally {
|
|
1391
1438
|
await fresh.close();
|
|
@@ -1470,7 +1517,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1470
1517
|
const b = await host.show(page, await host.app("url-siblings-b"));
|
|
1471
1518
|
const frameB = await b.frame();
|
|
1472
1519
|
await ready(frameB);
|
|
1473
|
-
expect(await load(frameB, script), "another app's frame loading it").toBe("error");
|
|
1520
|
+
expect(await load(frameB, script), "probe: another app's frame loading it").toBe("error");
|
|
1474
1521
|
}
|
|
1475
1522
|
// Each on a tab of its own, in one browser.
|
|
1476
1523
|
const c = await host.locate(await host.app("url-siblings-c"));
|
|
@@ -1483,7 +1530,9 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
|
|
|
1483
1530
|
expect(await load(tab.mainFrame(), script), "the app's own load").toBe("load");
|
|
1484
1531
|
await tab.goto(d.url);
|
|
1485
1532
|
await ready(tab.mainFrame());
|
|
1486
|
-
expect(await load(tab.mainFrame(), script), "another app's tab loading it").toBe(
|
|
1533
|
+
expect(await load(tab.mainFrame(), script), "probe: another app's tab loading it").toBe(
|
|
1534
|
+
"error",
|
|
1535
|
+
);
|
|
1487
1536
|
} finally {
|
|
1488
1537
|
await tab.close();
|
|
1489
1538
|
}
|
package/src/guide/guide.ts
CHANGED
|
@@ -253,6 +253,7 @@ function widget(c: Context): string {
|
|
|
253
253
|
),
|
|
254
254
|
`- An SVG scales with the frame: its text shows at font-size × frame width ÷ viewBox width, so a 680-wide viewBox turns 12 into 5 px on a phone. Draw it for the phone: viewBox="0 0 ${viewBox} H", no text under 13, width="100%" style="max-width: 400px"; its text then shows at ${smallest} to ${largest} px on every screen. Or draw it 1 unit = 1 px with a script (topic chart).`,
|
|
255
255
|
`- The frame never scrolls sideways: nothing fixed wider than ${layout.minWidthPx} px; images max-width: 100%; a grid or flex child with long text min-width: 0; a wide table or code block in its own box with overflow-x: auto.`,
|
|
256
|
+
`- It scrolls as a document: unless it's meant to fit one screen (a game, a canvas), don't hold html, body or the element that holds it all to one screen (height: 100% or 100vh with overflow: hidden, or position: fixed), or what's below the first screen can't be reached. A box that scrolls by itself takes the wheel while the pointer is over it: keep those to parts of the ${noun} (a wide table, a long list), never the whole of it.`,
|
|
256
257
|
"- Cards in a row wrap (flex-wrap: wrap; flex: 1 1 100px), or a grid of repeat(auto-fit, minmax(160px, 1fr)): at most 2 columns under 500 px, never a fixed repeat(3, …).",
|
|
257
258
|
"- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.",
|
|
258
259
|
fills
|
package/src/guide/runtime.ts
CHANGED
|
@@ -28,7 +28,7 @@ import { sizeWords } from "./limits.ts";
|
|
|
28
28
|
/** How each method is called, as the manual writes it. */
|
|
29
29
|
const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, string>>>> = {
|
|
30
30
|
user: { get: "user.get()" },
|
|
31
|
-
comments: { open: "comments.open({ name, label, quote })" },
|
|
31
|
+
comments: { open: "comments.open({ name, label, quote }, { draft })" },
|
|
32
32
|
clipboard: { copy: "clipboard.copy(text)" },
|
|
33
33
|
links: { open: "links.open(url)" },
|
|
34
34
|
downloads: { save: "downloads.save({ name, text | data })" },
|
|
@@ -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); the person
|
|
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",
|
|
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: () =>
|
package/src/host/create-host.ts
CHANGED
|
@@ -4,7 +4,13 @@ import {
|
|
|
4
4
|
type AnnotationMark,
|
|
5
5
|
type AnnotationReport,
|
|
6
6
|
} from "../annotate/types.ts";
|
|
7
|
-
import {
|
|
7
|
+
import {
|
|
8
|
+
annotateMode,
|
|
9
|
+
checkMarks,
|
|
10
|
+
clampRect,
|
|
11
|
+
hasMarker,
|
|
12
|
+
parseReport,
|
|
13
|
+
} from "../annotate/validate.ts";
|
|
8
14
|
import {
|
|
9
15
|
createBridge,
|
|
10
16
|
onceConsent,
|
|
@@ -194,12 +200,45 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
194
200
|
toFrame(ANNOTATE_METHODS.start, { ...annotating });
|
|
195
201
|
}
|
|
196
202
|
};
|
|
203
|
+
/**
|
|
204
|
+
* The frame's viewport as the platform tells it now; undefined where it can't (no
|
|
205
|
+
* `viewport`, or one that answers no size or throws, P105): every box is then nothing at the
|
|
206
|
+
* frame's corner, and nothing throws out of the frame's listener.
|
|
207
|
+
*/
|
|
208
|
+
const frameViewport = (): { width: number; height: number } | undefined => {
|
|
209
|
+
try {
|
|
210
|
+
const viewport: unknown = surface?.viewport?.();
|
|
211
|
+
if (viewport === null || typeof viewport !== "object") {
|
|
212
|
+
return undefined;
|
|
213
|
+
}
|
|
214
|
+
const size = viewport as { width?: unknown; height?: unknown };
|
|
215
|
+
const across = size.width;
|
|
216
|
+
const down = size.height;
|
|
217
|
+
return typeof across === "number" && typeof down === "number"
|
|
218
|
+
? { width: across, height: down }
|
|
219
|
+
: undefined;
|
|
220
|
+
} catch {
|
|
221
|
+
return undefined;
|
|
222
|
+
}
|
|
223
|
+
};
|
|
224
|
+
/**
|
|
225
|
+
* Whether the person is known to have made no gesture just now (P105): the platform says the
|
|
226
|
+
* page has no transient activation, or fails to say. Where it can't tell (undefined), as for
|
|
227
|
+
* the gesture gate, a report passes.
|
|
228
|
+
*/
|
|
229
|
+
const noGesture = (): boolean => {
|
|
230
|
+
try {
|
|
231
|
+
return surface?.userActivation() === false;
|
|
232
|
+
} catch {
|
|
233
|
+
return true;
|
|
234
|
+
}
|
|
235
|
+
};
|
|
197
236
|
/**
|
|
198
237
|
* Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
|
|
199
238
|
* places the host's own UI nowhere outside its frame.
|
|
200
239
|
*/
|
|
201
240
|
const withinFrame = (report: AnnotationReport): AnnotationReport => {
|
|
202
|
-
const viewport =
|
|
241
|
+
const viewport = frameViewport();
|
|
203
242
|
switch (report.type) {
|
|
204
243
|
case "selected":
|
|
205
244
|
case "activated":
|
|
@@ -220,7 +259,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
220
259
|
/**
|
|
221
260
|
* A report from the frame: checked, taken only while the host asked for it (a selection
|
|
222
261
|
* only in select mode, results only for its own marks, a marker's click only for a mark it
|
|
223
|
-
* shows with one), then through the bridge's gates.
|
|
262
|
+
* shows with one, a count's or a draft's, within a gesture), then through the bridge's gates.
|
|
224
263
|
*/
|
|
225
264
|
const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
|
|
226
265
|
if (
|
|
@@ -277,7 +316,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
277
316
|
}
|
|
278
317
|
case "activated": {
|
|
279
318
|
const { id } = report;
|
|
280
|
-
if (!marks.some((mark) => mark.id === id && mark
|
|
319
|
+
if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
320
|
+
return;
|
|
321
|
+
}
|
|
322
|
+
// A marker's real click gives the host's page transient activation (measured on all
|
|
323
|
+
// three engines, P105); a click a page posts at load, on a timer or on a scroll has
|
|
324
|
+
// none and is dropped. One posted on the person's own press in the content passes: the
|
|
325
|
+
// host's view guards itself against that (THREAT_MODEL §6).
|
|
326
|
+
if (noGesture()) {
|
|
281
327
|
return;
|
|
282
328
|
}
|
|
283
329
|
break;
|
package/src/index.ts
CHANGED
package/src/platform/types.ts
CHANGED
|
@@ -35,13 +35,15 @@ export interface Surface {
|
|
|
35
35
|
setColorScheme(scheme: ColorScheme): void;
|
|
36
36
|
/**
|
|
37
37
|
* Whether the embedding page has transient user activation now (a gesture in the frame
|
|
38
|
-
* activates its ancestors), or undefined where the platform can't tell.
|
|
38
|
+
* activates its ancestors), or undefined where the platform can't tell. The gesture gate reads
|
|
39
|
+
* it, and so does a marker's click (P105): false, or a throw, drops it.
|
|
39
40
|
*/
|
|
40
41
|
userActivation(): boolean | undefined;
|
|
41
42
|
/**
|
|
42
43
|
* The frame's viewport now, CSS px (its content box): what a box the frame reports is clamped
|
|
43
44
|
* to (P104). Undefined, or absent, where the platform can't tell: every reported box is then
|
|
44
|
-
* clamped to nothing, at the frame's corner
|
|
45
|
+
* clamped to nothing, at the frame's corner, as it is for an answer that isn't a size, or a
|
|
46
|
+
* throw (P105).
|
|
45
47
|
*/
|
|
46
48
|
viewport?(): { readonly width: number; readonly height: number } | undefined;
|
|
47
49
|
/**
|
package/src/react/frame.tsx
CHANGED
|
@@ -587,7 +587,8 @@ export interface PortholeFrameProps {
|
|
|
587
587
|
readonly annotating?: AnnotateMode | null;
|
|
588
588
|
/**
|
|
589
589
|
* The anchors to mark in the frame (the host's comments). A mark with a `count` gets a
|
|
590
|
-
* clickable marker (P104)
|
|
590
|
+
* clickable marker (P104); a draft (`kind: "draft"`, the author's own frame only) a hollow one
|
|
591
|
+
* with no number (P107). Compared by value.
|
|
591
592
|
*/
|
|
592
593
|
readonly annotations?: readonly AnnotationMark[];
|
|
593
594
|
/**
|
package/src/runtime/requests.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { unseen } from "../bridge/unseen.ts";
|
|
1
2
|
import type { Limits } from "../config/schema.ts";
|
|
2
3
|
import { fileLimits, filePathProblem } from "../files/paths.ts";
|
|
3
4
|
import { fileTypeOf } from "../files/types.ts";
|
|
@@ -62,16 +63,36 @@ export interface CommentAnchor {
|
|
|
62
63
|
|
|
63
64
|
export interface CommentRequest {
|
|
64
65
|
readonly anchor: CommentAnchor;
|
|
66
|
+
/**
|
|
67
|
+
* Text to start the person's comment with (P108): the content's word, a draft in the composer
|
|
68
|
+
* that the person edits and posts themselves, or doesn't. Never posted by the host on its own.
|
|
69
|
+
*/
|
|
70
|
+
readonly draft?: string;
|
|
65
71
|
}
|
|
66
72
|
|
|
73
|
+
/**
|
|
74
|
+
* A draft (P108): text the person will post in their own name, so all of it must be text they can
|
|
75
|
+
* see: at most 2,000 characters, well-formed, not blank, and nothing `unseen` (P100: no zero-width
|
|
76
|
+
* or bidi characters, no tags, no controls but a new line and a tab), which a host would show as
|
|
77
|
+
* nothing and an agent would read as the person's words. Lines and tabs are fine: a checklist.
|
|
78
|
+
*/
|
|
79
|
+
const draftText = (value: unknown): value is string =>
|
|
80
|
+
typeof value === "string" &&
|
|
81
|
+
value.trim() !== "" &&
|
|
82
|
+
value.length <= 2_000 &&
|
|
83
|
+
value.isWellFormed() &&
|
|
84
|
+
!unseen(value);
|
|
85
|
+
|
|
67
86
|
export function parseCommentRequest(args: unknown): CommentRequest | null {
|
|
68
87
|
const anchor = isRecord(args) ? args.anchor : undefined;
|
|
69
88
|
if (!isRecord(anchor) || !shortText(anchor.name, 256)) {
|
|
70
89
|
return null;
|
|
71
90
|
}
|
|
91
|
+
const draft = isRecord(args) ? args.draft : undefined;
|
|
72
92
|
if (
|
|
73
93
|
(anchor.label !== undefined && !shortText(anchor.label, 200)) ||
|
|
74
|
-
(anchor.quote !== undefined && !shortText(anchor.quote, 2_000))
|
|
94
|
+
(anchor.quote !== undefined && !shortText(anchor.quote, 2_000)) ||
|
|
95
|
+
(draft !== undefined && !draftText(draft))
|
|
75
96
|
) {
|
|
76
97
|
return null;
|
|
77
98
|
}
|
|
@@ -81,6 +102,7 @@ export function parseCommentRequest(args: unknown): CommentRequest | null {
|
|
|
81
102
|
...(anchor.label === undefined ? {} : { label: anchor.label }),
|
|
82
103
|
...(anchor.quote === undefined ? {} : { quote: anchor.quote }),
|
|
83
104
|
},
|
|
105
|
+
...(draft === undefined ? {} : { draft }),
|
|
84
106
|
};
|
|
85
107
|
}
|
|
86
108
|
|
|
@@ -7,7 +7,7 @@ export const RUNTIME_TYPES: Readonly<Record<string, Readonly<Record<string, stri
|
|
|
7
7
|
"assets": "// Porthole capability runtime, contract 1: assets (the artifact's asset library). Declare it: { assets: {} }.\n// Assets live outside every version, at \"/_blob/<id>\" on the page's own origin: keep that url (or\n// the id) in your data, and show it with assets.url(id). Images, media and fonts load; scripts and\n// stylesheets only where the app lets only admins upload, and only those an admin added. Not for\n// files that version with the page: publish those with it.\n\ninterface PortholeAsset {\n /** 32 hex characters. */\n readonly id: string;\n /** \"/_blob/<id>\": use it as given. */\n readonly url: string;\n readonly name: string;\n /** Porthole's type for the name's extension. */\n readonly type: string;\n readonly size: number;\n}\n\ninterface PortholeAssets {\n /** The library, people's uploads through the page included. Level: view. */\n list(): Promise<readonly PortholeAsset[]>;\n /**\n * Adds a file (a File from an <input type=\"file\">, a Blob, bytes) under its name (a File's own,\n * or options.name): an image, media, a font, a PDF, text or data, never HTML; a script or a\n * stylesheet only where uploads are the admins'. The app may ask the person first. Level: admin,\n * unless the app lets people who interact upload.\n */\n upload(\n file: Blob | ArrayBuffer | ArrayBufferView,\n options?: { readonly name?: string },\n ): Promise<PortholeAsset>;\n /**\n * The address that loads an asset in this page now: put it in src or href when you show it.\n * Store the id (or \"/_blob/<id>\"), never this: it carries this page's access. A \"/_blob/<id>\"\n * written in the page loads too, except in some browsers' frames (Safari's); this always does.\n */\n url(id: string): string;\n /** Removes one, from a click; the app asks the person first. Level: admin. */\n delete(id: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n assets: PortholeAssets;\n}\n",
|
|
8
8
|
"chat": "// Porthole capability runtime, contract 1: chat. Declare it: { chat: {} }.\n\ninterface PortholeChat {\n /**\n * Sends text to the agent as the person's message (\"explain this point\"). Call it from a click.\n * Resolves true if it was sent. Level: interact.\n */\n send(text: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n chat: PortholeChat;\n}\n",
|
|
9
9
|
"clipboard": "// Porthole capability runtime, contract 1: clipboard. Built in: never declare it.\n\ninterface PortholeClipboard {\n /**\n * Copies text to the person's clipboard (at most 20,000 characters); the app shows them what\n * was copied. Nothing else in the page can write the clipboard. Call it from a click.\n * Resolves true if it was copied. Level: view.\n */\n copy(text: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n clipboard: PortholeClipboard;\n}\n",
|
|
10
|
-
"comments": "// Porthole capability runtime, contract 1: comments. Built in: never declare it.\n\n/** Where a comment goes, in the page's own words. */\ninterface PortholeCommentAnchor {\n /** A stable name the page chose: \"slide-3\", \"refs/a.md#L12\" (at most 256 characters). */\n readonly name: string;\n /** What the app shows for it (at most 200). */\n readonly label?: string;\n /** The text the comment is about (at most 2,000). */\n readonly quote?: string;\n}\n\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }). The person writes
|
|
10
|
+
"comments": "// Porthole capability runtime, contract 1: comments. Built in: never declare it.\n\n/** Where a comment goes, in the page's own words. */\ninterface PortholeCommentAnchor {\n /** A stable name the page chose: \"slide-3\", \"refs/a.md#L12\" (at most 256 characters). */\n readonly name: string;\n /** What the app shows for it (at most 200). */\n readonly label?: string;\n /** The text the comment is about (at most 2,000). */\n readonly quote?: string;\n}\n\n/** How the composer opens. */\ninterface PortholeCommentOptions {\n /**\n * Text the composer starts with (at most 2,000 characters): a draft the person edits, posts\n * or discards in the app. It is never posted without them. Visible text only: new lines and\n * tabs are fine; a draft with zero-width, bidi or tag characters is refused.\n */\n readonly draft?: string;\n}\n\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }), starting with\n * `options.draft` if given. The person writes and posts it in the app. Resolves true if the\n * composer opened. Write-only: a page never reads comments. Call it from a click. Level: view.\n */\n open(anchor: PortholeCommentAnchor | string, options?: PortholeCommentOptions): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n comments: PortholeComments;\n}\n",
|
|
11
11
|
"context": "// Porthole capability runtime, contract 1: context. Declare it: { context: {} }.\n\ninterface PortholeContextUpdate {\n /**\n * MCP text blocks only: [{ type: \"text\", text: \"…\" }]. Visible characters only, here and in\n * structuredContent: no zero-width or bidi controls, variation selectors, tag or private-use\n * characters, or controls other than new lines and tabs (refused), but the selectors and\n * joiners inside real emoji (☀️, 👨👩👧, 1️⃣), and a joiner or non-joiner between two letters of\n * a script it shapes (Arabic, Persian, the Indic scripts, Myanmar…).\n */\n readonly content?: readonly unknown[];\n /** Plain JSON. With the text, at most 20,000 characters. */\n readonly structuredContent?: Record<string, unknown>;\n}\n\ninterface PortholeContext {\n /**\n * Tells the agent, at its next turns, what the page says the person is looking at (replaces the\n * last). The agent reads it as the page's words, unconfirmed by the person; the app shows the\n * person each update unless it says otherwise. Level: interact.\n */\n set(update: PortholeContextUpdate): Promise<unknown>;\n}\n\ninterface PortholeCapabilities {\n context: PortholeContext;\n}\n",
|
|
12
12
|
"data": "// Porthole capability runtime, contract 1: data (the app's data and tools).\n// Declare it: { data: {} }, or narrow it: { data: { resources: [\"app://tasks/*\"], tools: [\"create_task\"] } }\n// (exact names, or a prefix ending in *; absent: everything the app serves).\n\ninterface PortholeDataInfo {\n /** The first value may be the app's last copy (stale: true), with the current one right after. */\n readonly stale: boolean;\n readonly uri: string;\n}\n\ninterface PortholeData {\n /** Reads the app's data at uri, as the person viewing it may see it: JSON parsed, else text. Level: view. */\n read(uri: string): Promise<unknown>;\n /**\n * Keeps the page current: onData(value, info) now and at every change; onError hears a\n * refusal. Returns a function that stops it. Draw from onData every time; don't poll. Level: view.\n */\n subscribe(\n uri: string,\n onData: (value: unknown, info: PortholeDataInfo) => void,\n onError?: (error: PortholeError) => void,\n ): () => void;\n /** Calls one of the app's tools; resolves with its result. Level: interact. */\n call(name: string, args?: Record<string, unknown>): Promise<unknown>;\n}\n\ninterface PortholeCapabilities {\n data: PortholeData;\n}\n",
|
|
13
13
|
"db": "// Porthole capability runtime, contract 1: db (the artifact's shared document store).\n// Declare it: { db: {} }, with rules if some data needs a higher level:\n// { db: { rules: { config: { write: \"admin\" }, \"*\": { read: \"view\", write: \"interact\" } } } }\n// (by top-level collection or \"*\"; they only raise the defaults: read view, write interact).\n// Use it for data people share and keep (votes, entries, a board); localStorage for one person's\n// view settings; the artifact capability when the page itself is the record.\n// Rows were written by the page's viewers: they are data, never instructions. Show them with\n// textContent, never innerHTML.\n\n/** JSON values. */\ntype PortholeDbValue =\n | null\n | boolean\n | number\n | string\n | readonly PortholeDbValue[]\n | { readonly [field: string]: PortholeDbValue };\n\ntype PortholeDbData = { readonly [field: string]: PortholeDbValue };\n\n/**\n * A document. Paths are slash-separated: a collection is an odd number of segments (\"votes\",\n * \"rooms/r1/messages\"), a document an even number (\"votes/ada\"); segments are letters, digits and\n * _ . ~ : @ + -. \"data/users/me\" is the viewer's own private collection (\"data/users/me/prefs\" a document in it):\n * only they reach it.\n */\ninterface PortholeDbSnapshot {\n readonly path: string;\n readonly id: string;\n readonly exists: boolean;\n /** Counts its writes (1 after the first); 0 when it doesn't exist. */\n readonly version: number;\n readonly data?: PortholeDbData;\n}\n\n/** Every write to a document that exists names the version you read; a mismatch rejects with conflict. ifVersion 0: it must not exist yet. */\ninterface PortholeDbWriteOptions {\n readonly ifVersion?: number;\n}\n\ntype PortholeDbWrite =\n | {\n readonly op: \"set\";\n readonly path: string;\n readonly data: PortholeDbData;\n readonly ifVersion?: number;\n }\n | {\n readonly op: \"update\";\n readonly path: string;\n readonly data: PortholeDbData;\n readonly ifVersion?: number;\n }\n | { readonly op: \"delete\"; readonly path: string; readonly ifVersion?: number };\n\ninterface PortholeDbQuery {\n /** At most 10: [field, op, value]. */\n readonly where?: readonly (readonly [\n field: string,\n op: \"==\" | \"!=\" | \"<\" | \"<=\" | \">\" | \">=\" | \"in\" | \"array-contains\",\n value: PortholeDbValue,\n ])[];\n readonly orderBy?: { readonly field: string; readonly direction?: \"asc\" | \"desc\" };\n /** 1 to 500. */\n readonly limit?: number;\n}\n\ninterface PortholeDb {\n /** Level: view. */\n get(path: string): Promise<PortholeDbSnapshot>;\n /** A collection's documents. Level: view. */\n query(\n collection: string,\n query?: PortholeDbQuery,\n ): Promise<{ readonly docs: readonly PortholeDbSnapshot[] }>;\n /** Writes a whole document (at most 1 MiB of JSON). Level: interact. */\n set(\n path: string,\n data: PortholeDbData,\n options?: PortholeDbWriteOptions,\n ): Promise<{ readonly version: number }>;\n /** Merges fields over a document's. Level: interact. */\n update(\n path: string,\n data: PortholeDbData,\n options?: PortholeDbWriteOptions,\n ): Promise<{ readonly version: number }>;\n /** Level: interact. */\n delete(path: string, options?: PortholeDbWriteOptions): Promise<null>;\n /**\n * Up to 50 writes to different documents, all or none. Each write's new version (null for a\n * delete). Each write at its own level.\n */\n batch(\n writes: readonly PortholeDbWrite[],\n ): Promise<{ readonly versions: readonly (number | null)[] }>;\n /**\n * Follows a document (a snapshot) or a collection ({ docs }) now and at every change. Returns a\n * function that stops it. Draw from onData; don't poll. Level: view.\n */\n onSnapshot(\n path: string,\n onData: (state: PortholeDbSnapshot | { readonly docs: readonly PortholeDbSnapshot[] }) => void,\n onError?: (error: PortholeError) => void,\n ): () => void;\n}\n\ninterface PortholeCapabilities {\n db: PortholeDb;\n}\n",
|