@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
@@ -359,6 +359,11 @@ export function createHost(config, options = {}) {
359
359
  tracking = null;
360
360
  toFrame(ANNOTATE_METHODS.clear, {});
361
361
  },
362
+ clearSelection() {
363
+ // Host → frame only, and kept for no later frame (P115).
364
+ needsAnnotate("clearSelection");
365
+ toFrame(ANNOTATE_METHODS.clearSelection, {});
366
+ },
362
367
  };
363
368
  const hostContext = () => {
364
369
  const width = container.getBoundingClientRect().width;
@@ -252,6 +252,13 @@ export interface AnnotationControls {
252
252
  track(id: string | null): void;
253
253
  /** Removes every mark. */
254
254
  clear(): void;
255
+ /**
256
+ * Takes the page's text selection away (P115), its highlight with it: for when the host has
257
+ * used it (a comment posted, a draft added). No `unselected` follows; marks (posted and drafts),
258
+ * the mode and a followed mark stay as they are. Nothing selected: nothing happens. Not kept for
259
+ * a frame that runs later (it has no selection to clear).
260
+ */
261
+ clearSelection(): void;
255
262
  }
256
263
  export interface DisplayControls {
257
264
  readonly displayId: string;
@@ -1,6 +1,6 @@
1
1
  import type { PageDeclaration } from "../runtime/declaration.ts";
2
2
  import type { ViewerInfo } from "../runtime/levels.ts";
3
- import { type CSSProperties, type ReactElement, type ReactNode } from "react";
3
+ import { type CSSProperties, type ReactElement, type ReactNode, type Ref } from "react";
4
4
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
5
5
  import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
6
6
  import { Refused, type RefusalReason } from "../bridge/refusal.ts";
@@ -140,6 +140,20 @@ export interface PlaceholderProps {
140
140
  /** Runs the display again (a stopped one), stopping another if the page is at its most. */
141
141
  readonly run: () => void;
142
142
  }
143
+ /**
144
+ * What a `ref` on `PortholeFrame` or `PortholeView` holds (P118): the display's few imperative
145
+ * calls, never the display itself. The same handle for the frame's whole life: its calls do
146
+ * nothing while no display runs (waiting to near the screen, stopped, a fallback drawn).
147
+ */
148
+ export interface PortholeFrameHandle {
149
+ /**
150
+ * Takes the page's text selection away, and its highlight (`annotations.clearSelection()`,
151
+ * P115), once the host has used it (a comment posted, a draft added). No `unselected` follows.
152
+ * Nothing runs: nothing happens. A config without `annotate`: `onHostError`, kind
153
+ * `"annotations"` (the core's call throws; this never does).
154
+ */
155
+ clearSelection(): void;
156
+ }
143
157
  export interface PortholeFrameProps {
144
158
  /** A preset's config. Keep it stable (module scope or memoized): a new one remounts the frame. */
145
159
  readonly config: PortholeConfig;
@@ -160,10 +174,11 @@ export interface PortholeFrameProps {
160
174
  readonly instance?: InstanceRef;
161
175
  /**
162
176
  * What the page declared (P086), as the host stored it with the artifact: the capabilities it
163
- * reaches through `porthole.use`, and its pinned runtime. By value: a change makes the display
164
- * again.
177
+ * reaches through `porthole.use`, and its pinned runtime. Under `config.runtime`, `null` says
178
+ * the page was published before 0.7 and has 0.6's surface (`MountOptions.declaration`). By
179
+ * value: a change makes the display again.
165
180
  */
166
- readonly declaration?: PageDeclaration;
181
+ readonly declaration?: PageDeclaration | null;
167
182
  /**
168
183
  * Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
169
184
  * makes the display again.
@@ -272,6 +287,17 @@ export interface PortholeFrameProps {
272
287
  readonly id: string;
273
288
  readonly key: string | number;
274
289
  } | null;
290
+ /**
291
+ * The mark to follow (`annotations.track`, P112, P118): while it moves, `onAnnotation` gets
292
+ * `{ type: "tracked", id, rect }` at most once per animation frame, for it alone. `null` (or
293
+ * leaving it out once set) stops. By value: given when it changes, and when the display is made.
294
+ * Only a shown mark (`annotations`) is followed: another id, or a config without `annotate`, is
295
+ * `onHostError` (kind `"annotations"`), as the core's call throws. `annotations` without it
296
+ * stop the following, as the core's `show` does; it starts again once they have it back.
297
+ */
298
+ readonly trackedAnnotation?: string | null;
299
+ /** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
300
+ readonly ref?: Ref<PortholeFrameHandle>;
275
301
  /**
276
302
  * What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
277
303
  * pick, where marks are (again once a scroll settles: those that moved), a marker clicked
@@ -1,5 +1,5 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
2
+ import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
3
3
  import { isRefused, reasonOf, Refused } from "../bridge/refusal.js";
4
4
  import { writeClipboard } from "../host/clipboard.js";
5
5
  import { createHost } from "../host/create-host.js";
@@ -292,7 +292,25 @@ export function PortholeFrame(props) {
292
292
  const box = useRef(null);
293
293
  const max = props.config.limits.maxLiveFrames;
294
294
  const state = useSyncExternalStore((listener) => live.subscribe(listener), () => live.state(key), () => "waiting");
295
- const { eager } = props;
295
+ const { eager, ref: handleRef } = props;
296
+ // The running display (the Mount's), for the handle's calls; null while none runs.
297
+ const display = useRef(null);
298
+ const running = useCallback((each) => {
299
+ display.current = each;
300
+ }, []);
301
+ // The props as of the last render, read when the handle is called (never during render).
302
+ const own = useRef(props);
303
+ useLayoutEffect(() => {
304
+ own.current = props;
305
+ });
306
+ useImperativeHandle(handleRef, () => ({
307
+ clearSelection() {
308
+ const now = display.current;
309
+ if (now !== null) {
310
+ attempt(() => now.annotations.clearSelection(), own.current);
311
+ }
312
+ },
313
+ }), []);
296
314
  useEffect(() => {
297
315
  const element = box.current;
298
316
  if (element === null) {
@@ -343,12 +361,15 @@ export function PortholeFrame(props) {
343
361
  : {}),
344
362
  ...(state === "running" ? {} : { minHeight: Math.max(height, PLACEHOLDER_HEIGHT_PX) }),
345
363
  ...props.style,
346
- }, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
364
+ }, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, running: running, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
347
365
  }
348
366
  /** One running display: created when mounted, torn down when unmounted, fed as props change. */
349
- function Mount({ frame, page, initialHeightPx, placeholder, run }) {
367
+ function Mount({ frame, page, running, initialHeightPx, placeholder, run, }) {
350
368
  const holder = useRef(null);
351
369
  const handle = useRef(null);
370
+ // The mark the display follows now, as the core keeps it (P118), and the prop as last seen.
371
+ const following = useRef(null);
372
+ const asked = useRef(null);
352
373
  const [ready, setReady] = useState(false);
353
374
  // The height this display started at: later reports don't make it start again.
354
375
  const [startHeight] = useState(initialHeightPx);
@@ -527,6 +548,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
527
548
  return;
528
549
  }
529
550
  handle.current = display;
551
+ running(display);
530
552
  const events = [
531
553
  "initialized",
532
554
  "resize",
@@ -547,12 +569,24 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
547
569
  if (config.capabilities.annotate !== undefined) {
548
570
  applyAnnotations(display, first);
549
571
  }
572
+ // The followed mark, once the marks are shown; without `annotate`, the core's error.
573
+ following.current = null;
574
+ const wanted = first.trackedAnnotation ?? null;
575
+ asked.current = wanted;
576
+ if (wanted !== null) {
577
+ attempt(() => {
578
+ display.annotations.track(wanted);
579
+ following.current = wanted;
580
+ }, first);
581
+ }
550
582
  if (first.content !== undefined) {
551
583
  display.setContent(first.content, { partial: first.partial === true });
552
584
  }
553
585
  return () => {
554
586
  display.destroy();
555
587
  handle.current = null;
588
+ running(null);
589
+ following.current = null;
556
590
  };
557
591
  // A new display only for a new config, document or instance, or what the provider makes
558
592
  // displays with (its nonce, hostInfo by value, whether it locates or confirms; generation, by
@@ -575,6 +609,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
575
609
  hostInfo,
576
610
  locate,
577
611
  nonce,
612
+ running,
578
613
  ]);
579
614
  useEffect(() => {
580
615
  if (content !== undefined) {
@@ -608,9 +643,34 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
608
643
  useEffect(() => {
609
644
  const display = handle.current;
610
645
  if (annotates && display !== null) {
611
- attempt(() => display.annotations.show(annotations ?? []), latest());
646
+ attempt(() => {
647
+ display.annotations.show(annotations ?? []);
648
+ // A show without the followed mark stops the following (the core's own).
649
+ if (following.current !== null && !shown(annotations, following.current)) {
650
+ following.current = null;
651
+ }
652
+ }, latest());
612
653
  }
613
654
  }, [annotates, annotations]);
655
+ // The followed mark follows its prop (after the marks above, so the two can change together).
656
+ const trackedAnnotation = frame.trackedAnnotation ?? null;
657
+ useEffect(() => {
658
+ const display = handle.current;
659
+ const changed = trackedAnnotation !== asked.current;
660
+ asked.current = trackedAnnotation;
661
+ if (display === null || trackedAnnotation === following.current) {
662
+ return;
663
+ }
664
+ // Its mark was taken off (the error, if any, was told when the prop said it): followed again
665
+ // once the marks have it back.
666
+ if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
667
+ return;
668
+ }
669
+ attempt(() => {
670
+ display.annotations.track(trackedAnnotation);
671
+ following.current = trackedAnnotation;
672
+ }, latest());
673
+ }, [trackedAnnotation, annotations]);
614
674
  useEffect(() => {
615
675
  const display = handle.current;
616
676
  const id = focusOf(latest().focusedAnnotation);
@@ -695,6 +755,10 @@ function useByValue(value) {
695
755
  const key = value === undefined ? "" : JSON.stringify(value);
696
756
  return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
697
757
  }
758
+ /** Whether `marks` has a mark `id`. */
759
+ function shown(marks, id) {
760
+ return (marks ?? []).some((mark) => mark.id === id);
761
+ }
698
762
  /** The id `focusedAnnotation` names, if any. */
699
763
  function focusOf(value) {
700
764
  return typeof value === "string"
@@ -8,7 +8,7 @@
8
8
  * theme={tokensFor} onError={report} />
9
9
  * </PortholeProvider>
10
10
  */
11
- export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameProps, type ConfirmActions, type PortholeProviderProps, } from "./frame.tsx";
11
+ export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameHandle, type PortholeFrameProps, type ConfirmActions, type PortholeProviderProps, } from "./frame.tsx";
12
12
  export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
13
13
  export { ContextNotice, contextSize, contextText, type ContextNoticeProps, type ContextUpdate, } from "./context-notice.tsx";
14
14
  export { cssVariableTheme, PortholeView, usePortholeLink, useRunAgain, type PortholeFallbackProps, type PortholeViewProps, } from "./view.tsx";
@@ -1,7 +1,7 @@
1
1
  import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { useCallback, useContext, useEffect, useState, useSyncExternalStore, } from "react";
2
+ import { useCallback, useContext, useEffect, useImperativeHandle, useRef, useState, useSyncExternalStore, } from "react";
3
3
  import { frameFallback } from "../host/client.js";
4
- import { PortholeFrame, PortholeContext } from "./frame.js";
4
+ import { PortholeFrame, PortholeContext, } from "./frame.js";
5
5
  function useClient() {
6
6
  const client = useContext(PortholeContext).client;
7
7
  if (client === undefined) {
@@ -24,7 +24,13 @@ function DefaultFallback({ title, message, link }) {
24
24
  export function PortholeView(props) {
25
25
  const client = useClient();
26
26
  const meta = useMeta(client);
27
- const { display, instance, content, fallback, pending, onOutcome, ...frame } = props;
27
+ const { display, instance, content, fallback, pending, onOutcome, ref, ...frame } = props;
28
+ // The view's handle (P118) is there while the view is, a fallback drawn or not: its calls reach
29
+ // the frame's display when one runs, and do nothing otherwise.
30
+ const shown = useRef(null);
31
+ useImperativeHandle(ref, () => ({
32
+ clearSelection: () => shown.current?.clearSelection(),
33
+ }), []);
28
34
  const [failed, setFailed] = useState(null);
29
35
  const [generation, setGeneration] = useState(0);
30
36
  const [link, setLink] = useState(null);
@@ -73,7 +79,7 @@ export function PortholeView(props) {
73
79
  if (failed !== null) {
74
80
  return _jsx(_Fragment, { children: (fallback ?? DefaultFallback)({ ...failed, link, retry }) });
75
81
  }
76
- return (_jsx(PortholeFrame, { ...frame, config: config, generation: (frame.generation ?? 0) + generation, ...(instance === undefined ? {} : { instance }), ...(content === undefined ? {} : { content }), onOutcome: (outcome) => {
82
+ return (_jsx(PortholeFrame, { ...frame, ref: shown, config: config, generation: (frame.generation ?? 0) + generation, ...(instance === undefined ? {} : { instance }), ...(content === undefined ? {} : { content }), onOutcome: (outcome) => {
77
83
  onOutcome?.(outcome);
78
84
  const said = frameFallback(outcome, { url });
79
85
  if (said !== null) {
@@ -37,7 +37,7 @@ export { createContentHost, HEALTH_PATH, ISSUE_BODY_BYTES, type ContentHealthVie
37
37
  export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDomainInfo, type ContentDomainProblem, } from "./domain.ts";
38
38
  export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
39
39
  export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
40
- export { NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedShellCsp, nestedShellResponse, } from "./nested.ts";
40
+ export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.ts";
41
41
  export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
42
42
  export { conformancePage } from "../conformance/page.ts";
43
43
  export type { PortholeConfig } from "../config/schema.ts";
@@ -38,9 +38,10 @@ export { clashOf, contentDomain, ContentDomainError, hostnameOf, } from "./domai
38
38
  export { d1TicketSchema, d1TicketStore, memoryTicketStore, } from "./tickets.js";
39
39
  export { FRAME_STATUS_METHOD } from "../isolation/types.js";
40
40
  // A nested page (P111): Porthole's shell at the framed address, the page and its files below the
41
- // sealed prefix. `/server` serves them for a config with `nested`; a content Worker of its own
42
- // answers the same (docs/ADOPTING.md, "Nested pages").
43
- export { NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedShellCsp, nestedShellResponse, } from "./nested.js";
41
+ // sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
42
+ // config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
43
+ // pages").
44
+ export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
44
45
  export { isHostLabel, prefixedName } from "./naming.js";
45
46
  // The page an app serves in conformance test mode (P071).
46
47
  export { conformancePage } from "../conformance/page.js";
@@ -17,6 +17,10 @@ export function prefixedName(prefix) {
17
17
  if (!PREFIX.test(prefix)) {
18
18
  throw new TypeError("A name prefix is a lowercase letter, then letters or digits, then '-' (a-)");
19
19
  }
20
+ // Porthole's own labels (a nested page's shell's, P114) are never a scope's.
21
+ if (prefix === "porthole-") {
22
+ throw new TypeError("The name prefix porthole- is Porthole's own: choose another (a-)");
23
+ }
20
24
  const name = (scope) => {
21
25
  const label = `${prefix}${scope}`;
22
26
  if (!ID.test(scope) || !isHostLabel(label)) {
@@ -5,7 +5,29 @@ import { type FrameShellOptions } from "../shell/frame.ts";
5
5
  * `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
6
6
  * (`nestedAncestors`, `NESTED_FILE_HEADERS`). `/server` serves both for a config with `nested`;
7
7
  * a host serving its own content origin (its own Worker) answers the same.
8
+ *
9
+ * All of it is served on the shell's own label (P114, `nestedLabelOf`), never on the scope's: every
10
+ * other display of the scope runs agent-made content on the scope's origin with
11
+ * `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
12
+ * address.
8
13
  */
14
+ /**
15
+ * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
16
+ * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
17
+ */
18
+ export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
19
+ /**
20
+ * The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
21
+ * base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
22
+ * content label is ever one (a keyed label has no hyphen, a host's is refused the prefix), so
23
+ * nothing but a nested page's shell, its opaque page, that page's files and Porthole's status pages
24
+ * is ever served on it: no other display's content runs there with `allow-same-origin`. Not a
25
+ * secret: anyone who knows the scope's label may work it out. A content Worker of a host's own
26
+ * serves its nested pages on it too.
27
+ */
28
+ export declare function nestedLabelOf(label: string): string;
29
+ /** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
30
+ export declare const isNestedLabel: (label: string) => boolean;
9
31
  /** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
10
32
  export declare const NESTED_FILES_PREFIX = "/__porthole/f/";
11
33
  /**
@@ -24,8 +46,8 @@ export declare function nestedShellResponse(compiled: CompiledConfig, options: F
24
46
  readonly method?: string;
25
47
  }): Response;
26
48
  /**
27
- * Who may frame a nested page and its files' answers: its shell (the content origin) and, above
28
- * it, the host origins (`frame-ancestors` names every ancestor).
49
+ * Who may frame a nested page and its files' answers: its shell (the shell's own origin, P114) and,
50
+ * above it, the host origins (`frame-ancestors` names every ancestor).
29
51
  */
30
52
  export declare const nestedAncestors: (origin: string, frameAncestors: string) => string;
31
53
  /**
@@ -1,12 +1,38 @@
1
1
  import { servedPermissionsPolicy, serializeCsp } from "../compile/policy.js";
2
2
  import { frameShellDocument, frameShellScript } from "../shell/frame.js";
3
3
  import { sha256, utf8 } from "./crypto.js";
4
+ import { base32 } from "./keys.js";
4
5
  /**
5
6
  * A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
6
7
  * `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
7
8
  * (`nestedAncestors`, `NESTED_FILE_HEADERS`). `/server` serves both for a config with `nested`;
8
9
  * a host serving its own content origin (its own Worker) answers the same.
10
+ *
11
+ * All of it is served on the shell's own label (P114, `nestedLabelOf`), never on the scope's: every
12
+ * other display of the scope runs agent-made content on the scope's origin with
13
+ * `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
14
+ * address.
9
15
  */
16
+ /**
17
+ * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
18
+ * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
19
+ */
20
+ export const PORTHOLE_LABEL_PREFIX = "porthole-";
21
+ const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
22
+ /**
23
+ * The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
24
+ * base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
25
+ * content label is ever one (a keyed label has no hyphen, a host's is refused the prefix), so
26
+ * nothing but a nested page's shell, its opaque page, that page's files and Porthole's status pages
27
+ * is ever served on it: no other display's content runs there with `allow-same-origin`. Not a
28
+ * secret: anyone who knows the scope's label may work it out. A content Worker of a host's own
29
+ * serves its nested pages on it too.
30
+ */
31
+ export function nestedLabelOf(label) {
32
+ return `${PORTHOLE_LABEL_PREFIX}${base32(sha256(utf8(`porthole/nested/${label}`)).subarray(0, 15))}`;
33
+ }
34
+ /** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
35
+ export const isNestedLabel = (label) => NESTED_LABEL.test(label);
10
36
  /** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
11
37
  export const NESTED_FILES_PREFIX = "/__porthole/f/";
12
38
  const base64 = (bytes) => btoa(String.fromCharCode(...bytes));
@@ -54,8 +80,8 @@ export function nestedShellResponse(compiled, options) {
54
80
  });
55
81
  }
56
82
  /**
57
- * Who may frame a nested page and its files' answers: its shell (the content origin) and, above
58
- * it, the host origins (`frame-ancestors` names every ancestor).
83
+ * Who may frame a nested page and its files' answers: its shell (the shell's own origin, P114) and,
84
+ * above it, the host origins (`frame-ancestors` names every ancestor).
59
85
  */
60
86
  export const nestedAncestors = (origin, frameAncestors) => `${origin} ${frameAncestors}`;
61
87
  /**