@botiverse/porthole 0.14.6 → 0.14.8
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 +60 -0
- package/dist/check/files.js +2 -0
- package/dist/check/lint.js +82 -3
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +17 -6
- package/dist/compile/policy.js +22 -7
- package/dist/config/schema.d.ts +13 -0
- package/dist/config/validate.js +15 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/kit.d.ts +5 -0
- package/dist/conformance/kit.js +21 -0
- package/dist/conformance/limits.js +10 -5
- package/dist/conformance/probes.js +139 -28
- package/dist/conformance/served.js +43 -14
- package/dist/guide/limits.js +8 -1
- package/dist/host/create-host.js +35 -4
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +6 -0
- package/dist/server/files.js +4 -3
- package/dist/server/index.js +2 -1
- package/dist/server/server.js +89 -37
- package/dist/server/types.d.ts +23 -0
- package/dist/shell/plan.d.ts +5 -0
- package/dist/shell/plan.js +2 -0
- package/dist/shell/runtime.d.ts +30 -1
- package/dist/shell/runtime.js +785 -104
- package/docs/ADOPTING.md +36 -0
- package/docs/DECISIONS.md +341 -0
- package/docs/DESIGN.md +7 -4
- package/docs/THREAT_MODEL.md +30 -5
- package/docs/insertion-entry-points.md +95 -0
- package/package.json +1 -1
- package/src/check/files.ts +2 -0
- package/src/check/lint.ts +97 -8
- package/src/compile/policy.ts +23 -6
- package/src/config/schema.ts +13 -0
- package/src/config/validate.ts +16 -0
- package/src/conformance/kit.ts +22 -0
- package/src/conformance/limits.ts +10 -5
- package/src/conformance/probes.ts +149 -28
- package/src/conformance/served.ts +43 -14
- package/src/guide/limits.ts +9 -1
- package/src/host/create-host.ts +37 -4
- package/src/index.ts +1 -0
- package/src/presets/presets.ts +15 -0
- package/src/server/files.ts +8 -2
- package/src/server/index.ts +2 -1
- package/src/server/server.ts +116 -46
- package/src/server/types.ts +25 -0
- package/src/shell/plan.ts +7 -0
- package/src/shell/runtime.ts +788 -104
package/dist/server/server.js
CHANGED
|
@@ -879,62 +879,82 @@ export function createServer(options) {
|
|
|
879
879
|
const rest = isPageRest(asked) ? asked : undefined;
|
|
880
880
|
return serveAccess(request, access, cookie, undefined, rest);
|
|
881
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
|
+
});
|
|
882
891
|
/**
|
|
883
892
|
* A served display's door (P125): its own ticket's, taken once, for this instance on this
|
|
884
|
-
* origin
|
|
885
|
-
*
|
|
886
|
-
*
|
|
887
|
-
* own ticket and checks again (P050), so the door only tells. No other ticket opens it, and a
|
|
888
|
-
* nested page's shell's label serves none (`serveShellLabel`).
|
|
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`).
|
|
889
896
|
*/
|
|
890
897
|
async function serveDoor(request, url, label, key) {
|
|
891
898
|
const method = request.method.toUpperCase();
|
|
892
|
-
const say = (status, reason, code) => doorStatusResponse({
|
|
893
|
-
status,
|
|
894
|
-
reason,
|
|
895
|
-
...(code === undefined ? {} : { code }),
|
|
896
|
-
hostOrigins: options.hostOrigins,
|
|
897
|
-
frameAncestors,
|
|
898
|
-
method,
|
|
899
|
-
});
|
|
900
899
|
if (method !== "GET" && method !== "HEAD") {
|
|
901
|
-
return
|
|
900
|
+
return doorSays(405, "error", method);
|
|
902
901
|
}
|
|
902
|
+
let record;
|
|
903
903
|
try {
|
|
904
|
-
|
|
904
|
+
record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
|
|
905
905
|
if (record === null ||
|
|
906
906
|
record.door !== true ||
|
|
907
907
|
record.entry !== undefined ||
|
|
908
908
|
record.instance.document.kind === "external" ||
|
|
909
909
|
keys.instanceKey(record.instance) !== key ||
|
|
910
910
|
compiledFor(record.instance)?.config.nested === true) {
|
|
911
|
-
return
|
|
911
|
+
return doorSays(401, "session", method);
|
|
912
912
|
}
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
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 {
|
|
921
942
|
const refused = await refusalOf(request, access);
|
|
922
943
|
if (refused !== null) {
|
|
923
|
-
return
|
|
944
|
+
return doorSays(403, "denied", method, refused.code);
|
|
924
945
|
}
|
|
925
946
|
const served = await documentOf(access.instance);
|
|
926
947
|
// The same document, entry and page checks the content's address runs (`serveAccess`).
|
|
927
|
-
const below = isPageRest(record.page) ? record.page : undefined;
|
|
928
948
|
if (served === null ||
|
|
929
949
|
("files" in served
|
|
930
950
|
? !entryIsPage(served.files) || ticketPage(served.files, below) === null
|
|
931
951
|
: below !== undefined)) {
|
|
932
|
-
return
|
|
952
|
+
return doorSays(404, "not-found", method);
|
|
933
953
|
}
|
|
934
954
|
return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
|
|
935
955
|
}
|
|
936
956
|
catch {
|
|
937
|
-
return
|
|
957
|
+
return doorSays(500, "error", method);
|
|
938
958
|
}
|
|
939
959
|
}
|
|
940
960
|
/**
|
|
@@ -1012,6 +1032,9 @@ export function createServer(options) {
|
|
|
1012
1032
|
const ancestors = nested ? nestedAncestors(access.origin, frameAncestors) : frameAncestors;
|
|
1013
1033
|
if ("files" in served) {
|
|
1014
1034
|
if (at !== undefined) {
|
|
1035
|
+
// A page's own frames (P128): its files below the base are framed by its own pages too,
|
|
1036
|
+
// on this origin (`frame-ancestors` names every ancestor). Never another origin's.
|
|
1037
|
+
const own = served.compiled.config.nestedFrames === "own";
|
|
1015
1038
|
return serveFile({
|
|
1016
1039
|
request,
|
|
1017
1040
|
set: served.files,
|
|
@@ -1023,7 +1046,7 @@ export function createServer(options) {
|
|
|
1023
1046
|
source: at.source,
|
|
1024
1047
|
compiled: served.compiled,
|
|
1025
1048
|
hostOrigins: options.hostOrigins,
|
|
1026
|
-
frameAncestors: ancestors,
|
|
1049
|
+
frameAncestors: own ? `${access.origin} ${ancestors}` : ancestors,
|
|
1027
1050
|
...versionOf(access.instance),
|
|
1028
1051
|
});
|
|
1029
1052
|
}
|
|
@@ -1496,12 +1519,8 @@ export function createServer(options) {
|
|
|
1496
1519
|
}
|
|
1497
1520
|
return page(404, "Nothing here", "This address names no content.", method);
|
|
1498
1521
|
}
|
|
1499
|
-
/** A
|
|
1500
|
-
|
|
1501
|
-
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1502
|
-
below) {
|
|
1503
|
-
const clean = cleanInstance(instance);
|
|
1504
|
-
check(clean);
|
|
1522
|
+
/** A grant, checked for an instance (`issue`'s rules, and `doorAnswer`'s, P126). */
|
|
1523
|
+
function checkGrant(clean, grant) {
|
|
1505
1524
|
const anonymous = grant.anonymous === true;
|
|
1506
1525
|
if (anonymous) {
|
|
1507
1526
|
if (grant.viewer !== undefined) {
|
|
@@ -1520,10 +1539,20 @@ export function createServer(options) {
|
|
|
1520
1539
|
(typeof grant.subject !== "string" || grant.subject.length > SUBJECT_MAX)) {
|
|
1521
1540
|
throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
|
|
1522
1541
|
}
|
|
1542
|
+
return { anonymous, viewer: anonymous ? "" : (grant.viewer ?? "") };
|
|
1543
|
+
}
|
|
1544
|
+
/** How long a grant's session lasts, checked (`sessionSeconds`). */
|
|
1545
|
+
const sessionOf = (grant) => seconds(grant.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SESSION_SECONDS, "sessionSeconds");
|
|
1546
|
+
/** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
|
|
1547
|
+
async function mint(instance, grant, entry,
|
|
1548
|
+
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1549
|
+
below) {
|
|
1550
|
+
const clean = cleanInstance(instance);
|
|
1551
|
+
check(clean);
|
|
1552
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
1523
1553
|
const ttl = seconds(grant.ttlSeconds, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
|
|
1524
|
-
const sessionSeconds =
|
|
1554
|
+
const sessionSeconds = sessionOf(grant);
|
|
1525
1555
|
const key = keys.instanceKey(clean);
|
|
1526
|
-
const viewer = anonymous ? "" : grant.viewer;
|
|
1527
1556
|
const probe = keys.sign({
|
|
1528
1557
|
i: clean,
|
|
1529
1558
|
w: viewer,
|
|
@@ -1634,6 +1663,29 @@ export function createServer(options) {
|
|
|
1634
1663
|
...(door === null ? {} : { door: { url: `${origin}${DOOR_PATH}${key}?ticket=${door}` } }),
|
|
1635
1664
|
};
|
|
1636
1665
|
},
|
|
1666
|
+
async doorAnswer(instance, grant, request, at = {}) {
|
|
1667
|
+
// A host that admitted the request itself (P126): no ticket here, the grant is its word.
|
|
1668
|
+
const clean = cleanInstance(instance);
|
|
1669
|
+
check(clean);
|
|
1670
|
+
if (!hasDoor(clean)) {
|
|
1671
|
+
throw new TypeError("This instance has no door (P125): a nested page's frame is its shell, a url-mode app has none");
|
|
1672
|
+
}
|
|
1673
|
+
const below = at.page;
|
|
1674
|
+
if (below !== undefined && (!isPageRest(below) || clean.document.kind !== "artifact")) {
|
|
1675
|
+
throw new TypeError("A frame's page is a relative path below an artifact's files (no . or ..)");
|
|
1676
|
+
}
|
|
1677
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
1678
|
+
const sessionSeconds = sessionOf(grant);
|
|
1679
|
+
const origin = originOfLabel(labelFor(clean));
|
|
1680
|
+
return answerDoor(request ?? new Request(`${origin}${DOOR_PATH}${keys.instanceKey(clean)}`), {
|
|
1681
|
+
instance: clean,
|
|
1682
|
+
viewer,
|
|
1683
|
+
origin,
|
|
1684
|
+
expiresAt: Date.now() + sessionSeconds * 1_000,
|
|
1685
|
+
...(anonymous ? { anonymous: true } : {}),
|
|
1686
|
+
...(grant.subject === undefined ? {} : { subject: grant.subject }),
|
|
1687
|
+
}, below);
|
|
1688
|
+
},
|
|
1637
1689
|
forget(filter = {}) {
|
|
1638
1690
|
for (const [key, each] of answers) {
|
|
1639
1691
|
if ((filter.scope === undefined || each.scope === filter.scope) &&
|
package/dist/server/types.d.ts
CHANGED
|
@@ -324,6 +324,29 @@ export interface PortholeServer {
|
|
|
324
324
|
at?: {
|
|
325
325
|
readonly page?: string;
|
|
326
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>;
|
|
327
350
|
/**
|
|
328
351
|
* The access a request's cookie carries for a url-mode app on the request's origin, or null
|
|
329
352
|
* (no good cookie, an `Origin` or `Sec-Fetch-Site` of another origin's (P101), or the host's
|
package/dist/shell/plan.d.ts
CHANGED
|
@@ -51,5 +51,10 @@ export interface ShellPlan {
|
|
|
51
51
|
/** The most text `copyText` carries. */
|
|
52
52
|
readonly maxCopyChars: number;
|
|
53
53
|
readonly protocolVersion: string;
|
|
54
|
+
/**
|
|
55
|
+
* `own` where the config lets content frame its own files and `srcdoc` (P128): the shell keeps
|
|
56
|
+
* those iframes and removes every other frame-like element. Absent: it removes them all.
|
|
57
|
+
*/
|
|
58
|
+
readonly nestedFrames?: "own";
|
|
54
59
|
}
|
|
55
60
|
export declare function shellPlan(config: PortholeConfig): ShellPlan | null;
|
package/dist/shell/plan.js
CHANGED
|
@@ -44,5 +44,7 @@ export function shellPlan(config) {
|
|
|
44
44
|
maxPromptChars: config.limits.maxPromptChars,
|
|
45
45
|
maxCopyChars: MAX_COPY_CHARS,
|
|
46
46
|
protocolVersion: MCP_APPS_PROTOCOL_VERSION,
|
|
47
|
+
// Only where opted into (P128): every other plan is the same as before it.
|
|
48
|
+
...(config.nestedFrames === "own" ? { nestedFrames: "own" } : {}),
|
|
47
49
|
};
|
|
48
50
|
}
|
package/dist/shell/runtime.d.ts
CHANGED
|
@@ -4,6 +4,31 @@
|
|
|
4
4
|
* more comes. Parsed as it is, a cut right after `<` or `</` draws them as text.
|
|
5
5
|
*/
|
|
6
6
|
export declare const HELD_BACK: string;
|
|
7
|
+
/**
|
|
8
|
+
* Which `<iframe>` the shell keeps under `nestedFrames: "own"` (P128), spliced into the runtime:
|
|
9
|
+
* one with a `srcdoc` attribute (which wins over any `src`), or one whose `src`, resolved by the
|
|
10
|
+
* platform's own URL parser (`resolve`, which normalizes `..`, `%2e` and backslashes), is under the
|
|
11
|
+
* version's own files' address (`filesBase`, ending in `/`). Nothing else: no `src` or a blank one
|
|
12
|
+
* (`about:blank`), another path of the origin, another origin, `data:`, `blob:`, `javascript:`.
|
|
13
|
+
* Only comparisons and indexing, which content can't replace (no String.prototype method).
|
|
14
|
+
*/
|
|
15
|
+
export declare const OWN_FRAME: string;
|
|
16
|
+
/**
|
|
17
|
+
* Which values a guard forwards as they are (P129, P130), spliced into the runtime: those that are
|
|
18
|
+
* their own single reading. A string, a number, a boolean, a bigint, `null`, and a genuine
|
|
19
|
+
* `undefined` (`value === undefined`: an object whose `typeof` is "undefined" isn't one). Nothing
|
|
20
|
+
* here can throw or run content's code (`typeof` and `===` read no property).
|
|
21
|
+
*/
|
|
22
|
+
export declare const PASSES_AS_IS: string;
|
|
23
|
+
/**
|
|
24
|
+
* A name or value a guard inspects and then forwards, pinned to one reading (P129, P130), spliced
|
|
25
|
+
* into the runtime as `ONCE(passesAsIs, toText)`: a value `passesAsIs` lets through goes on
|
|
26
|
+
* unchanged; anything else is turned into its string once, by `toText` (the platform's own
|
|
27
|
+
* `String`, kept before content runs), and that string is what is both checked and forwarded. A
|
|
28
|
+
* symbol, a conversion that throws, or one that doesn't give a string is refused (the guard throws
|
|
29
|
+
* and nothing is forwarded): fail closed.
|
|
30
|
+
*/
|
|
31
|
+
export declare const ONCE: string;
|
|
7
32
|
/**
|
|
8
33
|
* The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
|
|
9
34
|
* no imports and no build step, so every engine (a browser frame now, a native web view later)
|
|
@@ -17,7 +42,11 @@ export declare const HELD_BACK: string;
|
|
|
17
42
|
* 3. removes every frame-like element content adds, wherever it adds it (the document, any shadow
|
|
18
43
|
* root), since a nested frame runs in a fresh realm where step 2 never happened (and not every
|
|
19
44
|
* engine enforces `frame-src 'none'` for `srcdoc`/`about:blank` children); and the resource
|
|
20
|
-
* hints and refreshes a CSP doesn't govern
|
|
45
|
+
* hints and refreshes a CSP doesn't govern. Where the config opts in (`nestedFrames: "own"`,
|
|
46
|
+
* P128), an `<iframe>` of the page's own files or with `srcdoc` is kept (`OWN_FRAME`), and
|
|
47
|
+
* one that is kept leaves the document before a change would make it any other; in such a
|
|
48
|
+
* child realm steps 1, 2, 5 and 6 never ran (a page of the set has its own shell there), which
|
|
49
|
+
* the host accepted by opting in;
|
|
21
50
|
* 4. closes the parser entry points that could build a shadow root step 3 can't see (declarative
|
|
22
51
|
* shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`);
|
|
23
52
|
* 5. keeps content off the clipboard: the async Clipboard API refuses, `execCommand` won't copy or
|