@botiverse/porthole 0.14.0 → 0.14.2

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.
Files changed (46) hide show
  1. package/CHANGELOG.md +782 -0
  2. package/dist/annotate/types.d.ts +4 -1
  3. package/dist/annotate/types.js +2 -0
  4. package/dist/annotate/validate.d.ts +2 -1
  5. package/dist/annotate/validate.js +11 -4
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.js +2 -2
  8. package/dist/conformance/harness-source.js +1 -1
  9. package/dist/host/create-host.js +5 -0
  10. package/dist/host/types.d.ts +7 -0
  11. package/dist/react/frame.d.ts +30 -4
  12. package/dist/react/frame.js +69 -5
  13. package/dist/react/index.d.ts +1 -1
  14. package/dist/react/view.js +10 -4
  15. package/dist/server/index.d.ts +1 -1
  16. package/dist/server/index.js +4 -3
  17. package/dist/server/naming.js +4 -0
  18. package/dist/server/nested.d.ts +24 -2
  19. package/dist/server/nested.js +28 -2
  20. package/dist/server/server.js +145 -25
  21. package/dist/server/types.d.ts +5 -0
  22. package/dist/shell/annotate.d.ts +3 -2
  23. package/dist/shell/annotate.js +22 -2
  24. package/dist/shell/runtime.d.ts +6 -0
  25. package/dist/shell/runtime.js +11 -1
  26. package/docs/ADOPTING.md +55 -7
  27. package/docs/ARCHITECTURE.md +10 -5
  28. package/docs/DECISIONS.md +248 -1
  29. package/docs/DESIGN.md +18 -7
  30. package/docs/THREAT_MODEL.md +30 -3
  31. package/package.json +6 -5
  32. package/src/annotate/types.ts +4 -1
  33. package/src/annotate/validate.ts +11 -6
  34. package/src/compile/policy.ts +2 -2
  35. package/src/host/create-host.ts +5 -0
  36. package/src/host/types.ts +7 -0
  37. package/src/react/frame.tsx +114 -6
  38. package/src/react/index.ts +1 -0
  39. package/src/react/view.tsx +20 -2
  40. package/src/server/index.ts +6 -2
  41. package/src/server/naming.ts +4 -0
  42. package/src/server/nested.ts +32 -2
  43. package/src/server/server.ts +168 -24
  44. package/src/server/types.ts +5 -0
  45. package/src/shell/annotate.ts +22 -2
  46. package/src/shell/runtime.ts +12 -1
@@ -7,7 +7,7 @@ import { isHostLabel, reservedLabels } from "./naming.js";
7
7
  import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
8
8
  import { libraryFile } from "./libraries.js";
9
9
  import { isNavigation, ownLoad, serveAsset, serveFile } from "./files.js";
