@botiverse/porthole 0.14.5 → 0.14.7
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 +66 -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 +148 -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 +124 -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 +54 -1
- package/dist/host/outcome.js +33 -8
- package/dist/host/types.d.ts +10 -2
- 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/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 +7 -1
- package/dist/server/pages.d.ts +32 -0
- package/dist/server/pages.js +82 -6
- package/dist/server/server.js +194 -16
- package/dist/server/types.d.ts +38 -1
- package/dist/transport/post-message.d.ts +1 -9
- package/dist/transport/post-message.js +2 -8
- package/docs/ADOPTING.md +73 -4
- package/docs/DECISIONS.md +245 -0
- package/docs/DESIGN.md +24 -18
- package/docs/THREAT_MODEL.md +79 -13
- 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 +184 -0
- package/src/files/paths.ts +11 -2
- package/src/host/client.ts +59 -22
- package/src/host/create-host.ts +144 -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 +41 -9
- package/src/host/types.ts +10 -2
- 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/view.tsx +149 -2
- package/src/server/files.ts +37 -5
- package/src/server/host.ts +131 -46
- package/src/server/index.ts +7 -1
- package/src/server/pages.ts +101 -6
- package/src/server/server.ts +266 -32
- package/src/server/types.ts +41 -1
- package/src/transport/post-message.ts +1 -9
package/dist/host/outcome.d.ts
CHANGED
|
@@ -1,8 +1,55 @@
|
|
|
1
1
|
import { type FrameSource } from "../isolation/types.ts";
|
|
2
2
|
import type { Surface } from "../platform/types.ts";
|
|
3
3
|
import type { FrameBlock, FrameOutcome } from "./types.ts";
|
|
4
|
+
/**
|
|
5
|
+
* How a display's first document went (P040). A frame's content is another origin's, so the host
|
|
6
|
+
* can't look inside; it goes by what it can see:
|
|
7
|
+
*
|
|
8
|
+
* - a shell or view that speaks for itself is loaded when it finishes its handshake;
|
|
9
|
+
* - a page of Porthole's `/server` says how it went (`porthole/notifications/frame-status`): it is
|
|
10
|
+
* entering an app, or blocked (its ticket used, no cookie kept in a frame, the app down); a url
|
|
11
|
+
* app is loaded when its document loads after the entry page;
|
|
12
|
+
* - a load from which nothing ever spoke, where something should have, is a page that never ran:
|
|
13
|
+
* framing refused;
|
|
14
|
+
* - an app from a host's own gateway is loaded on its first load, unless its page says it is
|
|
15
|
+
* blocked (the gateway may send the same message);
|
|
16
|
+
* - nothing settled in `timeoutMs`: a timeout.
|
|
17
|
+
*
|
|
18
|
+
* Who may say how loading went (P124). A frame status is taken only from a document of Porthole's
|
|
19
|
+
* server, a host's gateway or the host's own pages, never from content: its words draw the host's
|
|
20
|
+
* fallback, in Porthole's wording, with a link. Nothing in a message tells who sent it (a page
|
|
21
|
+
* that shares the frame's window and origin can send the same bytes), so the host goes by what
|
|
22
|
+
* content can't change: where the frame's documents come from, and in what order they speak.
|
|
23
|
+
*
|
|
24
|
+
* - An opaque frame's only document is the host's own shell, with the content in it: no page of
|
|
25
|
+
* Porthole's server ever loads there, so its every frame status is the content's.
|
|
26
|
+
* - A frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell)
|
|
27
|
+
* says Porthole's own word first in every document that holds content, before any of the
|
|
28
|
+
* content's code runs: the shell's hello, the proxy's ready (a nested page's own runtime's hello
|
|
29
|
+
* reaches the host before anything its page says, through its shell). A status page says
|
|
30
|
+
* nothing but its frame status. So a frame status is taken only before anything else was heard
|
|
31
|
+
* from the frame in this run: from its first document, which then was a page of Porthole's.
|
|
32
|
+
* After that, it came from the content (or from a later document, which in a display without
|
|
33
|
+
* files starts the display again, whose first document then says how it went).
|
|
34
|
+
* That holds against the display's own content, not against another display's (P125): a
|
|
35
|
+
* scope's displays share its origin, and one that runs reaches a new document of another's
|
|
36
|
+
* before that document's first script, where it can speak first, or stop or rewrite it so it
|
|
37
|
+
* says nothing. So the rule holds only where no content runs on the frame's origin: a nested
|
|
38
|
+
* page's shell, on a label of its own (P114).
|
|
39
|
+
* - A served display that isn't nested (a served shell, a page, a view through the sandbox proxy)
|
|
40
|
+
* takes no frame status from its frame at all, and infers nothing from its silence (a load and
|
|
41
|
+
* no word is a timeout, never `framing`): its door said how loading went before the frame was
|
|
42
|
+
* made (P125, `watchDoor`), from an opaque frame of the host's that no content can reach.
|
|
43
|
+
* - A url-mode app has no shell to speak first, and shares its origin with the entry page and the
|
|
44
|
+
* status pages: its frame status is taken as before, the app's word (THREAT_MODEL S6).
|
|
45
|
+
*
|
|
46
|
+
* A frame status not taken is dropped, and told once a run to the host (`refused`).
|
|
47
|
+
*/
|
|
48
|
+
/** How long after a load the frame's word may still arrive. */
|
|
49
|
+
export declare const SETTLE_MS = 400;
|
|
4
50
|
interface FrameStatus {
|
|
5
|
-
|
|
51
|
+
/** `open` is a door's word alone (P125): its display may be framed. */
|
|
52
|
+
readonly state: "entering" | "open" | "blocked";
|
|
6
53
|
readonly reason?: FrameBlock;
|
|
7
54
|
readonly status?: number;
|
|
8
55
|
readonly code?: string;
|
|
@@ -21,6 +68,12 @@ export declare function watchOutcome(options: {
|
|
|
21
68
|
readonly source: FrameSource;
|
|
22
69
|
/** Whether the frame speaks for itself (a shell or a view): then its handshake is the proof. */
|
|
23
70
|
readonly speaks: boolean;
|
|
71
|
+
/**
|
|
72
|
+
* The config nests its pages (P111): the frame holds Porthole's shell, on a label no content
|
|
73
|
+
* runs on, whose first word may be a frame status. Any other served frame that speaks takes
|
|
74
|
+
* none: its door told (P125).
|
|
75
|
+
*/
|
|
76
|
+
readonly nested?: boolean;
|
|
24
77
|
readonly timeoutMs: number;
|
|
25
78
|
readonly onOutcome: (outcome: FrameOutcome) => void;
|
|
26
79
|
/** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
|
package/dist/host/outcome.js
CHANGED
|
@@ -29,13 +29,22 @@ import { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
|
29
29
|
* from the frame in this run: from its first document, which then was a page of Porthole's.
|
|
30
30
|
* After that, it came from the content (or from a later document, which in a display without
|
|
31
31
|
* files starts the display again, whose first document then says how it went).
|
|
32
|
+
* That holds against the display's own content, not against another display's (P125): a
|
|
33
|
+
* scope's displays share its origin, and one that runs reaches a new document of another's
|
|
34
|
+
* before that document's first script, where it can speak first, or stop or rewrite it so it
|
|
35
|
+
* says nothing. So the rule holds only where no content runs on the frame's origin: a nested
|
|
36
|
+
* page's shell, on a label of its own (P114).
|
|
37
|
+
* - A served display that isn't nested (a served shell, a page, a view through the sandbox proxy)
|
|
38
|
+
* takes no frame status from its frame at all, and infers nothing from its silence (a load and
|
|
39
|
+
* no word is a timeout, never `framing`): its door said how loading went before the frame was
|
|
40
|
+
* made (P125, `watchDoor`), from an opaque frame of the host's that no content can reach.
|
|
32
41
|
* - A url-mode app has no shell to speak first, and shares its origin with the entry page and the
|
|
33
42
|
* status pages: its frame status is taken as before, the app's word (THREAT_MODEL S6).
|
|
34
43
|
*
|
|
35
44
|
* A frame status not taken is dropped, and told once a run to the host (`refused`).
|
|
36
45
|
*/
|
|
37
46
|
/** How long after a load the frame's word may still arrive. */
|
|
38
|
-
const SETTLE_MS = 400;
|
|
47
|
+
export const SETTLE_MS = 400;
|
|
39
48
|
const BLOCKS = [
|
|
40
49
|
"framing",
|
|
41
50
|
"cookies",
|
|
@@ -59,8 +68,8 @@ export function parseFrameStatus(data) {
|
|
|
59
68
|
if (params === null || typeof params !== "object") {
|
|
60
69
|
return null;
|
|
61
70
|
}
|
|
62
|
-
if (params.state === "entering") {
|
|
63
|
-
return { state:
|
|
71
|
+
if (params.state === "entering" || params.state === "open") {
|
|
72
|
+
return { state: params.state };
|
|
64
73
|
}
|
|
65
74
|
if (params.state !== "blocked") {
|
|
66
75
|
return null;
|
|
@@ -87,6 +96,7 @@ const namesFrameStatus = (data) => data !== null &&
|
|
|
87
96
|
export const UNTRUSTED_FRAME_STATUS = "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
|
|
88
97
|
export function watchOutcome(options) {
|
|
89
98
|
const { surface, source, speaks } = options;
|
|
99
|
+
const nested = options.nested === true;
|
|
90
100
|
const reports = source.kind === "url" && source.reports === true;
|
|
91
101
|
// The first outcome; after a load, only a later block (a status page, access revoked) is told.
|
|
92
102
|
let decided = null;
|
|
@@ -126,8 +136,8 @@ export function watchOutcome(options) {
|
|
|
126
136
|
options.onOutcome(outcome);
|
|
127
137
|
}
|
|
128
138
|
};
|
|
129
|
-
// Whether a frame status may be the word of a page of Porthole's (P124, above).
|
|
130
|
-
const mayBePorthole = () => source.kind === "url" && (!speaks || !spoke);
|
|
139
|
+
// Whether a frame status may be the word of a page of Porthole's (P124, P125, above).
|
|
140
|
+
const mayBePorthole = () => source.kind === "url" && (!speaks || (nested && !spoke));
|
|
131
141
|
const unlisten = surface.transport.listen((data) => {
|
|
132
142
|
heard = true;
|
|
133
143
|
if (!namesFrameStatus(data)) {
|
|
@@ -142,6 +152,7 @@ export function watchOutcome(options) {
|
|
|
142
152
|
return;
|
|
143
153
|
}
|
|
144
154
|
const status = parseFrameStatus(data);
|
|
155
|
+
// `open` is a door's word (P125), never a frame's: nothing here.
|
|
145
156
|
if (status?.state === "entering") {
|
|
146
157
|
entering = true;
|
|
147
158
|
}
|
|
@@ -159,16 +170,30 @@ export function watchOutcome(options) {
|
|
|
159
170
|
decide({ state: "blocked", reason: "framing" });
|
|
160
171
|
}
|
|
161
172
|
});
|
|
173
|
+
// A served frame whose door told (P125): a load from which nothing spoke shows nothing, and
|
|
174
|
+
// no one can say why (another display of its scope may have stopped or rewritten it): a timeout,
|
|
175
|
+
// without waiting the whole of it, never `framing`.
|
|
176
|
+
const silent = () => later(SETTLE_MS, () => {
|
|
177
|
+
if (!spoke) {
|
|
178
|
+
decide({ state: "timeout" });
|
|
179
|
+
}
|
|
180
|
+
});
|
|
162
181
|
const unload = surface.onLoad(() => {
|
|
163
182
|
loads += 1;
|
|
164
183
|
if (decided !== null) {
|
|
165
184
|
return;
|
|
166
185
|
}
|
|
167
186
|
if (speaks) {
|
|
168
|
-
// A served shell or view says something before its first load ends;
|
|
169
|
-
// never ran.
|
|
187
|
+
// A served shell or view says something before its first load ends; a nested page's shell
|
|
188
|
+
// that never did never ran. Any other served frame's silence tells nothing (P125). (An
|
|
189
|
+
// opaque srcdoc frame always runs: its handshake decides.)
|
|
170
190
|
if (source.kind === "url") {
|
|
171
|
-
|
|
191
|
+
if (nested) {
|
|
192
|
+
neverRan();
|
|
193
|
+
}
|
|
194
|
+
else {
|
|
195
|
+
silent();
|
|
196
|
+
}
|
|
172
197
|
}
|
|
173
198
|
return;
|
|
174
199
|
}
|
package/dist/host/types.d.ts
CHANGED
|
@@ -121,9 +121,17 @@ export type HostErrorKind =
|
|
|
121
121
|
/**
|
|
122
122
|
* A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
|
|
123
123
|
* from the frame's content, not from a page of Porthole's server (P124): never shown, never an
|
|
124
|
-
* outcome. Told once a run.
|
|
124
|
+
* outcome. Told once a run. A served display that isn't nested takes none from its frame at
|
|
125
|
+
* all: its door says how loading went (P125).
|
|
125
126
|
*/
|
|
126
|
-
| "frame-status"
|
|
127
|
+
| "frame-status"
|
|
128
|
+
/**
|
|
129
|
+
* A served display that has a door (P125: a served shell, a page that isn't nested, the sandbox
|
|
130
|
+
* proxy) was located without one: the server is older than the host (upgrade it first), or a
|
|
131
|
+
* locator dropped `FrameLocation.door`. The display shows, but no frame status is taken, so a
|
|
132
|
+
* block is told as a timeout. Told once a mount.
|
|
133
|
+
*/
|
|
134
|
+
| "door";
|
|
127
135
|
/** What a display reports, by event name. */
|
|
128
136
|
/** Why a display's frame showed nothing of its content (`FrameOutcome`). */
|
|
129
137
|
export type FrameBlock =
|
package/dist/isolation/served.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { DOOR_PATH } from "./types.js";
|
|
1
2
|
/**
|
|
2
3
|
* Checks for served frames (domain and external isolation), shared by the host's mount and by
|
|
3
4
|
* `/server`: a served origin must be one the config names, and never of the host's own site
|
|
@@ -135,11 +136,45 @@ nested = false) {
|
|
|
135
136
|
if (nested && !onNestedLabel(location.origin)) {
|
|
136
137
|
throw new TypeError(`The located origin ${location.origin} isn't a nested page's own: its shell is served on a label of its own alone (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf(label), P114), never beside other content`);
|
|
137
138
|
}
|
|
139
|
+
if (location.door !== undefined) {
|
|
140
|
+
checkDoor(location.door, location.origin, nested);
|
|
141
|
+
}
|
|
138
142
|
const host = parseOrigin(hostOrigin);
|
|
139
143
|
if (host !== null && maybeSameSite(origin.host, host.host)) {
|
|
140
144
|
throw new TypeError(`The located origin ${location.origin} may be the same site as the host (${hostOrigin}): content must be served from a registrable domain the host uses for nothing else`);
|
|
141
145
|
}
|
|
142
146
|
}
|
|
147
|
+
/**
|
|
148
|
+
* A location's door (P125): on the location's own origin, at Porthole's door path, never for a
|
|
149
|
+
* nested page (its shell's label serves no door: its first document is Porthole's own, P114).
|
|
150
|
+
* Named by its origin only in what is thrown: the door's address carries a ticket.
|
|
151
|
+
*/
|
|
152
|
+
function checkDoor(door, origin, nested) {
|
|
153
|
+
const url = door !== null && typeof door === "object" ? door.url : undefined;
|
|
154
|
+
if (typeof url !== "string") {
|
|
155
|
+
throw new TypeError("The located door is not { url }");
|
|
156
|
+
}
|
|
157
|
+
if (nested) {
|
|
158
|
+
throw new TypeError("A nested page is located with no door: its shell is Porthole's own first document (P125)");
|
|
159
|
+
}
|
|
160
|
+
let parsed;
|
|
161
|
+
try {
|
|
162
|
+
parsed = new URL(url);
|
|
163
|
+
}
|
|
164
|
+
catch {
|
|
165
|
+
throw new TypeError("The located door is not a URL");
|
|
166
|
+
}
|
|
167
|
+
// The load-bearing check (P125): the door is on the display's own origin, the one its issue
|
|
168
|
+
// located. Its path is pinned below too, for now; a later relaxation of the path (a content
|
|
169
|
+
// Worker's own door route) must keep this check as it is, apart from the path's.
|
|
170
|
+
if (parsed.origin !== origin) {
|
|
171
|
+
throw new TypeError(`The located door is not on its location's origin ${JSON.stringify(origin)} (it is on ${JSON.stringify(safeOrigin(url))})`);
|
|
172
|
+
}
|
|
173
|
+
// Porthole's door route (P125): pinned for now, not what makes the door the display's.
|
|
174
|
+
if (!parsed.pathname.startsWith(DOOR_PATH) || parsed.hash !== "") {
|
|
175
|
+
throw new TypeError(`The located door is not at ${DOOR_PATH}<key> on its origin`);
|
|
176
|
+
}
|
|
177
|
+
}
|
|
143
178
|
/** A URL's origin, for a message: never its path or query (a ticket). */
|
|
144
179
|
function safeOrigin(url) {
|
|
145
180
|
try {
|
|
@@ -76,7 +76,22 @@ export interface FrameLocation {
|
|
|
76
76
|
* the display's bridge checks each runtime method's level against it.
|
|
77
77
|
*/
|
|
78
78
|
readonly viewer?: ViewerInfo;
|
|
79
|
+
/**
|
|
80
|
+
* The display's door (P125): a page of Porthole's on the same origin, at
|
|
81
|
+
* `/__porthole/door/<instance key>?ticket=<its own ticket>`, that says how loading went before
|
|
82
|
+
* any content is framed. The host frames it opaque and hidden, and takes its one frame status
|
|
83
|
+
* (`open`, or `blocked` and why); then frames `url`. Given for a served shell, a page that isn't
|
|
84
|
+
* nested and the sandbox proxy: content of the scope runs on their origin, so no frame status
|
|
85
|
+
* from their own frame is ever Porthole's. A host that is given none for one of them takes no
|
|
86
|
+
* frame status at all (a load that shows nothing is a timeout) and says so (`hostError` kind
|
|
87
|
+
* `door`). A custom locator passes it on as it came.
|
|
88
|
+
*/
|
|
89
|
+
readonly door?: {
|
|
90
|
+
readonly url: string;
|
|
91
|
+
};
|
|
79
92
|
}
|
|
93
|
+
/** Where a served display's door is (P125): `<origin>/__porthole/door/<instance key>`. */
|
|
94
|
+
export declare const DOOR_PATH = "/__porthole/door/";
|
|
80
95
|
/** The message a served page sends its host about loading (own-prefixed, P040). */
|
|
81
96
|
export declare const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
|
|
82
97
|
/** A nested page's shell's report of its own state to the host (P111). */
|
|
@@ -94,8 +109,9 @@ export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
|
94
109
|
export declare const STORAGE_USED_METHOD = "porthole/storage-used";
|
|
95
110
|
/**
|
|
96
111
|
* Turns an instance into the URL its frame loads. Implemented by the host, usually by asking its
|
|
97
|
-
* own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called
|
|
98
|
-
* mount
|
|
112
|
+
* own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called for every
|
|
113
|
+
* run (a mount, a reload, a restart after the content navigated away): answer each with a fresh
|
|
114
|
+
* issue, since a ticket and a door ticket are each good once (P125).
|
|
99
115
|
*/
|
|
100
116
|
export interface InstanceLocator {
|
|
101
117
|
locate(instance: InstanceRef, signal?: AbortSignal): Promise<FrameLocation>;
|
|
@@ -114,4 +130,6 @@ export type FrameSource = {
|
|
|
114
130
|
readonly reports?: boolean;
|
|
115
131
|
/** The issue's viewer (`FrameLocation.viewer`), for the display's bridge. */
|
|
116
132
|
readonly viewer?: ViewerInfo;
|
|
133
|
+
/** The display's door (`FrameLocation.door`, P125): framed before `url`. */
|
|
134
|
+
readonly door?: string;
|
|
117
135
|
};
|
package/dist/isolation/types.js
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
/** Where a served display's door is (P125): `<origin>/__porthole/door/<instance key>`. */
|
|
2
|
+
export const DOOR_PATH = "/__porthole/door/";
|
|
1
3
|
/** The message a served page sends its host about loading (own-prefixed, P040). */
|
|
2
4
|
export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
|
|
3
5
|
/** A nested page's shell's report of its own state to the host (P111). */
|
package/dist/platform/types.d.ts
CHANGED
|
@@ -80,8 +80,30 @@ export interface Surface {
|
|
|
80
80
|
onLoad(listener: () => void): () => void;
|
|
81
81
|
destroy(): void;
|
|
82
82
|
}
|
|
83
|
+
/**
|
|
84
|
+
* A served display's door (P125): a hidden frame of the host's own at the door's address,
|
|
85
|
+
* sandboxed with scripts alone (an opaque origin no content shares), with no `allow`, no name, out
|
|
86
|
+
* of focus and of the accessibility tree. Its one frame status is heard from its window and the
|
|
87
|
+
* opaque origin (`"null"`) alone.
|
|
88
|
+
*/
|
|
89
|
+
export interface DoorSurface {
|
|
90
|
+
readonly transport: Transport;
|
|
91
|
+
/** The platform's own element for the door (an `HTMLIFrameElement` on the web). */
|
|
92
|
+
readonly element: unknown;
|
|
93
|
+
/** Every load of the door's document. */
|
|
94
|
+
onLoad(listener: () => void): () => void;
|
|
95
|
+
destroy(): void;
|
|
96
|
+
}
|
|
83
97
|
export interface PlatformHost<Container = HTMLElement> {
|
|
84
98
|
readonly name: string;
|
|
85
99
|
/** Creates an isolated frame in `container`, its policy set before its document loads. */
|
|
86
100
|
createSurface(container: Container, spec: SurfaceSpec): Surface;
|
|
101
|
+
/**
|
|
102
|
+
* Creates a served display's door in `container` (P125), loading `url`. A platform without one
|
|
103
|
+
* shows served displays that have a door without it: no frame status is taken from them, and
|
|
104
|
+
* the host hears a `door` host error.
|
|
105
|
+
*/
|
|
106
|
+
createDoor?(container: Container, spec: {
|
|
107
|
+
readonly url: string;
|
|
108
|
+
}): DoorSurface;
|
|
87
109
|
}
|
package/dist/platform/web.js
CHANGED
|
@@ -1,11 +1,7 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { DOOR_SANDBOX_TOKENS } from "../compile/policy.js";
|
|
2
|
+
import { SHELL_BEAT_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
|
|
2
3
|
import { postMessageTransport } from "../transport/post-message.js";
|
|
3
4
|
import { focusGuard } from "./focus-guard.js";
|
|
4
|
-
/** A frame-status message (`porthole/notifications/frame-status`), by its method alone. */
|
|
5
|
-
const isFrameStatus = (data) => data !== null &&
|
|
6
|
-
typeof data === "object" &&
|
|
7
|
-
data.jsonrpc === "2.0" &&
|
|
8
|
-
data.method === FRAME_STATUS_METHOD;
|
|
9
5
|
/** A shell's own message (P111), by its namespace. */
|
|
10
6
|
const isShellWord = (data) => data !== null &&
|
|
11
7
|
typeof data === "object" &&
|
|
@@ -120,12 +116,10 @@ export const webPlatform = {
|
|
|
120
116
|
const guard = focusGuard(view);
|
|
121
117
|
const taken = new Set();
|
|
122
118
|
const nested = spec.nested === true && spec.source.kind === "url";
|
|
123
|
-
// A
|
|
124
|
-
//
|
|
125
|
-
|
|
126
|
-
const opened = postMessageTransport(() => frame.contentWindow, origin, view
|
|
127
|
-
? undefined
|
|
128
|
-
: { origin: own, accept: isFrameStatus });
|
|
119
|
+
// A frame is heard from its own window and its located origin alone: never the host's own
|
|
120
|
+
// origin (P125 removed P068's in-frame pages and the channel that heard them), so no page of
|
|
121
|
+
// the host's own can speak for a frame either.
|
|
122
|
+
const opened = postMessageTransport(() => frame.contentWindow, origin, view);
|
|
129
123
|
const unguard = guard.add(frame, (take) => {
|
|
130
124
|
for (const listener of taken) {
|
|
131
125
|
listener(take);
|
|
@@ -194,4 +188,53 @@ export const webPlatform = {
|
|
|
194
188
|
},
|
|
195
189
|
};
|
|
196
190
|
},
|
|
191
|
+
/**
|
|
192
|
+
* A served display's door (P125): hidden (no size, `visibility: hidden`, which still runs its
|
|
193
|
+
* script and fires its load on all three engines), out of focus and of the accessibility tree,
|
|
194
|
+
* sandboxed with scripts alone, no `allow`, no name. Nothing but its frame status is heard from
|
|
195
|
+
* it, from its window and the opaque origin alone; the focus guard, the bridge and annotations
|
|
196
|
+
* never see it.
|
|
197
|
+
*/
|
|
198
|
+
createDoor(container, spec) {
|
|
199
|
+
// oxlint-disable-next-line react/iframe-missing-sandbox -- set from the door's list, next
|
|
200
|
+
const frame = container.ownerDocument.createElement("iframe");
|
|
201
|
+
frame.setAttribute("sandbox", DOOR_SANDBOX_TOKENS.join(" "));
|
|
202
|
+
frame.setAttribute("allow", "");
|
|
203
|
+
frame.setAttribute("referrerpolicy", "no-referrer");
|
|
204
|
+
frame.setAttribute("aria-hidden", "true");
|
|
205
|
+
frame.setAttribute("tabindex", "-1");
|
|
206
|
+
frame.setAttribute("inert", "");
|
|
207
|
+
frame.setAttribute("loading", "eager");
|
|
208
|
+
frame.dataset.portholeDoor = "";
|
|
209
|
+
Object.assign(frame.style, {
|
|
210
|
+
display: "block",
|
|
211
|
+
width: "0",
|
|
212
|
+
height: "0",
|
|
213
|
+
border: "0",
|
|
214
|
+
visibility: "hidden",
|
|
215
|
+
});
|
|
216
|
+
frame.src = spec.url;
|
|
217
|
+
const loaded = new Set();
|
|
218
|
+
frame.addEventListener("load", () => {
|
|
219
|
+
for (const listener of loaded) {
|
|
220
|
+
listener();
|
|
221
|
+
}
|
|
222
|
+
});
|
|
223
|
+
container.append(frame);
|
|
224
|
+
const view = container.ownerDocument.defaultView ?? window;
|
|
225
|
+
const transport = postMessageTransport(() => frame.contentWindow, "null", view);
|
|
226
|
+
return {
|
|
227
|
+
transport,
|
|
228
|
+
element: frame,
|
|
229
|
+
onLoad(listener) {
|
|
230
|
+
loaded.add(listener);
|
|
231
|
+
return () => loaded.delete(listener);
|
|
232
|
+
},
|
|
233
|
+
destroy() {
|
|
234
|
+
loaded.clear();
|
|
235
|
+
transport.close();
|
|
236
|
+
frame.remove();
|
|
237
|
+
},
|
|
238
|
+
};
|
|
239
|
+
},
|
|
197
240
|
};
|
package/dist/react/view.d.ts
CHANGED
|
@@ -27,6 +27,13 @@ export interface PortholeViewProps extends Omit<PortholeFrameProps, "config" | "
|
|
|
27
27
|
* back in its confirmations only, never sent to the frame (P077).
|
|
28
28
|
*/
|
|
29
29
|
readonly instance?: InstanceRef;
|
|
30
|
+
/**
|
|
31
|
+
* A clean address to show instead of an instance (P125): resolved through the client
|
|
32
|
+
* (`client.resolve`) before any frame. What it names is framed through its issued location (a
|
|
33
|
+
* door, a ticket); signed out, denied or not found, the fallback is drawn from that answer, and
|
|
34
|
+
* no frame is made. A clean address is never framed itself.
|
|
35
|
+
*/
|
|
36
|
+
readonly address?: string;
|
|
30
37
|
/**
|
|
31
38
|
* The content: a served shell's to draw, and what an opaque frame shows while frames aren't
|
|
32
39
|
* served (a stored page's HTML). Without it, a served-only display shows the fallback then.
|
|
@@ -38,6 +45,12 @@ export interface PortholeViewProps extends Omit<PortholeFrameProps, "config" | "
|
|
|
38
45
|
readonly pending?: ReactNode;
|
|
39
46
|
}
|
|
40
47
|
export declare function PortholeView(props: PortholeViewProps): ReactElement | null;
|
|
48
|
+
/**
|
|
49
|
+
* Whether `address` may be offered as a fallback's "open in a new tab": a clean address on the
|
|
50
|
+
* served content domain (`contentSource`, its scheme and port), not Porthole's own paths. Anything
|
|
51
|
+
* else (another site, a typo the server answered 404 for elsewhere) gets no link.
|
|
52
|
+
*/
|
|
53
|
+
export declare function tabLinkOf(address: string, contentSource: string | null | undefined): string | null;
|
|
41
54
|
/** An instance's clean address, and its "open in a new tab" and "copy link" (P072). */
|
|
42
55
|
export declare function usePortholeLink(instance: InstanceRef | null): {
|
|
43
56
|
readonly link: string | null;
|
package/dist/react/view.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
-
import { useCallback, useContext, useEffect, useImperativeHandle, useRef, useState, useSyncExternalStore, } from "react";
|
|
2
|
+
import { useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState, useSyncExternalStore, } from "react";
|
|
3
3
|
import { frameFallback } from "../host/client.js";
|
|
4
|
+
import { oneShot } from "../host/locator.js";
|
|
5
|
+
import { originMatchesSource } from "../isolation/served.js";
|
|
4
6
|
import { PortholeFrame, PortholeContext, } from "./frame.js";
|
|
5
7
|
function useClient() {
|
|
6
8
|
const client = useContext(PortholeContext).client;
|
|
@@ -22,9 +24,106 @@ function DefaultFallback({ title, message, link }) {
|
|
|
22
24
|
return (_jsxs("div", { "data-porthole-fallback": "", role: "status", style: { padding: 16 }, children: [_jsx("strong", { children: title }), " ", _jsx("span", { children: message }), " ", link === null ? null : (_jsx("a", { href: link, target: "_blank", rel: "noopener", children: "Open in a new tab" }))] }));
|
|
23
25
|
}
|
|
24
26
|
export function PortholeView(props) {
|
|
27
|
+
return props.address !== undefined && props.instance === undefined ? (_jsx(AddressView, { ...props, address: props.address })) : (_jsx(InstanceView, { ...props }));
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Whether `address` may be offered as a fallback's "open in a new tab": a clean address on the
|
|
31
|
+
* served content domain (`contentSource`, its scheme and port), not Porthole's own paths. Anything
|
|
32
|
+
* else (another site, a typo the server answered 404 for elsewhere) gets no link.
|
|
33
|
+
*/
|
|
34
|
+
export function tabLinkOf(address, contentSource) {
|
|
35
|
+
if (contentSource === null || contentSource === undefined) {
|
|
36
|
+
return null;
|
|
37
|
+
}
|
|
38
|
+
try {
|
|
39
|
+
const url = new URL(address);
|
|
40
|
+
return originMatchesSource(url.origin, contentSource) &&
|
|
41
|
+
!url.pathname.startsWith("/__porthole/")
|
|
42
|
+
? url.href
|
|
43
|
+
: null;
|
|
44
|
+
}
|
|
45
|
+
catch {
|
|
46
|
+
return null;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
/** A clean address's view (P125): resolved first; its instance's view, or the answer's fallback. */
|
|
50
|
+
function AddressView(props) {
|
|
51
|
+
const client = useClient();
|
|
52
|
+
const page = useContext(PortholeContext);
|
|
53
|
+
const meta = useMeta(client);
|
|
54
|
+
const { address, fallback, pending, onOutcome } = props;
|
|
55
|
+
const [state, setState] = useState({ kind: "resolving" });
|
|
56
|
+
const [generation, setGeneration] = useState(0);
|
|
57
|
+
const retry = useCallback(() => setGeneration((each) => each + 1), []);
|
|
58
|
+
useEffect(() => {
|
|
59
|
+
const controller = new AbortController();
|
|
60
|
+
setState({ kind: "resolving" });
|
|
61
|
+
client.resolve(address, controller.signal).then((resolved) => {
|
|
62
|
+
if (controller.signal.aborted) {
|
|
63
|
+
return;
|
|
64
|
+
}
|
|
65
|
+
if ("outcome" in resolved) {
|
|
66
|
+
onOutcome?.(resolved.outcome);
|
|
67
|
+
const said = frameFallback(resolved.outcome);
|
|
68
|
+
setState(said === null
|
|
69
|
+
? {
|
|
70
|
+
kind: "refused",
|
|
71
|
+
said: { kind: "failed", title: "This can't be shown now", message: "" },
|
|
72
|
+
}
|
|
73
|
+
: { kind: "refused", said });
|
|
74
|
+
return;
|
|
75
|
+
}
|
|
76
|
+
setState({ kind: "instance", instance: resolved.instance, location: resolved.location });
|
|
77
|
+
}, () => {
|
|
78
|
+
if (controller.signal.aborted) {
|
|
79
|
+
return;
|
|
80
|
+
}
|
|
81
|
+
const outcome = { state: "blocked", reason: "locate" };
|
|
82
|
+
onOutcome?.(outcome);
|
|
83
|
+
setState({
|
|
84
|
+
kind: "refused",
|
|
85
|
+
said: frameFallback(outcome) ?? {
|
|
86
|
+
kind: "failed",
|
|
87
|
+
title: "This can't be shown now",
|
|
88
|
+
message: "",
|
|
89
|
+
},
|
|
90
|
+
});
|
|
91
|
+
});
|
|
92
|
+
return () => controller.abort();
|
|
93
|
+
// The address and a retry decide; a new onOutcome doesn't resolve it again.
|
|
94
|
+
// oxlint-disable-next-line react-hooks/exhaustive-deps
|
|
95
|
+
}, [client, address, generation]);
|
|
96
|
+
// This view's own locator (P125): its frame's first run takes the location it resolved, once;
|
|
97
|
+
// every later run issues afresh. No other view of the instance can take it.
|
|
98
|
+
const located = state.kind === "instance" ? state.location : null;
|
|
99
|
+
const own = useMemo(() => {
|
|
100
|
+
if (located === null) {
|
|
101
|
+
return null;
|
|
102
|
+
}
|
|
103
|
+
const locator = oneShot(located, { locate: (each, signal) => client.locate(each, signal) });
|
|
104
|
+
return {
|
|
105
|
+
...page,
|
|
106
|
+
locate: (each, signal) => locator.locate(each, signal),
|
|
107
|
+
};
|
|
108
|
+
}, [page, located, client]);
|
|
109
|
+
if (state.kind === "resolving") {
|
|
110
|
+
return _jsx(_Fragment, { children: pending ?? null });
|
|
111
|
+
}
|
|
112
|
+
if (state.kind === "refused") {
|
|
113
|
+
// The clean address is the "open in a new tab" only where it is one: on the content domain.
|
|
114
|
+
return (_jsx(_Fragment, { children: (fallback ?? DefaultFallback)({
|
|
115
|
+
...state.said,
|
|
116
|
+
link: tabLinkOf(address, meta?.contentSource),
|
|
117
|
+
retry,
|
|
118
|
+
}) }));
|
|
119
|
+
}
|
|
120
|
+
const { address: _address, ...rest } = props;
|
|
121
|
+
return (_jsx(PortholeContext.Provider, { value: own ?? page, children: _jsx(InstanceView, { ...rest, instance: state.instance }) }));
|
|
122
|
+
}
|
|
123
|
+
function InstanceView(props) {
|
|
25
124
|
const client = useClient();
|
|
26
125
|
const meta = useMeta(client);
|
|
27
|
-
const { display, instance, content, fallback, pending, onOutcome, ref, ...frame } = props;
|
|
126
|
+
const { display, instance, content, fallback, pending, onOutcome, ref, address: _address, ...frame } = props;
|
|
28
127
|
// The view's handle (P118) is there while the view is, a fallback drawn or not: its calls reach
|
|
29
128
|
// the frame's display when one runs, and do nothing otherwise.
|
|
30
129
|
const shown = useRef(null);
|
package/dist/server/files.d.ts
CHANGED
|
@@ -32,6 +32,11 @@ export interface FileServing {
|
|
|
32
32
|
*/
|
|
33
33
|
readonly ticket?: {
|
|
34
34
|
readonly expires: number;
|
|
35
|
+
/**
|
|
36
|
+
* A page below the base the ticket was issued for (P125: a clean address's file, resolved
|
|
37
|
+
* through `issue`), opened instead of the entry (`ticketPage`).
|
|
38
|
+
*/
|
|
39
|
+
readonly page?: string;
|
|
35
40
|
};
|
|
36
41
|
/** The artifact version the set is, which its pages name in their notices to the host (P098). */
|
|
37
42
|
readonly artifact?: {
|
|
@@ -46,6 +51,12 @@ export declare function isNavigation(request: Request): boolean;
|
|
|
46
51
|
* only a browser sets and no page can change), and not a navigation.
|
|
47
52
|
*/
|
|
48
53
|
export declare const ownLoad: (request: Request) => boolean;
|
|
54
|
+
/**
|
|
55
|
+
* The page a ticket opens in a set (P081, P125): its entry, or the page below the base it was
|
|
56
|
+
* issued for, found as a navigation finds it (`dir/` its index, `name` its `.html`); null when
|
|
57
|
+
* that is no page of the set. The door asks the same (`serveDoor`), so both say `not-found` alike.
|
|
58
|
+
*/
|
|
59
|
+
export declare function ticketPage(set: StoredFiles, page?: string): string | null;
|
|
49
60
|
export declare function serveFile(serving: FileServing): Promise<Response>;
|
|
50
61
|
/**
|
|
51
62
|
* An asset of an artifact's library (P089), at `/_blob/<id>`: typed by Porthole's table by its
|
package/dist/server/files.js
CHANGED
|
@@ -108,6 +108,30 @@ function nothing(serving, status, method) {
|
|
|
108
108
|
},
|
|
109
109
|
});
|
|
110
110
|
}
|
|
111
|
+
/**
|
|
112
|
+
* The page a ticket opens in a set (P081, P125): its entry, or the page below the base it was
|
|
113
|
+
* issued for, found as a navigation finds it (`dir/` its index, `name` its `.html`); null when
|
|
114
|
+
* that is no page of the set. The door asks the same (`serveDoor`), so both say `not-found` alike.
|
|
115
|
+
*/
|
|
116
|
+
export function ticketPage(set, page) {
|
|
117
|
+
const has = (each) => Object.hasOwn(set.files, each);
|
|
118
|
+
const entry = set.entry ?? DEFAULT_ENTRY;
|
|
119
|
+
if (page === undefined || page === "") {
|
|
120
|
+
return has(entry) ? entry : null;
|
|
121
|
+
}
|
|
122
|
+
const path = requestFilePath(page);
|
|
123
|
+
if (path === null) {
|
|
124
|
+
return null;
|
|
125
|
+
}
|
|
126
|
+
let found = lookupFile(has, path, { entry, navigation: false });
|
|
127
|
+
if (found.kind === "redirect") {
|
|
128
|
+
found = lookupFile(has, found.to, { entry, navigation: false });
|
|
129
|
+
}
|
|
130
|
+
return found.kind === "file" && found.status === 200 && fileTypeOf(found.path).role === "page"
|
|
131
|
+
? found.path
|
|
132
|
+
: null;
|
|
133
|
+
}
|
|
134
|
+
const ticketLookup = (path) => path === null ? { kind: "none" } : { kind: "file", path, status: 200 };
|
|
111
135
|
export async function serveFile(serving) {
|
|
112
136
|
const { request, set } = serving;
|
|
113
137
|
const method = request.method.toUpperCase();
|
|
@@ -127,9 +151,7 @@ export async function serveFile(serving) {
|
|
|
127
151
|
const has = (each) => Object.hasOwn(set.files, each);
|
|
128
152
|
const entryPath = set.entry ?? DEFAULT_ENTRY;
|
|
129
153
|
const found = serving.ticket !== undefined
|
|
130
|
-
?
|
|
131
|
-
? { kind: "file", path: entryPath, status: 200 }
|
|
132
|
-
: { kind: "none" }
|
|
154
|
+
? ticketLookup(ticketPage(set, serving.ticket.page))
|
|
133
155
|
: lookupFile(has, path, {
|
|
134
156
|
...(set.entry === undefined ? {} : { entry: set.entry }),
|
|
135
157
|
...(set.spa === undefined ? {} : { spa: set.spa }),
|
|
@@ -206,7 +228,7 @@ export async function serveFile(serving) {
|
|
|
206
228
|
...(serving.ticket === undefined
|
|
207
229
|
? {}
|
|
208
230
|
: {
|
|
209
|
-
address: `${base}${found.path.includes("/") ? encodePath(found.path)
|
|
231
|
+
address: `${base}${found.path === entryPath && !found.path.includes("/") ? "" : encodePath(found.path)}`,
|
|
210
232
|
expires: serving.ticket.expires,
|
|
211
233
|
}),
|
|
212
234
|
...(serving.artifact === undefined ? {} : { set: serving.artifact }),
|