@botiverse/porthole 0.14.4 → 0.14.6

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 (78) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/dist/check/page-source.js +1 -1
  3. package/dist/check/page.js +5 -1
  4. package/dist/compile/policy.d.ts +6 -0
  5. package/dist/compile/policy.js +6 -0
  6. package/dist/conformance/entry.d.ts +25 -6
  7. package/dist/conformance/entry.js +69 -18
  8. package/dist/conformance/harness/page.d.ts +12 -0
  9. package/dist/conformance/harness/page.js +95 -51
  10. package/dist/conformance/harness-source.js +1 -1
  11. package/dist/conformance/host-kit.js +39 -13
  12. package/dist/conformance/served.js +140 -0
  13. package/dist/files/paths.d.ts +2 -2
  14. package/dist/files/paths.js +12 -2
  15. package/dist/host/client.d.ts +8 -0
  16. package/dist/host/client.js +47 -17
  17. package/dist/host/create-host.d.ts +10 -0
  18. package/dist/host/create-host.js +126 -10
  19. package/dist/host/door.d.ts +41 -0
  20. package/dist/host/door.js +55 -0
  21. package/dist/host/locate.js +2 -0
  22. package/dist/host/locator.d.ts +55 -3
  23. package/dist/host/locator.js +152 -42
  24. package/dist/host/outcome.d.ts +58 -1
  25. package/dist/host/outcome.js +74 -6
  26. package/dist/host/types.d.ts +20 -4
  27. package/dist/isolation/served.d.ts +1 -1
  28. package/dist/isolation/served.js +35 -0
  29. package/dist/isolation/types.d.ts +20 -2
  30. package/dist/isolation/types.js +2 -0
  31. package/dist/platform/types.d.ts +22 -0
  32. package/dist/platform/web.js +55 -12
  33. package/dist/react/frame.d.ts +2 -1
  34. package/dist/react/view.d.ts +13 -0
  35. package/dist/react/view.js +101 -2
  36. package/dist/server/files.d.ts +11 -0
  37. package/dist/server/files.js +26 -4
  38. package/dist/server/host.js +106 -28
  39. package/dist/server/index.d.ts +2 -1
  40. package/dist/server/index.js +6 -1
  41. package/dist/server/pages.d.ts +32 -0
  42. package/dist/server/pages.js +82 -6
  43. package/dist/server/server.js +140 -11
  44. package/dist/server/types.d.ts +15 -1
  45. package/dist/transport/post-message.d.ts +1 -9
  46. package/dist/transport/post-message.js +2 -8
  47. package/docs/ADOPTING.md +58 -0
  48. package/docs/DECISIONS.md +290 -0
  49. package/docs/DESIGN.md +24 -16
  50. package/docs/THREAT_MODEL.md +98 -3
  51. package/package.json +1 -1
  52. package/src/check/page.ts +6 -1
  53. package/src/compile/policy.ts +7 -0
  54. package/src/conformance/entry.ts +129 -24
  55. package/src/conformance/harness/page.ts +112 -49
  56. package/src/conformance/host-kit.ts +53 -16
  57. package/src/conformance/served.ts +175 -0
  58. package/src/files/paths.ts +11 -2
  59. package/src/host/client.ts +59 -22
  60. package/src/host/create-host.ts +146 -18
  61. package/src/host/door.ts +97 -0
  62. package/src/host/locate.ts +2 -0
  63. package/src/host/locator.ts +208 -57
  64. package/src/host/outcome.ts +88 -7
  65. package/src/host/types.ts +20 -4
  66. package/src/isolation/served.ts +40 -1
  67. package/src/isolation/types.ts +19 -2
  68. package/src/platform/types.ts +21 -0
  69. package/src/platform/web.ts +55 -20
  70. package/src/react/frame.tsx +2 -1
  71. package/src/react/view.tsx +149 -2
  72. package/src/server/files.ts +37 -5
  73. package/src/server/host.ts +131 -46
  74. package/src/server/index.ts +6 -1
  75. package/src/server/pages.ts +101 -6
  76. package/src/server/server.ts +186 -19
  77. package/src/server/types.ts +16 -1
  78. package/src/transport/post-message.ts +1 -9
@@ -10,6 +10,8 @@ import { capabilitySpec } from "../config/capabilities.js";
10
10
  import { locateServed } from "./locate.js";
11
11
  import { mayPassOn } from "./pass-on.js";
12
12
  import { watchOutcome } from "./outcome.js";
