@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.
- package/CHANGELOG.md +71 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -1
- package/dist/compile/policy.d.ts +6 -0
- package/dist/compile/policy.js +6 -0
- package/dist/conformance/entry.d.ts +25 -6
- package/dist/conformance/entry.js +69 -18
- package/dist/conformance/harness/page.d.ts +12 -0
- package/dist/conformance/harness/page.js +95 -51
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +39 -13
- package/dist/conformance/served.js +140 -0
- package/dist/files/paths.d.ts +2 -2
- package/dist/files/paths.js +12 -2
- package/dist/host/client.d.ts +8 -0
- package/dist/host/client.js +47 -17
- package/dist/host/create-host.d.ts +10 -0
- package/dist/host/create-host.js +126 -10
- package/dist/host/door.d.ts +41 -0
- package/dist/host/door.js +55 -0
- package/dist/host/locate.js +2 -0
- package/dist/host/locator.d.ts +55 -3
- package/dist/host/locator.js +152 -42
- package/dist/host/outcome.d.ts +58 -1
- package/dist/host/outcome.js +74 -6
- package/dist/host/types.d.ts +20 -4
- package/dist/isolation/served.d.ts +1 -1
- package/dist/isolation/served.js +35 -0
- package/dist/isolation/types.d.ts +20 -2
- package/dist/isolation/types.js +2 -0
- package/dist/platform/types.d.ts +22 -0
- package/dist/platform/web.js +55 -12
- package/dist/react/frame.d.ts +2 -1
- package/dist/react/view.d.ts +13 -0
- package/dist/react/view.js +101 -2
- package/dist/server/files.d.ts +11 -0
- package/dist/server/files.js +26 -4
- package/dist/server/host.js +106 -28
- package/dist/server/index.d.ts +2 -1
- package/dist/server/index.js +6 -1
- package/dist/server/pages.d.ts +32 -0
- package/dist/server/pages.js +82 -6
- package/dist/server/server.js +140 -11
- package/dist/server/types.d.ts +15 -1
- package/dist/transport/post-message.d.ts +1 -9
- package/dist/transport/post-message.js +2 -8
- package/docs/ADOPTING.md +58 -0
- package/docs/DECISIONS.md +290 -0
- package/docs/DESIGN.md +24 -16
- package/docs/THREAT_MODEL.md +98 -3
- package/package.json +1 -1
- package/src/check/page.ts +6 -1
- package/src/compile/policy.ts +7 -0
- package/src/conformance/entry.ts +129 -24
- package/src/conformance/harness/page.ts +112 -49
- package/src/conformance/host-kit.ts +53 -16
- package/src/conformance/served.ts +175 -0
- package/src/files/paths.ts +11 -2
- package/src/host/client.ts +59 -22
- package/src/host/create-host.ts +146 -18
- package/src/host/door.ts +97 -0
- package/src/host/locate.ts +2 -0
- package/src/host/locator.ts +208 -57
- package/src/host/outcome.ts +88 -7
- package/src/host/types.ts +20 -4
- package/src/isolation/served.ts +40 -1
- package/src/isolation/types.ts +19 -2
- package/src/platform/types.ts +21 -0
- package/src/platform/web.ts +55 -20
- package/src/react/frame.tsx +2 -1
- package/src/react/view.tsx +149 -2
- package/src/server/files.ts +37 -5
- package/src/server/host.ts +131 -46
- package/src/server/index.ts +6 -1
- package/src/server/pages.ts +101 -6
- package/src/server/server.ts +186 -19
- package/src/server/types.ts +16 -1
- package/src/transport/post-message.ts +1 -9
package/dist/host/create-host.js
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
624
|
-
|
|
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
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
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
|
+
}
|
package/dist/host/locate.js
CHANGED
|
@@ -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
|
}
|
package/dist/host/locator.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
|
|
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;
|
package/dist/host/locator.js
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
|
|
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
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|