@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/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,84 @@ export function createServer(options) {
|
|
|
861
879
|
const rest = isPageRest(asked) ? asked : undefined;
|
|
862
880
|
return serveAccess(request, access, cookie, undefined, rest);
|
|
863
881
|
}
|
|
882
|
+
/** A door that doesn't open (P125): its status, reason and the host's code, if any. */
|
|
883
|
+
const doorSays = (status, reason, method, code) => doorStatusResponse({
|
|
884
|
+
status,
|
|
885
|
+
reason,
|
|
886
|
+
...(code === undefined ? {} : { code }),
|
|
887
|
+
hostOrigins: options.hostOrigins,
|
|
888
|
+
frameAncestors,
|
|
889
|
+
method,
|
|
890
|
+
});
|
|
891
|
+
/**
|
|
892
|
+
* A served display's door (P125): its own ticket's, taken once, for this instance on this
|
|
893
|
+
* origin; then the door's answer for that ticket's grant (`answerDoor`, the one `doorAnswer`
|
|
894
|
+
* gives, P126). No other ticket opens it, and a nested page's shell's label serves none
|
|
895
|
+
* (`serveShellLabel`).
|
|
896
|
+
*/
|
|
897
|
+
async function serveDoor(request, url, label, key) {
|
|
898
|
+
const method = request.method.toUpperCase();
|
|
899
|
+
if (method !== "GET" && method !== "HEAD") {
|
|
900
|
+
return doorSays(405, "error", method);
|
|
901
|
+
}
|
|
902
|
+
let record;
|
|
903
|
+
try {
|
|
904
|
+
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 doorSays(401, "session", method);
|
|
912
|
+
}
|
|
913
|
+
}
|
|
914
|
+
catch {
|
|
915
|
+
return doorSays(500, "error", method);
|
|
916
|
+
}
|
|
917
|
+
return answerDoor(request, {
|
|
918
|
+
instance: record.instance,
|
|
919
|
+
viewer: record.viewer,
|
|
920
|
+
origin: originOfLabel(label),
|
|
921
|
+
expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
|
|
922
|
+
...(record.anonymous === true ? { anonymous: true } : {}),
|
|
923
|
+
...(record.subject === undefined ? {} : { subject: record.subject }),
|
|
924
|
+
}, isPageRest(record.page) ? record.page : undefined);
|
|
925
|
+
}
|
|
926
|
+
/**
|
|
927
|
+
* The door's answer for an access already admitted (P125, P126): the checks the content's
|
|
928
|
+
* address runs for the same grant (the host's check, the document, its entry, the page it opens
|
|
929
|
+
* at), so the door says what the content's address would: `open`, or `blocked` and why. It sets
|
|
930
|
+
* no cookie and serves nothing of the content; the content's address takes its own ticket and
|
|
931
|
+
* checks again (P050), so the door only tells. `serveDoor` answers with it once its ticket is
|
|
932
|
+
* taken, and `doorAnswer` for a host that admitted the request itself: one answer for both.
|
|
933
|
+
*/
|
|
934
|
+
async function answerDoor(request, access,
|
|
935
|
+
/** A page below a file set's base its frame opens at (P125). */
|
|
936
|
+
below) {
|
|
937
|
+
const method = request.method.toUpperCase();
|
|
938
|
+
if (method !== "GET" && method !== "HEAD") {
|
|
939
|
+
return doorSays(405, "error", method);
|
|
940
|
+
}
|
|
941
|
+
try {
|
|
942
|
+
const refused = await refusalOf(request, access);
|
|
943
|
+
if (refused !== null) {
|
|
944
|
+
return doorSays(403, "denied", method, refused.code);
|
|
945
|
+
}
|
|
946
|
+
const served = await documentOf(access.instance);
|
|
947
|
+
// The same document, entry and page checks the content's address runs (`serveAccess`).
|
|
948
|
+
if (served === null ||
|
|
949
|
+
("files" in served
|
|
950
|
+
? !entryIsPage(served.files) || ticketPage(served.files, below) === null
|
|
951
|
+
: below !== undefined)) {
|
|
952
|
+
return doorSays(404, "not-found", method);
|
|
953
|
+
}
|
|
954
|
+
return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
|
|
955
|
+
}
|
|
956
|
+
catch {
|
|
957
|
+
return doorSays(500, "error", method);
|
|
958
|
+
}
|
|
959
|
+
}
|
|
864
960
|
/**
|
|
865
961
|
* The document an access opens, once the host's check lets it in: at its document's path, or
|
|
866
962
|
* (`at`) a path under a file set's base (P081).
|
|
@@ -877,6 +973,18 @@ export function createServer(options) {
|
|
|
877
973
|
if (served === null) {
|
|
878
974
|
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
879
975
|
}
|
|
976
|
+
// A frame's document opens at its file set's entry, which is a page (P125, P124-2): a set
|
|
977
|
+
// stored before that was checked shows Porthole's word, never an inert file that says nothing.
|
|
978
|
+
if ("files" in served && at === undefined && !entryIsPage(served.files)) {
|
|
979
|
+
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
980
|
+
}
|
|
981
|
+
// A page below a base (P125) names a file set's page: for one page alone, nothing; for a set,
|
|
982
|
+
// the page the frame opens at (its entry, or the page it was issued for) must be one of its
|
|
983
|
+
// pages. The door asks the same (`serveDoor`), so both say `not-found` alike.
|
|
984
|
+
if (at === undefined &&
|
|
985
|
+
("files" in served ? ticketPage(served.files, pageAt) === null : pageAt !== undefined)) {
|
|
986
|
+
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
987
|
+
}
|
|
880
988
|
// A nested page (P111): the address the host frames (a ticket's, a cookie's, an entered
|
|
881
989
|
// one's) answers Porthole's shell, which frames the page at its sealed files' address; only
|
|
882
990
|
// that address, below the sealed prefix, answers the page and its files, without a cookie.
|
|
@@ -955,7 +1063,7 @@ export function createServer(options) {
|
|
|
955
1063
|
compiled: served.compiled,
|
|
956
1064
|
hostOrigins: options.hostOrigins,
|
|
957
1065
|
frameAncestors,
|
|
958
|
-
ticket: { expires: sealed.expires },
|
|
1066
|
+
ticket: { expires: sealed.expires, ...(pageAt === undefined ? {} : { page: pageAt }) },
|
|
959
1067
|
...versionOf(access.instance),
|
|
960
1068
|
});
|
|
961
1069
|
}
|
|
@@ -1167,6 +1275,13 @@ export function createServer(options) {
|
|
|
1167
1275
|
*/
|
|
1168
1276
|
async function beginEntry(request, url, label, to) {
|
|
1169
1277
|
const method = request.method.toUpperCase();
|
|
1278
|
+
// A clean address is for a tab (P125): in a frame it never goes to the app (no authorize, no
|
|
1279
|
+
// sign-in, no refusal of the app's) and says nothing to the page that frames it, whatever it
|
|
1280
|
+
// names. A host frames what a clean address names by resolving it through `issue`.
|
|
1281
|
+
const framedAs = request.headers.get("sec-fetch-dest");
|
|
1282
|
+
if (framedAs === "iframe" || framedAs === "frame") {
|
|
1283
|
+
return tabOnlyPage(frameAncestors, method);
|
|
1284
|
+
}
|
|
1170
1285
|
// An address that names nothing is nothing here (P070): never a trip to the app's sign-in.
|
|
1171
1286
|
const scopeOf = content.name?.scopeOf;
|
|
1172
1287
|
const named = options.entry?.named;
|
|
@@ -1401,10 +1516,8 @@ export function createServer(options) {
|
|
|
1401
1516
|
}
|
|
1402
1517
|
return page(404, "Nothing here", "This address names no content.", method);
|
|
1403
1518
|
}
|
|
1404
|
-
/** A
|
|
1405
|
-
|
|
1406
|
-
const clean = cleanInstance(instance);
|
|
1407
|
-
check(clean);
|
|
1519
|
+
/** A grant, checked for an instance (`issue`'s rules, and `doorAnswer`'s, P126). */
|
|
1520
|
+
function checkGrant(clean, grant) {
|
|
1408
1521
|
const anonymous = grant.anonymous === true;
|
|
1409
1522
|
if (anonymous) {
|
|
1410
1523
|
if (grant.viewer !== undefined) {
|
|
@@ -1423,10 +1536,20 @@ export function createServer(options) {
|
|
|
1423
1536
|
(typeof grant.subject !== "string" || grant.subject.length > SUBJECT_MAX)) {
|
|
1424
1537
|
throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
|
|
1425
1538
|
}
|
|
1539
|
+
return { anonymous, viewer: anonymous ? "" : (grant.viewer ?? "") };
|
|
1540
|
+
}
|
|
1541
|
+
/** How long a grant's session lasts, checked (`sessionSeconds`). */
|
|
1542
|
+
const sessionOf = (grant) => seconds(grant.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SESSION_SECONDS, "sessionSeconds");
|
|
1543
|
+
/** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
|
|
1544
|
+
async function mint(instance, grant, entry,
|
|
1545
|
+
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1546
|
+
below) {
|
|
1547
|
+
const clean = cleanInstance(instance);
|
|
1548
|
+
check(clean);
|
|
1549
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
1426
1550
|
const ttl = seconds(grant.ttlSeconds, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
|
|
1427
|
-
const sessionSeconds =
|
|
1551
|
+
const sessionSeconds = sessionOf(grant);
|
|
1428
1552
|
const key = keys.instanceKey(clean);
|
|
1429
|
-
const viewer = anonymous ? "" : grant.viewer;
|
|
1430
1553
|
const probe = keys.sign({
|
|
1431
1554
|
i: clean,
|
|
1432
1555
|
w: viewer,
|
|
@@ -1442,7 +1565,7 @@ export function createServer(options) {
|
|
|
1442
1565
|
throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
|
|
1443
1566
|
}
|
|
1444
1567
|
const ticket = newTicket();
|
|
1445
|
-
|
|
1568
|
+
const record = {
|
|
1446
1569
|
instance: clean,
|
|
1447
1570
|
viewer,
|
|
1448
1571
|
expiresAt: Date.now() + ttl * 1_000,
|
|
@@ -1450,8 +1573,24 @@ export function createServer(options) {
|
|
|
1450
1573
|
...(anonymous ? { anonymous: true } : {}),
|
|
1451
1574
|
...(grant.subject === undefined ? {} : { subject: grant.subject }),
|
|
1452
1575
|
...(entry === undefined ? {} : { entry }),
|
|
1453
|
-
|
|
1454
|
-
|
|
1576
|
+
...(below === undefined ? {} : { page: below }),
|
|
1577
|
+
};
|
|
1578
|
+
await tickets.put(ticketId(ticket), record);
|
|
1579
|
+
// A frame on its scope's origin has a door (P125): its ticket, for the same grant and as long.
|
|
1580
|
+
let door = null;
|
|
1581
|
+
if (entry === undefined && hasDoor(clean)) {
|
|
1582
|
+
door = newTicket();
|
|
1583
|
+
await tickets.put(ticketId(door), { ...record, door: true });
|
|
1584
|
+
}
|
|
1585
|
+
return { clean, key, ticket, door };
|
|
1586
|
+
}
|
|
1587
|
+
/**
|
|
1588
|
+
* Whether an instance's frame has a door (P125): a document framed on its scope's origin, where
|
|
1589
|
+
* the scope's other displays run content (a served shell, a page that isn't nested, the sandbox
|
|
1590
|
+
* proxy). A nested page's frame is its shell, on a label of its own; a url-mode app has none.
|
|
1591
|
+
*/
|
|
1592
|
+
function hasDoor(instance) {
|
|
1593
|
+
return instance.document.kind !== "external" && compiledFor(instance)?.config.nested !== true;
|
|
1455
1594
|
}
|
|
1456
1595
|
const underDomain = (host) => host === domain || host.endsWith(`.${domain}`);
|
|
1457
1596
|
/**
|
|
@@ -1498,8 +1637,13 @@ export function createServer(options) {
|
|
|
1498
1637
|
return {
|
|
1499
1638
|
contentSource,
|
|
1500
1639
|
originFor: (scope) => originOfLabel(nameOf(scope)),
|
|
1501
|
-
async issue(instance, grant) {
|
|
1502
|
-
|
|
1640
|
+
async issue(instance, grant, at = {}) {
|
|
1641
|
+
// A page below a file set's base (P125: what a clean address names, resolved for a frame).
|
|
1642
|
+
const below = at.page;
|
|
1643
|
+
if (below !== undefined && (!isPageRest(below) || instance.document?.kind !== "artifact")) {
|
|
1644
|
+
throw new TypeError("A frame's page is a relative path below an artifact's files (no . or ..)");
|
|
1645
|
+
}
|
|
1646
|
+
const { clean, key, ticket, door } = await mint(instance, grant, undefined, below);
|
|
1503
1647
|
// A nested page's frame is its shell, on the shell's own label (P114).
|
|
1504
1648
|
const origin = originOfLabel(labelFor(clean));
|
|
1505
1649
|
const path = clean.document.kind === "external"
|
|
@@ -1507,7 +1651,37 @@ export function createServer(options) {
|
|
|
1507
1651
|
: `${PREFIX}d/${key}?ticket=${ticket}`;
|
|
1508
1652
|
// The viewer's level, as the host's access decided it now (P087): for the display's bridge.
|
|
1509
1653
|
const viewer = viewerOfGrant(grant);
|
|
1510
|
-
return {
|
|
1654
|
+
return {
|
|
1655
|
+
url: `${origin}${path}`,
|
|
1656
|
+
origin,
|
|
1657
|
+
reports: true,
|
|
1658
|
+
...(viewer ? { viewer } : {}),
|
|
1659
|
+
// Its door (P125): the host frames it first, and takes its word alone.
|
|
1660
|
+
...(door === null ? {} : { door: { url: `${origin}${DOOR_PATH}${key}?ticket=${door}` } }),
|
|
1661
|
+
};
|
|
1662
|
+
},
|
|
1663
|
+
async doorAnswer(instance, grant, request, at = {}) {
|
|
1664
|
+
// A host that admitted the request itself (P126): no ticket here, the grant is its word.
|
|
1665
|
+
const clean = cleanInstance(instance);
|
|
1666
|
+
check(clean);
|
|
1667
|
+
if (!hasDoor(clean)) {
|
|
1668
|
+
throw new TypeError("This instance has no door (P125): a nested page's frame is its shell, a url-mode app has none");
|
|
1669
|
+
}
|
|
1670
|
+
const below = at.page;
|
|
1671
|
+
if (below !== undefined && (!isPageRest(below) || clean.document.kind !== "artifact")) {
|
|
1672
|
+
throw new TypeError("A frame's page is a relative path below an artifact's files (no . or ..)");
|
|
1673
|
+
}
|
|
1674
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
1675
|
+
const sessionSeconds = sessionOf(grant);
|
|
1676
|
+
const origin = originOfLabel(labelFor(clean));
|
|
1677
|
+
return answerDoor(request ?? new Request(`${origin}${DOOR_PATH}${keys.instanceKey(clean)}`), {
|
|
1678
|
+
instance: clean,
|
|
1679
|
+
viewer,
|
|
1680
|
+
origin,
|
|
1681
|
+
expiresAt: Date.now() + sessionSeconds * 1_000,
|
|
1682
|
+
...(anonymous ? { anonymous: true } : {}),
|
|
1683
|
+
...(grant.subject === undefined ? {} : { subject: grant.subject }),
|
|
1684
|
+
}, below);
|
|
1511
1685
|
},
|
|
1512
1686
|
forget(filter = {}) {
|
|
1513
1687
|
for (const [key, each] of answers) {
|
|
@@ -1643,6 +1817,10 @@ export function createServer(options) {
|
|
|
1643
1817
|
if (asset?.[1] !== undefined) {
|
|
1644
1818
|
return await serveAssetAt(request, label, asset[1]);
|
|
1645
1819
|
}
|
|
1820
|
+
const door = DOOR_ROUTE.exec(url.pathname);
|
|
1821
|
+
if (door?.[1] !== undefined) {
|
|
1822
|
+
return await serveDoor(request, url, label, door[1]);
|
|
1823
|
+
}
|
|
1646
1824
|
const document = DOCUMENT_PATH.exec(url.pathname);
|
|
1647
1825
|
if (document?.[1] !== undefined) {
|
|
1648
1826
|
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,37 @@ 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>;
|
|
327
|
+
/**
|
|
328
|
+
* A served display's door answer for a grant the host has already admitted (P126): exactly the
|
|
329
|
+
* Response its door (`DOOR_PATH<key>`, P125) answers once it has taken its own ticket for that
|
|
330
|
+
* instance and grant. The content's address's checks for that grant run here: the host's
|
|
331
|
+
* `authorize` check (`denied`, with its code), the document and its version (`not-found`), a file
|
|
332
|
+
* set's entry being a page and the page `at` names (`not-found`). The answer is `doorResponse`
|
|
333
|
+
* (open) or `doorStatusResponse` (blocked: reason, status, code), with the door's CSP (`sandbox
|
|
334
|
+
* allow-scripts`, `frame-ancestors` the host origins), `no-store`, and no cookie.
|
|
335
|
+
*
|
|
336
|
+
* It is a function, not a route, and it never takes a ticket: it is for a host that signs its own
|
|
337
|
+
* tickets (a content Worker that verifies them itself) and answers its door with it. The caller
|
|
338
|
+
* must have authenticated the request and established the grant itself, as it does before
|
|
339
|
+
* `issue`; Porthole's own door route takes its door ticket and then answers with this. `request`
|
|
340
|
+
* is what `authorize.check` is handed (and gives the method: HEAD has no body, a method other
|
|
341
|
+
* than GET or HEAD is 405); default, a GET of the door on the instance's origin. Throws, as
|
|
342
|
+
* `issue` does, for an instance or grant `issue` would refuse, and for an instance with no door
|
|
343
|
+
* (a nested page, a url-mode app).
|
|
344
|
+
*/
|
|
345
|
+
doorAnswer(instance: InstanceRef, grant: Grant, request?: Request,
|
|
346
|
+
/** The page below a file set's base the frame opens at, as `issue`'s `at` (P125). */
|
|
347
|
+
at?: {
|
|
348
|
+
readonly page?: string;
|
|
349
|
+
}): Promise<Response>;
|
|
313
350
|
/**
|
|
314
351
|
* The access a request's cookie carries for a url-mode app on the request's origin, or null
|
|
315
352
|
* (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,79 @@ 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`.
|
|
876
|
+
|
|
877
|
+
**A host that signs its own tickets** (P126) — its server mints its own ticket for a display and its
|
|
878
|
+
content Worker verifies it, so the Worker holds no Porthole ticket when the door is asked — answers
|
|
879
|
+
the door with **`server.doorAnswer(instance, grant, request?)`**, on the object `createServer`
|
|
880
|
+
returns. Raft's shape: the Worker routes its door path (`/__porthole/door/_raft`, say), verifies
|
|
881
|
+
its own ticket (signature, single use, bound to the label and the instance, and a door's, never its
|
|
882
|
+
content's), admits the request and recovers the grant it was signed for, then returns `await
|
|
883
|
+
server.doorAnswer(instance, grant, request)`. The answer is exactly what `/server`'s own door route
|
|
884
|
+
gives once it has taken its ticket: the host's `authorize` check (`denied` with its code), the
|
|
885
|
+
document and version, a file set's entry being a page (`not-found`), `doorResponse` or
|
|
886
|
+
`doorStatusResponse` with the door's CSP and no cookie. It never takes a ticket and checks nothing
|
|
887
|
+
about the request but its method: **you must have authenticated the request and established the
|
|
888
|
+
grant yourself**, as before `issue`. Pass the request so `authorize.check` sees it, and `{ page }`
|
|
889
|
+
as the fourth argument for a frame that opens at a file set's page below its version. It throws for
|
|
890
|
+
an instance with no door (a nested page, a url-mode app) and for an instance or grant `issue` would
|
|
891
|
+
refuse. The content route still takes its own ticket and checks again (P050).
|
|
823
892
|
|
|
824
893
|
`porthole.config(kind)` is the served config while frames are served, the opaque one while they
|
|
825
894
|
aren't, and null until the meta is known, so a frame never starts opaque and then restarts
|