@botiverse/porthole 0.5.1 → 0.6.0
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/README.md +25 -0
- package/dist/bridge/bridge.js +8 -5
- package/dist/bridge/navigation.d.ts +1 -6
- package/dist/bridge/navigation.js +11 -0
- package/dist/check/check.d.ts +12 -3
- package/dist/check/check.js +54 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/lint.js +27 -10
- package/dist/check/page-source.js +1 -1
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +25 -0
- package/dist/compile/policy.d.ts +15 -0
- package/dist/compile/policy.js +32 -0
- package/dist/config/schema.d.ts +8 -0
- package/dist/config/validate.js +8 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -0
- package/dist/guide/guide.js +11 -1
- package/dist/host/create-host.js +21 -0
- package/dist/index.d.ts +6 -3
- package/dist/index.js +8 -3
- package/dist/protocol/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/shell-adapter.js +5 -1
- package/dist/server/files.d.ts +44 -0
- package/dist/server/files.js +244 -0
- package/dist/server/host.d.ts +38 -1
- package/dist/server/host.js +37 -2
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +4 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -0
- package/dist/server/server.js +287 -22
- package/dist/server/types.d.ts +49 -5
- package/dist/shell/document.d.ts +19 -0
- package/dist/shell/document.js +30 -0
- package/dist/shell/runtime.d.ts +2 -1
- package/dist/shell/runtime.js +85 -4
- package/docs/ADOPTING.md +56 -4
- package/docs/ARCHITECTURE.md +13 -3
- package/docs/DECISIONS.md +304 -4
- package/docs/DESIGN.md +31 -3
- package/package.json +1 -1
- package/src/bridge/bridge.ts +8 -5
- package/src/bridge/navigation.ts +12 -0
- package/src/check/check.ts +92 -14
- package/src/check/files.ts +384 -0
- package/src/check/lint.ts +29 -10
- package/src/check/tools.ts +50 -0
- package/src/compile/policy.ts +38 -0
- package/src/config/schema.ts +8 -0
- package/src/config/validate.ts +8 -1
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/guide.ts +20 -0
- package/src/host/create-host.ts +21 -0
- package/src/index.ts +32 -0
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/shell-adapter.ts +5 -0
- package/src/server/files.ts +312 -0
- package/src/server/host.ts +72 -3
- package/src/server/index.ts +19 -0
- package/src/server/keys.ts +53 -0
- package/src/server/server.ts +353 -24
- package/src/server/types.ts +56 -4
- package/src/shell/document.ts +53 -0
- package/src/shell/runtime.ts +85 -4
package/dist/server/server.js
CHANGED
|
@@ -6,6 +6,8 @@ import { randomBytes } from "./crypto.js";
|
|
|
6
6
|
import { isHostLabel, reservedLabels } from "./naming.js";
|
|
7
7
|
import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
|
|
8
8
|
import { libraryFile } from "./libraries.js";
|
|
9
|
+
import { ownLoad, serveFile } from "./files.js";
|
|
10
|
+
import { INERT_FILE_CSP } from "../compile/policy.js";
|
|
9
11
|
import { memoryTicketStore } from "./tickets.js";
|
|
10
12
|
/**
|
|
11
13
|
* Paths on a content origin. Porthole's own live under `/__porthole/`; on a url-mode app's origin
|
|
@@ -14,6 +16,21 @@ import { memoryTicketStore } from "./tickets.js";
|
|
|
14
16
|
const PREFIX = "/__porthole/";
|
|
15
17
|
/** A served document (shell, artifact page, sandbox proxy), by its instance's key. */
|
|
16
18
|
const DOCUMENT_PATH = /^\/__porthole\/d\/([a-z2-7]{16})$/u;
|
|
19
|
+
/**
|
|
20
|
+
* A file set's files in a frame (P083): `/__porthole/f/<sealed access>/<path>`. The access is
|
|
21
|
+
* in the path, so a frame whose engine keeps no cookie (WebKit, P025) loads them too.
|
|
22
|
+
*/
|
|
23
|
+
const FILES_PATH = /^\/__porthole\/f\/([A-Za-z0-9_-]{40,4096})(\/.*)?$/u;
|
|
24
|
+
const FILES_PREFIX = "/__porthole/f/";
|
|
25
|
+
/** How long a sealed files' address opens a page's files on its own (P083); the shell renews it. */
|
|
26
|
+
const FILES_ADDRESS_MS = 3_600_000;
|
|
27
|
+
/** Below a sealed address: where the page's shell renews it (no file has a `__porthole/` path). */
|
|
28
|
+
const RENEW_PATH = "/__porthole/renew";
|
|
29
|
+
/**
|
|
30
|
+
* A clean address's base (P081): a path ending in `/`, each segment of letters, digits and
|
|
31
|
+
* `. _ : ~ -` (nothing a CSP source or a header would read otherwise), never `.` or `..`.
|
|
32
|
+
*/
|
|
33
|
+
const BASE = /^\/(?:(?!\.{1,2}\/)[A-Za-z0-9._:~-]{1,200}\/){0,16}$/u;
|
|
17
34
|
/** Where a url-mode app's ticket is taken, before the app's own landing path. */
|
|
18
35
|
const ENTER_PATH = "/__porthole/enter";
|
|
19
36
|
/** Where a redirect entry's code is redeemed, before its clean address (P068). */
|
|
@@ -49,6 +66,9 @@ function normalHost(value, protocol) {
|
|
|
49
66
|
: host;
|
|
50
67
|
}
|
|
51
68
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
69
|
+
const isStoredFiles = (stored) => isRecord(stored) &&
|
|
70
|
+
isRecord(stored.files) &&
|
|
71
|
+
typeof stored.read === "function";
|
|
52
72
|
/** Which configs a kind of served document may be served under. */
|
|
53
73
|
const MODES = {
|
|
54
74
|
shell: ["inline", "artifact"],
|
|
@@ -357,7 +377,14 @@ export function createServer(options) {
|
|
|
357
377
|
return { html: config.shellDocument({ origins, cspMeta: false }), csp: config.csp };
|
|
358
378
|
case "artifact": {
|
|
359
379
|
const stored = await options.artifacts?.get(document.id, document.version);
|
|
360
|
-
if (stored === null || stored === undefined
|
|
380
|
+
if (stored === null || stored === undefined) {
|
|
381
|
+
return null;
|
|
382
|
+
}
|
|
383
|
+
// A version made of files (P081): served file by file under its base.
|
|
384
|
+
if (isStoredFiles(stored)) {
|
|
385
|
+
return { files: stored, compiled: config };
|
|
386
|
+
}
|
|
387
|
+
if (typeof stored.html !== "string") {
|
|
361
388
|
return null;
|
|
362
389
|
}
|
|
363
390
|
return {
|
|
@@ -379,7 +406,7 @@ export function createServer(options) {
|
|
|
379
406
|
* page that frames it; on a tab of its own, `Lax`. (Engines that keep no cookie in a cross-site
|
|
380
407
|
* frame, measured: WebKit, still get the document, which comes with the ticket's answer.)
|
|
381
408
|
*/
|
|
382
|
-
function sessionCookie(request, record,
|
|
409
|
+
function sessionCookie(request, record, at = {}) {
|
|
383
410
|
const sessionSeconds = record.sessionSeconds ?? DEFAULT_SESSION_SECONDS;
|
|
384
411
|
const session = {
|
|
385
412
|
i: record.instance,
|
|
@@ -387,7 +414,9 @@ export function createServer(options) {
|
|
|
387
414
|
x: Date.now() + sessionSeconds * 1_000,
|
|
388
415
|
...(record.anonymous === true ? { a: 1 } : {}),
|
|
389
416
|
...(record.subject === undefined ? {} : { s: record.subject }),
|
|
390
|
-
...(
|
|
417
|
+
...(at.p === undefined ? {} : { p: at.p }),
|
|
418
|
+
...(at.b === undefined ? {} : { b: at.b }),
|
|
419
|
+
...(at.k === undefined ? {} : { k: at.k }),
|
|
391
420
|
};
|
|
392
421
|
return [
|
|
393
422
|
`${cookieName(keys.instanceKey(record.instance))}=${keys.sign(session)}`,
|
|
@@ -454,16 +483,26 @@ export function createServer(options) {
|
|
|
454
483
|
}
|
|
455
484
|
return best;
|
|
456
485
|
}
|
|
457
|
-
/**
|
|
458
|
-
|
|
486
|
+
/**
|
|
487
|
+
* The access a request's cookies give to the document entered at `pathname` (P068), or to a
|
|
488
|
+
* file set's path under the base it was entered at (P081): with where the path falls under the
|
|
489
|
+
* base, or the base itself to go to (`/v/3` → `/v/3/`).
|
|
490
|
+
*/
|
|
491
|
+
function accessAtPath(request, label, url) {
|
|
492
|
+
const { pathname } = url;
|
|
459
493
|
let best = null;
|
|
460
494
|
for (const [name, value] of cookiesOf(request)) {
|
|
461
495
|
if (!ourCookie(name)) {
|
|
462
496
|
continue;
|
|
463
497
|
}
|
|
464
498
|
const session = keys.verify(value);
|
|
465
|
-
if (!isRecord(session)
|
|
466
|
-
|
|
499
|
+
if (!isRecord(session)) {
|
|
500
|
+
continue;
|
|
501
|
+
}
|
|
502
|
+
const base = typeof session.b === "string" && BASE.test(session.b) ? session.b : null;
|
|
503
|
+
const under = base !== null && pathname.startsWith(base);
|
|
504
|
+
const atBase = base !== null && `${pathname}/` === base;
|
|
505
|
+
if ((session.p !== pathname && !under && !atBase) ||
|
|
467
506
|
typeof session.w !== "string" ||
|
|
468
507
|
typeof session.x !== "number" ||
|
|
469
508
|
session.x <= Date.now() ||
|
|
@@ -480,14 +519,37 @@ export function createServer(options) {
|
|
|
480
519
|
catch {
|
|
481
520
|
continue;
|
|
482
521
|
}
|
|
483
|
-
|
|
522
|
+
// The most specific first: the path entered itself, then the longest base, then the
|
|
523
|
+
// latest to end.
|
|
524
|
+
const rank = session.p === pathname ? Number.MAX_SAFE_INTEGER : (base?.length ?? 0);
|
|
525
|
+
if (best === null ||
|
|
526
|
+
rank > best.rank ||
|
|
527
|
+
(rank === best.rank && session.x > best.access.expiresAt)) {
|
|
528
|
+
const origin = originOfLabel(label);
|
|
484
529
|
best = {
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
530
|
+
rank,
|
|
531
|
+
access: {
|
|
532
|
+
instance,
|
|
533
|
+
viewer: session.w,
|
|
534
|
+
origin,
|
|
535
|
+
expiresAt: session.x,
|
|
536
|
+
...(session.a === 1 ? { anonymous: true } : {}),
|
|
537
|
+
...(typeof session.s === "string" ? { subject: session.s } : {}),
|
|
538
|
+
},
|
|
539
|
+
...(base !== null && under
|
|
540
|
+
? {
|
|
541
|
+
at: {
|
|
542
|
+
base,
|
|
543
|
+
rest: pathname.slice(base.length),
|
|
544
|
+
search: url.search,
|
|
545
|
+
pinned: session.k === 1,
|
|
546
|
+
source: new URL(base, origin).href,
|
|
547
|
+
},
|
|
548
|
+
}
|
|
549
|
+
: {}),
|
|
550
|
+
...(base !== null && atBase && session.p !== pathname
|
|
551
|
+
? { redirect: `${origin}${base}${url.search}` }
|
|
552
|
+
: {}),
|
|
491
553
|
};
|
|
492
554
|
}
|
|
493
555
|
}
|
|
@@ -520,6 +582,103 @@ export function createServer(options) {
|
|
|
520
582
|
"x-robots-tag": "noindex, nofollow",
|
|
521
583
|
});
|
|
522
584
|
}
|
|
585
|
+
/**
|
|
586
|
+
* A file set's file in a frame (P083): the sealed access in its path opens it, once it holds
|
|
587
|
+
* for this origin and the host's check lets it in; every path under it is the same version's.
|
|
588
|
+
*/
|
|
589
|
+
/** A files' address for an access (P083): sealed, its own end within the session's. */
|
|
590
|
+
async function sealFiles(access) {
|
|
591
|
+
const expires = Math.min(access.expiresAt, Date.now() + FILES_ADDRESS_MS);
|
|
592
|
+
const token = await keys.seal({
|
|
593
|
+
i: access.instance,
|
|
594
|
+
w: access.viewer,
|
|
595
|
+
x: expires,
|
|
596
|
+
e: access.expiresAt,
|
|
597
|
+
...(access.anonymous === true ? { a: 1 } : {}),
|
|
598
|
+
...(access.subject === undefined ? {} : { s: access.subject }),
|
|
599
|
+
});
|
|
600
|
+
return { base: `${FILES_PREFIX}${token}/`, expires };
|
|
601
|
+
}
|
|
602
|
+
/**
|
|
603
|
+
* A file set's file in a frame (P083): the sealed access in its path opens it, once it holds
|
|
604
|
+
* for this origin and the host's check lets it in; every path under it is the same version's.
|
|
605
|
+
* The address opens on its own for an hour (its `x`); after that, until the session's end (its
|
|
606
|
+
* `e`), only the running page's own loads (same-origin, not a navigation), from addresses it
|
|
607
|
+
* already holds, while its shell renews the address (`__porthole/renew`).
|
|
608
|
+
*/
|
|
609
|
+
async function serveSealed(request, url, label, token, rest) {
|
|
610
|
+
const method = request.method.toUpperCase();
|
|
611
|
+
const origin = originOfLabel(label);
|
|
612
|
+
const base = `${FILES_PREFIX}${token}/`;
|
|
613
|
+
if (rest === undefined) {
|
|
614
|
+
return new Response(null, {
|
|
615
|
+
status: 307,
|
|
616
|
+
headers: { location: `${origin}${base}${url.search}`, "cache-control": "no-store" },
|
|
617
|
+
});
|
|
618
|
+
}
|
|
619
|
+
const session = await keys.unseal(token);
|
|
620
|
+
const now = Date.now();
|
|
621
|
+
let instance = null;
|
|
622
|
+
let end = 0;
|
|
623
|
+
if (isRecord(session) &&
|
|
624
|
+
typeof session.w === "string" &&
|
|
625
|
+
typeof session.x === "number" &&
|
|
626
|
+
typeof session.e === "number" &&
|
|
627
|
+
(session.s === undefined || typeof session.s === "string")) {
|
|
628
|
+
end = session.e;
|
|
629
|
+
const open = session.x > now || (session.e > now && ownLoad(request));
|
|
630
|
+
try {
|
|
631
|
+
const clean = cleanInstance(session.i);
|
|
632
|
+
instance =
|
|
633
|
+
open && clean.document.kind === "artifact" && nameOf(clean.scope) === label
|
|
634
|
+
? clean
|
|
635
|
+
: null;
|
|
636
|
+
}
|
|
637
|
+
catch {
|
|
638
|
+
instance = null;
|
|
639
|
+
}
|
|
640
|
+
}
|
|
641
|
+
if (instance === null || !isRecord(session)) {
|
|
642
|
+
return page(401, "This has ended", "Content here opens for a while. Open it again from the app that showed it.", method, "session");
|
|
643
|
+
}
|
|
644
|
+
const access = {
|
|
645
|
+
instance,
|
|
646
|
+
viewer: session.w,
|
|
647
|
+
origin,
|
|
648
|
+
expiresAt: end,
|
|
649
|
+
...(session.a === 1 ? { anonymous: true } : {}),
|
|
650
|
+
...(typeof session.s === "string" ? { subject: session.s } : {}),
|
|
651
|
+
};
|
|
652
|
+
if (rest === RENEW_PATH) {
|
|
653
|
+
// Only the page itself renews its address, while its session lasts and the host lets it.
|
|
654
|
+
if (method !== "GET" || !ownLoad(request)) {
|
|
655
|
+
return page(403, "Not allowed", "Only the page renews its own address.", method);
|
|
656
|
+
}
|
|
657
|
+
const refusal = await denied(request, access);
|
|
658
|
+
if (refusal !== null) {
|
|
659
|
+
return refusal;
|
|
660
|
+
}
|
|
661
|
+
const renewed = await sealFiles(access);
|
|
662
|
+
return Response.json({ base: `${origin}${renewed.base}`, expires: renewed.expires }, {
|
|
663
|
+
headers: {
|
|
664
|
+
"cache-control": "no-store",
|
|
665
|
+
"x-content-type-options": "nosniff",
|
|
666
|
+
"cross-origin-resource-policy": "same-origin",
|
|
667
|
+
"content-security-policy": `${INERT_FILE_CSP}; frame-ancestors ${frameAncestors}`,
|
|
668
|
+
"referrer-policy": "no-referrer",
|
|
669
|
+
},
|
|
670
|
+
});
|
|
671
|
+
}
|
|
672
|
+
return serveAccess(request, access, null, {
|
|
673
|
+
base,
|
|
674
|
+
rest: rest.slice(1),
|
|
675
|
+
search: url.search,
|
|
676
|
+
pinned: true,
|
|
677
|
+
// Every frame's files on this origin share the prefix (the scope's, P082): a page knows
|
|
678
|
+
// only its own access.
|
|
679
|
+
source: `${origin}${FILES_PREFIX}`,
|
|
680
|
+
});
|
|
681
|
+
}
|
|
523
682
|
async function serveDocument(request, url, label, key) {
|
|
524
683
|
const method = request.method.toUpperCase();
|
|
525
684
|
if (method !== "GET" && method !== "HEAD") {
|
|
@@ -549,8 +708,11 @@ export function createServer(options) {
|
|
|
549
708
|
}
|
|
550
709
|
return serveAccess(request, access, cookie);
|
|
551
710
|
}
|
|
552
|
-
/**
|
|
553
|
-
|
|
711
|
+
/**
|
|
712
|
+
* The document an access opens, once the host's check lets it in: at its document's path, or
|
|
713
|
+
* (`at`) a path under a file set's base (P081).
|
|
714
|
+
*/
|
|
715
|
+
async function serveAccess(request, access, cookie, at) {
|
|
554
716
|
const method = request.method.toUpperCase();
|
|
555
717
|
const refusal = await denied(request, access);
|
|
556
718
|
if (refusal !== null) {
|
|
@@ -560,6 +722,45 @@ export function createServer(options) {
|
|
|
560
722
|
if (served === null) {
|
|
561
723
|
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
562
724
|
}
|
|
725
|
+
if ("files" in served) {
|
|
726
|
+
if (at !== undefined) {
|
|
727
|
+
return serveFile({
|
|
728
|
+
request,
|
|
729
|
+
set: served.files,
|
|
730
|
+
rest: at.rest,
|
|
731
|
+
search: at.search,
|
|
732
|
+
base: at.base,
|
|
733
|
+
origin: access.origin,
|
|
734
|
+
pinned: at.pinned,
|
|
735
|
+
source: at.source,
|
|
736
|
+
compiled: served.compiled,
|
|
737
|
+
hostOrigins: options.hostOrigins,
|
|
738
|
+
frameAncestors,
|
|
739
|
+
});
|
|
740
|
+
}
|
|
741
|
+
// A frame's document (a ticket's): its files carry its access in their path (P083). The
|
|
742
|
+
// entry comes in the ticket's own answer (P025), its shell moving the frame to its address
|
|
743
|
+
// there before anything loads, and renewing it before it ends.
|
|
744
|
+
const sealed = await sealFiles(access);
|
|
745
|
+
return serveFile({
|
|
746
|
+
request,
|
|
747
|
+
set: served.files,
|
|
748
|
+
rest: "",
|
|
749
|
+
search: "",
|
|
750
|
+
base: sealed.base,
|
|
751
|
+
origin: access.origin,
|
|
752
|
+
pinned: true,
|
|
753
|
+
source: `${access.origin}${FILES_PREFIX}`,
|
|
754
|
+
compiled: served.compiled,
|
|
755
|
+
hostOrigins: options.hostOrigins,
|
|
756
|
+
frameAncestors,
|
|
757
|
+
ticket: { expires: sealed.expires },
|
|
758
|
+
});
|
|
759
|
+
}
|
|
760
|
+
// One page at a file set's base (P081): its base is the page, nothing under it is.
|
|
761
|
+
if (at !== undefined && at.rest !== "") {
|
|
762
|
+
return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
|
|
763
|
+
}
|
|
563
764
|
const headers = documentHeaders(served.csp);
|
|
564
765
|
if (cookie !== null) {
|
|
565
766
|
headers.set("set-cookie", cookie);
|
|
@@ -580,6 +781,22 @@ export function createServer(options) {
|
|
|
580
781
|
(named !== undefined && !(await named(label, url.pathname, request)))) {
|
|
581
782
|
return page(404, "Nothing here", "This address names no content.", method);
|
|
582
783
|
}
|
|
784
|
+
// Only a page opening is sent to sign in (a browser's navigation; a client that sends no fetch
|
|
785
|
+
// metadata may be one): a browser's subresource without a session is refused here, with no
|
|
786
|
+
// state of its own (no nonce cookie, nothing cached).
|
|
787
|
+
const mode = request.headers.get("sec-fetch-mode");
|
|
788
|
+
const dest = request.headers.get("sec-fetch-dest") ?? "";
|
|
789
|
+
if (mode !== null && mode !== "navigate" && !["document", "iframe", "frame"].includes(dest)) {
|
|
790
|
+
return new Response(method === "HEAD" ? null : "Open this address in a browser.", {
|
|
791
|
+
status: 401,
|
|
792
|
+
headers: {
|
|
793
|
+
"content-type": "text/plain; charset=utf-8",
|
|
794
|
+
"cache-control": "no-store",
|
|
795
|
+
"x-content-type-options": "nosniff",
|
|
796
|
+
"x-robots-tag": "noindex, nofollow",
|
|
797
|
+
},
|
|
798
|
+
});
|
|
799
|
+
}
|
|
583
800
|
if (method !== "GET" && method !== "HEAD") {
|
|
584
801
|
return page(401, "Open this from the app", "Open this address in a browser.", method, "session");
|
|
585
802
|
}
|
|
@@ -634,7 +851,7 @@ export function createServer(options) {
|
|
|
634
851
|
if (record?.entry === undefined) {
|
|
635
852
|
return page(403, "This sign-in link has been used", "It works once, for a short time. Open the address again.", method, "session");
|
|
636
853
|
}
|
|
637
|
-
const { nonce, path } = record.entry;
|
|
854
|
+
const { nonce, path, base, pinned } = record.entry;
|
|
638
855
|
const named = nonceCookie(nonce);
|
|
639
856
|
if (!cookiesOf(request).some(([name, value]) => name === named && value === "1")) {
|
|
640
857
|
return page(401, "Open this in a new tab", "This browser keeps no sign-in for it inside a frame.", method, "cookies");
|
|
@@ -660,7 +877,13 @@ export function createServer(options) {
|
|
|
660
877
|
"referrer-policy": "no-referrer",
|
|
661
878
|
"x-robots-tag": "noindex, nofollow",
|
|
662
879
|
});
|
|
663
|
-
|
|
880
|
+
// A file set's address (P081): the session serves every path under its base, the version's
|
|
881
|
+
// own address. Else the path it was entered at, alone (P068).
|
|
882
|
+
headers.append("set-cookie", sessionCookie(request, record, external
|
|
883
|
+
? {}
|
|
884
|
+
: base !== undefined
|
|
885
|
+
? { b: base, ...(pinned === true ? { k: 1 } : {}) }
|
|
886
|
+
: { p: target.pathname }));
|
|
664
887
|
headers.append("set-cookie", [
|
|
665
888
|
`${named}=${enteredMark(target.pathname)}`,
|
|
666
889
|
"Path=/",
|
|
@@ -792,6 +1015,9 @@ export function createServer(options) {
|
|
|
792
1015
|
...(anonymous ? { a: 1 } : {}),
|
|
793
1016
|
...(grant.subject === undefined ? {} : { s: grant.subject }),
|
|
794
1017
|
...(entry === undefined ? {} : { p: entry.path }),
|
|
1018
|
+
...(entry?.base === undefined
|
|
1019
|
+
? {}
|
|
1020
|
+
: { b: entry.base, ...(entry.pinned === true ? { k: 1 } : {}) }),
|
|
795
1021
|
});
|
|
796
1022
|
if (cookieName(key).length + probe.length + 120 > MAX_COOKIE_BYTES) {
|
|
797
1023
|
throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
|
|
@@ -897,7 +1123,7 @@ export function createServer(options) {
|
|
|
897
1123
|
expired: state.x <= Date.now(),
|
|
898
1124
|
};
|
|
899
1125
|
},
|
|
900
|
-
async enterBy(state, instance, grant) {
|
|
1126
|
+
async enterBy(state, instance, grant, address) {
|
|
901
1127
|
if (state.expired) {
|
|
902
1128
|
throw new TypeError("This entry's state has expired: start again from the clean address");
|
|
903
1129
|
}
|
|
@@ -905,9 +1131,38 @@ export function createServer(options) {
|
|
|
905
1131
|
if (nameOf(clean.scope) !== state.label) {
|
|
906
1132
|
throw new TypeError("The instance isn't served on the address the entry began at");
|
|
907
1133
|
}
|
|
1134
|
+
let path = state.path;
|
|
1135
|
+
if (address !== undefined) {
|
|
1136
|
+
// A file set's own address (P081): a path ending in /, not Porthole's own. An address
|
|
1137
|
+
// that isn't under it (the latest's) goes to the same file under it, which must stay
|
|
1138
|
+
// under it: no dot segment, no backslash, nothing the URL parser would resolve away.
|
|
1139
|
+
const { base, file = "" } = address;
|
|
1140
|
+
const segments = typeof file === "string" ? file.split("/") : [];
|
|
1141
|
+
if (typeof base !== "string" ||
|
|
1142
|
+
!BASE.test(base) ||
|
|
1143
|
+
base.startsWith(PREFIX) ||
|
|
1144
|
+
typeof file !== "string" ||
|
|
1145
|
+
file.length > MAX_PATH ||
|
|
1146
|
+
file.startsWith("/") ||
|
|
1147
|
+
// oxlint-disable-next-line no-control-regex -- control characters are what it refuses
|
|
1148
|
+
/[?#\\\u0000-\u001f\u007f]/u.test(file) ||
|
|
1149
|
+
segments.some((each) => /^(?:\.|%2e){1,2}$/iu.test(each))) {
|
|
1150
|
+
throw new TypeError("An entry's base is a path ending in / (not Porthole's own), its file a relative path below it");
|
|
1151
|
+
}
|
|
1152
|
+
const asked = new URL(state.path, "https://x.invalid");
|
|
1153
|
+
if (!asked.pathname.startsWith(base)) {
|
|
1154
|
+
path = `${base}${file}${asked.search}`;
|
|
1155
|
+
}
|
|
1156
|
+
if (!new URL(path, "https://x.invalid").pathname.startsWith(base)) {
|
|
1157
|
+
throw new TypeError("An entry's file must stay below its base");
|
|
1158
|
+
}
|
|
1159
|
+
}
|
|
908
1160
|
const { ticket } = await mint(clean, { ...grant, ttlSeconds: ENTRY_CODE_SECONDS }, {
|
|
909
|
-
path
|
|
1161
|
+
path,
|
|
910
1162
|
nonce: state.nonce,
|
|
1163
|
+
...(address === undefined
|
|
1164
|
+
? {}
|
|
1165
|
+
: { base: address.base, ...(address.pinned === true ? { pinned: true } : {}) }),
|
|
911
1166
|
});
|
|
912
1167
|
return `${originOfLabel(state.label)}${ENTRY_PATH}?code=${ticket}`;
|
|
913
1168
|
},
|
|
@@ -953,14 +1208,24 @@ export function createServer(options) {
|
|
|
953
1208
|
if (document?.[1] !== undefined) {
|
|
954
1209
|
return await serveDocument(request, url, label, document[1]);
|
|
955
1210
|
}
|
|
1211
|
+
const sealed = FILES_PATH.exec(url.pathname);
|
|
1212
|
+
if (sealed?.[1] !== undefined) {
|
|
1213
|
+
return await serveSealed(request, url, label, sealed[1], sealed[2]);
|
|
1214
|
+
}
|
|
956
1215
|
if (url.pathname.startsWith(PREFIX)) {
|
|
957
1216
|
return page(404, "Nothing here", "This address names no content.", method);
|
|
958
1217
|
}
|
|
959
1218
|
// A clean address (P068): the document entered here, else the app, else entry.
|
|
960
1219
|
if (authorizeUrl !== null) {
|
|
961
|
-
const entered = accessAtPath(request, label, url
|
|
1220
|
+
const entered = accessAtPath(request, label, url);
|
|
1221
|
+
if (entered?.redirect !== undefined) {
|
|
1222
|
+
return new Response(null, {
|
|
1223
|
+
status: 307,
|
|
1224
|
+
headers: { location: entered.redirect, "cache-control": "no-store" },
|
|
1225
|
+
});
|
|
1226
|
+
}
|
|
962
1227
|
if (entered !== null) {
|
|
963
|
-
return await serveAccess(request, entered, null);
|
|
1228
|
+
return await serveAccess(request, entered.access, null, entered.at);
|
|
964
1229
|
}
|
|
965
1230
|
if (options.upstream === undefined || accessOf(request, label, null) === null) {
|
|
966
1231
|
return await beginEntry(request, url, label, authorizeUrl);
|
package/dist/server/types.d.ts
CHANGED
|
@@ -75,6 +75,10 @@ export interface TicketRecord {
|
|
|
75
75
|
readonly entry?: {
|
|
76
76
|
readonly path: string;
|
|
77
77
|
readonly nonce: string;
|
|
78
|
+
/** A file set's version's own address (P081): the session serves every path under it. */
|
|
79
|
+
readonly base?: string;
|
|
80
|
+
/** Whether that address names this version and no other: its files are immutable there. */
|
|
81
|
+
readonly pinned?: boolean;
|
|
78
82
|
};
|
|
79
83
|
}
|
|
80
84
|
/** Where tickets live between `issue` and their one use. Default: in memory (one process). */
|
|
@@ -83,11 +87,44 @@ export interface TicketStore {
|
|
|
83
87
|
/** Returns the ticket once and never again (atomically), or null if unknown or expired. */
|
|
84
88
|
take(id: string): Promise<TicketRecord | null>;
|
|
85
89
|
}
|
|
90
|
+
/** One file of a version (P081), as the host stored it when the version was published. */
|
|
91
|
+
export interface StoredFile {
|
|
92
|
+
/** Its length, bytes. */
|
|
93
|
+
readonly size: number;
|
|
94
|
+
/** The SHA-256 of its bytes, lowercase hex: its strong ETag. */
|
|
95
|
+
readonly sha256: string;
|
|
96
|
+
/**
|
|
97
|
+
* The type it was published with, for the host's own use (a file list): never served. A file
|
|
98
|
+
* is served with the type Porthole's table gives its extension (`fileTypeOf`), never sniffed.
|
|
99
|
+
*/
|
|
100
|
+
readonly type?: string;
|
|
101
|
+
}
|
|
102
|
+
/** A file's bytes, whole: `/server` cuts the range a request asks for. */
|
|
103
|
+
export type FileBody = Uint8Array | ReadableStream<Uint8Array>;
|
|
104
|
+
/**
|
|
105
|
+
* A version made of files (P081): a manifest, and the bytes of each file by its path. Paths
|
|
106
|
+
* follow `checkFileSet`'s rules (check them when the version is published); a request is looked
|
|
107
|
+
* up in `files` only, and `read` is asked only for a path in it.
|
|
108
|
+
*/
|
|
109
|
+
export interface StoredFiles {
|
|
110
|
+
readonly files: Readonly<Record<string, StoredFile>>;
|
|
111
|
+
/** The page the version opens at: one of `files` (default `index.html`). */
|
|
112
|
+
readonly entry?: string;
|
|
113
|
+
/**
|
|
114
|
+
* A single-page app's routes: a navigation whose path finds no file answers the entry, where
|
|
115
|
+
* it would get the nearest `404.html` (default false). Subresources still 404.
|
|
116
|
+
*/
|
|
117
|
+
readonly spa?: boolean;
|
|
118
|
+
/** The bytes of a file in `files`; null if they are gone (a 404). */
|
|
119
|
+
read(path: string): Promise<FileBody | null>;
|
|
120
|
+
}
|
|
121
|
+
/** A stored version: one page (`{ html }`, as in 0.5), or a set of files (P081). */
|
|
122
|
+
export type StoredVersion = {
|
|
123
|
+
readonly html: string;
|
|
124
|
+
} | StoredFiles;
|
|
86
125
|
/** Stored pages (artifact mode). Versions are immutable: a new page is a new version. */
|
|
87
126
|
export interface ArtifactStore {
|
|
88
|
-
get(id: string, version: string): Promise<
|
|
89
|
-
readonly html: string;
|
|
90
|
-
} | null>;
|
|
127
|
+
get(id: string, version: string): Promise<StoredVersion | null>;
|
|
91
128
|
}
|
|
92
129
|
/** What a request's cookie lets in: one instance, for one viewer, on one origin, until a time. */
|
|
93
130
|
export interface Access {
|
|
@@ -219,7 +256,14 @@ export interface PortholeServer {
|
|
|
219
256
|
entryState(token: string): EntryState | null;
|
|
220
257
|
/**
|
|
221
258
|
* Once the host decided (its authorize route): a one-time code for `instance`, which must be
|
|
222
|
-
* served on the state's label, and the URL that redeems it there (`/__porthole/entry`).
|
|
259
|
+
* served on the state's label, and the URL that redeems it there (`/__porthole/entry`). With an
|
|
260
|
+
* `address` (a file set's, P081: `entry.at`'s `base` and `file`), the session it buys serves
|
|
261
|
+
* every path under `base`, and the redeem goes to `base` + `file` when the state's path isn't
|
|
262
|
+
* under it (a "latest" address goes to the version's own).
|
|
223
263
|
*/
|
|
224
|
-
enterBy(state: EntryState, instance: InstanceRef, grant: Grant
|
|
264
|
+
enterBy(state: EntryState, instance: InstanceRef, grant: Grant, address?: {
|
|
265
|
+
readonly base: string;
|
|
266
|
+
readonly file?: string;
|
|
267
|
+
readonly pinned?: boolean;
|
|
268
|
+
}): Promise<string>;
|
|
225
269
|
}
|
package/dist/shell/document.d.ts
CHANGED
|
@@ -27,6 +27,25 @@ export interface ShellDocumentOptions {
|
|
|
27
27
|
* every script the shell runs for the content. The frame can read it.
|
|
28
28
|
*/
|
|
29
29
|
readonly nonce?: string;
|
|
30
|
+
/**
|
|
31
|
+
* A page that comes with files (P081, P084): the absolute URL its version's files are under
|
|
32
|
+
* (`https://a-x.example-usercontent.com/v/3/`). The shell lets the frame navigate to the set's
|
|
33
|
+
* other pages there, and to nothing else.
|
|
34
|
+
*/
|
|
35
|
+
readonly files?: {
|
|
36
|
+
readonly base: string;
|
|
37
|
+
/**
|
|
38
|
+
* The page's own address under `base`, where the request's isn't it (a ticket's answer, P083):
|
|
39
|
+
* the shell puts it in the frame's history first, before anything loads, so the page's
|
|
40
|
+
* relative addresses are its files' and the spent ticket leaves the address.
|
|
41
|
+
*/
|
|
42
|
+
readonly address?: string;
|
|
43
|
+
/**
|
|
44
|
+
* When a sealed address stops opening the page's files on its own (epoch ms, P083): the shell
|
|
45
|
+
* renews it before then, at `<base>__porthole/renew`, and moves the page there.
|
|
46
|
+
*/
|
|
47
|
+
readonly expires?: number;
|
|
48
|
+
};
|
|
30
49
|
}
|
|
31
50
|
/**
|
|
32
51
|
* The frame's document: its policy first, then the base styles, an empty root, and the runtime.
|
package/dist/shell/document.js
CHANGED
|
@@ -1,6 +1,20 @@
|
|
|
1
1
|
import { hostOriginProblem } from "../isolation/served.js";
|
|
2
2
|
import { ANNOTATE_RUNTIME } from "./annotate.js";
|
|
3
3
|
import { SHELL_RUNTIME } from "./runtime.js";
|
|
4
|
+
/** A file set's base: an absolute http(s) URL that ends in `/`, no query or fragment. */
|
|
5
|
+
function filesBaseOk(base) {
|
|
6
|
+
try {
|
|
7
|
+
const url = new URL(base);
|
|
8
|
+
return ((url.protocol === "https:" || url.protocol === "http:") &&
|
|
9
|
+
url.href === base &&
|
|
10
|
+
base.endsWith("/") &&
|
|
11
|
+
url.search === "" &&
|
|
12
|
+
url.hash === "");
|
|
13
|
+
}
|
|
14
|
+
catch {
|
|
15
|
+
return false;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
4
18
|
/** A CSP nonce: base64 or base64url characters, 8 to 256 of them. */
|
|
5
19
|
const NONCE = /^[A-Za-z0-9+/_=-]{8,256}$/u;
|
|
6
20
|
const escapeAttribute = (value) => value.replace(/&/gu, "&").replace(/"/gu, """).replace(/</gu, "<");
|
|
@@ -58,6 +72,13 @@ export function shellDocument(plan, csp, options) {
|
|
|
58
72
|
if (options.nonce !== undefined && !NONCE.test(options.nonce)) {
|
|
59
73
|
throw new TypeError("shellDocument: a nonce is 8 to 256 base64 characters");
|
|
60
74
|
}
|
|
75
|
+
if (options.files !== undefined && !filesBaseOk(options.files.base)) {
|
|
76
|
+
throw new TypeError("shellDocument: files.base is an http(s) URL ending in /, with no query");
|
|
77
|
+
}
|
|
78
|
+
if (options.files?.address !== undefined &&
|
|
79
|
+
(!options.files.address.startsWith(options.files.base) || /[?#]/u.test(options.files.address))) {
|
|
80
|
+
throw new TypeError("shellDocument: files.address is under files.base, with no query");
|
|
81
|
+
}
|
|
61
82
|
const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
|
|
62
83
|
// The annotation runtime only where it is declared; spliced in before the plan, which may carry
|
|
63
84
|
// any text (a document) and must not be searched.
|
|
@@ -65,6 +86,15 @@ export function shellDocument(plan, csp, options) {
|
|
|
65
86
|
...plan,
|
|
66
87
|
origins: options.origins,
|
|
67
88
|
...(options.document === undefined ? {} : { document: options.document }),
|
|
89
|
+
...(options.files === undefined
|
|
90
|
+
? {}
|
|
91
|
+
: {
|
|
92
|
+
files: {
|
|
93
|
+
base: options.files.base,
|
|
94
|
+
...(options.files.address === undefined ? {} : { address: options.files.address }),
|
|
95
|
+
...(options.files.expires === undefined ? {} : { expires: options.files.expires }),
|
|
96
|
+
},
|
|
97
|
+
}),
|
|
68
98
|
}));
|
|
69
99
|
const head = [
|
|
70
100
|
'<meta charset="utf-8">',
|
package/dist/shell/runtime.d.ts
CHANGED
|
@@ -20,7 +20,8 @@
|
|
|
20
20
|
* 6. cancels every navigation the frame starts to another document (P079), before it sends a
|
|
21
21
|
* request: a navigation carries data out in its URL, and the embedding page's `frame-src`,
|
|
22
22
|
* the wall for that, must let served frames reach their own content origins. (Opaque frames
|
|
23
|
-
* get no navigate events: there `frame-src` is the wall.)
|
|
23
|
+
* get no navigate events: there `frame-src` is the wall.) A page that comes with files may
|
|
24
|
+
* open its set's other pages, under its version's own address, and nothing else (P084).
|
|
24
25
|
* A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
|
|
25
26
|
* imported, and its scripts run in order, as a fragment's are.
|
|
26
27
|
*
|