@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
|
@@ -67,6 +67,12 @@ export declare const STALE_META = "porthole/stale";
|
|
|
67
67
|
* one of its reports; the host's adapter carries it into `reportError`.
|
|
68
68
|
*/
|
|
69
69
|
export declare const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
|
|
70
|
+
/**
|
|
71
|
+
* Porthole's own notification from the shell (P084): a page that came with files is opening
|
|
72
|
+
* another page of its set, `{ url }`, in the frame. The host takes the frame's next load for that
|
|
73
|
+
* page rather than for content that left (P031). The content's word: it only spares a restart.
|
|
74
|
+
*/
|
|
75
|
+
export declare const NAVIGATING_METHOD = "porthole/navigating";
|
|
70
76
|
/** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
|
|
71
77
|
export declare const SHELL_LOGGER = "porthole";
|
|
72
78
|
/**
|
|
@@ -117,5 +117,11 @@ export const STALE_META = "porthole/stale";
|
|
|
117
117
|
* one of its reports; the host's adapter carries it into `reportError`.
|
|
118
118
|
*/
|
|
119
119
|
export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
|
|
120
|
+
/**
|
|
121
|
+
* Porthole's own notification from the shell (P084): a page that came with files is opening
|
|
122
|
+
* another page of its set, `{ url }`, in the frame. The host takes the frame's next load for that
|
|
123
|
+
* page rather than for content that left (P031). The content's word: it only spares a restart.
|
|
124
|
+
*/
|
|
125
|
+
export const NAVIGATING_METHOD = "porthole/navigating";
|
|
120
126
|
/** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
|
|
121
127
|
export const SHELL_LOGGER = "porthole";
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { JSON_RPC_ERRORS, parseJsonRpc, } from "./jsonrpc.js";
|
|
2
2
|
import { reasonFor } from "../bridge/refusal.js";
|
|
3
|
-
import { COPY_TEXT_METHOD, NAVIGATION_BLOCKED_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
|
|
3
|
+
import { COPY_TEXT_METHOD, NAVIGATING_METHOD, NAVIGATION_BLOCKED_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
|
|
4
4
|
import { liveData } from "./live-data.js";
|
|
5
5
|
/**
|
|
6
6
|
* The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
|
|
@@ -212,6 +212,10 @@ export const shellAdapter = {
|
|
|
212
212
|
// The shell stopped a navigation (P080): an error report, with its address.
|
|
213
213
|
void bridge.call("reportError", { navigationBlocked: params.url });
|
|
214
214
|
return;
|
|
215
|
+
case NAVIGATING_METHOD:
|
|
216
|
+
// Another page of the set opens in the frame (P084): its next load is that page.
|
|
217
|
+
session.emit({ type: "navigating" });
|
|
218
|
+
return;
|
|
215
219
|
case M.requestTeardown:
|
|
216
220
|
session.emit({ type: "teardown-requested" });
|
|
217
221
|
return;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { CompiledConfig } from "../compile/compile.ts";
|
|
2
|
+
import type { StoredFiles } from "./types.ts";
|
|
3
|
+
/**
|
|
4
|
+
* Serving a version made of files (P081, P082): each path looked up in its manifest only, each
|
|
5
|
+
* answer typed by Porthole's table, with `nosniff`, its CSP in a header, its cache rule and a
|
|
6
|
+
* strong ETag; pages in the shell, ranges for the rest.
|
|
7
|
+
*/
|
|
8
|
+
export interface FileServing {
|
|
9
|
+
readonly request: Request;
|
|
10
|
+
readonly set: StoredFiles;
|
|
11
|
+
/** The request's path below the base, as the URL has it (percent-encoded). */
|
|
12
|
+
readonly rest: string;
|
|
13
|
+
/** The search part, kept on a redirect. */
|
|
14
|
+
readonly search: string;
|
|
15
|
+
/** The version's own address on its origin: a path ending in `/`. */
|
|
16
|
+
readonly base: string;
|
|
17
|
+
readonly origin: string;
|
|
18
|
+
/**
|
|
19
|
+
* Whether `base` names this version and no other (a pinned address, a frame's): its files are
|
|
20
|
+
* immutable there. Else they are revalidated (an address that may mean another version later).
|
|
21
|
+
*/
|
|
22
|
+
readonly pinned: boolean;
|
|
23
|
+
/** The CSP source the version's files load from (P082): its path on the origin. */
|
|
24
|
+
readonly source: string;
|
|
25
|
+
readonly compiled: CompiledConfig;
|
|
26
|
+
readonly hostOrigins: readonly string[];
|
|
27
|
+
readonly frameAncestors: string;
|
|
28
|
+
/**
|
|
29
|
+
* A ticket's answer (P083): the entry, served at the ticket's address, never stored; its shell
|
|
30
|
+
* moves the frame to the entry's own address under `base` before anything loads, and renews
|
|
31
|
+
* that address before it ends (`expires`, epoch ms).
|
|
32
|
+
*/
|
|
33
|
+
readonly ticket?: {
|
|
34
|
+
readonly expires: number;
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
/** Whether the request is a page loading (a navigation), not a subresource. */
|
|
38
|
+
export declare function isNavigation(request: Request): boolean;
|
|
39
|
+
/**
|
|
40
|
+
* Whether the request is a running page's own load: from its own origin (`Sec-Fetch-Site`, which
|
|
41
|
+
* only a browser sets and no page can change), and not a navigation.
|
|
42
|
+
*/
|
|
43
|
+
export declare const ownLoad: (request: Request) => boolean;
|
|
44
|
+
export declare function serveFile(serving: FileServing): Promise<Response>;
|
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
import { fileSetCspDirectives, INERT_FILE_CSP, serializeCsp } from "../compile/policy.js";
|
|
2
|
+
import { DEFAULT_ENTRY, lookupFile, requestFilePath } from "../files/paths.js";
|
|
3
|
+
import { fileTypeOf } from "../files/types.js";
|
|
4
|
+
import { sha256, utf8 } from "./crypto.js";
|
|
5
|
+
const HEX = /^[0-9a-f]{64}$/u;
|
|
6
|
+
const YEAR = 31_536_000;
|
|
7
|
+
const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
8
|
+
/** A path's segments percent-encoded, for a `Location`. */
|
|
9
|
+
const encodePath = (path) => path
|
|
10
|
+
.split("/")
|
|
11
|
+
.map((segment) => encodeURIComponent(segment))
|
|
12
|
+
.join("/");
|
|
13
|
+
/** Whether the request is a page loading (a navigation), not a subresource. */
|
|
14
|
+
export function isNavigation(request) {
|
|
15
|
+
const mode = request.headers.get("sec-fetch-mode");
|
|
16
|
+
const dest = request.headers.get("sec-fetch-dest");
|
|
17
|
+
if (mode !== null || dest !== null) {
|
|
18
|
+
return mode === "navigate" || dest === "document" || dest === "iframe" || dest === "frame";
|
|
19
|
+
}
|
|
20
|
+
return (request.headers.get("accept") ?? "").includes("text/html");
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Whether the request is a running page's own load: from its own origin (`Sec-Fetch-Site`, which
|
|
24
|
+
* only a browser sets and no page can change), and not a navigation.
|
|
25
|
+
*/
|
|
26
|
+
export const ownLoad = (request) => request.headers.get("sec-fetch-site") === "same-origin" && !isNavigation(request);
|
|
27
|
+
/** Whether `If-None-Match` names this ETag. */
|
|
28
|
+
function notModified(request, etag) {
|
|
29
|
+
const asked = request.headers.get("if-none-match");
|
|
30
|
+
if (asked === null) {
|
|
31
|
+
return false;
|
|
32
|
+
}
|
|
33
|
+
return asked
|
|
34
|
+
.split(",")
|
|
35
|
+
.map((each) => each.trim().replace(/^W\//u, ""))
|
|
36
|
+
.some((each) => each === "*" || each === etag);
|
|
37
|
+
}
|
|
38
|
+
/** A single `bytes=` range of a body of `size` bytes: the range, "unsatisfiable", or null (ignore it). */
|
|
39
|
+
function rangeOf(header, size) {
|
|
40
|
+
if (header === null) {
|
|
41
|
+
return null;
|
|
42
|
+
}
|
|
43
|
+
const match = /^bytes=(\d*)-(\d*)$/u.exec(header.trim());
|
|
44
|
+
if (match === null) {
|
|
45
|
+
return null;
|
|
46
|
+
}
|
|
47
|
+
const [, from = "", to = ""] = match;
|
|
48
|
+
if (from === "" && to === "") {
|
|
49
|
+
return null;
|
|
50
|
+
}
|
|
51
|
+
if (from === "") {
|
|
52
|
+
// The last `to` bytes.
|
|
53
|
+
const length = Number(to);
|
|
54
|
+
if (length === 0) {
|
|
55
|
+
return "unsatisfiable";
|
|
56
|
+
}
|
|
57
|
+
return size === 0 ? "unsatisfiable" : { start: Math.max(0, size - length), end: size - 1 };
|
|
58
|
+
}
|
|
59
|
+
const start = Number(from);
|
|
60
|
+
const end = to === "" ? size - 1 : Math.min(Number(to), size - 1);
|
|
61
|
+
if (!Number.isSafeInteger(start) || start >= size || end < start) {
|
|
62
|
+
return "unsatisfiable";
|
|
63
|
+
}
|
|
64
|
+
return { start, end };
|
|
65
|
+
}
|
|
66
|
+
/** `body` from byte `start` through `end`. */
|
|
67
|
+
function slice(body, start, end) {
|
|
68
|
+
if (body instanceof Uint8Array) {
|
|
69
|
+
return body.subarray(start, end + 1);
|
|
70
|
+
}
|
|
71
|
+
let offset = 0;
|
|
72
|
+
return body.pipeThrough(new TransformStream({
|
|
73
|
+
transform(chunk, controller) {
|
|
74
|
+
const from = Math.max(start - offset, 0);
|
|
75
|
+
const to = Math.min(end + 1 - offset, chunk.byteLength);
|
|
76
|
+
if (from < to) {
|
|
77
|
+
controller.enqueue(chunk.subarray(from, to));
|
|
78
|
+
}
|
|
79
|
+
offset += chunk.byteLength;
|
|
80
|
+
if (offset > end) {
|
|
81
|
+
controller.terminate();
|
|
82
|
+
}
|
|
83
|
+
},
|
|
84
|
+
}));
|
|
85
|
+
}
|
|
86
|
+
async function textOf(body) {
|
|
87
|
+
if (body instanceof Uint8Array) {
|
|
88
|
+
return new TextDecoder().decode(body);
|
|
89
|
+
}
|
|
90
|
+
return new Response(body).text();
|
|
91
|
+
}
|
|
92
|
+
const asBody = (body) => body instanceof Uint8Array ? new Uint8Array(body) : body;
|
|
93
|
+
/** The answer for nothing found: plain, inert. */
|
|
94
|
+
function nothing(serving, status, method) {
|
|
95
|
+
const text = status === 404 ? "Not found" : status === 405 ? "Content here is only read" : "Not allowed";
|
|
96
|
+
return new Response(method === "HEAD" ? null : text, {
|
|
97
|
+
status,
|
|
98
|
+
headers: {
|
|
99
|
+
"content-type": "text/plain; charset=utf-8",
|
|
100
|
+
"content-security-policy": `${INERT_FILE_CSP}; frame-ancestors ${serving.frameAncestors}`,
|
|
101
|
+
"cache-control": "no-store",
|
|
102
|
+
"x-content-type-options": "nosniff",
|
|
103
|
+
"referrer-policy": "no-referrer",
|
|
104
|
+
"x-robots-tag": "noindex, nofollow",
|
|
105
|
+
...(status === 405 ? { allow: "GET, HEAD" } : {}),
|
|
106
|
+
},
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
export async function serveFile(serving) {
|
|
110
|
+
const { request, set } = serving;
|
|
111
|
+
const method = request.method.toUpperCase();
|
|
112
|
+
// No service worker, ever: one would answer this origin's requests with documents of its
|
|
113
|
+
// own making, outside the shell and its CSP (P081).
|
|
114
|
+
if (request.headers.get("service-worker") !== null ||
|
|
115
|
+
request.headers.get("sec-fetch-dest") === "serviceworker") {
|
|
116
|
+
return nothing(serving, 403, method);
|
|
117
|
+
}
|
|
118
|
+
if (method !== "GET" && method !== "HEAD") {
|
|
119
|
+
return nothing(serving, 405, method);
|
|
120
|
+
}
|
|
121
|
+
const path = requestFilePath(serving.rest);
|
|
122
|
+
if (path === null) {
|
|
123
|
+
return nothing(serving, 404, method);
|
|
124
|
+
}
|
|
125
|
+
const has = (each) => Object.hasOwn(set.files, each);
|
|
126
|
+
const entryPath = set.entry ?? DEFAULT_ENTRY;
|
|
127
|
+
const found = serving.ticket !== undefined
|
|
128
|
+
? has(entryPath)
|
|
129
|
+
? { kind: "file", path: entryPath, status: 200 }
|
|
130
|
+
: { kind: "none" }
|
|
131
|
+
: lookupFile(has, path, {
|
|
132
|
+
...(set.entry === undefined ? {} : { entry: set.entry }),
|
|
133
|
+
...(set.spa === undefined ? {} : { spa: set.spa }),
|
|
134
|
+
navigation: isNavigation(request),
|
|
135
|
+
});
|
|
136
|
+
if (found.kind === "none") {
|
|
137
|
+
return nothing(serving, 404, method);
|
|
138
|
+
}
|
|
139
|
+
// The version's own address, as a URL writes it.
|
|
140
|
+
const base = new URL(serving.base, serving.origin).href;
|
|
141
|
+
if (found.kind === "redirect") {
|
|
142
|
+
return new Response(null, {
|
|
143
|
+
status: 307,
|
|
144
|
+
headers: {
|
|
145
|
+
location: `${base}${encodePath(found.to)}${serving.search}`,
|
|
146
|
+
"cache-control": "no-store",
|
|
147
|
+
"referrer-policy": "no-referrer",
|
|
148
|
+
"x-robots-tag": "noindex, nofollow",
|
|
149
|
+
},
|
|
150
|
+
});
|
|
151
|
+
}
|
|
152
|
+
const entry = set.files[found.path];
|
|
153
|
+
const body = entry === undefined ? null : await set.read(found.path);
|
|
154
|
+
if (entry === undefined || body === null) {
|
|
155
|
+
return nothing(serving, 404, method);
|
|
156
|
+
}
|
|
157
|
+
const { type, role } = fileTypeOf(found.path);
|
|
158
|
+
const frameCsp = serializeCsp(fileSetCspDirectives(serving.compiled.cspDirectives, serving.source));
|
|
159
|
+
const headers = new Headers({
|
|
160
|
+
"content-type": type,
|
|
161
|
+
"x-content-type-options": "nosniff",
|
|
162
|
+
"referrer-policy": "no-referrer",
|
|
163
|
+
"x-robots-tag": "noindex, nofollow",
|
|
164
|
+
// A page and a script (a worker's policy is its script's) get the page's CSP; anything else
|
|
165
|
+
// runs nothing when opened on its own.
|
|
166
|
+
"content-security-policy": `${role === "file" ? INERT_FILE_CSP : frameCsp}; frame-ancestors ${serving.frameAncestors}`,
|
|
167
|
+
});
|
|
168
|
+
if (role === "page") {
|
|
169
|
+
// Every page of the set in the shell (P081): its hardening, its host functions, its theme.
|
|
170
|
+
const html = serving.compiled.shellDocument({
|
|
171
|
+
origins: serving.hostOrigins,
|
|
172
|
+
document: await textOf(body),
|
|
173
|
+
cspMeta: false,
|
|
174
|
+
files: {
|
|
175
|
+
base,
|
|
176
|
+
// At a ticket's address: the entry's own (its directory's, for an entry in one).
|
|
177
|
+
...(serving.ticket === undefined
|
|
178
|
+
? {}
|
|
179
|
+
: {
|
|
180
|
+
address: `${base}${found.path.includes("/") ? encodePath(found.path) : ""}`,
|
|
181
|
+
expires: serving.ticket.expires,
|
|
182
|
+
}),
|
|
183
|
+
},
|
|
184
|
+
});
|
|
185
|
+
if (serving.ticket !== undefined) {
|
|
186
|
+
headers.set("cache-control", "no-store");
|
|
187
|
+
return new Response(method === "HEAD" ? null : html, { status: 200, headers });
|
|
188
|
+
}
|
|
189
|
+
const etag = `"${hex(sha256(utf8(html)))}"`;
|
|
190
|
+
headers.set("etag", etag);
|
|
191
|
+
// A page is asked again each time it loads, so the host's check runs on every navigation.
|
|
192
|
+
headers.set("cache-control", "private, no-cache");
|
|
193
|
+
if (found.status === 200 && notModified(request, etag)) {
|
|
194
|
+
return new Response(null, { status: 304, headers });
|
|
195
|
+
}
|
|
196
|
+
return new Response(method === "HEAD" ? null : html, { status: found.status, headers });
|
|
197
|
+
}
|
|
198
|
+
const size = body instanceof Uint8Array ? body.byteLength : entry.size;
|
|
199
|
+
const etag = HEX.test(entry.sha256) ? `"${entry.sha256}"` : null;
|
|
200
|
+
if (etag !== null) {
|
|
201
|
+
headers.set("etag", etag);
|
|
202
|
+
}
|
|
203
|
+
headers.set("cache-control", serving.pinned ? `private, max-age=${YEAR}, immutable` : "private, no-cache");
|
|
204
|
+
// Only this origin's own pages load it: no other content origin (a sibling, same-site without
|
|
205
|
+
// the public suffix list) can embed it with the viewer's cookie.
|
|
206
|
+
headers.set("cross-origin-resource-policy", "same-origin");
|
|
207
|
+
headers.set("accept-ranges", "bytes");
|
|
208
|
+
if (role === "file" && type === "application/octet-stream") {
|
|
209
|
+
headers.set("content-disposition", "attachment");
|
|
210
|
+
}
|
|
211
|
+
if (etag !== null && notModified(request, etag)) {
|
|
212
|
+
if (!(body instanceof Uint8Array)) {
|
|
213
|
+
await body.cancel();
|
|
214
|
+
}
|
|
215
|
+
return new Response(null, { status: 304, headers });
|
|
216
|
+
}
|
|
217
|
+
const range = found.status === 200 ? rangeOf(request.headers.get("range"), size) : null;
|
|
218
|
+
if (range === "unsatisfiable") {
|
|
219
|
+
if (!(body instanceof Uint8Array)) {
|
|
220
|
+
await body.cancel();
|
|
221
|
+
}
|
|
222
|
+
headers.set("content-range", `bytes */${size}`);
|
|
223
|
+
return new Response(null, { status: 416, headers });
|
|
224
|
+
}
|
|
225
|
+
if (range !== null) {
|
|
226
|
+
headers.set("content-range", `bytes ${range.start}-${range.end}/${size}`);
|
|
227
|
+
headers.set("content-length", String(range.end - range.start + 1));
|
|
228
|
+
if (method === "HEAD" && !(body instanceof Uint8Array)) {
|
|
229
|
+
await body.cancel();
|
|
230
|
+
}
|
|
231
|
+
return new Response(method === "HEAD" ? null : asBody(slice(body, range.start, range.end)), {
|
|
232
|
+
status: 206,
|
|
233
|
+
headers,
|
|
234
|
+
});
|
|
235
|
+
}
|
|
236
|
+
// A stream's length is the manifest's word: said for HEAD, left to the transfer otherwise.
|
|
237
|
+
if (body instanceof Uint8Array || method === "HEAD") {
|
|
238
|
+
headers.set("content-length", String(size));
|
|
239
|
+
}
|
|
240
|
+
if (method === "HEAD" && !(body instanceof Uint8Array)) {
|
|
241
|
+
await body.cancel();
|
|
242
|
+
}
|
|
243
|
+
return new Response(method === "HEAD" ? null : asBody(body), { status: found.status, headers });
|
|
244
|
+
}
|
package/dist/server/host.d.ts
CHANGED
|
@@ -152,7 +152,7 @@ export interface EntryOptions<V> {
|
|
|
152
152
|
* authorize route with the viewer. Say what exists the same way for both; `access` says who
|
|
153
153
|
* may see it.
|
|
154
154
|
*/
|
|
155
|
-
readonly at: (scope: string, path: string, viewer: V | null, request: Request) => Awaitable<InstanceRef | null | undefined>;
|
|
155
|
+
readonly at: (scope: string, path: string, viewer: V | null, request: Request) => Awaitable<InstanceRef | FileAddress | null | undefined>;
|
|
156
156
|
/**
|
|
157
157
|
* The app's own sign-in, which comes back to `returnTo` (the authorize URL, as `authorizeUrl`
|
|
158
158
|
* names the app, with the entry's state) once signed in.
|
|
@@ -190,6 +190,43 @@ export interface EntryOptions<V> {
|
|
|
190
190
|
*/
|
|
191
191
|
readonly refusal?: (status: 403 | 404, request: Request, entry: EntryContext) => Awaitable<Response | null | undefined>;
|
|
192
192
|
}
|
|
193
|
+
/**
|
|
194
|
+
* What a clean address means when its instance is a version made of files (P081): the instance,
|
|
195
|
+
* the version's own address (`base`, a path ending in `/`: `/v/3/`), and the file the address
|
|
196
|
+
* asks for below it (`""`: the version's entry). The session the entry buys serves every path
|
|
197
|
+
* under `base`, so the page's relative addresses are its own version's. An address that isn't
|
|
198
|
+
* under `base` (`/`, `/style.css`: the latest) goes to `base` + `file`, so a page never mixes
|
|
199
|
+
* versions when a new one is published while it loads. `versionedAddress` reads the usual
|
|
200
|
+
* convention (`/v/<n>/<file>`, else the latest).
|
|
201
|
+
*/
|
|
202
|
+
export interface FileAddress {
|
|
203
|
+
readonly instance: InstanceRef;
|
|
204
|
+
/** A path ending in `/`, each segment of `A-Z a-z 0-9 . _ : ~ -`, no `.` or `..` segment. */
|
|
205
|
+
readonly base: string;
|
|
206
|
+
readonly file?: string;
|
|
207
|
+
/**
|
|
208
|
+
* Whether `base` names this version and no other (`/v/3/`, never `/` or `/latest/`): its files
|
|
209
|
+
* are then immutable there. Default false: revalidated, as an address that may mean another
|
|
210
|
+
* version later.
|
|
211
|
+
*/
|
|
212
|
+
readonly pinned?: boolean;
|
|
213
|
+
}
|
|
214
|
+
/** Whether `entry.at`'s answer is a file set's address rather than an instance. */
|
|
215
|
+
export declare const isFileAddress: (value: InstanceRef | FileAddress) => value is FileAddress;
|
|
216
|
+
/** Kept free on every content origin for an asset library across versions (P081): not built. */
|
|
217
|
+
export declare const ASSET_LIBRARY_PATH = "/_blob/";
|
|
218
|
+
/**
|
|
219
|
+
* The convention for a versioned scope's clean addresses (P081): `/v/<version>/<file>` is that
|
|
220
|
+
* version, pinned; any other path is the latest's `<file>` (`version` null). Null for a
|
|
221
|
+
* `/v/<version>` whose version isn't a name (`A-Z a-z 0-9 . _ : -`), and under `/_blob/`, kept for
|
|
222
|
+
* an asset library outside every version. `versionBase(version)` is the base to answer with.
|
|
223
|
+
*/
|
|
224
|
+
export declare function versionedAddress(path: string): {
|
|
225
|
+
readonly version: string | null;
|
|
226
|
+
readonly file: string;
|
|
227
|
+
} | null;
|
|
228
|
+
/** A version's own address in `versionedAddress`'s convention: `/v/<version>/`. */
|
|
229
|
+
export declare const versionBase: (version: string) => string;
|
|
193
230
|
/** The clean address a redirect entry is opening, as its authorize route decoded it (P070). */
|
|
194
231
|
export interface EntryContext {
|
|
195
232
|
/** The address's label, and the scope it names (null: one the naming never makes). */
|
package/dist/server/host.js
CHANGED
|
@@ -15,6 +15,32 @@ const DEFAULT_HEALTH_LABEL = "porthole-health";
|
|
|
15
15
|
const PROBE_TIMEOUT_MS = 10_000;
|
|
16
16
|
const UNHEALTHY_EVERY_MS = 60_000;
|
|
17
17
|
const HEALTHY_EVERY_MS = 600_000;
|
|
18
|
+
/** Whether `entry.at`'s answer is a file set's address rather than an instance. */
|
|
19
|
+
export const isFileAddress = (value) => "base" in value && "instance" in value;
|
|
20
|
+
/** Kept free on every content origin for an asset library across versions (P081): not built. */
|
|
21
|
+
export const ASSET_LIBRARY_PATH = "/_blob/";
|
|
22
|
+
/**
|
|
23
|
+
* The convention for a versioned scope's clean addresses (P081): `/v/<version>/<file>` is that
|
|
24
|
+
* version, pinned; any other path is the latest's `<file>` (`version` null). Null for a
|
|
25
|
+
* `/v/<version>` whose version isn't a name (`A-Z a-z 0-9 . _ : -`), and under `/_blob/`, kept for
|
|
26
|
+
* an asset library outside every version. `versionBase(version)` is the base to answer with.
|
|
27
|
+
*/
|
|
28
|
+
export function versionedAddress(path) {
|
|
29
|
+
if (path.startsWith(ASSET_LIBRARY_PATH)) {
|
|
30
|
+
return null;
|
|
31
|
+
}
|
|
32
|
+
const pinned = /^\/v\/([^/]*)(?:\/(.*))?$/u.exec(path);
|
|
33
|
+
if (pinned === null) {
|
|
34
|
+
return { version: null, file: path.replace(/^\//u, "") };
|
|
35
|
+
}
|
|
36
|
+
const [, version = "", file = ""] = pinned;
|
|
37
|
+
// A version is a name, never a dot segment.
|
|
38
|
+
return /^[A-Za-z0-9._:-]{1,200}$/u.test(version) && !/^\.{1,2}$/u.test(version)
|
|
39
|
+
? { version, file }
|
|
40
|
+
: null;
|
|
41
|
+
}
|
|
42
|
+
/** A version's own address in `versionedAddress`'s convention: `/v/<version>/`. */
|
|
43
|
+
export const versionBase = (version) => `/v/${version}/`;
|
|
18
44
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
19
45
|
const json = (status, body, headers = {}) => new Response(JSON.stringify(body), {
|
|
20
46
|
status,
|
|
@@ -631,9 +657,12 @@ export function createContentHost(options) {
|
|
|
631
657
|
return appPage(500, "Something went wrong", "The app couldn't tell who is asking.", "error", method);
|
|
632
658
|
}
|
|
633
659
|
try {
|
|
634
|
-
const
|
|
660
|
+
const answer = scope === null
|
|
635
661
|
? null
|
|
636
662
|
: ((await entry.at(scope, new URL(state.path, "https://x.invalid").pathname, viewer, request)) ?? null);
|
|
663
|
+
// A file set's address (P081) names its instance and where its version lives.
|
|
664
|
+
const address = answer !== null && isFileAddress(answer) ? answer : null;
|
|
665
|
+
const instance = address === null ? answer : address.instance;
|
|
637
666
|
const grant = instance === null ? null : await options.access(instance, viewer, request);
|
|
638
667
|
// The address being opened, decoded, for the app's sign-in and refusal pages.
|
|
639
668
|
const context = {
|
|
@@ -667,7 +696,13 @@ export function createContentHost(options) {
|
|
|
667
696
|
}
|
|
668
697
|
let location;
|
|
669
698
|
try {
|
|
670
|
-
location = await server.enterBy(state, instance, grant
|
|
699
|
+
location = await server.enterBy(state, instance, grant, address === null
|
|
700
|
+
? undefined
|
|
701
|
+
: {
|
|
702
|
+
base: address.base,
|
|
703
|
+
...(address.file === undefined ? {} : { file: address.file }),
|
|
704
|
+
...(address.pinned === true ? { pinned: true } : {}),
|
|
705
|
+
});
|
|
671
706
|
}
|
|
672
707
|
catch {
|
|
673
708
|
return appPage(409, "This can't be opened here", "Open the address again.", "error", method);
|
package/dist/server/index.d.ts
CHANGED
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
* content without a valid ticket or cookie gets nothing of the content.
|
|
34
34
|
*/
|
|
35
35
|
export { createServer } from "./server.ts";
|
|
36
|
-
export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type ContentClientMeta, type ContentLogger, type EntryContext, type EntryOptions, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
|
|
36
|
+
export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type ContentClientMeta, type ContentLogger, type EntryContext, type EntryOptions, ASSET_LIBRARY_PATH, type FileAddress, isFileAddress, versionBase, versionedAddress, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
|
|
37
37
|
export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDomainInfo, type ContentDomainProblem, } from "./domain.ts";
|
|
38
38
|
export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
|
|
39
39
|
export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
@@ -44,4 +44,6 @@ export type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/ty
|
|
|
44
44
|
export { isPortholeCookie, proxyTo, upstreamHeaders, withoutPortholeCookies, type ProxyOptions, } from "./proxy.ts";
|
|
45
45
|
export { statusPageOf as statusPage } from "./pages.ts";
|
|
46
46
|
export { contentHostFor, type ContentHostFor } from "./bootstrap.ts";
|
|
47
|
-
export
|
|
47
|
+
export { checkFileSet, DEFAULT_ENTRY, fileLimits, filePathProblem, type FileLimits, type FileSetProblem, } from "../files/paths.ts";
|
|
48
|
+
export { fileTypeOf, type FileRole, type FileType } from "../files/types.ts";
|
|
49
|
+
export type { Access, ArtifactStore, FileBody, StoredFile, StoredFiles, StoredVersion, AuthorizeAnswer, AuthorizeRequest, Authorizer, ContentDomain, EntryState, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";
|
package/dist/server/index.js
CHANGED
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
* content without a valid ticket or cookie gets nothing of the content.
|
|
34
34
|
*/
|
|
35
35
|
export { createServer } from "./server.js";
|
|
36
|
-
export { createContentHost, HEALTH_PATH, } from "./host.js";
|
|
36
|
+
export { createContentHost, HEALTH_PATH, ASSET_LIBRARY_PATH, isFileAddress, versionBase, versionedAddress, } from "./host.js";
|
|
37
37
|
export { clashOf, contentDomain, ContentDomainError, hostnameOf, } from "./domain.js";
|
|
38
38
|
export { d1TicketSchema, d1TicketStore, memoryTicketStore, } from "./tickets.js";
|
|
39
39
|
export { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
@@ -43,3 +43,6 @@ export { conformancePage } from "../conformance/page.js";
|
|
|
43
43
|
export { isPortholeCookie, proxyTo, upstreamHeaders, withoutPortholeCookies, } from "./proxy.js";
|
|
44
44
|
export { statusPageOf as statusPage } from "./pages.js";
|
|
45
45
|
export { contentHostFor } from "./bootstrap.js";
|
|
46
|
+
// A version made of files (P081): the rules its paths follow, its limits and its types.
|
|
47
|
+
export { checkFileSet, DEFAULT_ENTRY, fileLimits, filePathProblem, } from "../files/paths.js";
|
|
48
|
+
export { fileTypeOf } from "../files/types.js";
|
package/dist/server/keys.d.ts
CHANGED
|
@@ -11,6 +11,14 @@ export interface Keys {
|
|
|
11
11
|
sign(value: unknown): string;
|
|
12
12
|
/** The signed value, or null when the signature doesn't hold. */
|
|
13
13
|
verify(token: string): unknown;
|
|
14
|
+
/**
|
|
15
|
+
* `value` sealed (AES-256-GCM, Web Crypto): unreadable and unforgeable without the secret,
|
|
16
|
+
* base64url. A file set's access in a frame's path (P083), which content can read: the viewer
|
|
17
|
+
* and the host's subject inside it stay the host's.
|
|
18
|
+
*/
|
|
19
|
+
seal(value: unknown): Promise<string>;
|
|
20
|
+
/** The sealed value, or null when it doesn't open. */
|
|
21
|
+
unseal(token: string): Promise<unknown>;
|
|
14
22
|
}
|
|
15
23
|
export declare function createKeys(secret: Uint8Array): Keys;
|
|
16
24
|
/** A fresh one-time ticket: 160 random bits. */
|
package/dist/server/keys.js
CHANGED
|
@@ -36,6 +36,8 @@ export function canonicalJson(value) {
|
|
|
36
36
|
}
|
|
37
37
|
return JSON.stringify(value);
|
|
38
38
|
}
|
|
39
|
+
/** What a sealed value is bound to, so it can never be taken for anything else sealed. */
|
|
40
|
+
const SEAL_CONTEXT = utf8("porthole/files");
|
|
39
41
|
export function createKeys(secret) {
|
|
40
42
|
if (secret.byteLength < 32) {
|
|
41
43
|
throw new TypeError("The server's secret must be at least 32 random bytes");
|
|
@@ -44,6 +46,12 @@ export function createKeys(secret) {
|
|
|
44
46
|
const labelKey = derive("label");
|
|
45
47
|
const instanceKey = derive("instance");
|
|
46
48
|
const signKey = derive("session");
|
|
49
|
+
const sealKey = derive("files");
|
|
50
|
+
let sealing = null;
|
|
51
|
+
const sealingKey = () => (sealing ??= crypto.subtle.importKey("raw", new Uint8Array(sealKey), "AES-GCM", false, [
|
|
52
|
+
"encrypt",
|
|
53
|
+
"decrypt",
|
|
54
|
+
]));
|
|
47
55
|
const mac = (key, text) => hmacSha256(key, utf8(text));
|
|
48
56
|
return {
|
|
49
57
|
label: (scope) => base32(mac(labelKey, scope).subarray(0, 15)),
|
|
@@ -73,6 +81,32 @@ export function createKeys(secret) {
|
|
|
73
81
|
return null;
|
|
74
82
|
}
|
|
75
83
|
},
|
|
84
|
+
seal: async (value) => {
|
|
85
|
+
const iv = randomBytes(12);
|
|
86
|
+
const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: new Uint8Array(iv), additionalData: new Uint8Array(SEAL_CONTEXT) }, await sealingKey(), new Uint8Array(utf8(JSON.stringify(value)))));
|
|
87
|
+
const token = new Uint8Array(iv.length + sealed.length);
|
|
88
|
+
token.set(iv);
|
|
89
|
+
token.set(sealed, iv.length);
|
|
90
|
+
return base64url(token);
|
|
91
|
+
},
|
|
92
|
+
unseal: async (token) => {
|
|
93
|
+
const bytes = token.length > 8_192 ? null : fromBase64url(token);
|
|
94
|
+
// 12 bytes of IV and 16 of tag at least.
|
|
95
|
+
if (bytes === null || bytes.length < 29) {
|
|
96
|
+
return null;
|
|
97
|
+
}
|
|
98
|
+
try {
|
|
99
|
+
const opened = await crypto.subtle.decrypt({
|
|
100
|
+
name: "AES-GCM",
|
|
101
|
+
iv: new Uint8Array(bytes.subarray(0, 12)),
|
|
102
|
+
additionalData: new Uint8Array(SEAL_CONTEXT),
|
|
103
|
+
}, await sealingKey(), new Uint8Array(bytes.subarray(12)));
|
|
104
|
+
return JSON.parse(fromUtf8(new Uint8Array(opened)));
|
|
105
|
+
}
|
|
106
|
+
catch {
|
|
107
|
+
return null;
|
|
108
|
+
}
|
|
109
|
+
},
|
|
76
110
|
};
|
|
77
111
|
}
|
|
78
112
|
/** A fresh one-time ticket: 160 random bits. */
|