13
+ import { watchDoor } from "./door.js";
14
+ import { outcomeOfRefusal } from "./locator.js";
13
15
  import { STORAGE_USED_METHOD } from "../isolation/types.js";
14
16
  import { webPlatform } from "../platform/web.js";
15
17
  import { TAKES } from "../platform/focus-guard.js";
@@ -22,6 +24,16 @@ import { parseViewer } from "../runtime/levels.js";
22
24
  const DEFAULT_LOAD_TIMEOUT_MS = 15_000;
23
25
  /** How many times a display is started again after its content navigated its frame away. */
24
26
  const MAX_RESTARTS = 3;
27
+ /** What the host is told of a served display located without its door (P125), once a mount. */
28
+ export const NO_DOOR = "A served display needs a door from issue (FrameLocation.door, P125), and this location has none, so no frame was made: upgrade the server (or content Worker) that issues it, and pass the door on from a locator of your own. A clean address is for a tab: to frame what it names, resolve it with client.resolve(address) or <PortholeView address>";
29
+ /**
30
+ * What the host is told when its locator gives a run the location an earlier run had (P125): its
31
+ * tickets were taken by that run, so its door says `blocked: session`. A locator issues anew for
32
+ * every run (a reload, a restart after the content navigated away).
33
+ */
34
+ export const REUSED_LOCATION = "The locator gave this run a location an earlier run of this display already used (P125): its tickets are taken, so its door answers that the link has been used. A locator must issue anew for every run (InstanceLocator.locate is called for each one)";
35
+ /** What the host is told when its platform makes no doors (P125): no served frame is made. */
36
+ export const NO_DOOR_PLATFORM = "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display that isn't nested is framed on it";
25
37
  const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
26
38
  /** The frame's annotation reports, by method. */
