@botiverse/porthole 0.14.5 → 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 +53 -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 +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 +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 +57 -4
- package/docs/DECISIONS.md +198 -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 +175 -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 +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/server/pages.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { DOOR_SANDBOX_TOKENS } from "../compile/policy.js";
|
|
1
2
|
import { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
2
3
|
import { base64url, sha256, utf8 } from "./crypto.js";
|
|
3
4
|
/**
|
|
@@ -109,15 +110,16 @@ export function enterPage(target, frameAncestors, hostOrigins, cookie) {
|
|
|
109
110
|
headers.set("set-cookie", cookie);
|
|
110
111
|
return new Response(body, { status: 200, headers });
|
|
111
112
|
}
|
|
112
|
-
/**
|
|
113
|
-
|
|
114
|
-
const
|
|
115
|
-
statusHash ??= base64url(sha256(utf8(STATUS_SCRIPT)))
|
|
113
|
+
/** A script's hash, for a page that carries it inline (`script-src 'sha256-…'`). */
|
|
114
|
+
const hashOf = (script) => {
|
|
115
|
+
const hash = base64url(sha256(utf8(script)))
|
|
116
116
|
.replace(/-/gu, "+")
|
|
117
117
|
.replace(/_/gu, "/");
|
|
118
|
-
const padding = (4 - (
|
|
119
|
-
return `'sha256-${
|
|
118
|
+
const padding = (4 - (hash.length % 4)) % 4;
|
|
119
|
+
return `'sha256-${hash}${"=".repeat(padding)}'`;
|
|
120
120
|
};
|
|
121
|
+
let statusHash = null;
|
|
122
|
+
const hashOfStatus = () => (statusHash ??= hashOf(STATUS_SCRIPT));
|
|
121
123
|
/**
|
|
122
124
|
* A redirect entry's page on the app's own origin (P068): why it shows nothing, told to the page
|
|
123
125
|
* that frames it like a content origin's page. Plain, no app chrome; its one script inline under
|
|
@@ -148,3 +150,77 @@ export function appStatusPage(status, title, detail, frameAncestors, reason, hos
|
|
|
148
150
|
export function statusPageOf(options) {
|
|
149
151
|
return appStatusPage(options.status, options.title, options.detail, options.frameAncestors ?? options.hostOrigins.join(" "), options.reason ?? "error", options.hostOrigins, options.link, options.method);
|
|
150
152
|
}
|
|
153
|
+
/** A door's word that its display may be framed (P125), from the page's data attributes. */
|
|
154
|
+
const DOOR_SCRIPT = `(() => {
|
|
155
|
+
const main = document.querySelector("[data-porthole-door]");
|
|
156
|
+
if (main === null) return;
|
|
157
|
+
const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
|
|
158
|
+
${say()}
|
|
159
|
+
say({ state: "open" });
|
|
160
|
+
})();`;
|
|
161
|
+
let doorHash = null;
|
|
162
|
+
const hashOfDoor = () => (doorHash ??= hashOf(DOOR_SCRIPT));
|
|
163
|
+
/**
|
|
164
|
+
* A door's headers (P125): its one script by its hash (an opaque document has no `'self'` to load
|
|
165
|
+
* one from), nothing else loads, sandboxed with scripts alone in its header too (opaque on a tab, and
|
|
166
|
+
* in a frame whose attribute a host's own platform forgot), framed by the host origins, never
|
|
167
|
+
* cached, never sent on, no cookie.
|
|
168
|
+
*/
|
|
169
|
+
const doorHeaders = (script, frameAncestors) => new Headers({
|
|
170
|
+
"content-type": "text/html; charset=utf-8",
|
|
171
|
+
"cache-control": "no-store",
|
|
172
|
+
"content-security-policy": `default-src 'none'; script-src ${script}; base-uri 'none'; form-action 'none'; sandbox ${DOOR_SANDBOX_TOKENS.join(" ")}; frame-ancestors ${frameAncestors}`,
|
|
173
|
+
"referrer-policy": "no-referrer",
|
|
174
|
+
"x-content-type-options": "nosniff",
|
|
175
|
+
"x-robots-tag": "noindex, nofollow",
|
|
176
|
+
});
|
|
177
|
+
/**
|
|
178
|
+
* A door that opens (P125): its display may be framed. It says `open` to the page that frames it,
|
|
179
|
+
* at each web host origin and (a desktop scheme among them) to its parent (P070), once, as it
|
|
180
|
+
* parses. For a content Worker of a host's own: answer it at `DOOR_PATH<key>` only once the door's
|
|
181
|
+
* own ticket was taken and the checks the content's address runs passed for the same grant.
|
|
182
|
+
*/
|
|
183
|
+
export function doorResponse(options) {
|
|
184
|
+
const hosts = escape(JSON.stringify(options.hostOrigins));
|
|
185
|
+
const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Opening</title></head><body><main data-porthole-door="" data-porthole-hosts="${hosts}"></main><script>${DOOR_SCRIPT}</script></body></html>`;
|
|
186
|
+
return new Response(options.method?.toUpperCase() === "HEAD" ? null : body, {
|
|
187
|
+
status: 200,
|
|
188
|
+
headers: doorHeaders(hashOfDoor(), options.frameAncestors ?? options.hostOrigins.join(" ")),
|
|
189
|
+
});
|
|
190
|
+
}
|
|
191
|
+
/**
|
|
192
|
+
* A door that doesn't open (P125): why, said `blocked` to the page that frames it, as a content
|
|
193
|
+
* origin's status page says it (`session` 401: no ticket, or one used, ended, or not a door's of
|
|
194
|
+
* this instance on this origin; `denied` 403 with the host's code; `not-found` 404: no document, or
|
|
195
|
+
* a file set whose entry isn't a page; `error` 500).
|
|
196
|
+
*/
|
|
197
|
+
export function doorStatusResponse(options) {
|
|
198
|
+
const { status, reason, code } = options;
|
|
199
|
+
const hosts = escape(JSON.stringify(options.hostOrigins));
|
|
200
|
+
const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Not shown</title></head><body><main data-porthole-status="${status}" data-porthole-reason="${escape(reason)}"${code === undefined ? "" : ` data-porthole-code="${escape(code)}"`} data-porthole-hosts="${hosts}"></main><script>${STATUS_SCRIPT}</script></body></html>`;
|
|
201
|
+
return new Response(options.method?.toUpperCase() === "HEAD" ? null : body, {
|
|
202
|
+
status,
|
|
203
|
+
headers: doorHeaders(hashOfStatus(), options.frameAncestors ?? options.hostOrigins.join(" ")),
|
|
204
|
+
});
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* What a clean address answers in a frame (P125): a clean address is for a tab of its own, so in a
|
|
208
|
+
* frame it never goes to the app (no authorize, no sign-in, no refusal page of the app's) and says
|
|
209
|
+
* nothing to the page that frames it: no script at all, under the status pages' policy without
|
|
210
|
+
* `script-src` (so `default-src 'none'` forbids every script), framed by the host origins only. A
|
|
211
|
+
* host frames what a clean address names by resolving it through `issue` (`client.resolve`).
|
|
212
|
+
*/
|
|
213
|
+
export function tabOnlyPage(frameAncestors, method = "GET") {
|
|
214
|
+
const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Open this in a new tab</title><style>${STYLE}</style></head><body><main data-porthole-tab-only=""><h1>Open this in a new tab</h1><p>This address opens in a tab of its own, not inside a frame.</p></main></body></html>`;
|
|
215
|
+
return new Response(method.toUpperCase() === "HEAD" ? null : body, {
|
|
216
|
+
status: 403,
|
|
217
|
+
headers: {
|
|
218
|
+
"content-type": "text/html; charset=utf-8",
|
|
219
|
+
"cache-control": "no-store",
|
|
220
|
+
"content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`,
|
|
221
|
+
"referrer-policy": "no-referrer",
|
|
222
|
+
"x-content-type-options": "nosniff",
|
|
223
|
+
"x-robots-tag": "noindex, nofollow",
|
|
224
|
+
},
|
|
225
|
+
});
|
|
226
|
+
}
|
package/dist/server/server.js
CHANGED
|
@@ -1,14 +1,16 @@
|
|
|
1
1
|
import { compile } from "../compile/compile.js";
|
|
2
2
|
import { hostOriginProblem, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
|
|
3
|
+
import { DOOR_PATH, } from "../isolation/types.js";
|
|
3
4
|
import { sandboxProxyDocument } from "../mcp/proxy.js";
|
|
4
5
|
import { base32, createKeys, newTicket, ticketId } from "./keys.js";
|
|
5
6
|
import { randomBytes } from "./crypto.js";
|
|
6
7
|
import { isHostLabel, reservedLabels } from "./naming.js";
|
|
7
|
-
import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
|
|
8
|
+
import { doorResponse, doorStatusResponse, enterPage, pageScript, SESSION_PATH, statusPage, tabOnlyPage, } from "./pages.js";
|
|
8
9
|
import { libraryFile } from "./libraries.js";
|
|
9
|
-
import { isNavigation, ownLoad, serveAsset, serveFile } from "./files.js";
|
|
10
|
+
import { isNavigation, ownLoad, serveAsset, serveFile, ticketPage } from "./files.js";
|
|
10
11
|
import { isNestedLabel, nestedAncestors, nestedLabelOf, nestedFileCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
|
|
11
12
|
import { DEFAULT_ENTRY } from "../files/paths.js";
|
|
13
|
+
import { isPagePath } from "../files/types.js";
|
|
12
14
|
import { isPortholeCookie, setsPortholeCookie } from "./proxy.js";
|
|
13
15
|
import { assetCodeRuns, assetCspDirectives, INERT_FILE_CSP, servedDocumentCsp, servedPermissionsPolicy, } from "../compile/policy.js";
|
|
14
16
|
import { parseViewer } from "../runtime/levels.js";
|
|
@@ -20,6 +22,8 @@ import { memoryTicketStore } from "./tickets.js";
|
|
|
20
22
|
const PREFIX = "/__porthole/";
|
|
21
23
|
/** A served document (shell, artifact page, sandbox proxy), by its instance's key. */
|
|
22
24
|
const DOCUMENT_PATH = /^\/__porthole\/d\/([a-z2-7]{16})$/u;
|
|
25
|
+
/** A served display's door (P125), by its instance's key: `DOOR_PATH<key>`. */
|
|
26
|
+
const DOOR_ROUTE = /^\/__porthole\/door\/([a-z2-7]{16})$/u;
|
|
23
27
|
/**
|
|
24
28
|
* A file set's files in a frame (P083): `/__porthole/f/<sealed access>/<path>`. The access is
|
|
25
29
|
* in the path, so a frame whose engine keeps no cookie (WebKit, P025) loads them too.
|
|
@@ -87,6 +91,11 @@ function normalHost(value, protocol) {
|
|
|
87
91
|
: host;
|
|
88
92
|
}
|
|
89
93
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
94
|
+
/** Whether a file set opens at a page of its own (P125, P124-2): its entry is a file, and a page. */
|
|
95
|
+
const entryIsPage = (set) => {
|
|
96
|
+
const entry = set.entry ?? DEFAULT_ENTRY;
|
|
97
|
+
return Object.hasOwn(set.files, entry) && isPagePath(entry);
|
|
98
|
+
};
|
|
90
99
|
const isStoredFiles = (stored) => isRecord(stored) &&
|
|
91
100
|
isRecord(stored.files) &&
|
|
92
101
|
typeof stored.read === "function";
|
|
@@ -334,6 +343,13 @@ export function createServer(options) {
|
|
|
334
343
|
* page saying it's denied. Answers are reused only for the host's own `ttlSeconds`.
|
|
335
344
|
*/
|
|
336
345
|
async function denied(request, access) {
|
|
346
|
+
const refused = await refusalOf(request, access);
|
|
347
|
+
return refused === null
|
|
348
|
+
? null
|
|
349
|
+
: page(403, "You can't open this anymore", "The app that showed it no longer lets you see it here.", request.method.toUpperCase(), "denied", refused.code);
|
|
350
|
+
}
|
|
351
|
+
/** The host's check (P050): null to go on, or its refusal and the host's code, if a good one. */
|
|
352
|
+
async function refusalOf(request, access) {
|
|
337
353
|
if (authorize === undefined) {
|
|
338
354
|
return null;
|
|
339
355
|
}
|
|
@@ -379,7 +395,7 @@ export function createServer(options) {
|
|
|
379
395
|
return null;
|
|
380
396
|
}
|
|
381
397
|
const code = typeof given?.code === "string" && CODE.test(given.code) ? given.code : undefined;
|
|
382
|
-
return
|
|
398
|
+
return code === undefined ? {} : { code };
|
|
383
399
|
}
|
|
384
400
|
/** The config a served document is served under, checked to fit it and this server. */
|
|
385
401
|
function configFor(name, kind) {
|
|
@@ -838,8 +854,10 @@ export function createServer(options) {
|
|
|
838
854
|
// still shows it. The cookie serves what follows (a reload), where the engine keeps it.
|
|
839
855
|
const record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
|
|
840
856
|
// An entry code opens its clean address alone, through its own browser's nonce (P068, P114).
|
|
857
|
+
// A door's ticket is the door's alone (P125): here it is no ticket.
|
|
841
858
|
if (record !== null &&
|
|
842
859
|
record.entry === undefined &&
|
|
860
|
+
record.door !== true &&
|
|
843
861
|
record.instance.document.kind !== "external" &&
|
|
844
862
|
keys.instanceKey(record.instance) === key) {
|
|
845
863
|
cookie = sessionCookie(request, record);
|
|
@@ -861,6 +879,64 @@ export function createServer(options) {
|
|
|
861
879
|
const rest = isPageRest(asked) ? asked : undefined;
|
|
862
880
|
return serveAccess(request, access, cookie, undefined, rest);
|
|
863
881
|
}
|
|
882
|
+
/**
|
|
883
|
+
* A served display's door (P125): its own ticket's, taken once, for this instance on this
|
|
884
|
+
* origin, and the checks the content's address runs for the same grant (the host's check, the
|
|
885
|
+
* document, its entry), so the door says what the content's address would: `open`, or `blocked`
|
|
886
|
+
* and why. It sets no cookie and serves nothing of the content; the content's address takes its
|
|
887
|
+
* own ticket and checks again (P050), so the door only tells. No other ticket opens it, and a
|
|
888
|
+
* nested page's shell's label serves none (`serveShellLabel`).
|
|
889
|
+
*/
|
|
890
|
+
async function serveDoor(request, url, label, key) {
|
|
891
|
+
const method = request.method.toUpperCase();
|
|
892
|
+
const say = (status, reason, code) => doorStatusResponse({
|
|
893
|
+
status,
|
|
894
|
+
reason,
|
|
895
|
+
...(code === undefined ? {} : { code }),
|
|
896
|
+
hostOrigins: options.hostOrigins,
|
|
897
|
+
frameAncestors,
|
|
898
|
+
method,
|
|
899
|
+
});
|
|
900
|
+
if (method !== "GET" && method !== "HEAD") {
|
|
901
|
+
return say(405, "error");
|
|
902
|
+
}
|
|
903
|
+
try {
|
|
904
|
+
const record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
|
|
905
|
+
if (record === null ||
|
|
906
|
+
record.door !== true ||
|
|
907
|
+
record.entry !== undefined ||
|
|
908
|
+
record.instance.document.kind === "external" ||
|
|
909
|
+
keys.instanceKey(record.instance) !== key ||
|
|
910
|
+
compiledFor(record.instance)?.config.nested === true) {
|
|
911
|
+
return say(401, "session");
|
|
912
|
+
}
|
|
913
|
+
const access = {
|
|
914
|
+
instance: record.instance,
|
|
915
|
+
viewer: record.viewer,
|
|
916
|
+
origin: originOfLabel(label),
|
|
917
|
+
expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
|
|
918
|
+
...(record.anonymous === true ? { anonymous: true } : {}),
|
|
919
|
+
...(record.subject === undefined ? {} : { subject: record.subject }),
|
|
920
|
+
};
|
|
921
|
+
const refused = await refusalOf(request, access);
|
|
922
|
+
if (refused !== null) {
|
|
923
|
+
return say(403, "denied", refused.code);
|
|
924
|
+
}
|
|
925
|
+
const served = await documentOf(access.instance);
|
|
926
|
+
// The same document, entry and page checks the content's address runs (`serveAccess`).
|
|
927
|
+
const below = isPageRest(record.page) ? record.page : undefined;
|
|
928
|
+
if (served === null ||
|
|
929
|
+
("files" in served
|
|
930
|
+
? !entryIsPage(served.files) || ticketPage(served.files, below) === null
|
|
931
|
+
: below !== undefined)) {
|
|
932
|
+
return say(404, "not-found");
|
|
933
|
+
}
|
|
934
|
+
return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
|
|
935
|
+
}
|
|
936
|
+
catch {
|
|
937
|
+
return say(500, "error");
|
|
938
|
+
}
|
|
939
|
+
}
|
|
864
940
|
/**
|
|
865
941
|
* The document an access opens, once the host's check lets it in: at its document's path, or
|
|
866
942
|
* (`at`) a path under a file set's base (P081).
|
|
@@ -877,6 +953,18 @@ export function createServer(options) {
|
|
|
877
953
|
if (served === null) {
|
|
878
954
|
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
879
955
|
}
|
|
956
|
+
// A frame's document opens at its file set's entry, which is a page (P125, P124-2): a set
|
|
957
|
+
// stored before that was checked shows Porthole's word, never an inert file that says nothing.
|
|
958
|
+
if ("files" in served && at === undefined && !entryIsPage(served.files)) {
|
|
959
|
+
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
960
|
+
}
|
|
961
|
+
// A page below a base (P125) names a file set's page: for one page alone, nothing; for a set,
|
|
962
|
+
// the page the frame opens at (its entry, or the page it was issued for) must be one of its
|
|
963
|
+
// pages. The door asks the same (`serveDoor`), so both say `not-found` alike.
|
|
964
|
+
if (at === undefined &&
|
|
965
|
+
("files" in served ? ticketPage(served.files, pageAt) === null : pageAt !== undefined)) {
|
|
966
|
+
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
967
|
+
}
|
|
880
968
|
// A nested page (P111): the address the host frames (a ticket's, a cookie's, an entered
|
|
881
969
|
// one's) answers Porthole's shell, which frames the page at its sealed files' address; only
|
|
882
970
|
// that address, below the sealed prefix, answers the page and its files, without a cookie.
|
|
@@ -955,7 +1043,7 @@ export function createServer(options) {
|
|
|
955
1043
|
compiled: served.compiled,
|
|
956
1044
|
hostOrigins: options.hostOrigins,
|
|
957
1045
|
frameAncestors,
|
|
958
|
-
ticket: { expires: sealed.expires },
|
|
1046
|
+
ticket: { expires: sealed.expires, ...(pageAt === undefined ? {} : { page: pageAt }) },
|
|
959
1047
|
...versionOf(access.instance),
|
|
960
1048
|
});
|
|
961
1049
|
}
|
|
@@ -1167,6 +1255,13 @@ export function createServer(options) {
|
|
|
1167
1255
|
*/
|
|
1168
1256
|
async function beginEntry(request, url, label, to) {
|
|
1169
1257
|
const method = request.method.toUpperCase();
|
|
1258
|
+
// A clean address is for a tab (P125): in a frame it never goes to the app (no authorize, no
|
|
1259
|
+
// sign-in, no refusal of the app's) and says nothing to the page that frames it, whatever it
|
|
1260
|
+
// names. A host frames what a clean address names by resolving it through `issue`.
|
|
1261
|
+
const framedAs = request.headers.get("sec-fetch-dest");
|
|
1262
|
+
if (framedAs === "iframe" || framedAs === "frame") {
|
|
1263
|
+
return tabOnlyPage(frameAncestors, method);
|
|
1264
|
+
}
|
|
1170
1265
|
// An address that names nothing is nothing here (P070): never a trip to the app's sign-in.
|
|
1171
1266
|
const scopeOf = content.name?.scopeOf;
|
|
1172
1267
|
const named = options.entry?.named;
|
|
@@ -1402,7 +1497,9 @@ export function createServer(options) {
|
|
|
1402
1497
|
return page(404, "Nothing here", "This address names no content.", method);
|
|
1403
1498
|
}
|
|
1404
1499
|
/** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
|
|
1405
|
-
async function mint(instance, grant, entry
|
|
1500
|
+
async function mint(instance, grant, entry,
|
|
1501
|
+
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1502
|
+
below) {
|
|
1406
1503
|
const clean = cleanInstance(instance);
|
|
1407
1504
|
check(clean);
|
|
1408
1505
|
const anonymous = grant.anonymous === true;
|
|
@@ -1442,7 +1539,7 @@ export function createServer(options) {
|
|
|
1442
1539
|
throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
|
|
1443
1540
|
}
|
|
1444
1541
|
const ticket = newTicket();
|
|
1445
|
-
|
|
1542
|
+
const record = {
|
|
1446
1543
|
instance: clean,
|
|
1447
1544
|
viewer,
|
|
1448
1545
|
expiresAt: Date.now() + ttl * 1_000,
|
|
@@ -1450,8 +1547,24 @@ export function createServer(options) {
|
|
|
1450
1547
|
...(anonymous ? { anonymous: true } : {}),
|
|
1451
1548
|
...(grant.subject === undefined ? {} : { subject: grant.subject }),
|
|
1452
1549
|
...(entry === undefined ? {} : { entry }),
|
|
1453
|
-
|
|
1454
|
-
|
|
1550
|
+
...(below === undefined ? {} : { page: below }),
|
|
1551
|
+
};
|
|
1552
|
+
await tickets.put(ticketId(ticket), record);
|
|
1553
|
+
// A frame on its scope's origin has a door (P125): its ticket, for the same grant and as long.
|
|
1554
|
+
let door = null;
|
|
1555
|
+
if (entry === undefined && hasDoor(clean)) {
|
|
1556
|
+
door = newTicket();
|
|
1557
|
+
await tickets.put(ticketId(door), { ...record, door: true });
|
|
1558
|
+
}
|
|
1559
|
+
return { clean, key, ticket, door };
|
|
1560
|
+
}
|
|
1561
|
+
/**
|
|
1562
|
+
* Whether an instance's frame has a door (P125): a document framed on its scope's origin, where
|
|
1563
|
+
* the scope's other displays run content (a served shell, a page that isn't nested, the sandbox
|
|
1564
|
+
* proxy). A nested page's frame is its shell, on a label of its own; a url-mode app has none.
|
|
1565
|
+
*/
|
|
1566
|
+
function hasDoor(instance) {
|
|
1567
|
+
return instance.document.kind !== "external" && compiledFor(instance)?.config.nested !== true;
|
|
1455
1568
|
}
|
|
1456
1569
|
const underDomain = (host) => host === domain || host.endsWith(`.${domain}`);
|
|
1457
1570
|
/**
|
|
@@ -1498,8 +1611,13 @@ export function createServer(options) {
|
|
|
1498
1611
|
return {
|
|
1499
1612
|
contentSource,
|
|
1500
1613
|
originFor: (scope) => originOfLabel(nameOf(scope)),
|
|
1501
|
-
async issue(instance, grant) {
|
|
1502
|
-
|
|
1614
|
+
async issue(instance, grant, at = {}) {
|
|
1615
|
+
// A page below a file set's base (P125: what a clean address names, resolved for a frame).
|
|
1616
|
+
const below = at.page;
|
|
1617
|
+
if (below !== undefined && (!isPageRest(below) || instance.document?.kind !== "artifact")) {
|
|
1618
|
+
throw new TypeError("A frame's page is a relative path below an artifact's files (no . or ..)");
|
|
1619
|
+
}
|
|
1620
|
+
const { clean, key, ticket, door } = await mint(instance, grant, undefined, below);
|
|
1503
1621
|
// A nested page's frame is its shell, on the shell's own label (P114).
|
|
1504
1622
|
const origin = originOfLabel(labelFor(clean));
|
|
1505
1623
|
const path = clean.document.kind === "external"
|
|
@@ -1507,7 +1625,14 @@ export function createServer(options) {
|
|
|
1507
1625
|
: `${PREFIX}d/${key}?ticket=${ticket}`;
|
|
1508
1626
|
// The viewer's level, as the host's access decided it now (P087): for the display's bridge.
|
|
1509
1627
|
const viewer = viewerOfGrant(grant);
|
|
1510
|
-
return {
|
|
1628
|
+
return {
|
|
1629
|
+
url: `${origin}${path}`,
|
|
1630
|
+
origin,
|
|
1631
|
+
reports: true,
|
|
1632
|
+
...(viewer ? { viewer } : {}),
|
|
1633
|
+
// Its door (P125): the host frames it first, and takes its word alone.
|
|
1634
|
+
...(door === null ? {} : { door: { url: `${origin}${DOOR_PATH}${key}?ticket=${door}` } }),
|
|
1635
|
+
};
|
|
1511
1636
|
},
|
|
1512
1637
|
forget(filter = {}) {
|
|
1513
1638
|
for (const [key, each] of answers) {
|
|
@@ -1643,6 +1768,10 @@ export function createServer(options) {
|
|
|
1643
1768
|
if (asset?.[1] !== undefined) {
|
|
1644
1769
|
return await serveAssetAt(request, label, asset[1]);
|
|
1645
1770
|
}
|
|
1771
|
+
const door = DOOR_ROUTE.exec(url.pathname);
|
|
1772
|
+
if (door?.[1] !== undefined) {
|
|
1773
|
+
return await serveDoor(request, url, label, door[1]);
|
|
1774
|
+
}
|
|
1646
1775
|
const document = DOCUMENT_PATH.exec(url.pathname);
|
|
1647
1776
|
if (document?.[1] !== undefined) {
|
|
1648
1777
|
return await serveDocument(request, url, label, document[1]);
|
package/dist/server/types.d.ts
CHANGED
|
@@ -103,6 +103,13 @@ export interface TicketRecord {
|
|
|
103
103
|
* its files' base the shell opens (the entry page when absent).
|
|
104
104
|
*/
|
|
105
105
|
readonly page?: string;
|
|
106
|
+
/**
|
|
107
|
+
* A door's ticket (P125): `issue` mints one beside the content's, for the same grant and as
|
|
108
|
+
* long, for a display whose frame is on its scope's origin (a served shell, a page that isn't
|
|
109
|
+
* nested, the sandbox proxy). Taken only at the door (`/__porthole/door/<key>`), never at the
|
|
110
|
+
* content's address; the door takes no other.
|
|
111
|
+
*/
|
|
112
|
+
readonly door?: true;
|
|
106
113
|
}
|
|
107
114
|
/** Where tickets live between `issue` and their one use. Default: in memory (one process). */
|
|
108
115
|
export interface TicketStore {
|
|
@@ -309,7 +316,14 @@ export interface PortholeServer {
|
|
|
309
316
|
* Mints a one-time ticket for `instance` and returns the URL its frame loads. Call it from the
|
|
310
317
|
* host's own authenticated API, once the host has decided the viewer may see the instance.
|
|
311
318
|
*/
|
|
312
|
-
issue(instance: InstanceRef, grant: Grant
|
|
319
|
+
issue(instance: InstanceRef, grant: Grant,
|
|
320
|
+
/**
|
|
321
|
+
* Where in the instance its frame opens (P125): a page below a file set's base (what a clean
|
|
322
|
+
* address names, resolved by `issue` given `{ address }`). Default: its entry.
|
|
323
|
+
*/
|
|
324
|
+
at?: {
|
|
325
|
+
readonly page?: string;
|
|
326
|
+
}): Promise<FrameLocation>;
|
|
313
327
|
/**
|
|
314
328
|
* The access a request's cookie carries for a url-mode app on the request's origin, or null
|
|
315
329
|
* (no good cookie, an `Origin` or `Sec-Fetch-Site` of another origin's (P101), or the host's
|
|
@@ -6,12 +6,4 @@ import type { Transport } from "./types.ts";
|
|
|
6
6
|
* Messages go to the frame's window addressed to that origin; an opaque frame can only be
|
|
7
7
|
* addressed as `"*"`, so nothing secret is ever sent.
|
|
8
8
|
*/
|
|
9
|
-
export declare function postMessageTransport(frameWindow: () => Window | null, expectedOrigin: string, host?: Window
|
|
10
|
-
/**
|
|
11
|
-
* Another origin the frame's window may say some things from: the host's own, whose pages a
|
|
12
|
-
* served frame passes through on a redirect entry (P068), for their frame status only.
|
|
13
|
-
*/
|
|
14
|
-
also?: {
|
|
15
|
-
readonly origin: string;
|
|
16
|
-
readonly accept: (data: unknown) => boolean;
|
|
17
|
-
}): Transport;
|
|
9
|
+
export declare function postMessageTransport(frameWindow: () => Window | null, expectedOrigin: string, host?: Window): Transport;
|
|
@@ -5,12 +5,7 @@
|
|
|
5
5
|
* Messages go to the frame's window addressed to that origin; an opaque frame can only be
|
|
6
6
|
* addressed as `"*"`, so nothing secret is ever sent.
|
|
7
7
|
*/
|
|
8
|
-
export function postMessageTransport(frameWindow, expectedOrigin, host = window
|
|
9
|
-
/**
|
|
10
|
-
* Another origin the frame's window may say some things from: the host's own, whose pages a
|
|
11
|
-
* served frame passes through on a redirect entry (P068), for their frame status only.
|
|
12
|
-
*/
|
|
13
|
-
also) {
|
|
8
|
+
export function postMessageTransport(frameWindow, expectedOrigin, host = window) {
|
|
14
9
|
const listeners = new Set();
|
|
15
10
|
let closed = false;
|
|
16
11
|
const onMessage = (event) => {
|
|
@@ -18,8 +13,7 @@ also) {
|
|
|
18
13
|
if (closed || source === null || event.source !== source) {
|
|
19
14
|
return;
|
|
20
15
|
}
|
|
21
|
-
if (event.origin !== expectedOrigin
|
|
22
|
-
(also === undefined || event.origin !== also.origin || !also.accept(event.data))) {
|
|
16
|
+
if (event.origin !== expectedOrigin) {
|
|
23
17
|
return;
|
|
24
18
|
}
|
|
25
19
|
for (const listener of listeners) {
|
package/docs/ADOPTING.md
CHANGED
|
@@ -816,10 +816,63 @@ display.on("outcome", (outcome) => {
|
|
|
816
816
|
openButton.onclick = () => porthole.openInTab(instance); // the clean address
|
|
817
817
|
```
|
|
818
818
|
|
|
819
|
-
A `blocked` outcome is the word of Porthole's own pages, never of the content (P124): an
|
|
820
|
-
frame's frame status is never taken, nor one a frame says after its first word; the host
|
|
821
|
-
those as a `hostError` of kind `"frame-status"` (log it, show nothing for it). Draw the
|
|
822
|
-
from `outcome` only. A url-mode app is the exception: it can say any outcome (THREAT_MODEL
|
|
819
|
+
A `blocked` outcome is the word of Porthole's own pages, never of the content (P124, P125): an
|
|
820
|
+
opaque frame's frame status is never taken, nor one a frame says after its first word; the host
|
|
821
|
+
hears those as a `hostError` of kind `"frame-status"` (log it, show nothing for it). Draw the
|
|
822
|
+
fallback from `outcome` only. A url-mode app is the exception: it can say any outcome (THREAT_MODEL
|
|
823
|
+
S6).
|
|
824
|
+
|
|
825
|
+
**The door (P125).** A served display that isn't nested (a served shell, a page, a view through the
|
|
826
|
+
sandbox proxy) is framed on its scope's origin, where the scope's other displays run content: its
|
|
827
|
+
own frame can't be trusted for how loading went (a same-scope sibling could speak for it). So
|
|
828
|
+
`createHost` first frames a **door** — a page of Porthole's on the display's origin, in a hidden
|
|
829
|
+
opaque frame it can't reach — and takes the door's word (`FrameLocation.door`, which `issue` returns
|
|
830
|
+
for those kinds). The content frame's own frame status is then never taken, and its silence is a
|
|
831
|
+
`timeout`, never a fallback. You don't wire anything: `createHost` and `/server` do it. Two
|
|
832
|
+
requirements:
|
|
833
|
+
|
|
834
|
+
- **Deploy the server (or your content Worker) before the host.** The door is minted and served by
|
|
835
|
+
the server; a host given a served non-nested location with no door (from a server that doesn't
|
|
836
|
+
yet mint one) builds no frame for it: `blocked: locate`, and a `hostError` of kind `"door"`
|
|
837
|
+
naming the fix. Upgrade the server/Worker first, then the host. This is a hard requirement, not a
|
|
838
|
+
preference.
|
|
839
|
+
- **A custom locator must pass `door` through, and issue anew for every run.** If you rebuild
|
|
840
|
+
`FrameLocation` yourself (a locator of your own rather than `httpLocator`), carry `door` from your
|
|
841
|
+
issue endpoint unchanged; `httpLocator` and the host kit's client already do. Dropping it refuses
|
|
842
|
+
every served non-nested display, as above. And `locate` is called again on every run (a reload,
|
|
843
|
+
a restart after the content navigated its frame away): answer each call with a fresh issue (a new
|
|
844
|
+
ticket, a new door ticket). A location reused from an earlier run carries tickets already taken,
|
|
845
|
+
so its door says `blocked: session` ("this link has been used"), and `createHost` tells you
|
|
846
|
+
with a `hostError` of kind `"locate"`. (A sibling of the scope could force that by reloading the
|
|
847
|
+
display.)
|
|
848
|
+
- **A platform of your own makes the web's doors.** A `PlatformHost` that wraps
|
|
849
|
+
`webPlatform.createSurface` must also give `createDoor` (delegate to `webPlatform.createDoor`):
|
|
850
|
+
a platform without doors frames no served display that isn't nested (`blocked: locate`, a `door`
|
|
851
|
+
host error).
|
|
852
|
+
- **The door sits in the display's container while it decides**, a hidden 0×0 frame
|
|
853
|
+
(`data-porthole-door`), removed once it says its word. Code that grabs
|
|
854
|
+
`container.querySelector("iframe")` just after mounting may get the door: select
|
|
855
|
+
`iframe:not([data-porthole-door])`.
|
|
856
|
+
- **A clean address is for a tab.** Never give `createHost` a clean address (`urlOf`, `link`) as a
|
|
857
|
+
frame's location: it has no door, so it is refused before any frame, as above, and the content
|
|
858
|
+
origin answers it in a frame with a page that has no script and goes nowhere. To frame what a
|
|
859
|
+
clean address names, resolve it through your issue endpoint first: `client.resolve(address)` (or
|
|
860
|
+
`<PortholeView address>`) posts `{ address }`, and the endpoint answers the location for what it
|
|
861
|
+
names (with its door; a file set's page below its version opens at that page), or the refusal its
|
|
862
|
+
tab would get. A refusal is the display's outcome with no frame built: 401 `blocked: sign-in`,
|
|
863
|
+
403 `blocked: denied` (with your reason code if your answer gives `error.reason`), 404 `blocked:
|
|
864
|
+
not-found`; any other failure is `blocked: locate` with a `locate` host error, and a backend that
|
|
865
|
+
never answers is a `timeout`. That mapping holds for every locate, an instance's too.
|
|
866
|
+
|
|
867
|
+
A **content Worker of your own** (one that answers the content origins itself, instead of
|
|
868
|
+
`/server`) serves the door too: `issue` mints the door ticket and returns `door: { url }`, and the
|
|
869
|
+
Worker routes `DOOR_PATH + <key>` (`/__porthole/door/<key>`) on every label — take the door ticket
|
|
870
|
+
(`TicketRecord.door === true`, bound to the label and key), run the same access, document and entry
|
|
871
|
+
checks the content route runs for that grant, then answer `doorResponse({ hostOrigins })` (open) or
|
|
872
|
+
`doorStatusResponse({ status, reason, code?, hostOrigins })` (401 `session` / 403 `denied` / 404
|
|
873
|
+
`not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d/`, and serve no door on a nested
|
|
874
|
+
page's shell label. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
|
|
875
|
+
`@botiverse/porthole/server`.
|
|
823
876
|
|
|
824
877
|
`porthole.config(kind)` is the served config while frames are served, the opaque one while they
|
|
825
878
|
aren't, and null until the meta is known, so a frame never starts opaque and then restarts
|