@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/src/server/pages.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
|
|
1
2
|
import { FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
2
3
|
import type { FrameBlock } from "../host/types.ts";
|
|
3
4
|
import { base64url, sha256, utf8 } from "./crypto.ts";
|
|
@@ -142,15 +143,16 @@ export function enterPage(
|
|
|
142
143
|
return new Response(body, { status: 200, headers });
|
|
143
144
|
}
|
|
144
145
|
|
|
145
|
-
/**
|
|
146
|
-
|
|
147
|
-
const
|
|
148
|
-
statusHash ??= base64url(sha256(utf8(STATUS_SCRIPT)))
|
|
146
|
+
/** A script's hash, for a page that carries it inline (`script-src 'sha256-…'`). */
|
|
147
|
+
const hashOf = (script: string): string => {
|
|
148
|
+
const hash = base64url(sha256(utf8(script)))
|
|
149
149
|
.replace(/-/gu, "+")
|
|
150
150
|
.replace(/_/gu, "/");
|
|
151
|
-
const padding = (4 - (
|
|
152
|
-
return `'sha256-${
|
|
151
|
+
const padding = (4 - (hash.length % 4)) % 4;
|
|
152
|
+
return `'sha256-${hash}${"=".repeat(padding)}'`;
|
|
153
153
|
};
|
|
154
|
+
let statusHash: string | null = null;
|
|
155
|
+
const hashOfStatus = (): string => (statusHash ??= hashOf(STATUS_SCRIPT));
|
|
154
156
|
|
|
155
157
|
/**
|
|
156
158
|
* A redirect entry's page on the app's own origin (P068): why it shows nothing, told to the page
|
|
@@ -212,3 +214,96 @@ export function statusPageOf(options: {
|
|
|
212
214
|
options.method,
|
|
213
215
|
);
|
|
214
216
|
}
|
|
217
|
+
|
|
218
|
+
/** A door's word that its display may be framed (P125), from the page's data attributes. */
|
|
219
|
+
const DOOR_SCRIPT = `(() => {
|
|
220
|
+
const main = document.querySelector("[data-porthole-door]");
|
|
221
|
+
if (main === null) return;
|
|
222
|
+
const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
|
|
223
|
+
${say()}
|
|
224
|
+
say({ state: "open" });
|
|
225
|
+
})();`;
|
|
226
|
+
let doorHash: string | null = null;
|
|
227
|
+
const hashOfDoor = (): string => (doorHash ??= hashOf(DOOR_SCRIPT));
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* A door's headers (P125): its one script by its hash (an opaque document has no `'self'` to load
|
|
231
|
+
* one from), nothing else loads, sandboxed with scripts alone in its header too (opaque on a tab, and
|
|
232
|
+
* in a frame whose attribute a host's own platform forgot), framed by the host origins, never
|
|
233
|
+
* cached, never sent on, no cookie.
|
|
234
|
+
*/
|
|
235
|
+
const doorHeaders = (script: string, frameAncestors: string): Headers =>
|
|
236
|
+
new Headers({
|
|
237
|
+
"content-type": "text/html; charset=utf-8",
|
|
238
|
+
"cache-control": "no-store",
|
|
239
|
+
"content-security-policy": `default-src 'none'; script-src ${script}; base-uri 'none'; form-action 'none'; sandbox ${DOOR_SANDBOX_TOKENS.join(" ")}; frame-ancestors ${frameAncestors}`,
|
|
240
|
+
"referrer-policy": "no-referrer",
|
|
241
|
+
"x-content-type-options": "nosniff",
|
|
242
|
+
"x-robots-tag": "noindex, nofollow",
|
|
243
|
+
});
|
|
244
|
+
|
|
245
|
+
/** What a door is given: the host origins it tells, and who may frame it (default, those). */
|
|
246
|
+
export interface DoorOptions {
|
|
247
|
+
readonly hostOrigins: readonly string[];
|
|
248
|
+
readonly frameAncestors?: string;
|
|
249
|
+
readonly method?: string;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* A door that opens (P125): its display may be framed. It says `open` to the page that frames it,
|
|
254
|
+
* at each web host origin and (a desktop scheme among them) to its parent (P070), once, as it
|
|
255
|
+
* parses. For a content Worker of a host's own: answer it at `DOOR_PATH<key>` only once the door's
|
|
256
|
+
* own ticket was taken and the checks the content's address runs passed for the same grant.
|
|
257
|
+
*/
|
|
258
|
+
export function doorResponse(options: DoorOptions): Response {
|
|
259
|
+
const hosts = escape(JSON.stringify(options.hostOrigins));
|
|
260
|
+
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>`;
|
|
261
|
+
return new Response(options.method?.toUpperCase() === "HEAD" ? null : body, {
|
|
262
|
+
status: 200,
|
|
263
|
+
headers: doorHeaders(hashOfDoor(), options.frameAncestors ?? options.hostOrigins.join(" ")),
|
|
264
|
+
});
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/**
|
|
268
|
+
* A door that doesn't open (P125): why, said `blocked` to the page that frames it, as a content
|
|
269
|
+
* origin's status page says it (`session` 401: no ticket, or one used, ended, or not a door's of
|
|
270
|
+
* this instance on this origin; `denied` 403 with the host's code; `not-found` 404: no document, or
|
|
271
|
+
* a file set whose entry isn't a page; `error` 500).
|
|
272
|
+
*/
|
|
273
|
+
export function doorStatusResponse(
|
|
274
|
+
options: DoorOptions & {
|
|
275
|
+
readonly status: number;
|
|
276
|
+
readonly reason: FrameBlock;
|
|
277
|
+
readonly code?: string;
|
|
278
|
+
},
|
|
279
|
+
): Response {
|
|
280
|
+
const { status, reason, code } = options;
|
|
281
|
+
const hosts = escape(JSON.stringify(options.hostOrigins));
|
|
282
|
+
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>`;
|
|
283
|
+
return new Response(options.method?.toUpperCase() === "HEAD" ? null : body, {
|
|
284
|
+
status,
|
|
285
|
+
headers: doorHeaders(hashOfStatus(), options.frameAncestors ?? options.hostOrigins.join(" ")),
|
|
286
|
+
});
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* What a clean address answers in a frame (P125): a clean address is for a tab of its own, so in a
|
|
291
|
+
* frame it never goes to the app (no authorize, no sign-in, no refusal page of the app's) and says
|
|
292
|
+
* nothing to the page that frames it: no script at all, under the status pages' policy without
|
|
293
|
+
* `script-src` (so `default-src 'none'` forbids every script), framed by the host origins only. A
|
|
294
|
+
* host frames what a clean address names by resolving it through `issue` (`client.resolve`).
|
|
295
|
+
*/
|
|
296
|
+
export function tabOnlyPage(frameAncestors: string, method = "GET"): Response {
|
|
297
|
+
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>`;
|
|
298
|
+
return new Response(method.toUpperCase() === "HEAD" ? null : body, {
|
|
299
|
+
status: 403,
|
|
300
|
+
headers: {
|
|
301
|
+
"content-type": "text/html; charset=utf-8",
|
|
302
|
+
"cache-control": "no-store",
|
|
303
|
+
"content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`,
|
|
304
|
+
"referrer-policy": "no-referrer",
|
|
305
|
+
"x-content-type-options": "nosniff",
|
|
306
|
+
"x-robots-tag": "noindex, nofollow",
|
|
307
|
+
},
|
|
308
|
+
});
|
|
309
|
+
}
|
package/src/server/server.ts
CHANGED
|
@@ -6,14 +6,27 @@ import {
|
|
|
6
6
|
originMatchesSource,
|
|
7
7
|
parseOrigin,
|
|
8
8
|
} from "../isolation/served.ts";
|
|
9
|
-
import
|
|
9
|
+
import {
|
|
10
|
+
DOOR_PATH,
|
|
11
|
+
type FrameLocation,
|
|
12
|
+
type InstanceRef,
|
|
13
|
+
type ServedDocument,
|
|
14
|
+
} from "../isolation/types.ts";
|
|
10
15
|
import { sandboxProxyDocument } from "../mcp/proxy.ts";
|
|
11
16
|
import { base32, createKeys, newTicket, ticketId } from "./keys.ts";
|
|
12
17
|
import { randomBytes } from "./crypto.ts";
|
|
13
18
|
import { isHostLabel, reservedLabels } from "./naming.ts";
|
|
14
|
-
import {
|
|
19
|
+
import {
|
|
20
|
+
doorResponse,
|
|
21
|
+
doorStatusResponse,
|
|
22
|
+
enterPage,
|
|
23
|
+
pageScript,
|
|
24
|
+
SESSION_PATH,
|
|
25
|
+
statusPage,
|
|
26
|
+
tabOnlyPage,
|
|
27
|
+
} from "./pages.ts";
|
|
15
28
|
import { libraryFile } from "./libraries.ts";
|
|
16
|
-
import { isNavigation, ownLoad, serveAsset, serveFile } from "./files.ts";
|
|
29
|
+
import { isNavigation, ownLoad, serveAsset, serveFile, ticketPage } from "./files.ts";
|
|
17
30
|
import {
|
|
18
31
|
isNestedLabel,
|
|
19
32
|
nestedAncestors,
|
|
@@ -23,6 +36,7 @@ import {
|
|
|
23
36
|
PORTHOLE_LABEL_PREFIX,
|
|
24
37
|
} from "./nested.ts";
|
|
25
38
|
import { DEFAULT_ENTRY } from "../files/paths.ts";
|
|
39
|
+
import { isPagePath } from "../files/types.ts";
|
|
26
40
|
import { isPortholeCookie, setsPortholeCookie } from "./proxy.ts";
|
|
27
41
|
import {
|
|
28
42
|
assetCodeRuns,
|
|
@@ -54,6 +68,8 @@ import type {
|
|
|
54
68
|
const PREFIX = "/__porthole/";
|
|
55
69
|
/** A served document (shell, artifact page, sandbox proxy), by its instance's key. */
|
|
56
70
|
const DOCUMENT_PATH = /^\/__porthole\/d\/([a-z2-7]{16})$/u;
|
|
71
|
+
/** A served display's door (P125), by its instance's key: `DOOR_PATH<key>`. */
|
|
72
|
+
const DOOR_ROUTE = /^\/__porthole\/door\/([a-z2-7]{16})$/u;
|
|
57
73
|
/**
|
|
58
74
|
* A file set's files in a frame (P083): `/__porthole/f/<sealed access>/<path>`. The access is
|
|
59
75
|
* in the path, so a frame whose engine keeps no cookie (WebKit, P025) loads them too.
|
|
@@ -159,6 +175,12 @@ interface FilesAt {
|
|
|
159
175
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
160
176
|
value !== null && typeof value === "object" && !Array.isArray(value);
|
|
161
177
|
|
|
178
|
+
/** Whether a file set opens at a page of its own (P125, P124-2): its entry is a file, and a page. */
|
|
179
|
+
const entryIsPage = (set: StoredFiles): boolean => {
|
|
180
|
+
const entry = set.entry ?? DEFAULT_ENTRY;
|
|
181
|
+
return Object.hasOwn(set.files, entry) && isPagePath(entry);
|
|
182
|
+
};
|
|
183
|
+
|
|
162
184
|
const isStoredFiles = (stored: StoredVersion): stored is StoredFiles =>
|
|
163
185
|
isRecord(stored) &&
|
|
164
186
|
isRecord((stored as Partial<StoredFiles>).files) &&
|
|
@@ -453,6 +475,24 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
453
475
|
* page saying it's denied. Answers are reused only for the host's own `ttlSeconds`.
|
|
454
476
|
*/
|
|
455
477
|
async function denied(request: Request, access: Access): Promise<Response | null> {
|
|
478
|
+
const refused = await refusalOf(request, access);
|
|
479
|
+
return refused === null
|
|
480
|
+
? null
|
|
481
|
+
: page(
|
|
482
|
+
403,
|
|
483
|
+
"You can't open this anymore",
|
|
484
|
+
"The app that showed it no longer lets you see it here.",
|
|
485
|
+
request.method.toUpperCase(),
|
|
486
|
+
"denied",
|
|
487
|
+
refused.code,
|
|
488
|
+
);
|
|
489
|
+
}
|
|
490
|
+
|
|
491
|
+
/** The host's check (P050): null to go on, or its refusal and the host's code, if a good one. */
|
|
492
|
+
async function refusalOf(
|
|
493
|
+
request: Request,
|
|
494
|
+
access: Access,
|
|
495
|
+
): Promise<{ readonly code?: string } | null> {
|
|
456
496
|
if (authorize === undefined) {
|
|
457
497
|
return null;
|
|
458
498
|
}
|
|
@@ -497,14 +537,7 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
497
537
|
return null;
|
|
498
538
|
}
|
|
499
539
|
const code = typeof given?.code === "string" && CODE.test(given.code) ? given.code : undefined;
|
|
500
|
-
return
|
|
501
|
-
403,
|
|
502
|
-
"You can't open this anymore",
|
|
503
|
-
"The app that showed it no longer lets you see it here.",
|
|
504
|
-
request.method.toUpperCase(),
|
|
505
|
-
"denied",
|
|
506
|
-
code,
|
|
507
|
-
);
|
|
540
|
+
return code === undefined ? {} : { code };
|
|
508
541
|
}
|
|
509
542
|
|
|
510
543
|
/** The config a served document is served under, checked to fit it and this server. */
|
|
@@ -1058,9 +1091,11 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1058
1091
|
// still shows it. The cookie serves what follows (a reload), where the engine keeps it.
|
|
1059
1092
|
const record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
|
|
1060
1093
|
// An entry code opens its clean address alone, through its own browser's nonce (P068, P114).
|
|
1094
|
+
// A door's ticket is the door's alone (P125): here it is no ticket.
|
|
1061
1095
|
if (
|
|
1062
1096
|
record !== null &&
|
|
1063
1097
|
record.entry === undefined &&
|
|
1098
|
+
record.door !== true &&
|
|
1064
1099
|
record.instance.document.kind !== "external" &&
|
|
1065
1100
|
keys.instanceKey(record.instance) === key
|
|
1066
1101
|
) {
|
|
@@ -1090,6 +1125,102 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1090
1125
|
return serveAccess(request, access, cookie, undefined, rest);
|
|
1091
1126
|
}
|
|
1092
1127
|
|
|
1128
|
+
/** A door that doesn't open (P125): its status, reason and the host's code, if any. */
|
|
1129
|
+
const doorSays = (status: number, reason: FrameBlock, method: string, code?: string): Response =>
|
|
1130
|
+
doorStatusResponse({
|
|
1131
|
+
status,
|
|
1132
|
+
reason,
|
|
1133
|
+
...(code === undefined ? {} : { code }),
|
|
1134
|
+
hostOrigins: options.hostOrigins,
|
|
1135
|
+
frameAncestors,
|
|
1136
|
+
method,
|
|
1137
|
+
});
|
|
1138
|
+
|
|
1139
|
+
/**
|
|
1140
|
+
* A served display's door (P125): its own ticket's, taken once, for this instance on this
|
|
1141
|
+
* origin; then the door's answer for that ticket's grant (`answerDoor`, the one `doorAnswer`
|
|
1142
|
+
* gives, P126). No other ticket opens it, and a nested page's shell's label serves none
|
|
1143
|
+
* (`serveShellLabel`).
|
|
1144
|
+
*/
|
|
1145
|
+
async function serveDoor(
|
|
1146
|
+
request: Request,
|
|
1147
|
+
url: URL,
|
|
1148
|
+
label: string,
|
|
1149
|
+
key: string,
|
|
1150
|
+
): Promise<Response> {
|
|
1151
|
+
const method = request.method.toUpperCase();
|
|
1152
|
+
if (method !== "GET" && method !== "HEAD") {
|
|
1153
|
+
return doorSays(405, "error", method);
|
|
1154
|
+
}
|
|
1155
|
+
let record: TicketRecord | null;
|
|
1156
|
+
try {
|
|
1157
|
+
record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
|
|
1158
|
+
if (
|
|
1159
|
+
record === null ||
|
|
1160
|
+
record.door !== true ||
|
|
1161
|
+
record.entry !== undefined ||
|
|
1162
|
+
record.instance.document.kind === "external" ||
|
|
1163
|
+
keys.instanceKey(record.instance) !== key ||
|
|
1164
|
+
compiledFor(record.instance)?.config.nested === true
|
|
1165
|
+
) {
|
|
1166
|
+
return doorSays(401, "session", method);
|
|
1167
|
+
}
|
|
1168
|
+
} catch {
|
|
1169
|
+
return doorSays(500, "error", method);
|
|
1170
|
+
}
|
|
1171
|
+
return answerDoor(
|
|
1172
|
+
request,
|
|
1173
|
+
{
|
|
1174
|
+
instance: record.instance,
|
|
1175
|
+
viewer: record.viewer,
|
|
1176
|
+
origin: originOfLabel(label),
|
|
1177
|
+
expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
|
|
1178
|
+
...(record.anonymous === true ? { anonymous: true } : {}),
|
|
1179
|
+
...(record.subject === undefined ? {} : { subject: record.subject }),
|
|
1180
|
+
},
|
|
1181
|
+
isPageRest(record.page) ? record.page : undefined,
|
|
1182
|
+
);
|
|
1183
|
+
}
|
|
1184
|
+
|
|
1185
|
+
/**
|
|
1186
|
+
* The door's answer for an access already admitted (P125, P126): the checks the content's
|
|
1187
|
+
* address runs for the same grant (the host's check, the document, its entry, the page it opens
|
|
1188
|
+
* at), so the door says what the content's address would: `open`, or `blocked` and why. It sets
|
|
1189
|
+
* no cookie and serves nothing of the content; the content's address takes its own ticket and
|
|
1190
|
+
* checks again (P050), so the door only tells. `serveDoor` answers with it once its ticket is
|
|
1191
|
+
* taken, and `doorAnswer` for a host that admitted the request itself: one answer for both.
|
|
1192
|
+
*/
|
|
1193
|
+
async function answerDoor(
|
|
1194
|
+
request: Request,
|
|
1195
|
+
access: Access,
|
|
1196
|
+
/** A page below a file set's base its frame opens at (P125). */
|
|
1197
|
+
below: string | undefined,
|
|
1198
|
+
): Promise<Response> {
|
|
1199
|
+
const method = request.method.toUpperCase();
|
|
1200
|
+
if (method !== "GET" && method !== "HEAD") {
|
|
1201
|
+
return doorSays(405, "error", method);
|
|
1202
|
+
}
|
|
1203
|
+
try {
|
|
1204
|
+
const refused = await refusalOf(request, access);
|
|
1205
|
+
if (refused !== null) {
|
|
1206
|
+
return doorSays(403, "denied", method, refused.code);
|
|
1207
|
+
}
|
|
1208
|
+
const served = await documentOf(access.instance);
|
|
1209
|
+
// The same document, entry and page checks the content's address runs (`serveAccess`).
|
|
1210
|
+
if (
|
|
1211
|
+
served === null ||
|
|
1212
|
+
("files" in served
|
|
1213
|
+
? !entryIsPage(served.files) || ticketPage(served.files, below) === null
|
|
1214
|
+
: below !== undefined)
|
|
1215
|
+
) {
|
|
1216
|
+
return doorSays(404, "not-found", method);
|
|
1217
|
+
}
|
|
1218
|
+
return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
|
|
1219
|
+
} catch {
|
|
1220
|
+
return doorSays(500, "error", method);
|
|
1221
|
+
}
|
|
1222
|
+
}
|
|
1223
|
+
|
|
1093
1224
|
/**
|
|
1094
1225
|
* The document an access opens, once the host's check lets it in: at its document's path, or
|
|
1095
1226
|
* (`at`) a path under a file set's base (P081).
|
|
@@ -1111,6 +1242,20 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1111
1242
|
if (served === null) {
|
|
1112
1243
|
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
1113
1244
|
}
|
|
1245
|
+
// A frame's document opens at its file set's entry, which is a page (P125, P124-2): a set
|
|
1246
|
+
// stored before that was checked shows Porthole's word, never an inert file that says nothing.
|
|
1247
|
+
if ("files" in served && at === undefined && !entryIsPage(served.files)) {
|
|
1248
|
+
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
1249
|
+
}
|
|
1250
|
+
// A page below a base (P125) names a file set's page: for one page alone, nothing; for a set,
|
|
1251
|
+
// the page the frame opens at (its entry, or the page it was issued for) must be one of its
|
|
1252
|
+
// pages. The door asks the same (`serveDoor`), so both say `not-found` alike.
|
|
1253
|
+
if (
|
|
1254
|
+
at === undefined &&
|
|
1255
|
+
("files" in served ? ticketPage(served.files, pageAt) === null : pageAt !== undefined)
|
|
1256
|
+
) {
|
|
1257
|
+
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
1258
|
+
}
|
|
1114
1259
|
// A nested page (P111): the address the host frames (a ticket's, a cookie's, an entered
|
|
1115
1260
|
// one's) answers Porthole's shell, which frames the page at its sealed files' address; only
|
|
1116
1261
|
// that address, below the sealed prefix, answers the page and its files, without a cookie.
|
|
@@ -1189,7 +1334,7 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1189
1334
|
compiled: served.compiled,
|
|
1190
1335
|
hostOrigins: options.hostOrigins,
|
|
1191
1336
|
frameAncestors,
|
|
1192
|
-
ticket: { expires: sealed.expires },
|
|
1337
|
+
ticket: { expires: sealed.expires, ...(pageAt === undefined ? {} : { page: pageAt }) },
|
|
1193
1338
|
...versionOf(access.instance),
|
|
1194
1339
|
});
|
|
1195
1340
|
}
|
|
@@ -1418,6 +1563,13 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1418
1563
|
*/
|
|
1419
1564
|
async function beginEntry(request: Request, url: URL, label: string, to: URL): Promise<Response> {
|
|
1420
1565
|
const method = request.method.toUpperCase();
|
|
1566
|
+
// A clean address is for a tab (P125): in a frame it never goes to the app (no authorize, no
|
|
1567
|
+
// sign-in, no refusal of the app's) and says nothing to the page that frames it, whatever it
|
|
1568
|
+
// names. A host frames what a clean address names by resolving it through `issue`.
|
|
1569
|
+
const framedAs = request.headers.get("sec-fetch-dest");
|
|
1570
|
+
if (framedAs === "iframe" || framedAs === "frame") {
|
|
1571
|
+
return tabOnlyPage(frameAncestors, method);
|
|
1572
|
+
}
|
|
1421
1573
|
// An address that names nothing is nothing here (P070): never a trip to the app's sign-in.
|
|
1422
1574
|
const scopeOf = content.name?.scopeOf;
|
|
1423
1575
|
const named = options.entry?.named;
|
|
@@ -1715,14 +1867,11 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1715
1867
|
return page(404, "Nothing here", "This address names no content.", method);
|
|
1716
1868
|
}
|
|
1717
1869
|
|
|
1718
|
-
/** A
|
|
1719
|
-
|
|
1720
|
-
|
|
1870
|
+
/** A grant, checked for an instance (`issue`'s rules, and `doorAnswer`'s, P126). */
|
|
1871
|
+
function checkGrant(
|
|
1872
|
+
clean: InstanceRef,
|
|
1721
1873
|
grant: Grant,
|
|
1722
|
-
|
|
1723
|
-
): Promise<{ readonly clean: InstanceRef; readonly key: string; readonly ticket: string }> {
|
|
1724
|
-
const clean = cleanInstance(instance);
|
|
1725
|
-
check(clean);
|
|
1874
|
+
): { readonly anonymous: boolean; readonly viewer: string } {
|
|
1726
1875
|
const anonymous = grant.anonymous === true;
|
|
1727
1876
|
if (anonymous) {
|
|
1728
1877
|
if (grant.viewer !== undefined) {
|
|
@@ -1744,15 +1893,33 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1744
1893
|
) {
|
|
1745
1894
|
throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
|
|
1746
1895
|
}
|
|
1896
|
+
return { anonymous, viewer: anonymous ? "" : (grant.viewer ?? "") };
|
|
1897
|
+
}
|
|
1898
|
+
|
|
1899
|
+
/** How long a grant's session lasts, checked (`sessionSeconds`). */
|
|
1900
|
+
const sessionOf = (grant: Grant): number =>
|
|
1901
|
+
seconds(grant.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SESSION_SECONDS, "sessionSeconds");
|
|
1902
|
+
|
|
1903
|
+
/** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
|
|
1904
|
+
async function mint(
|
|
1905
|
+
instance: InstanceRef,
|
|
1906
|
+
grant: Grant,
|
|
1907
|
+
entry?: TicketRecord["entry"],
|
|
1908
|
+
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1909
|
+
below?: string,
|
|
1910
|
+
): Promise<{
|
|
1911
|
+
readonly clean: InstanceRef;
|
|
1912
|
+
readonly key: string;
|
|
1913
|
+
readonly ticket: string;
|
|
1914
|
+
/** The door's own ticket (P125), for a display framed on its scope's origin. */
|
|
1915
|
+
readonly door: string | null;
|
|
1916
|
+
}> {
|
|
1917
|
+
const clean = cleanInstance(instance);
|
|
1918
|
+
check(clean);
|
|
1919
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
1747
1920
|
const ttl = seconds(grant.ttlSeconds, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
|
|
1748
|
-
const sessionSeconds =
|
|
1749
|
-
grant.sessionSeconds,
|
|
1750
|
-
DEFAULT_SESSION_SECONDS,
|
|
1751
|
-
MAX_SESSION_SECONDS,
|
|
1752
|
-
"sessionSeconds",
|
|
1753
|
-
);
|
|
1921
|
+
const sessionSeconds = sessionOf(grant);
|
|
1754
1922
|
const key = keys.instanceKey(clean);
|
|
1755
|
-
const viewer = anonymous ? "" : grant.viewer;
|
|
1756
1923
|
const probe = keys.sign({
|
|
1757
1924
|
i: clean,
|
|
1758
1925
|
w: viewer,
|
|
@@ -1768,7 +1935,7 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1768
1935
|
throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
|
|
1769
1936
|
}
|
|
1770
1937
|
const ticket = newTicket();
|
|
1771
|
-
|
|
1938
|
+
const record: TicketRecord = {
|
|
1772
1939
|
instance: clean,
|
|
1773
1940
|
viewer,
|
|
1774
1941
|
expiresAt: Date.now() + ttl * 1_000,
|
|
@@ -1776,8 +1943,25 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1776
1943
|
...(anonymous ? { anonymous: true } : {}),
|
|
1777
1944
|
...(grant.subject === undefined ? {} : { subject: grant.subject }),
|
|
1778
1945
|
...(entry === undefined ? {} : { entry }),
|
|
1779
|
-
|
|
1780
|
-
|
|
1946
|
+
...(below === undefined ? {} : { page: below }),
|
|
1947
|
+
};
|
|
1948
|
+
await tickets.put(ticketId(ticket), record);
|
|
1949
|
+
// A frame on its scope's origin has a door (P125): its ticket, for the same grant and as long.
|
|
1950
|
+
let door: string | null = null;
|
|
1951
|
+
if (entry === undefined && hasDoor(clean)) {
|
|
1952
|
+
door = newTicket();
|
|
1953
|
+
await tickets.put(ticketId(door), { ...record, door: true });
|
|
1954
|
+
}
|
|
1955
|
+
return { clean, key, ticket, door };
|
|
1956
|
+
}
|
|
1957
|
+
|
|
1958
|
+
/**
|
|
1959
|
+
* Whether an instance's frame has a door (P125): a document framed on its scope's origin, where
|
|
1960
|
+
* the scope's other displays run content (a served shell, a page that isn't nested, the sandbox
|
|
1961
|
+
* proxy). A nested page's frame is its shell, on a label of its own; a url-mode app has none.
|
|
1962
|
+
*/
|
|
1963
|
+
function hasDoor(instance: InstanceRef): boolean {
|
|
1964
|
+
return instance.document.kind !== "external" && compiledFor(instance)?.config.nested !== true;
|
|
1781
1965
|
}
|
|
1782
1966
|
|
|
1783
1967
|
const underDomain = (host: string): boolean => host === domain || host.endsWith(`.${domain}`);
|
|
@@ -1832,8 +2016,15 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1832
2016
|
|
|
1833
2017
|
originFor: (scope) => originOfLabel(nameOf(scope)),
|
|
1834
2018
|
|
|
1835
|
-
async issue(instance, grant): Promise<FrameLocation> {
|
|
1836
|
-
|
|
2019
|
+
async issue(instance, grant, at = {}): Promise<FrameLocation> {
|
|
2020
|
+
// A page below a file set's base (P125: what a clean address names, resolved for a frame).
|
|
2021
|
+
const below = at.page;
|
|
2022
|
+
if (below !== undefined && (!isPageRest(below) || instance.document?.kind !== "artifact")) {
|
|
2023
|
+
throw new TypeError(
|
|
2024
|
+
"A frame's page is a relative path below an artifact's files (no . or ..)",
|
|
2025
|
+
);
|
|
2026
|
+
}
|
|
2027
|
+
const { clean, key, ticket, door } = await mint(instance, grant, undefined, below);
|
|
1837
2028
|
// A nested page's frame is its shell, on the shell's own label (P114).
|
|
1838
2029
|
const origin = originOfLabel(labelFor(clean));
|
|
1839
2030
|
const path =
|
|
@@ -1842,7 +2033,46 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1842
2033
|
: `${PREFIX}d/${key}?ticket=${ticket}`;
|
|
1843
2034
|
// The viewer's level, as the host's access decided it now (P087): for the display's bridge.
|
|
1844
2035
|
const viewer = viewerOfGrant(grant);
|
|
1845
|
-
return {
|
|
2036
|
+
return {
|
|
2037
|
+
url: `${origin}${path}`,
|
|
2038
|
+
origin,
|
|
2039
|
+
reports: true,
|
|
2040
|
+
...(viewer ? { viewer } : {}),
|
|
2041
|
+
// Its door (P125): the host frames it first, and takes its word alone.
|
|
2042
|
+
...(door === null ? {} : { door: { url: `${origin}${DOOR_PATH}${key}?ticket=${door}` } }),
|
|
2043
|
+
};
|
|
2044
|
+
},
|
|
2045
|
+
|
|
2046
|
+
async doorAnswer(instance, grant, request, at = {}): Promise<Response> {
|
|
2047
|
+
// A host that admitted the request itself (P126): no ticket here, the grant is its word.
|
|
2048
|
+
const clean = cleanInstance(instance);
|
|
2049
|
+
check(clean);
|
|
2050
|
+
if (!hasDoor(clean)) {
|
|
2051
|
+
throw new TypeError(
|
|
2052
|
+
"This instance has no door (P125): a nested page's frame is its shell, a url-mode app has none",
|
|
2053
|
+
);
|
|
2054
|
+
}
|
|
2055
|
+
const below = at.page;
|
|
2056
|
+
if (below !== undefined && (!isPageRest(below) || clean.document.kind !== "artifact")) {
|
|
2057
|
+
throw new TypeError(
|
|
2058
|
+
"A frame's page is a relative path below an artifact's files (no . or ..)",
|
|
2059
|
+
);
|
|
2060
|
+
}
|
|
2061
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
2062
|
+
const sessionSeconds = sessionOf(grant);
|
|
2063
|
+
const origin = originOfLabel(labelFor(clean));
|
|
2064
|
+
return answerDoor(
|
|
2065
|
+
request ?? new Request(`${origin}${DOOR_PATH}${keys.instanceKey(clean)}`),
|
|
2066
|
+
{
|
|
2067
|
+
instance: clean,
|
|
2068
|
+
viewer,
|
|
2069
|
+
origin,
|
|
2070
|
+
expiresAt: Date.now() + sessionSeconds * 1_000,
|
|
2071
|
+
...(anonymous ? { anonymous: true } : {}),
|
|
2072
|
+
...(grant.subject === undefined ? {} : { subject: grant.subject }),
|
|
2073
|
+
},
|
|
2074
|
+
below,
|
|
2075
|
+
);
|
|
1846
2076
|
},
|
|
1847
2077
|
|
|
1848
2078
|
forget(filter = {}) {
|
|
@@ -2004,6 +2234,10 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
2004
2234
|
if (asset?.[1] !== undefined) {
|
|
2005
2235
|
return await serveAssetAt(request, label, asset[1]);
|
|
2006
2236
|
}
|
|
2237
|
+
const door = DOOR_ROUTE.exec(url.pathname);
|
|
2238
|
+
if (door?.[1] !== undefined) {
|
|
2239
|
+
return await serveDoor(request, url, label, door[1]);
|
|
2240
|
+
}
|
|
2007
2241
|
const document = DOCUMENT_PATH.exec(url.pathname);
|
|
2008
2242
|
if (document?.[1] !== undefined) {
|
|
2009
2243
|
return await serveDocument(request, url, label, document[1]);
|
package/src/server/types.ts
CHANGED
|
@@ -106,6 +106,13 @@ export interface TicketRecord {
|
|
|
106
106
|
* its files' base the shell opens (the entry page when absent).
|
|
107
107
|
*/
|
|
108
108
|
readonly page?: string;
|
|
109
|
+
/**
|
|
110
|
+
* A door's ticket (P125): `issue` mints one beside the content's, for the same grant and as
|
|
111
|
+
* long, for a display whose frame is on its scope's origin (a served shell, a page that isn't
|
|
112
|
+
* nested, the sandbox proxy). Taken only at the door (`/__porthole/door/<key>`), never at the
|
|
113
|
+
* content's address; the door takes no other.
|
|
114
|
+
*/
|
|
115
|
+
readonly door?: true;
|
|
109
116
|
}
|
|
110
117
|
|
|
111
118
|
/** Where tickets live between `issue` and their one use. Default: in memory (one process). */
|
|
@@ -326,7 +333,40 @@ export interface PortholeServer {
|
|
|
326
333
|
* Mints a one-time ticket for `instance` and returns the URL its frame loads. Call it from the
|
|
327
334
|
* host's own authenticated API, once the host has decided the viewer may see the instance.
|
|
328
335
|
*/
|
|
329
|
-
issue(
|
|
336
|
+
issue(
|
|
337
|
+
instance: InstanceRef,
|
|
338
|
+
grant: Grant,
|
|
339
|
+
/**
|
|
340
|
+
* Where in the instance its frame opens (P125): a page below a file set's base (what a clean
|
|
341
|
+
* address names, resolved by `issue` given `{ address }`). Default: its entry.
|
|
342
|
+
*/
|
|
343
|
+
at?: { readonly page?: string },
|
|
344
|
+
): Promise<FrameLocation>;
|
|
345
|
+
/**
|
|
346
|
+
* A served display's door answer for a grant the host has already admitted (P126): exactly the
|
|
347
|
+
* Response its door (`DOOR_PATH<key>`, P125) answers once it has taken its own ticket for that
|
|
348
|
+
* instance and grant. The content's address's checks for that grant run here: the host's
|
|
349
|
+
* `authorize` check (`denied`, with its code), the document and its version (`not-found`), a file
|
|
350
|
+
* set's entry being a page and the page `at` names (`not-found`). The answer is `doorResponse`
|
|
351
|
+
* (open) or `doorStatusResponse` (blocked: reason, status, code), with the door's CSP (`sandbox
|
|
352
|
+
* allow-scripts`, `frame-ancestors` the host origins), `no-store`, and no cookie.
|
|
353
|
+
*
|
|
354
|
+
* It is a function, not a route, and it never takes a ticket: it is for a host that signs its own
|
|
355
|
+
* tickets (a content Worker that verifies them itself) and answers its door with it. The caller
|
|
356
|
+
* must have authenticated the request and established the grant itself, as it does before
|
|
357
|
+
* `issue`; Porthole's own door route takes its door ticket and then answers with this. `request`
|
|
358
|
+
* is what `authorize.check` is handed (and gives the method: HEAD has no body, a method other
|
|
359
|
+
* than GET or HEAD is 405); default, a GET of the door on the instance's origin. Throws, as
|
|
360
|
+
* `issue` does, for an instance or grant `issue` would refuse, and for an instance with no door
|
|
361
|
+
* (a nested page, a url-mode app).
|
|
362
|
+
*/
|
|
363
|
+
doorAnswer(
|
|
364
|
+
instance: InstanceRef,
|
|
365
|
+
grant: Grant,
|
|
366
|
+
request?: Request,
|
|
367
|
+
/** The page below a file set's base the frame opens at, as `issue`'s `at` (P125). */
|
|
368
|
+
at?: { readonly page?: string },
|
|
369
|
+
): Promise<Response>;
|
|
330
370
|
/**
|
|
331
371
|
* The access a request's cookie carries for a url-mode app on the request's origin, or null
|
|
332
372
|
* (no good cookie, an `Origin` or `Sec-Fetch-Site` of another origin's (P101), or the host's
|
|
@@ -12,11 +12,6 @@ export function postMessageTransport(
|
|
|
12
12
|
frameWindow: () => Window | null,
|
|
13
13
|
expectedOrigin: string,
|
|
14
14
|
host: Window = window,
|
|
15
|
-
/**
|
|
16
|
-
* Another origin the frame's window may say some things from: the host's own, whose pages a
|
|
17
|
-
* served frame passes through on a redirect entry (P068), for their frame status only.
|
|
18
|
-
*/
|
|
19
|
-
also?: { readonly origin: string; readonly accept: (data: unknown) => boolean },
|
|
20
15
|
): Transport {
|
|
21
16
|
const listeners = new Set<(message: unknown) => void>();
|
|
22
17
|
let closed = false;
|
|
@@ -25,10 +20,7 @@ export function postMessageTransport(
|
|
|
25
20
|
if (closed || source === null || event.source !== source) {
|
|
26
21
|
return;
|
|
27
22
|
}
|
|
28
|
-
if (
|
|
29
|
-
event.origin !== expectedOrigin &&
|
|
30
|
-
(also === undefined || event.origin !== also.origin || !also.accept(event.data))
|
|
31
|
-
) {
|
|
23
|
+
if (event.origin !== expectedOrigin) {
|
|
32
24
|
return;
|
|
33
25
|
}
|
|
34
26
|
for (const listener of listeners) {
|