27
39
  const REPORTS = {
@@ -48,6 +60,10 @@ export function createHost(config, options = {}) {
48
60
  }
49
61
  // A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
50
62
  const speaks = config.mode !== "url";
63
+ const nested = config.nested === true;
64
+ // A served display on its scope's origin, beside the scope's other content (P125): its door
65
+ // says how loading went, before its frame is made.
66
+ const hasDoor = config.isolation === "domain" && speaks && !nested;
51
67
  const adapter = (options.adapter ?? shellAdapter);
52
68
  const platform = options.platform ?? webPlatform;
53
69
  const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
@@ -88,6 +104,11 @@ export function createHost(config, options = {}) {
88
104
  }
89
105
  const listeners = new Map();
90
106
  const emit = (event, detail) => {
107
+ // An outcome ends a loading episode: the next run (a restart, a reload) gets a clock of
108
+ // its own (P125).
109
+ if (event === "outcome") {
110
+ episodeBegan = null;
111
+ }
91
112
  for (const listener of listeners.get(event) ?? []) {
92
113
  listener(detail);
93
114
  }
@@ -111,6 +132,10 @@ export function createHost(config, options = {}) {
111
132
  let bridge = null;
112
133
  let destroyed = false;
113
134
  let restarts = 0;
135
+ // When the loading episode that has no outcome yet began: its first run, not each restart's
136
+ // (P125). However often a frame is started again (a sibling of its scope wiping or
137
+ // navigating it, P125 S7), the display's time runs out and it has an outcome.
138
+ let episodeBegan = null;
114
139
  let generation = 0;
115
140
  // The viewer's answer for this display (P079): asked once, kept across its frames; or the
116
141
  // host's refusal of them all (P080).
@@ -119,6 +144,10 @@ export function createHost(config, options = {}) {
119
144
  : onceConsent(options.consent);
120
145
  let abort = null;
121
146
  let outcomeWatch = null;
147
+ let door = null;
148
+ // The addresses earlier runs were located at (P125): a ticket opens once, so a run given one
149
+ // again is told to the host (its outcome is the server's word, unchanged).
150
+ const locatedAt = new Set();
122
151
  let themeFrame = null;
123
152
  const view = container.ownerDocument.defaultView;
124
153
  // The adapter's own operations, the last call of each, replayed into every new frame.
@@ -420,6 +449,11 @@ export function createHost(config, options = {}) {
420
449
  return;
421
450
  }
422
451
  };
452
+ const closeDoor = () => {
453
+ door?.watch.stop();
454
+ door?.frame.destroy();
455
+ door = null;
456
+ };
423
457
  const stop = () => {
424
458
  // A run that ran a page with storage of its own making and never heard it used: no (P111).
425
459
  if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
@@ -435,12 +469,48 @@ export function createHost(config, options = {}) {
435
469
  abort = null;
436
470
  outcomeWatch?.stop();
437
471
  outcomeWatch = null;
472
+ closeDoor();
438
473
  connection?.close();
439
474
  connection = null;
440
475
  surface?.destroy();
441
476
  surface = null;
442
477
  };
443
- const start = (source) => {
478
+ const timeoutMs = config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
479
+ /**
480
+ * A served display with a door (P125): its door first, alone, in a frame of the host's own;
481
+ * its frame only once the door said `open`, within what is left of the run's time. A door
482
+ * that said `blocked` (or never ran, or never answered) is the run's outcome, and nothing of
483
+ * the content is framed. A location without a door (an older server, a locator that drops
484
+ * it, a clean address someone framed) is refused before any frame is made: `blocked:
485
+ * locate`, and the host hears why (`door`). Nothing infers a door's word from anything else.
486
+ */
487
+ const enter = (source, timeLeft = timeoutMs) => {
488
+ if (!hasDoor || source.kind !== "url") {
489
+ start(source, timeLeft);
490
+ return;
491
+ }
492
+ if (source.door === undefined || platform.createDoor === undefined) {
493
+ hostError(source.door === undefined ? NO_DOOR : NO_DOOR_PLATFORM, "door");
494
+ emit("outcome", { state: "blocked", reason: "locate" });
495
+ return;
496
+ }
497
+ const began = Date.now();
498
+ const frame = platform.createDoor(container, { url: source.door });
499
+ const watch = watchDoor({
500
+ door: frame,
501
+ timeoutMs: timeLeft,
502
+ onOpen: () => {
503
+ closeDoor();
504
+ start(source, Math.max(0, timeLeft - (Date.now() - began)));
505
+ },
506
+ onOutcome: (outcome) => {
507
+ closeDoor();
508
+ emit("outcome", outcome);
509
+ },
510
+ });
511
+ door = { frame, watch };
512
+ };
513
+ const start = (source, timeLeft) => {
444
514
  const navigatedAway = () => {
445
515
  emit("navigated", undefined);
446
516
  if (restarts < MAX_RESTARTS) {
@@ -450,6 +520,9 @@ export function createHost(config, options = {}) {
450
520
  else {
451
521
  stop();
452
522
  contentError("The content kept navigating its frame away; it was stopped.");
523
+ // Every display ends with an outcome (P125): a frame stopped after its restarts ran out
524
+ // is one the host can draw a fallback for, never an empty box.
525
+ emit("outcome", { state: "blocked", reason: "error" });
453
526
  }
454
527
  };
455
528
  const framed = platform.createSurface(container, {
@@ -512,8 +585,11 @@ export function createHost(config, options = {}) {
512
585
  surface: created,
513
586
  source,
514
587
  speaks,
515
- timeoutMs: config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS,
588
+ nested,
589
+ timeoutMs: timeLeft,
516
590
  onOutcome: (outcome) => emit("outcome", outcome),
591
+ // A frame status from the content (P124): never shown, the host's to hear.
592
+ refused: (message) => hostError(message, "frame-status"),
517
593
  });
518
594
  outcomeWatch = watch;
519
595
  if (!speaks) {
@@ -598,8 +674,13 @@ export function createHost(config, options = {}) {
598
674
  return;
599
675
  }
600
676
  generation += 1;
677
+ if (episodeBegan === null) {
678
+ episodeBegan = Date.now();
679
+ }
680
+ // What is left of this episode's time: a restart doesn't start the clock again.
681
+ const timeLeft = Math.max(0, timeoutMs - (Date.now() - episodeBegan));
601
682
  if (config.isolation === "opaque") {
602
- start({
683
+ enter({
603
684
  kind: "srcdoc",
604
685
  html: compiled.shellDocument({
605
686
  origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
@@ -607,7 +688,7 @@ export function createHost(config, options = {}) {
607
688
  ...nonceOf(options.nonce),
608
689
  ...(mount.document === undefined ? {} : { document: mount.document }),
609
690
  }),
610
- });
691
+ }, timeLeft);
611
692
  return;
612
693
  }
613
694
  const mine = generation;
@@ -619,16 +700,50 @@ export function createHost(config, options = {}) {
619
700
  return;
620
701
  }
621
702
  const hostOrigin = container.ownerDocument.defaultView?.location.origin ?? "";
703
+ // The run's time covers locating too: a backend that never answers is a timeout.
704
+ const began = Date.now();
705
+ let settled = false;
706
+ const late = setTimeout(() => {
707
+ if (!settled && mine === generation && !destroyed) {
708
+ settled = true;
709
+ controller.abort();
710
+ hostError("The host's backend didn't give a location in time", "locate");
711
+ emit("outcome", { state: "timeout" });
712
+ }
713
+ }, timeLeft);
714
+ // A run stopped (destroyed, started again) stops its clock too.
715
+ controller.signal.addEventListener("abort", () => clearTimeout(late), { once: true });
622
716
  locateServed(locator, instance, config, hostOrigin, controller.signal).then((source) => {
623
- if (mine === generation && !destroyed) {
624
- start(source);
717
+ clearTimeout(late);
718
+ if (!settled && mine === generation && !destroyed) {
719
+ settled = true;
720
+ if (source.kind === "url") {
721
+ const seen = [source.url, ...(source.door === undefined ? [] : [source.door])];
722
+ if (seen.some((each) => locatedAt.has(each))) {
723
+ hostError(REUSED_LOCATION, "locate");
724
+ }
725
+ for (const each of seen) {
726
+ locatedAt.add(each);
727
+ }
728
+ }
729
+ enter(source, Math.max(0, timeLeft - (Date.now() - began)));
625
730
  }
626
731
  }, (error) => {
627
- if (mine === generation && !controller.signal.aborted) {
628
- // The host's own failure (its backend down, access gone): never the content's.
629
- hostError(error instanceof Error ? error.message : String(error), "locate");
630
- emit("outcome", { state: "blocked", reason: "locate" });
732
+ clearTimeout(late);
733
+ if (settled || mine !== generation || controller.signal.aborted) {
734
+ return;
735
+ }
736
+ settled = true;
737
+ // The host's own issue endpoint refused (signed out, denied, not found, P125): its
738
+ // word, before any frame, never the content's. Anything else is the host's own failure
739
+ // (its backend down, a network error, a malformed answer): `locate`, never `denied`.
740
+ const refused = outcomeOfRefusal(error);
741
+ if (refused !== null) {
742
+ emit("outcome", refused);
743
+ return;
631
744
  }
745
+ hostError(error instanceof Error ? error.message : String(error), "locate");
746
+ emit("outcome", { state: "blocked", reason: "locate" });
632
747
  });
633
748
  };
634
749
  run();
@@ -668,6 +783,7 @@ export function createHost(config, options = {}) {
668
783
  },
669
784
  reload() {
670
785
  restarts = 0;
786
+ episodeBegan = null;
671
787
  run();
672
788
  },
673
789
  focus() {
@@ -0,0 +1,41 @@
1
+ import type { DoorSurface } from "../platform/types.ts";
2
+ import type { FrameOutcome } from "./types.ts";
3
+ /**
4
+ * A served display's door (P125). A served display that isn't nested (a served shell, a page, a
5
+ * view through the sandbox proxy) is framed on its scope's origin, where the scope's other displays
6
+ * run content with `allow-same-origin`: one of them reaches a new document there before its first
7
+ * script runs, so nothing its frame says, and nothing its silence suggests, is Porthole's word.
8
+ *
9
+ * So before its frame is made, the host frames its door: a page of Porthole's server on the same
10
+ * origin, in a frame of the host's own, hidden, sandboxed with scripts alone (an opaque origin, a
11
+ * new one each time, which no content is the same origin as), with no name (nothing targets it).
12
+ * The server takes the door's own ticket and runs the checks the content's address runs for the
13
+ * same grant (the host's check, the document, its entry), and the door says how loading went, once:
14
+ * `open` (frame the display), or `blocked` and why. The host takes that word only from the door
15
+ * frame's window, from an opaque origin (`"null"`), the first well-formed frame status it says; a
16
+ * door that loaded and said nothing never ran (`framing`: its server didn't let this page frame
17
+ * it). The door's frame is gone once it said, before the display's frame is made.
18
+ *
19
+ * "A `load` event is not a committed document" (DECISIONS P125): a document wiped and navigated
20
+ * while it parses never fires `load`, so no host may read a frame's first load as its first
21
+ * document. The door's "load, then `SETTLE_MS` of silence: framing" doesn't rest on that: no content
22
+ * ever runs in the door (its one script is Porthole's, by its hash, under `default-src 'none'`),
23
+ * so nothing navigates it from inside; and a sibling of its scope, which does get its `WindowProxy`
24
+ * while it loads, can't reach in: reading it throws (it is opaque), setting or replacing its
25
+ * `location` throws (the sibling's own sandbox navigates no frame not its own), and it has no
26
+ * name, so `window.open` and a link's or a form's `target` find nothing. The host hears it from
27
+ * `"null"` alone. `[door-reach]` and the `door-opaque` control hold that.
28
+ */
29
+ export interface DoorWatch {
30
+ stop(): void;
31
+ }
32
+ export declare function watchDoor(options: {
33
+ readonly door: DoorSurface;
34
+ readonly timeoutMs: number;
35
+ /** The door said `open`: the display may be framed. */
36
+ readonly onOpen: () => void;
37
+ /** The door said `blocked`, or loaded and said nothing (`framing`), or nothing came in time. */
38
+ readonly onOutcome: (outcome: Exclude<FrameOutcome, {
39
+ state: "loaded";
40
+ }>) => void;
41
+ }): DoorWatch;
@@ -0,0 +1,55 @@
1
+ import { parseFrameStatus, SETTLE_MS } from "./outcome.js";
2
+ export function watchDoor(options) {
3
+ const { door } = options;
4
+ let decided = false;
5
+ const timers = new Set();
6
+ const later = (ms, run) => {
7
+ const timer = setTimeout(() => {
8
+ timers.delete(timer);
9
+ run();
10
+ }, ms);
11
+ timers.add(timer);
12
+ };
13
+ const stop = () => {
14
+ decided = true;
15
+ for (const timer of timers) {
16
+ clearTimeout(timer);
17
+ }
18
+ timers.clear();
19
+ unlisten();
20
+ unload();
21
+ };
22
+ const unlisten = door.transport.listen((data) => {
23
+ if (decided) {
24
+ return;
25
+ }
26
+ const status = parseFrameStatus(data);
27
+ // A door says `open` or `blocked`, nothing else: anything else is no door's word.
28
+ if (status?.state === "open") {
29
+ stop();
30
+ options.onOpen();
31
+ }
32
+ else if (status?.state === "blocked") {
33
+ stop();
34
+ options.onOutcome({
35
+ state: "blocked",
36
+ reason: status.reason ?? "error",
37
+ ...(status.status === undefined ? {} : { status: status.status }),
38
+ ...(status.code === undefined ? {} : { code: status.code }),
39
+ });
40
+ }
41
+ });
42
+ const unload = door.onLoad(() => later(SETTLE_MS, () => {
43
+ if (!decided) {
44
+ stop();
45
+ options.onOutcome({ state: "blocked", reason: "framing" });
46
+ }
47
+ }));
48
+ later(options.timeoutMs, () => {
49
+ if (!decided) {
50
+ stop();
51
+ options.onOutcome({ state: "timeout" });
52
+ }
53
+ });
54
+ return { stop };
55
+ }
@@ -20,5 +20,7 @@ export async function locateServed(locator, instance, config, hostOrigin, signal
20
20
  origin: location.origin,
21
21
  ...(location.reports === true ? { reports: true } : {}),
22
22
  ...(viewer === null ? {} : { viewer }),
23
+ // Its door (P125), checked with the location: the host frames it before `url`.
24
+ ...(location.door === undefined ? {} : { door: new URL(location.door.url).href }),
23
25
  };
24
26
  }
@@ -1,17 +1,31 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
- import type { InstanceLocator } from "../isolation/types.ts";
2
+ import type { FrameLocation, InstanceLocator, InstanceRef } from "../isolation/types.ts";
3
+ import type { FrameOutcome } from "./types.ts";
3
4
  /**
4
5
  * The client half of the host kit (P066): a locator that asks the app's issue endpoint
5
6
  * (`ContentHost.issue`) for a frame's location, and the choice between served and opaque configs.
6
7
  * The client proposes an instance; the server's mapping decides what it means, and the server
7
8
  * alone chooses the origin.
8
9
  */
9
- /** Why the issue endpoint gave no location: its status and code (`not-served`, `forbidden`, …). */
10
+ /**
11
+ * Why the issue endpoint gave no location: its status and code (`not-served`, `forbidden`, …), and
12
+ * for a refusal the host's own reason code where its answer gave one (`error.reason`, P125).
13
+ */
10
14
  export declare class LocateError extends Error {
11
15
  readonly status: number;
12
16
  readonly code: string;
13
- constructor(message: string, status: number, code: string);
17
+ /** The host's reason code from the issue answer's `error.reason` (a short lowercase token). */
18
+ readonly reason?: string;
19
+ constructor(message: string, status: number, code: string, reason?: string);
14
20
  }
21
+ /**
22
+ * What a display shows when the host's own issue endpoint refused it (P125): the host asked before
23
+ * it built any frame, so this is the host's word, never a frame's. Only a refusal maps (401: sign
24
+ * in, 403: denied, with the host's code if its answer gave one, 404: not found); anything else
25
+ * (5xx, a network failure, a malformed answer) is null, the host's own failure (`locate`), never
26
+ * `denied`.
27
+ */
28
+ export declare function outcomeOfRefusal(error: unknown): FrameOutcome | null;
15
29
  export interface HttpLocatorOptions {
16
30
  /** Headers for each request (an `authorization`), or a function giving them now. */
17
31
  readonly headers?: HeadersInit | (() => HeadersInit);
@@ -21,8 +35,46 @@ export interface HttpLocatorOptions {
21
35
  readonly onNotServed?: () => void;
22
36
  readonly fetch?: typeof fetch;
23
37
  }
38
+ /**
39
+ * A location's door as an issue endpoint answered it (P125): passed on as it came, checked with the
40
+ * location before any frame is made (`checkFrameLocation`); null for none, "bad" for one that
41
+ * isn't `{ url: string }`.
42
+ */
43
+ export declare function doorOf(data: Record<string, unknown>): {
44
+ readonly url: string;
45
+ } | null | "bad";
46
+ /** The refusal an issue endpoint answered: its message, status, code and the host's reason. */
47
+ export declare function refusalOf(response: {
48
+ readonly status: number;
49
+ }, data: unknown): LocateError;
50
+ /** A frame location as an issue endpoint answered it, checked in shape; throws a `LocateError`. */
51
+ export declare function locationOf(status: number, data: unknown): FrameLocation;
24
52
  /** A locator that POSTs `{ instance }` to the app's issue endpoint at `url`. */
25
53
  export declare function httpLocator(url: string, options?: HttpLocatorOptions): InstanceLocator;
54
+ /**
55
+ * What a clean address resolves to (P125): its instance and an issued location for it (a ticket,
56
+ * a door), or the outcome the host's issue endpoint answered instead (signed out, denied, not
57
+ * found), before any frame is built. A clean address is for a tab; a frame shows what it names
58
+ * through `issue`.
59
+ */
60
+ export type Resolved = {
61
+ readonly instance: InstanceRef;
62
+ readonly location: FrameLocation;
63
+ } | {
64
+ readonly outcome: FrameOutcome;
65
+ };
66
+ /**
67
+ * A locator whose first call answers `location` (one a `resolve` got), once, and every later one
68
+ * asks `then` (P125): bound to the one display that resolved it, so no other view of the same
69
+ * instance can take its tickets, and every run after the first issues afresh.
70
+ */
71
+ export declare function oneShot(location: FrameLocation, then: InstanceLocator): InstanceLocator;
72
+ /**
73
+ * Asks the app's issue endpoint at `url` what the clean address `address` names, for this viewer
74
+ * (`{ address }`, P125). A refusal (401, 403, 404) is an outcome; anything else that isn't a
75
+ * location is thrown, the host's own failure.
76
+ */
77
+ export declare function resolveAddress(url: string, address: string, options?: HttpLocatorOptions, signal?: AbortSignal): Promise<Resolved>;
26
78
  /** What the page knows of content (`ContentHost.meta`, as the app's own meta carries it). */
27
79
  export interface ServedMeta {
28
80
  readonly served: boolean;
@@ -5,65 +5,175 @@ import { parseViewer } from "../runtime/levels.js";
5
5
  * The client proposes an instance; the server's mapping decides what it means, and the server
6
6
  * alone chooses the origin.
7
7
  */
8
- /** Why the issue endpoint gave no location: its status and code (`not-served`, `forbidden`, …). */
8
+ /**
9
+ * Why the issue endpoint gave no location: its status and code (`not-served`, `forbidden`, …), and
10
+ * for a refusal the host's own reason code where its answer gave one (`error.reason`, P125).
11
+ */
9
12
  export class LocateError extends Error {
10
13
  status;
11
14
  code;
12
- constructor(message, status, code) {
15
+ /** The host's reason code from the issue answer's `error.reason` (a short lowercase token). */
16
+ reason;
17
+ constructor(message, status, code, reason) {
13
18
  super(message);
14
19
  this.name = "LocateError";
15
20
  this.status = status;
16
21
  this.code = code;
22
+ if (reason !== undefined) {
23
+ this.reason = reason;
24
+ }
25
+ }
26
+ }
27
+ /** A host's reason code, as an outcome's `code` takes it (`FrameOutcome.code`). */
28
+ const REASON_CODE = /^[a-z0-9-]{1,40}$/u;
29
+ /**
30
+ * What a display shows when the host's own issue endpoint refused it (P125): the host asked before
31
+ * it built any frame, so this is the host's word, never a frame's. Only a refusal maps (401: sign
32
+ * in, 403: denied, with the host's code if its answer gave one, 404: not found); anything else
33
+ * (5xx, a network failure, a malformed answer) is null, the host's own failure (`locate`), never
34
+ * `denied`.
35
+ */
36
+ export function outcomeOfRefusal(error) {
37
+ if (!(error instanceof LocateError)) {
38
+ return null;
39
+ }
40
+ const code = error.reason !== undefined && REASON_CODE.test(error.reason) ? { code: error.reason } : {};
41
+ // Only the issue endpoint's own refusal, by its shape (`{ error: { code } }` with the code that
42
+ // goes with its status): a bare 401, 403 or 404 from a router or a firewall in front of it is no
43
+ // answer of the host's, so it stays the host's own failure (`locate`).
44
+ if (error.status === 401 && error.code === "unauthenticated") {
45
+ return { state: "blocked", reason: "sign-in", status: 401 };
46
+ }
47
+ if (error.status === 403 && error.code === "forbidden") {
48
+ return { state: "blocked", reason: "denied", status: 403, ...code };
17
49
  }
50
+ if (error.status === 404 && error.code === "not-found") {
51
+ return { state: "blocked", reason: "not-found", status: 404 };
52
+ }
53
+ return null;
18
54
  }
19
55
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
56
+ /**
57
+ * A location's door as an issue endpoint answered it (P125): passed on as it came, checked with the
58
+ * location before any frame is made (`checkFrameLocation`); null for none, "bad" for one that
59
+ * isn't `{ url: string }`.
60
+ */
61
+ export function doorOf(data) {
62
+ if (data.door === undefined) {
63
+ return null;
64
+ }
65
+ return isRecord(data.door) && typeof data.door.url === "string" ? { url: data.door.url } : "bad";
66
+ }
67
+ /** The refusal an issue endpoint answered: its message, status, code and the host's reason. */
68
+ export function refusalOf(response, data) {
69
+ const error = isRecord(data) && isRecord(data.error) ? data.error : {};
70
+ const code = typeof error.code === "string" ? error.code : "failed";
71
+ const reason = typeof error.reason === "string" && REASON_CODE.test(error.reason) ? error.reason : undefined;
72
+ return new LocateError(typeof error.message === "string"
73
+ ? error.message
74
+ : `The app's issue endpoint answered ${response.status}`, response.status, code, reason);
75
+ }
76
+ /** A frame location as an issue endpoint answered it, checked in shape; throws a `LocateError`. */
77
+ export function locationOf(status, data) {
78
+ if (!isRecord(data) ||
79
+ typeof data.url !== "string" ||
80
+ typeof data.origin !== "string" ||
81
+ (data.reports !== undefined && typeof data.reports !== "boolean")) {
82
+ throw new LocateError("The app's issue endpoint gave no frame location", status, "bad-location");
83
+ }
84
+ // Who is viewing, as the app's access decided (P087); one that doesn't parse is an error.
85
+ const viewer = data.viewer === undefined ? null : parseViewer(data.viewer);
86
+ if (data.viewer !== undefined && viewer === null) {
87
+ throw new LocateError("The app's issue endpoint named a viewer that isn't one", status, "bad-location");
88
+ }
89
+ const door = doorOf(data);
90
+ if (door === "bad") {
91
+ throw new LocateError("The app's issue endpoint named a door that isn't one", status, "bad-location");
92
+ }
93
+ return {
94
+ url: data.url,
95
+ origin: data.origin,
96
+ ...(typeof data.reports === "boolean" ? { reports: data.reports } : {}),
97
+ ...(viewer === null ? {} : { viewer }),
98
+ ...(door === null ? {} : { door }),
99
+ };
100
+ }
101
+ /** POSTs `body` to the app's issue endpoint at `url`: its answer's JSON, or the refusal thrown. */
102
+ async function askIssue(url, body, options, signal) {
103
+ const extra = typeof options.headers === "function" ? options.headers() : options.headers;
104
+ const headers = new Headers(extra);
105
+ headers.set("content-type", "application/json");
106
+ headers.set("accept", "application/json");
107
+ const response = await (options.fetch ?? fetch)(url, {
108
+ method: "POST",
109
+ headers,
110
+ credentials: options.credentials ?? "same-origin",
111
+ redirect: "error",
112
+ body: JSON.stringify(body),
113
+ ...(signal === undefined ? {} : { signal }),
114
+ });
115
+ const data = await response.json().catch(() => null);
116
+ if (!response.ok) {
117
+ const refused = refusalOf(response, data);
118
+ if (refused.code === "not-served") {
119
+ options.onNotServed?.();
120
+ }
121
+ throw refused;
122
+ }
123
+ return { status: response.status, data };
124
+ }
20
125
  /** A locator that POSTs `{ instance }` to the app's issue endpoint at `url`. */
21
126
  export function httpLocator(url, options = {}) {
22
127
  return {
23
128
  async locate(instance, signal) {
24
- const extra = typeof options.headers === "function" ? options.headers() : options.headers;
25
- const headers = new Headers(extra);
26
- headers.set("content-type", "application/json");
27
- headers.set("accept", "application/json");
28
- const response = await (options.fetch ?? fetch)(url, {
29
- method: "POST",
30
- headers,
31
- credentials: options.credentials ?? "same-origin",
32
- redirect: "error",
33
- body: JSON.stringify({ instance }),
34
- ...(signal === undefined ? {} : { signal }),
35
- });
36
- const data = await response.json().catch(() => null);
37
- if (!response.ok) {
38
- const error = isRecord(data) && isRecord(data.error) ? data.error : {};
39
- const code = typeof error.code === "string" ? error.code : "failed";
40
- if (code === "not-served") {
41
- options.onNotServed?.();
42
- }
43
- throw new LocateError(typeof error.message === "string"
44
- ? error.message
45
- : `The app's issue endpoint answered ${response.status}`, response.status, code);
46
- }
47
- if (!isRecord(data) ||
48
- typeof data.url !== "string" ||
49
- typeof data.origin !== "string" ||
50
- (data.reports !== undefined && typeof data.reports !== "boolean")) {
51
- throw new LocateError("The app's issue endpoint gave no frame location", response.status, "bad-location");
52
- }
53
- // Who is viewing, as the app's access decided (P087); one that doesn't parse is an error.
54
- const viewer = data.viewer === undefined ? null : parseViewer(data.viewer);
55
- if (data.viewer !== undefined && viewer === null) {
56
- throw new LocateError("The app's issue endpoint named a viewer that isn't one", response.status, "bad-location");
57
- }
58
- return {
59
- url: data.url,
60
- origin: data.origin,
61
- ...(typeof data.reports === "boolean" ? { reports: data.reports } : {}),
62
- ...(viewer === null ? {} : { viewer }),
63
- };
129
+ const { status, data } = await askIssue(url, { instance }, options, signal);
130
+ return locationOf(status, data);
131
+ },
132
+ };
133
+ }
134
+ /**
135
+ * A locator whose first call answers `location` (one a `resolve` got), once, and every later one
136
+ * asks `then` (P125): bound to the one display that resolved it, so no other view of the same
137
+ * instance can take its tickets, and every run after the first issues afresh.
138
+ */
139
+ export function oneShot(location, then) {
140
+ let first = location;
141
+ return {
142
+ locate(instance, signal) {
143
+ const given = first;
144
+ first = null;
145
+ return given === null ? then.locate(instance, signal) : Promise.resolve(given);
64
146
  },
65
147
  };
66
148
  }
149
+ /** Whether a value is an instance as an issue endpoint gives it back: `{ scope, document }`. */
150
+ const isInstance = (value) => isRecord(value) &&
151
+ typeof value.scope === "string" &&
152
+ isRecord(value.document) &&
153
+ typeof value.document.kind === "string";
154
+ /**
155
+ * Asks the app's issue endpoint at `url` what the clean address `address` names, for this viewer
156
+ * (`{ address }`, P125). A refusal (401, 403, 404) is an outcome; anything else that isn't a
157
+ * location is thrown, the host's own failure.
158
+ */
159
+ export async function resolveAddress(url, address, options = {}, signal) {
160
+ let answer;
161
+ try {
162
+ answer = await askIssue(url, { address }, options, signal);
163
+ }
164
+ catch (error) {
165
+ const outcome = outcomeOfRefusal(error);
166
+ if (outcome !== null) {
167
+ return { outcome };
168
+ }
169
+ throw error;
170
+ }
171
+ const { status, data } = answer;
172
+ if (!isRecord(data) || !isInstance(data.instance)) {
173
+ throw new LocateError("The app's issue endpoint resolved the address to no instance", status, "bad-location");
174
+ }
175
+ return { instance: data.instance, location: locationOf(status, data) };
176
+ }
67
177
  /**
68
178
  * The configs a page's displays run under: served (from the content source) while content is
69
179
  * served, opaque otherwise; null while the page doesn't know yet, so a frame never starts opaque