10
- import { nestedAncestors, nestedShellResponse } from "./nested.js";
10
+ import { isNestedLabel, nestedAncestors, nestedLabelOf, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
11
11
  import { DEFAULT_ENTRY } from "../files/paths.js";
12
12
  import { isPortholeCookie, setsPortholeCookie } from "./proxy.js";
13
13
  import { assetCodeRuns, assetCspDirectives, INERT_FILE_CSP, servedDocumentCsp, servedPermissionsPolicy, } from "../compile/policy.js";
@@ -43,6 +43,19 @@ const BASE = /^\/(?:(?!\.{1,2}\/)[A-Za-z0-9._:~-]{1,200}\/){0,16}$/u;
43
43
  const ENTER_PATH = "/__porthole/enter";
44
44
  /** Where a redirect entry's code is redeemed, before its clean address (P068). */
45
45
  const ENTRY_PATH = "/__porthole/entry";
46
+ /** How long a nested page's ticket from its clean address to its shell's label lasts (P114). */
47
+ const HOP_SECONDS = 60;
48
+ /**
49
+ * A path below a file set's base, as a hop's ticket carries it (P114): a relative path of URL path
50
+ * characters, no empty segment but a last one, no dot segment (encoded or not), no query.
51
+ */
52
+ const isPageRest = (rest) => typeof rest === "string" &&
53
+ rest.length > 0 &&
54
+ rest.length <= MAX_PATH &&
55
+ /^[A-Za-z0-9._~!$&'()*+,;=:@%/-]+$/u.test(rest) &&
56
+ rest
57
+ .split("/")
58
+ .every((segment, index, all) => (segment !== "" || index === all.length - 1) && !/^(?:\.|%2e){1,2}$/iu.test(segment));
46
59
  /** How long a redirect entry may take (the person may sign in on the way), and its code. */
47
60
  const ENTRY_STATE_MS = 5 * 60_000;
48
61
  const ENTRY_CODE_SECONDS = 60;
@@ -235,13 +248,34 @@ export function createServer(options) {
235
248
  return keys.label(scope);
236
249
  }
237
250
  const label = content.name(scope);
238
- if (!isHostLabel(label) || isReserved(label)) {
239
- throw new TypeError(`content.name gave ${JSON.stringify(label)} for a scope: it must be one lowercase DNS label (a-z 0-9 -, at most 63, not xn--), not reserved`);
251
+ if (!isHostLabel(label) || isReserved(label) || label.startsWith(PORTHOLE_LABEL_PREFIX)) {
252
+ throw new TypeError(`content.name gave ${JSON.stringify(label)} for a scope: it must be one lowercase DNS label (a-z 0-9 -, at most 63, not xn--), not reserved, not Porthole's own (${PORTHOLE_LABEL_PREFIX}…)`);
240
253
  }
241
254
  return label;
242
255
  };
243
- /** Whether a request's label may be one this server named. */
244
- const ours = (label) => !isReserved(label) && (content.name === undefined ? LABEL.test(label) : isHostLabel(label));
256
+ /**
257
+ * The label an instance is served on: its scope's, or a nested page's shell's own (P114), on
258
+ * which nothing but nested pages' shells, their pages and those pages' files is ever served.
259
+ * Every other display of the scope runs agent-made content on the scope's origin with
260
+ * `allow-same-origin`: on that origin, the shell's realm (its word to the host, the page's
261
+ * sealed address) would be theirs.
262
+ */
263
+ const labelFor = (instance) => {
264
+ const label = nameOf(instance.scope);
265
+ if (instance.document.kind !== "artifact" || compiledFor(instance)?.config.nested !== true) {
266
+ return label;
267
+ }
268
+ const own = nestedLabelOf(label);
269
+ if (isReserved(own)) {
270
+ throw new TypeError(`content.reserved holds ${own}, a nested page's shell's label: reserve no ${PORTHOLE_LABEL_PREFIX} label`);
271
+ }
272
+ return own;
273
+ };
274
+ /** Whether a request's label may be one this server named (a nested page's shell's, P114). */
275
+ const ours = (label) => !isReserved(label) &&
276
+ (isNestedLabel(label) ||
277
+ (!label.startsWith(PORTHOLE_LABEL_PREFIX) &&
278
+ (content.name === undefined ? LABEL.test(label) : isHostLabel(label))));
245
279
  const secure = content.scheme === "https";
246
280
  const defaultPort = secure ? 443 : 80;
247
281
  const portPart = content.port === undefined || content.port === defaultPort ? "" : `:${content.port}`;
@@ -249,6 +283,7 @@ export function createServer(options) {
249
283
  const contentSource = `${content.scheme}://*.${domain}${portPart}`;
250
284
  const sampleHost = `${keys.label("")}.${domain}`;
251
285
  const sampleOrigin = originOfLabel(keys.label(""));
286
+ const sampleNestedOrigin = originOfLabel(nestedLabelOf(keys.label("")));
252
287
  const authorize = options.authorize;
253
288
  const authorizeTtl = authorize?.ttlSeconds ?? 0;
254
289
  if (!Number.isInteger(authorizeTtl) || authorizeTtl < 0 || authorizeTtl > 300) {
@@ -356,7 +391,9 @@ export function createServer(options) {
356
391
  if (config.isolation !== "domain" || !MODES[kind].includes(config.mode)) {
357
392
  throw new TypeError(`The config ${JSON.stringify(name)} (${config.mode}, ${config.isolation}) can't serve a ${kind}: it needs ${MODES[kind].join(" or ")} mode with domain isolation`);
358
393
  }
359
- if (!config.contentOrigins.some((source) => originMatchesSource(sampleOrigin, source))) {
394
+ // A nested page's shell is on a label of its own (P114): its frame source is the same.
395
+ const samples = config.nested === true ? [sampleOrigin, sampleNestedOrigin] : [sampleOrigin];
396
+ if (!samples.every((sample) => config.contentOrigins.some((source) => originMatchesSource(sample, source)))) {
360
397
  throw new TypeError(`The config ${JSON.stringify(name)}'s contentOrigins don't include this server's (${contentSource})`);
361
398
  }
362
399
  return each;
@@ -540,7 +577,7 @@ export function createServer(options) {
540
577
  }
541
578
  let named;
542
579
  try {
543
- named = nameOf(instance.scope);
580
+ named = labelFor(instance);
544
581
  }
545
582
  catch {
546
583
  continue;
@@ -634,8 +671,11 @@ export function createServer(options) {
634
671
  }
635
672
  return best;
636
673
  }
637
- /** A taken ticket, if it is good for `label`'s origin. */
638
- async function take(ticket, label) {
674
+ /**
675
+ * A taken ticket, if it is good for `label`'s origin: its instance's own (a nested page's shell's,
676
+ * P114), or for an entry code (`entry`) its scope's, where a clean address is.
677
+ */
678
+ async function take(ticket, label, entry = false) {
639
679
  if (ticket === null || ticket.length === 0 || ticket.length > 128) {
640
680
  return null;
641
681
  }
@@ -645,7 +685,9 @@ export function createServer(options) {
645
685
  }
646
686
  try {
647
687
  const instance = cleanInstance(record.instance);
648
- return nameOf(instance.scope) === label ? { ...record, instance } : null;
688
+ return (entry ? nameOf(instance.scope) : labelFor(instance)) === label
689
+ ? { ...record, instance }
690
+ : null;
649
691
  }
650
692
  catch {
651
693
  return null;
@@ -685,7 +727,14 @@ export function createServer(options) {
685
727
  catch {
686
728
  return null;
687
729
  }
688
- if (!open || instance.document.kind !== "artifact" || nameOf(instance.scope) !== label) {
730
+ let named;
731
+ try {
732
+ named = labelFor(instance);
733
+ }
734
+ catch {
735
+ return null;
736
+ }
737
+ if (!open || instance.document.kind !== "artifact" || named !== label) {
689
738
  return null;
690
739
  }
691
740
  return {
@@ -741,7 +790,8 @@ export function createServer(options) {
741
790
  // sends a frame's path, where some send no Referer that names it.
742
791
  const blob = SEALED_ASSET.exec(rest)?.[1];
743
792
  if (blob !== undefined) {
744
- if (options.assets === undefined) {
793
+ // A nested page loads no assets (its config refuses them): none on its shell's label (P114).
794
+ if (options.assets === undefined || isNestedLabel(label)) {
745
795
  return page(404, "Not found", "This address names no content.", method);
746
796
  }
747
797
  return ((await assetFor(request, label, access, blob)) ??
@@ -787,7 +837,9 @@ export function createServer(options) {
787
837
  // The ticket's own answer carries the document: an engine that keeps no cookie in a frame
788
838
  // still shows it. The cookie serves what follows (a reload), where the engine keeps it.
789
839
  const record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
840
+ // An entry code opens its clean address alone, through its own browser's nonce (P068, P114).
790
841
  if (record !== null &&
842
+ record.entry === undefined &&
791
843
  record.instance.document.kind !== "external" &&
792
844
  keys.instanceKey(record.instance) === key) {
793
845
  cookie = sessionCookie(request, record);
@@ -804,13 +856,18 @@ export function createServer(options) {
804
856
  if (access === null) {
805
857
  return page(401, "This link has been used", "Content here opens once per link. Open it again from the app that showed it.", method, "session");
806
858
  }
807
- return serveAccess(request, access, cookie);
859
+ // A nested page's hop from its clean address (P114): the page below its base it was entered at.
860
+ const asked = cookie === null ? undefined : record?.page;
861
+ const rest = isPageRest(asked) ? asked : undefined;
862
+ return serveAccess(request, access, cookie, undefined, rest);
808
863
  }
809
864
  /**
810
865
  * The document an access opens, once the host's check lets it in: at its document's path, or
811
866
  * (`at`) a path under a file set's base (P081).
812
867
  */
813
- async function serveAccess(request, access, cookie, at) {
868
+ async function serveAccess(request, access, cookie, at,
869
+ /** A nested page's path below its files' base, from its hop's ticket (P114). */
870
+ pageAt) {
814
871
  const method = request.method.toUpperCase();
815
872
  const refusal = await denied(request, access);
816
873
  if (refusal !== null) {
@@ -829,19 +886,27 @@ export function createServer(options) {
829
886
  if (!isNavigation(request)) {
830
887
  return page(404, "Not found", "This page's files are at its own address.", method);
831
888
  }
889
+ // Its shell is served on its own label alone (P114): a clean address, entered on the scope's
890
+ // label (P068), goes there with a one-time ticket of its own, for what is left of its session.
891
+ const own = originOfLabel(labelFor(access.instance));
892
+ if (access.origin !== own) {
893
+ return hop(access, own, "files" in served && at !== undefined ? at.rest : "");
894
+ }
832
895
  const sealed = await sealFiles(access);
833
896
  let rest = "";
834
897
  if ("files" in served) {
835
898
  const entry = served.files.entry ?? DEFAULT_ENTRY;
836
899
  rest =
837
- at !== undefined && at.rest !== ""
838
- ? at.rest
839
- : entry.includes("/")
840
- ? entry
841
- .split("/")
842
- .map((segment) => encodeURIComponent(segment))
843
- .join("/")
844
- : "";
900
+ pageAt !== undefined
901
+ ? pageAt
902
+ : at !== undefined && at.rest !== ""
903
+ ? at.rest
904
+ : entry.includes("/")
905
+ ? entry
906
+ .split("/")
907
+ .map((segment) => encodeURIComponent(segment))
908
+ .join("/")
909
+ : "";
845
910
  }
846
911
  const shell = nestedShellResponse(served.compiled, {
847
912
  origin: access.origin,
@@ -915,6 +980,35 @@ export function createServer(options) {
915
980
  : served.html;
916
981
  return new Response(method === "HEAD" ? null : html, { status: 200, headers });
917
982
  }
983
+ /**
984
+ * A nested page entered at its clean address (P114), whose shell is never served there: on to the
985
+ * shell's own label, with a one-time ticket for the same access (its viewer, its subject, what is
986
+ * left of its session) and the path below its base it was entered at. Only this server's own
987
+ * answer carries the ticket, as `issue`'s frame address does; the host's check already let the
988
+ * request in.
989
+ */
990
+ async function hop(access, own, rest) {
991
+ const now = Date.now();
992
+ const ticket = newTicket();
993
+ await tickets.put(ticketId(ticket), {
994
+ instance: access.instance,
995
+ viewer: access.viewer,
996
+ expiresAt: now + HOP_SECONDS * 1_000,
997
+ sessionSeconds: Math.min(MAX_SESSION_SECONDS, Math.max(1, Math.floor((access.expiresAt - now) / 1_000))),
998
+ ...(access.anonymous === true ? { anonymous: true } : {}),
999
+ ...(access.subject === undefined ? {} : { subject: access.subject }),
1000
+ ...(isPageRest(rest) ? { page: rest } : {}),
1001
+ });
1002
+ return new Response(null, {
1003
+ status: 303,
1004
+ headers: {
1005
+ location: `${own}${PREFIX}d/${keys.instanceKey(access.instance)}?ticket=${ticket}`,
1006
+ "cache-control": "no-store",
1007
+ "referrer-policy": "no-referrer",
1008
+ "x-robots-tag": "noindex, nofollow",
1009
+ },
1010
+ });
1011
+ }
918
1012
  /**
919
1013
  * An asset at `/_blob/<id>` (P089, after the review): a request carrying an access to an
920
1014
  * artifact of this origin (its page's sealed files' address, as its `Referer` says, P091; or a
@@ -1045,7 +1139,7 @@ export function createServer(options) {
1045
1139
  let instance;
1046
1140
  try {
1047
1141
  instance = cleanInstance(session.i);
1048
- if (instance.document.kind !== "artifact" || nameOf(instance.scope) !== label) {
1142
+ if (instance.document.kind !== "artifact" || labelFor(instance) !== label) {
1049
1143
  continue;
1050
1144
  }
1051
1145
  }
@@ -1144,7 +1238,7 @@ export function createServer(options) {
1144
1238
  if (method !== "GET") {
1145
1239
  return page(405, "Not allowed", "Open this link in a browser.", method);
1146
1240
  }
1147
- const record = await take(url.searchParams.get("code"), label);
1241
+ const record = await take(url.searchParams.get("code"), label, true);
1148
1242
  if (record?.entry === undefined) {
1149
1243
  return page(403, "This sign-in link has been used", "It works once, for a short time. Open the address again.", method, "session");
1150
1244
  }
@@ -1282,6 +1376,28 @@ export function createServer(options) {
1282
1376
  return page(502, "The app didn't answer", "Its server couldn't be reached.", method);
1283
1377
  }
1284
1378
  }
1379
+ /**
1380
+ * A nested page's shell's own label (P114): Porthole's shell at a frame's address, its page and
1381
+ * that page's files below the sealed prefix, and Porthole's status pages (and their script).
1382
+ * Nothing else: no clean address, entry, asset, library or app, so no agent-made content ever
1383
+ * runs on this origin with it (every file below the prefix carries a sandbox without it).
1384
+ */
1385
+ async function serveShellLabel(request, url, label) {
1386
+ const method = request.method.toUpperCase();
1387
+ const script = pageScript(url.pathname);
1388
+ if (script !== null) {
1389
+ return script;
1390
+ }
1391
+ const document = DOCUMENT_PATH.exec(url.pathname);
1392
+ if (document?.[1] !== undefined) {
1393
+ return serveDocument(request, url, label, document[1]);
1394
+ }
1395
+ const sealed = FILES_PATH.exec(url.pathname);
1396
+ if (sealed?.[1] !== undefined) {
1397
+ return serveSealed(request, url, label, sealed[1], sealed[2]);
1398
+ }
1399
+ return page(404, "Nothing here", "This address names no content.", method);
1400
+ }
1285
1401
  /** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
1286
1402
  async function mint(instance, grant, entry) {
1287
1403
  const clean = cleanInstance(instance);
@@ -1381,7 +1497,8 @@ export function createServer(options) {
1381
1497
  originFor: (scope) => originOfLabel(nameOf(scope)),
1382
1498
  async issue(instance, grant) {
1383
1499
  const { clean, key, ticket } = await mint(instance, grant);
1384
- const origin = originOfLabel(nameOf(clean.scope));
1500
+ // A nested page's frame is its shell, on the shell's own label (P114).
1501
+ const origin = originOfLabel(labelFor(clean));
1385
1502
  const path = clean.document.kind === "external"
1386
1503
  ? `${ENTER_PATH}?ticket=${ticket}`
1387
1504
  : `${PREFIX}d/${key}?ticket=${ticket}`;
@@ -1494,6 +1611,9 @@ export function createServer(options) {
1494
1611
  if (!ours(label)) {
1495
1612
  return page(404, "Nothing here", "This address names no content.", method);
1496
1613
  }
1614
+ if (isNestedLabel(label)) {
1615
+ return await serveShellLabel(request, url, label);
1616
+ }
1497
1617
  if (url.pathname === ENTER_PATH) {
1498
1618
  return await enter(request, url, label);
1499
1619
  }
@@ -98,6 +98,11 @@ export interface TicketRecord {
98
98
  /** Whether that address names this version and no other: its files are immutable there. */
99
99
  readonly pinned?: boolean;
100
100
  };
101
+ /**
102
+ * A nested page's ticket from its clean address to its shell's own label (P114): the path below
103
+ * its files' base the shell opens (the entry page when absent).
104
+ */
105
+ readonly page?: string;
101
106
  }
102
107
  /** Where tickets live between `issue` and their one use. Default: in memory (one process). */
103
108
  export interface TicketStore {
@@ -4,12 +4,13 @@
4
4
  * functions as they were. Plain ES2020 like the rest of the shell; no template literals (it sits
5
5
  * in one).
6
6
  *
7
- * The host drives it (`porthole/annotate.start|stop|show|focus|clear`) and it reports
8
- * (`porthole/annotate.selected|unselected|cancelled|anchored|activated`):
7
+ * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection`) and it
8
+ * reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
9
9
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
10
10
  * click or tap picks it, and the content's own handlers never see that click (unless the content
11
11
  * patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
12
12
  * - selecting text: each selection that settles is reported, with where it is, and its clearing;
13
+ * the host's `clearSelection` (P115) takes the page's selection away and tells nothing back;
13
14
  * - marks: each anchor is found in the content as it is now (its CSS selector, its text where it
14
15
  * was, its text anywhere, its words with any spacing) and drawn over it, in a layer of the
15
16
  * shell's own (a closed shadow root), again whenever the content changes; what can't be found
@@ -4,12 +4,13 @@
4
4
  * functions as they were. Plain ES2020 like the rest of the shell; no template literals (it sits
5
5
  * in one).
6
6
  *
7
- * The host drives it (`porthole/annotate.start|stop|show|focus|clear`) and it reports
8
- * (`porthole/annotate.selected|unselected|cancelled|anchored|activated`):
7
+ * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection`) and it
8
+ * reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
9
9
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
10
10
  * click or tap picks it, and the content's own handlers never see that click (unless the content
11
11
  * patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
12
12
  * - selecting text: each selection that settles is reported, with where it is, and its clearing;
13
+ * the host's `clearSelection` (P115) takes the page's selection away and tells nothing back;
13
14
  * - marks: each anchor is found in the content as it is now (its CSS selector, its text where it
14
15
  * was, its text anywhere, its words with any spacing) and drawn over it, in a layer of the
15
16
  * shell's own (a closed shadow root), again whenever the content changes; what can't be found
@@ -41,6 +42,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
41
42
  activated: "porthole/annotate.activated",
42
43
  track: "porthole/annotate.track",
43
44
  tracked: "porthole/annotate.tracked",
45
+ clearSelection: "porthole/annotate.clearSelection",
44
46
  };
45
47
  // The DOM's own functions, taken before content runs.
46
48
  const elementFromPoint = Document.prototype.elementFromPoint;
@@ -50,6 +52,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
50
52
  const createElement = Document.prototype.createElement;
51
53
  const createElementNS = Document.prototype.createElementNS;
52
54
  const selectionOf = Document.prototype.getSelection;
55
+ const removeAllRanges = Selection.prototype.removeAllRanges;
53
56
  const elementRect = Element.prototype.getBoundingClientRect;
54
57
  const rangeRect = Range.prototype.getBoundingClientRect;
55
58
  const rangeRects = Range.prototype.getClientRects;
@@ -1425,6 +1428,23 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1425
1428
  case M.track:
1426
1429
  track(params.id);
1427
1430
  break;
1431
+ case M.clearSelection: {
1432
+ // The host used the person's selection (P115): it goes, and with it what the shell
1433
+ // held of it (a report waiting to settle, the one last told, a scroll's follow-up), so
1434
+ // nothing is told back: the host knows, and the selectionchange this makes finds
1435
+ // nothing to report. Marks, a pick and the mode stay as they are. With nothing
1436
+ // selected, nothing changes.
1437
+ cancelLater(selectionTimer);
1438
+ selectionTimer = 0;
1439
+ reported = null;
1440
+ reportedBox = null;
1441
+ selectionScrolled = false;
1442
+ const selection = selectionOf.call(document);
1443
+ if (selection !== null) {
1444
+ removeAllRanges.call(selection);
1445
+ }
1446
+ break;
1447
+ }
1428
1448
  case M.clear:
1429
1449
  track(null);
1430
1450
  pendingFocus = null;
@@ -1,3 +1,9 @@
1
+ /**
2
+ * What a draft holds back (P117), spliced into the runtime: a tag start the content was cut in
3
+ * (a trailing `<`, `</`, or `<` and a tag's name or attributes, with no `>` yet) is left out until
4
+ * more comes. Parsed as it is, a cut right after `<` or `</` draws them as text.
5
+ */
6
+ export declare const HELD_BACK: string;
1
7
  /**
2
8
  * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
3
9
  * no imports and no build step, so every engine (a browser frame now, a native web view later)
@@ -1,3 +1,12 @@
1
+ /**
2
+ * What a draft holds back (P117), spliced into the runtime: a tag start the content was cut in
3
+ * (a trailing `<`, `</`, or `<` and a tag's name or attributes, with no `>` yet) is left out until
4
+ * more comes. Parsed as it is, a cut right after `<` or `</` draws them as text.
5
+ */
6
+ export const HELD_BACK = String.raw `(html) => {
7
+ const at = html.lastIndexOf("<");
8
+ return at !== -1 && /^\/?(?:[A-Za-z][^>]*)?$/.test(html.slice(at + 1)) ? html.slice(0, at) : html;
9
+ }`;
1
10
  /**
2
11
  * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
3
12
  * no imports and no build step, so every engine (a browser frame now, a native web view later)
@@ -1423,11 +1432,12 @@ export const SHELL_RUNTIME = String.raw `(() => {
1423
1432
  }
1424
1433
  };
1425
1434
  let drafted = false;
1435
+ const heldBack = ${HELD_BACK};
1426
1436
  const draft = (input) => {
1427
1437
  if (rendered || root === null || input === null || typeof input !== "object" || plan.content === "document") {
1428
1438
  return;
1429
1439
  }
1430
- morph(root, inert(parseInert(input.html || "")));
1440
+ morph(root, inert(parseInert(heldBack(String(input.html || "")))));
1431
1441
  drafted = true;
1432
1442
  drawn = true;
1433
1443
  schedule();
package/docs/ADOPTING.md CHANGED
@@ -267,8 +267,38 @@ display.on("annotation", (report) => {
267
267
  if (report.type === "activated") bubble.openBeside(frame, report.rect, report.id);
268
268
  if (report.type === "anchored") bubble.follow(report.results);
269
269
  });
270
+ // The selection was used (a comment posted, a draft added): take it, and its highlight, away.
271
+ composer.onDone(() => display.annotations.clearSelection());
270
272
  ```
271
273
 
274
+ - **Clear the selection once you used it** (`annotations.clearSelection()`, P115): the page's text
275
+ selection, and the highlight the browser leaves on it (gray while focus is in your composer),
276
+ stay until something clears them; the person's next click in the page would, and this does it
277
+ when your composer is done with it. No `unselected` follows it (you know), and nothing else
278
+ changes: your marks and drafts, the mode (`start`) and a followed mark stay. With nothing
279
+ selected it does nothing; it is never sent to a frame that runs later (a reload has no selection
280
+ to clear). Like `start` and `show`, only where the config declares `annotate`. The shell is your
281
+ content server's: an older one ignores it.
282
+
283
+ - **React** (P118): `PortholeFrame` and `PortholeView` take the same as props: `annotating`,
284
+ `annotations`, `focusedAnnotation` and `trackedAnnotation` (the mark to follow, by value; `null`
285
+ stops), every report through `onAnnotation` (`tracked` too). The selection is cleared through a
286
+ ref, which holds `clearSelection()` only (a `PortholeFrameHandle`; never the display, whose life
287
+ is the binding's); with no display running it does nothing. Errors the core's calls throw (an id
288
+ no shown mark has, a config without `annotate`) reach `onHostError`, kind `"annotations"`.
289
+
290
+ ```tsx
291
+ const frame = useRef<PortholeFrameHandle>(null);
292
+ <PortholeView ref={frame} display="page" instance={instance} displayId={id} title={title}
293
+ annotating={commenting ? { elements: false, text: true } : null}
294
+ annotations={marks} trackedAnnotation={openCard?.markId ?? null}
295
+ onAnnotation={(report) => {
296
+ if (report.type === "tracked") card.moveBeside(report.rect);
297
+ if (report.type === "selected") composer.openBeside(report.rect, report.anchor);
298
+ }} />
299
+ composer.onDone(() => frame.current?.clearSelection());
300
+ ```
301
+
272
302
  - **Ids say nothing, and a count only where the page may know it**: the content reads every
273
303
  `show`. Who wrote what stays in your view, outside the frame.
274
304
  - **Drafts only to their author's frame**: the page reads which marks are drafts (that its viewer
@@ -544,7 +574,10 @@ entry: {
544
574
  ### Nested pages: the page below Porthole's shell
545
575
 
546
576
  `nested: true` (P111) on an artifact kind served by the host kit puts the page in a frame of its
547
- own below Porthole's shell, on the same origin, with an opaque origin of its own. Do it where people
577
+ own below Porthole's shell, with an opaque origin of its own. The shell, the page and its files are
578
+ served on a label of the scope's own, `porthole-<24 base32>.<content domain>` (P114), not on the
579
+ scope's label: the scope's other displays run content there with `allow-same-origin`, which would
580
+ reach the shell (porthole#56). Do it where people
548
581
  type beside your displays: in full Chromium (a person's browser, not Playwright's headless shell) a
549
582
  served page's frame is out of process, and your page can't see a press in it, so without nesting a
550
583
  real click into the page's field is taken back and `comments.open` from a real click is refused
@@ -561,7 +594,15 @@ const displays = defineDisplays({
561
594
  ```
562
595
 
563
596
  Nothing else changes on your page: the same `createHost` (or `PortholeFrame`), the same handlers
564
- and events, the same `frame-src`. The display has one more event, `storage` (`{ used }`, once per
597
+ and events, the same `frame-src` (the content domain's wildcard covers the shell's label). Your
598
+ frames route answers the shell's origin (`issue`'s location); a clean address stays on the scope's
599
+ label and sends the browser on to the shell's with a one-time ticket.
600
+
601
+ **Route the shell's label.** `porthole-<…>.<content domain>` must reach the content server as
602
+ your other labels do. Wildcard DNS and a wildcard certificate (`*.<content domain>`) already cover
603
+ it; a route, an edge rule or a firewall that matches labels by a pattern of yours (`a-*`) must let
604
+ `porthole-*` through too. Every `porthole-` label is Porthole's: your naming may not make one
605
+ (`content.name` giving one throws), and `reserved` may not hold one a shell would be on. The display has one more event, `storage` (`{ used }`, once per
565
606
  run: whether the page touched `localStorage` or `sessionStorage`, never what it kept), for you to
566
607
  count the pages that would need storage. A nested page's workers come from Blob URLs (a worker from
567
608
  a script of its own set is refused: its origin is opaque), which may `importScripts` the set's
@@ -569,14 +610,21 @@ scripts; Chromium refuses a Blob module worker there. Not yet with a nested page
569
610
  and Porthole's libraries (`egress.libraries`); the config refuses them.
570
611
 
571
612
  What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
572
- own answers the same, with the helpers `/server` exports: `nestedShellResponse`,
573
- `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the artifact's own,
574
- `https://<label>.<content domain>`; `<token>` is the access in the path (Porthole's sealed
575
- session, or a signed token of your own: the shell only needs addresses under the prefix).
613
+ own answers the same, with the helpers `/server` exports: `nestedLabelOf`, `nestedShellResponse`,
614
+ `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
615
+ `https://<nestedLabelOf(label)>.<content domain>`, where `label` is the scope's label (the one its
616
+ other displays are served on); `<token>` is the access in the path (Porthole's sealed session, or a
617
+ signed token of your own: the shell only needs addresses under the prefix). Your frame location
618
+ for a nested page is on `<origin>`.
619
+
620
+ **The rule** (P114): `<origin>` answers the four rows below and Porthole's status pages, nothing
621
+ else (no other display, no clean address, no asset, no app), and the scope's label never answers a
622
+ nested page's shell, page or files. That is what keeps the shell's realm (its word to your page,
623
+ the page's sealed address) out of every other display's reach.
576
624
 
577
625
  | Request | Answer |
578
626
  | --- | --- |
579
- | The framed address (a ticket's, a cookie's reload, an entered clean address), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
627
+ | `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
580
628
  | `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy: <the page's directives, its files' prefix opened>; sandbox allow-scripts; frame-ancestors <origin> <host origins>` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
581
629
  | `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin`: a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
582
630
  | `<origin>/__porthole/f/<token>/__porthole/renew` | Only the shell's own fetch (`Sec-Fetch-Site: same-origin`, not a navigation): `{ "base": "<origin>/__porthole/f/<new token>/", "expires": <epoch ms> }`, `no-store`; anything else 403. The shell renews 5 minutes before `expires` and moves the page to the new base. |
@@ -202,13 +202,14 @@ holds the page and needs no stable origin, the shell writes it into an opaque
202
202
  frame instead.
203
203
 
204
204
  A **nested** page (P111) splits the shell from the page. The address the host frames
205
- serves Porthole's shell alone: a document with no content, on the content origin. It
205
+ serves Porthole's shell alone: a document with no content, on an origin of its own (a
206
+ label of the scope's, `porthole-<…>`, on which nothing else is ever served, P114). It
206
207
  frames the page in a child sandboxed without `allow-same-origin` (an opaque origin) at
207
- the page's sealed files' address, fetched without a cookie, and passes messages between
208
- the host and the page:
208
+ the page's sealed files' address on that origin, fetched without a cookie, and passes
209
+ messages between the host and the page:
209
210
 
210
211
  ```
211
- Host app Shell (content origin) Page (opaque child)
212
+ Host app Shell (its own origin) Page (opaque child)
212
213
  │ frame src = ticketed URL ──►│ frames the sealed address ───►│ runtime + page
213
214
  │◄── the page's messages ──────│◄── postMessage (by source) ───│
214
215
  │── the host's messages ──────►│── postMessage ───────────────►│
@@ -281,7 +282,11 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
281
282
  bounds it and uses it as a UI hint, never as a permission (P053).
282
283
  A nested page (P111) is the one place they don't: the shell is a document of its
283
284
  own, the page's parent, on another origin than the page's (opaque), so the page
284
- reaches nothing of the shell's realm. The shell trusts the page's messages by
285
+ reaches nothing of the shell's realm. Nor does any other content: the shell's
286
+ origin is a label of its own that hosts nothing but nested pages' shells, their
287
+ opaque pages, those pages' files and status pages (P114), never the scope's
288
+ origin, where the scope's other displays run content with `allow-same-origin`
289
+ (porthole#56). The server holds that rule, not the host's layout. The shell trusts the page's messages by
285
290
  `event.source` alone and passes them on unchanged, never in its own namespace
286
291
  (`porthole/shell/`); what it says in that namespace is the shell's own word (its
287
292
  transient activation, which only a press or key in the page turns on, and whether