@botiverse/porthole 0.5.1 → 0.7.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.
Files changed (167) hide show
  1. package/README.md +41 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +208 -13
  4. package/dist/bridge/navigation.d.ts +1 -6
  5. package/dist/bridge/navigation.js +11 -0
  6. package/dist/bridge/refusal.d.ts +5 -1
  7. package/dist/bridge/refusal.js +16 -0
  8. package/dist/bridge/types.d.ts +41 -4
  9. package/dist/check/check.d.ts +19 -3
  10. package/dist/check/check.js +55 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/instrument.d.ts +3 -0
  14. package/dist/check/lint.js +31 -12
  15. package/dist/check/page-source.js +1 -1
  16. package/dist/check/page.js +14 -0
  17. package/dist/check/tools.d.ts +23 -0
  18. package/dist/check/tools.js +27 -3
  19. package/dist/compile/policy.d.ts +34 -0
  20. package/dist/compile/policy.js +74 -0
  21. package/dist/config/capabilities.d.ts +62 -3
  22. package/dist/config/capabilities.js +20 -0
  23. package/dist/config/schema.d.ts +32 -0
  24. package/dist/config/validate.d.ts +1 -1
  25. package/dist/config/validate.js +74 -5
  26. package/dist/conformance/harness-source.js +1 -1
  27. package/dist/conformance/index.d.ts +1 -0
  28. package/dist/conformance/index.js +2 -0
  29. package/dist/conformance/runtime.d.ts +58 -0
  30. package/dist/conformance/runtime.js +314 -0
  31. package/dist/files/paths.d.ts +99 -0
  32. package/dist/files/paths.js +263 -0
  33. package/dist/files/types.d.ts +24 -0
  34. package/dist/files/types.js +83 -0
  35. package/dist/guide/gates.d.ts +3 -0
  36. package/dist/guide/gates.js +19 -0
  37. package/dist/guide/guide.d.ts +2 -0
  38. package/dist/guide/guide.js +44 -32
  39. package/dist/guide/limits.js +4 -4
  40. package/dist/guide/runtime.d.ts +13 -0
  41. package/dist/guide/runtime.js +202 -0
  42. package/dist/host/create-host.js +45 -0
  43. package/dist/host/locate.js +8 -0
  44. package/dist/host/locator.js +7 -0
  45. package/dist/host/types.d.ts +18 -0
  46. package/dist/index.d.ts +13 -4
  47. package/dist/index.js +16 -3
  48. package/dist/isolation/types.d.ts +8 -0
  49. package/dist/presets/presets.d.ts +6 -0
  50. package/dist/presets/presets.js +1 -0
  51. package/dist/protocol/adapter.d.ts +4 -0
  52. package/dist/protocol/mcp-apps.d.ts +6 -0
  53. package/dist/protocol/mcp-apps.js +6 -0
  54. package/dist/protocol/runtime-calls.d.ts +28 -0
  55. package/dist/protocol/runtime-calls.js +113 -0
  56. package/dist/protocol/shell-adapter.js +52 -3
  57. package/dist/react/dialog.js +31 -0
  58. package/dist/react/frame.d.ts +13 -0
  59. package/dist/react/frame.js +6 -0
  60. package/dist/runtime/contract.d.ts +193 -0
  61. package/dist/runtime/contract.js +216 -0
  62. package/dist/runtime/db.d.ts +153 -0
  63. package/dist/runtime/db.js +398 -0
  64. package/dist/runtime/declaration.d.ts +86 -0
  65. package/dist/runtime/declaration.js +266 -0
  66. package/dist/runtime/levels.d.ts +33 -0
  67. package/dist/runtime/levels.js +41 -0
  68. package/dist/runtime/requests.d.ts +125 -0
  69. package/dist/runtime/requests.js +199 -0
  70. package/dist/runtime/segments.d.ts +8 -0
  71. package/dist/runtime/segments.js +14 -0
  72. package/dist/runtime/types.generated.d.ts +1 -0
  73. package/dist/runtime/types.generated.js +19 -0
  74. package/dist/server/files.d.ts +57 -0
  75. package/dist/server/files.js +338 -0
  76. package/dist/server/host.d.ts +44 -2
  77. package/dist/server/host.js +42 -2
  78. package/dist/server/index.d.ts +5 -2
  79. package/dist/server/index.js +5 -1
  80. package/dist/server/keys.d.ts +8 -0
  81. package/dist/server/keys.js +34 -0
  82. package/dist/server/pseudonym.d.ts +9 -0
  83. package/dist/server/pseudonym.js +20 -0
  84. package/dist/server/server.d.ts +0 -5
  85. package/dist/server/server.js +468 -24
  86. package/dist/server/types.d.ts +118 -5
  87. package/dist/shell/document.d.ts +27 -0
  88. package/dist/shell/document.js +46 -2
  89. package/dist/shell/legacy.d.ts +21 -0
  90. package/dist/shell/legacy.js +63 -0
  91. package/dist/shell/plan.d.ts +17 -1
  92. package/dist/shell/plan.js +13 -2
  93. package/dist/shell/runtime.d.ts +2 -1
  94. package/dist/shell/runtime.js +114 -46
  95. package/dist/shell/use.d.ts +15 -0
  96. package/dist/shell/use.js +235 -0
  97. package/docs/ADOPTING.md +142 -5
  98. package/docs/ARCHITECTURE.md +34 -5
  99. package/docs/DECISIONS.md +716 -7
  100. package/docs/DESIGN.md +97 -3
  101. package/package.json +3 -1
  102. package/src/bridge/bridge.ts +281 -17
  103. package/src/bridge/navigation.ts +12 -0
  104. package/src/bridge/refusal.ts +16 -0
  105. package/src/bridge/types.ts +46 -4
  106. package/src/check/check.ts +100 -14
  107. package/src/check/files.ts +384 -0
  108. package/src/check/instrument.ts +3 -0
  109. package/src/check/lint.ts +33 -12
  110. package/src/check/page.ts +14 -0
  111. package/src/check/tools.ts +52 -3
  112. package/src/compile/policy.ts +92 -0
  113. package/src/config/capabilities.ts +49 -2
  114. package/src/config/schema.ts +32 -0
  115. package/src/config/validate.ts +107 -5
  116. package/src/conformance/index.ts +7 -0
  117. package/src/conformance/runtime.ts +573 -0
  118. package/src/files/paths.ts +323 -0
  119. package/src/files/types.ts +101 -0
  120. package/src/guide/gates.ts +25 -0
  121. package/src/guide/guide.ts +78 -52
  122. package/src/guide/limits.ts +4 -4
  123. package/src/guide/runtime.ts +244 -0
  124. package/src/host/create-host.ts +55 -0
  125. package/src/host/locate.ts +10 -0
  126. package/src/host/locator.ts +11 -0
  127. package/src/host/types.ts +18 -0
  128. package/src/index.ts +121 -0
  129. package/src/isolation/types.ts +8 -0
  130. package/src/presets/presets.ts +7 -0
  131. package/src/protocol/adapter.ts +3 -1
  132. package/src/protocol/mcp-apps.ts +7 -0
  133. package/src/protocol/runtime-calls.ts +138 -0
  134. package/src/protocol/shell-adapter.ts +56 -2
  135. package/src/react/dialog.tsx +33 -0
  136. package/src/react/frame.tsx +19 -0
  137. package/src/runtime/contract.ts +305 -0
  138. package/src/runtime/db.ts +530 -0
  139. package/src/runtime/declaration.ts +378 -0
  140. package/src/runtime/levels.ts +69 -0
  141. package/src/runtime/requests.ts +339 -0
  142. package/src/runtime/segments.ts +17 -0
  143. package/src/runtime/types.generated.ts +19 -0
  144. package/src/server/files.ts +425 -0
  145. package/src/server/host.ts +84 -3
  146. package/src/server/index.ts +22 -0
  147. package/src/server/keys.ts +53 -0
  148. package/src/server/pseudonym.ts +21 -0
  149. package/src/server/server.ts +565 -26
  150. package/src/server/types.ts +124 -4
  151. package/src/shell/document.ts +74 -4
  152. package/src/shell/legacy.ts +64 -0
  153. package/src/shell/plan.ts +37 -3
  154. package/src/shell/runtime.ts +114 -46
  155. package/src/shell/use.ts +235 -0
  156. package/types/runtime/v1/artifact.d.ts +50 -0
  157. package/types/runtime/v1/assets.d.ts +43 -0
  158. package/types/runtime/v1/chat.d.ts +13 -0
  159. package/types/runtime/v1/clipboard.d.ts +14 -0
  160. package/types/runtime/v1/comments.d.ts +24 -0
  161. package/types/runtime/v1/context.d.ts +16 -0
  162. package/types/runtime/v1/data.d.ts +29 -0
  163. package/types/runtime/v1/db.d.ts +110 -0
  164. package/types/runtime/v1/downloads.d.ts +22 -0
  165. package/types/runtime/v1/links.d.ts +13 -0
  166. package/types/runtime/v1/porthole.d.ts +44 -0
  167. package/types/runtime/v1/user.d.ts +19 -0
@@ -0,0 +1,425 @@
1
+ import type { CompiledConfig } from "../compile/compile.ts";
2
+ import {
3
+ assetCspDirectives,
4
+ fileSetCspDirectives,
5
+ INERT_FILE_CSP,
6
+ serializeCsp,
7
+ } from "../compile/policy.ts";
8
+ import { DEFAULT_ENTRY, lookupFile, requestFilePath, type FileLookup } from "../files/paths.ts";
9
+ import { fileTypeOf } from "../files/types.ts";
10
+ import { isCodeAsset } from "../runtime/requests.ts";
11
+ import { sha256, utf8 } from "./crypto.ts";
12
+ import type { FileBody, StoredAsset, StoredFiles } from "./types.ts";
13
+
14
+ /**
15
+ * Serving a version made of files (P081, P082): each path looked up in its manifest only, each
16
+ * answer typed by Porthole's table, with `nosniff`, its CSP in a header, its cache rule and a
17
+ * strong ETag; pages in the shell, ranges for the rest.
18
+ */
19
+
20
+ export interface FileServing {
21
+ readonly request: Request;
22
+ readonly set: StoredFiles;
23
+ /** The request's path below the base, as the URL has it (percent-encoded). */
24
+ readonly rest: string;
25
+ /** The search part, kept on a redirect. */
26
+ readonly search: string;
27
+ /** The version's own address on its origin: a path ending in `/`. */
28
+ readonly base: string;
29
+ readonly origin: string;
30
+ /**
31
+ * Whether `base` names this version and no other (a pinned address, a frame's): its files are
32
+ * immutable there. Else they are revalidated (an address that may mean another version later).
33
+ */
34
+ readonly pinned: boolean;
35
+ /** The CSP source the version's files load from (P082): its path on the origin. */
36
+ readonly source: string;
37
+ readonly compiled: CompiledConfig;
38
+ readonly hostOrigins: readonly string[];
39
+ readonly frameAncestors: string;
40
+ /**
41
+ * A ticket's answer (P083): the entry, served at the ticket's address, never stored; its shell
42
+ * moves the frame to the entry's own address under `base` before anything loads, and renews
43
+ * that address before it ends (`expires`, epoch ms).
44
+ */
45
+ readonly ticket?: { readonly expires: number };
46
+ }
47
+
48
+ const HEX = /^[0-9a-f]{64}$/u;
49
+ const YEAR = 31_536_000;
50
+
51
+ const hex = (bytes: Uint8Array): string =>
52
+ Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
53
+
54
+ /** A path's segments percent-encoded, for a `Location`. */
55
+ const encodePath = (path: string): string =>
56
+ path
57
+ .split("/")
58
+ .map((segment) => encodeURIComponent(segment))
59
+ .join("/");
60
+
61
+ /** Whether the request is a page loading (a navigation), not a subresource. */
62
+ export function isNavigation(request: Request): boolean {
63
+ const mode = request.headers.get("sec-fetch-mode");
64
+ const dest = request.headers.get("sec-fetch-dest");
65
+ if (mode !== null || dest !== null) {
66
+ return mode === "navigate" || dest === "document" || dest === "iframe" || dest === "frame";
67
+ }
68
+ return (request.headers.get("accept") ?? "").includes("text/html");
69
+ }
70
+
71
+ /**
72
+ * Whether the request is a running page's own load: from its own origin (`Sec-Fetch-Site`, which
73
+ * only a browser sets and no page can change), and not a navigation.
74
+ */
75
+ export const ownLoad = (request: Request): boolean =>
76
+ request.headers.get("sec-fetch-site") === "same-origin" && !isNavigation(request);
77
+
78
+ /** Whether `If-None-Match` names this ETag. */
79
+ function notModified(request: Request, etag: string): boolean {
80
+ const asked = request.headers.get("if-none-match");
81
+ if (asked === null) {
82
+ return false;
83
+ }
84
+ return asked
85
+ .split(",")
86
+ .map((each) => each.trim().replace(/^W\//u, ""))
87
+ .some((each) => each === "*" || each === etag);
88
+ }
89
+
90
+ /** A single `bytes=` range of a body of `size` bytes: the range, "unsatisfiable", or null (ignore it). */
91
+ function rangeOf(
92
+ header: string | null,
93
+ size: number,
94
+ ): { readonly start: number; readonly end: number } | "unsatisfiable" | null {
95
+ if (header === null) {
96
+ return null;
97
+ }
98
+ const match = /^bytes=(\d*)-(\d*)$/u.exec(header.trim());
99
+ if (match === null) {
100
+ return null;
101
+ }
102
+ const [, from = "", to = ""] = match;
103
+ if (from === "" && to === "") {
104
+ return null;
105
+ }
106
+ if (from === "") {
107
+ // The last `to` bytes.
108
+ const length = Number(to);
109
+ if (length === 0) {
110
+ return "unsatisfiable";
111
+ }
112
+ return size === 0 ? "unsatisfiable" : { start: Math.max(0, size - length), end: size - 1 };
113
+ }
114
+ const start = Number(from);
115
+ const end = to === "" ? size - 1 : Math.min(Number(to), size - 1);
116
+ if (!Number.isSafeInteger(start) || start >= size || end < start) {
117
+ return "unsatisfiable";
118
+ }
119
+ return { start, end };
120
+ }
121
+
122
+ /** `body` from byte `start` through `end`. */
123
+ function slice(body: FileBody, start: number, end: number): FileBody {
124
+ if (body instanceof Uint8Array) {
125
+ return body.subarray(start, end + 1);
126
+ }
127
+ let offset = 0;
128
+ return body.pipeThrough(
129
+ new TransformStream<Uint8Array, Uint8Array>({
130
+ transform(chunk, controller) {
131
+ const from = Math.max(start - offset, 0);
132
+ const to = Math.min(end + 1 - offset, chunk.byteLength);
133
+ if (from < to) {
134
+ controller.enqueue(chunk.subarray(from, to));
135
+ }
136
+ offset += chunk.byteLength;
137
+ if (offset > end) {
138
+ controller.terminate();
139
+ }
140
+ },
141
+ }),
142
+ );
143
+ }
144
+
145
+ async function textOf(body: FileBody): Promise<string> {
146
+ if (body instanceof Uint8Array) {
147
+ return new TextDecoder().decode(body);
148
+ }
149
+ return new Response(body).text();
150
+ }
151
+
152
+ const asBody = (body: FileBody): BodyInit =>
153
+ body instanceof Uint8Array ? new Uint8Array(body) : body;
154
+
155
+ /** The answer for nothing found: plain, inert. */
156
+ function nothing(serving: FileServing, status: 403 | 404 | 405, method: string): Response {
157
+ const text =
158
+ status === 404 ? "Not found" : status === 405 ? "Content here is only read" : "Not allowed";
159
+ return new Response(method === "HEAD" ? null : text, {
160
+ status,
161
+ headers: {
162
+ "content-type": "text/plain; charset=utf-8",
163
+ "content-security-policy": `${INERT_FILE_CSP}; frame-ancestors ${serving.frameAncestors}`,
164
+ "cache-control": "no-store",
165
+ "x-content-type-options": "nosniff",
166
+ "referrer-policy": "no-referrer",
167
+ "x-robots-tag": "noindex, nofollow",
168
+ ...(status === 405 ? { allow: "GET, HEAD" } : {}),
169
+ },
170
+ });
171
+ }
172
+
173
+ export async function serveFile(serving: FileServing): Promise<Response> {
174
+ const { request, set } = serving;
175
+ const method = request.method.toUpperCase();
176
+ // No service worker, ever: one would answer this origin's requests with documents of its
177
+ // own making, outside the shell and its CSP (P081).
178
+ if (
179
+ request.headers.get("service-worker") !== null ||
180
+ request.headers.get("sec-fetch-dest") === "serviceworker"
181
+ ) {
182
+ return nothing(serving, 403, method);
183
+ }
184
+ if (method !== "GET" && method !== "HEAD") {
185
+ return nothing(serving, 405, method);
186
+ }
187
+ const path = requestFilePath(serving.rest);
188
+ if (path === null) {
189
+ return nothing(serving, 404, method);
190
+ }
191
+ const has = (each: string): boolean => Object.hasOwn(set.files, each);
192
+ const entryPath = set.entry ?? DEFAULT_ENTRY;
193
+ const found: FileLookup =
194
+ serving.ticket !== undefined
195
+ ? has(entryPath)
196
+ ? { kind: "file", path: entryPath, status: 200 }
197
+ : { kind: "none" }
198
+ : lookupFile(has, path, {
199
+ ...(set.entry === undefined ? {} : { entry: set.entry }),
200
+ ...(set.spa === undefined ? {} : { spa: set.spa }),
201
+ navigation: isNavigation(request),
202
+ });
203
+ if (found.kind === "none") {
204
+ return nothing(serving, 404, method);
205
+ }
206
+ // The version's own address, as a URL writes it.
207
+ const base = new URL(serving.base, serving.origin).href;
208
+ if (found.kind === "redirect") {
209
+ return new Response(null, {
210
+ status: 307,
211
+ headers: {
212
+ location: `${base}${encodePath(found.to)}${serving.search}`,
213
+ "cache-control": "no-store",
214
+ "referrer-policy": "no-referrer",
215
+ "x-robots-tag": "noindex, nofollow",
216
+ },
217
+ });
218
+ }
219
+ const entry = set.files[found.path];
220
+ const body = entry === undefined ? null : await set.read(found.path);
221
+ if (entry === undefined || body === null) {
222
+ return nothing(serving, 404, method);
223
+ }
224
+ const { type, role } = fileTypeOf(found.path);
225
+ // In a frame, the version's files are at a sealed address (P083), which their own loads of the
226
+ // artifact's assets carry as their `Referer` (P091): to this origin only, never another.
227
+ const referrer =
228
+ serving.base.startsWith("/__porthole/f/") &&
229
+ serving.compiled.config.capabilities.assets !== undefined
230
+ ? "same-origin"
231
+ : "no-referrer";
232
+ // Its version's files (P082), and its artifact's assets where the config serves them (P089).
233
+ const frameCsp = serializeCsp(
234
+ assetCspDirectives(
235
+ serving.compiled.config,
236
+ fileSetCspDirectives(serving.compiled.cspDirectives, serving.source),
237
+ serving.origin,
238
+ ),
239
+ );
240
+ const headers = new Headers({
241
+ "content-type": type,
242
+ "x-content-type-options": "nosniff",
243
+ "referrer-policy": referrer,
244
+ "x-robots-tag": "noindex, nofollow",
245
+ // A page and a script (a worker's policy is its script's) get the page's CSP; anything else
246
+ // runs nothing when opened on its own.
247
+ "content-security-policy": `${role === "file" ? INERT_FILE_CSP : frameCsp}; frame-ancestors ${serving.frameAncestors}`,
248
+ });
249
+
250
+ if (role === "page") {
251
+ // Every page of the set in the shell (P081): its hardening, its host functions, its theme.
252
+ const html = serving.compiled.shellDocument({
253
+ origins: serving.hostOrigins,
254
+ document: await textOf(body),
255
+ cspMeta: false,
256
+ ...(referrer === "same-origin" ? { referrer } : {}),
257
+ files: {
258
+ base,
259
+ // At a ticket's address: the entry's own (its directory's, for an entry in one).
260
+ ...(serving.ticket === undefined
261
+ ? {}
262
+ : {
263
+ address: `${base}${found.path.includes("/") ? encodePath(found.path) : ""}`,
264
+ expires: serving.ticket.expires,
265
+ }),
266
+ },
267
+ });
268
+ if (serving.ticket !== undefined) {
269
+ headers.set("cache-control", "no-store");
270
+ return new Response(method === "HEAD" ? null : html, { status: 200, headers });
271
+ }
272
+ const etag = `"${hex(sha256(utf8(html)))}"`;
273
+ headers.set("etag", etag);
274
+ // A page is asked again each time it loads, so the host's check runs on every navigation.
275
+ headers.set("cache-control", "private, no-cache");
276
+ if (found.status === 200 && notModified(request, etag)) {
277
+ return new Response(null, { status: 304, headers });
278
+ }
279
+ return new Response(method === "HEAD" ? null : html, { status: found.status, headers });
280
+ }
281
+
282
+ const size = body instanceof Uint8Array ? body.byteLength : entry.size;
283
+ const etag = HEX.test(entry.sha256) ? `"${entry.sha256}"` : null;
284
+ if (etag !== null) {
285
+ headers.set("etag", etag);
286
+ }
287
+ headers.set(
288
+ "cache-control",
289
+ serving.pinned ? `private, max-age=${YEAR}, immutable` : "private, no-cache",
290
+ );
291
+ // Only this origin's own pages load it: no other content origin (a sibling, same-site without
292
+ // the public suffix list) can embed it with the viewer's cookie.
293
+ headers.set("cross-origin-resource-policy", "same-origin");
294
+ headers.set("accept-ranges", "bytes");
295
+ if (role === "file" && type === "application/octet-stream") {
296
+ headers.set("content-disposition", "attachment");
297
+ }
298
+ if (etag !== null && notModified(request, etag)) {
299
+ if (!(body instanceof Uint8Array)) {
300
+ await body.cancel();
301
+ }
302
+ return new Response(null, { status: 304, headers });
303
+ }
304
+ const range = found.status === 200 ? rangeOf(request.headers.get("range"), size) : null;
305
+ if (range === "unsatisfiable") {
306
+ if (!(body instanceof Uint8Array)) {
307
+ await body.cancel();
308
+ }
309
+ headers.set("content-range", `bytes */${size}`);
310
+ return new Response(null, { status: 416, headers });
311
+ }
312
+ if (range !== null) {
313
+ headers.set("content-range", `bytes ${range.start}-${range.end}/${size}`);
314
+ headers.set("content-length", String(range.end - range.start + 1));
315
+ if (method === "HEAD" && !(body instanceof Uint8Array)) {
316
+ await body.cancel();
317
+ }
318
+ return new Response(method === "HEAD" ? null : asBody(slice(body, range.start, range.end)), {
319
+ status: 206,
320
+ headers,
321
+ });
322
+ }
323
+ // A stream's length is the manifest's word: said for HEAD, left to the transfer otherwise.
324
+ if (body instanceof Uint8Array || method === "HEAD") {
325
+ headers.set("content-length", String(size));
326
+ }
327
+ if (method === "HEAD" && !(body instanceof Uint8Array)) {
328
+ await body.cancel();
329
+ }
330
+ return new Response(method === "HEAD" ? null : asBody(body), { status: found.status, headers });
331
+ }
332
+
333
+ /**
334
+ * An asset of an artifact's library (P089), at `/_blob/<id>`: typed by Porthole's table by its
335
+ * name, never as a page (one named so goes as a download), inert opened on its own (an SVG runs
336
+ * nothing), `nosniff`, loaded only by its own origin's pages (CORP), immutable (an id never names
337
+ * other bytes), its sha256 the ETag, ranges for media.
338
+ */
339
+ export async function serveAsset(serving: {
340
+ readonly request: Request;
341
+ readonly asset: StoredAsset;
342
+ readonly frameAncestors: string;
343
+ /** Whether a code-typed asset is served as code (trusted, where uploaded code runs). */
344
+ readonly code: boolean;
345
+ }): Promise<Response> {
346
+ const { request, asset } = serving;
347
+ const method = request.method.toUpperCase();
348
+ const plain = (status: 404 | 405) =>
349
+ new Response(method === "HEAD" ? null : status === 404 ? "Not found" : "Only read", {
350
+ status,
351
+ headers: {
352
+ "content-type": "text/plain; charset=utf-8",
353
+ "content-security-policy": `${INERT_FILE_CSP}; frame-ancestors ${serving.frameAncestors}`,
354
+ "cache-control": "no-store",
355
+ "x-content-type-options": "nosniff",
356
+ ...(status === 405 ? { allow: "GET, HEAD" } : {}),
357
+ },
358
+ });
359
+ if (method !== "GET" && method !== "HEAD") {
360
+ return plain(405);
361
+ }
362
+ const body = await asset.read();
363
+ if (body === null) {
364
+ return plain(404);
365
+ }
366
+ const typed = fileTypeOf(asset.name);
367
+ // Never a page: an asset is the library's, outside the shell (P089); code only where it was
368
+ // trusted when it was uploaded (after the review).
369
+ const type =
370
+ typed.role === "page" || (isCodeAsset(asset.name) && !serving.code)
371
+ ? "application/octet-stream"
372
+ : typed.type;
373
+ const headers = new Headers({
374
+ "content-type": type,
375
+ "x-content-type-options": "nosniff",
376
+ "referrer-policy": "no-referrer",
377
+ "x-robots-tag": "noindex, nofollow",
378
+ "content-security-policy": `${INERT_FILE_CSP}; frame-ancestors ${serving.frameAncestors}`,
379
+ // Asked again at each load, so a removal or a revocation holds at once (after the review);
380
+ // the ETag keeps it cheap.
381
+ "cache-control": "private, no-cache",
382
+ "cross-origin-resource-policy": "same-origin",
383
+ "accept-ranges": "bytes",
384
+ });
385
+ if (type === "application/octet-stream") {
386
+ headers.set("content-disposition", "attachment");
387
+ }
388
+ const etag = HEX.test(asset.sha256) ? `"${asset.sha256}"` : null;
389
+ if (etag !== null) {
390
+ headers.set("etag", etag);
391
+ if (notModified(request, etag)) {
392
+ if (!(body instanceof Uint8Array)) {
393
+ await body.cancel();
394
+ }
395
+ return new Response(null, { status: 304, headers });
396
+ }
397
+ }
398
+ const size = body instanceof Uint8Array ? body.byteLength : asset.size;
399
+ const range = rangeOf(request.headers.get("range"), size);
400
+ if (range === "unsatisfiable") {
401
+ if (!(body instanceof Uint8Array)) {
402
+ await body.cancel();
403
+ }
404
+ headers.set("content-range", `bytes */${size}`);
405
+ return new Response(null, { status: 416, headers });
406
+ }
407
+ if (range !== null) {
408
+ headers.set("content-range", `bytes ${range.start}-${range.end}/${size}`);
409
+ headers.set("content-length", String(range.end - range.start + 1));
410
+ if (method === "HEAD" && !(body instanceof Uint8Array)) {
411
+ await body.cancel();
412
+ }
413
+ return new Response(method === "HEAD" ? null : asBody(slice(body, range.start, range.end)), {
414
+ status: 206,
415
+ headers,
416
+ });
417
+ }
418
+ if (body instanceof Uint8Array || method === "HEAD") {
419
+ headers.set("content-length", String(size));
420
+ }
421
+ if (method === "HEAD" && !(body instanceof Uint8Array)) {
422
+ await body.cancel();
423
+ }
424
+ return new Response(method === "HEAD" ? null : asBody(body), { status: 200, headers });
425
+ }
@@ -16,6 +16,7 @@ import { createServer } from "./server.ts";
16
16
  import type {
17
17
  Access,
18
18
  ArtifactStore,
19
+ AssetStore,
19
20
  AuthorizeAnswer,
20
21
  AuthorizeRequest,
21
22
  Grant,
@@ -156,6 +157,11 @@ export interface ContentHostOptions<V> {
156
157
  readonly authorizeTtlSeconds?: number;
157
158
  /** Policy 4, source: a stored page by id and version (artifact documents). */
158
159
  readonly source?: ArtifactStore["get"];
160
+ /**
161
+ * Policy 5, assets (P089): an artifact's asset library by id, served at `/_blob/<id>` to an
162
+ * access for its artifact; or the store itself, with `bearer` (an explicit opt-in).
163
+ */
164
+ readonly assets?: AssetStore["get"] | AssetStore;
159
165
  readonly upstream?: Upstream;
160
166
  /**
161
167
  * The health gate, and with it the opaque fallback (P066): the kit checks the content domain
@@ -199,7 +205,7 @@ export interface EntryOptions<V> {
199
205
  path: string,
200
206
  viewer: V | null,
201
207
  request: Request,
202
- ) => Awaitable<InstanceRef | null | undefined>;
208
+ ) => Awaitable<InstanceRef | FileAddress | null | undefined>;
203
209
  /**
204
210
  * The app's own sign-in, which comes back to `returnTo` (the authorize URL, as `authorizeUrl`
205
211
  * names the app, with the entry's state) once signed in.
@@ -244,6 +250,61 @@ export interface EntryOptions<V> {
244
250
  ) => Awaitable<Response | null | undefined>;
245
251
  }
246
252
 
253
+ /**
254
+ * What a clean address means when its instance is a version made of files (P081): the instance,
255
+ * the version's own address (`base`, a path ending in `/`: `/v/3/`), and the file the address
256
+ * asks for below it (`""`: the version's entry). The session the entry buys serves every path
257
+ * under `base`, so the page's relative addresses are its own version's. An address that isn't
258
+ * under `base` (`/`, `/style.css`: the latest) goes to `base` + `file`, so a page never mixes
259
+ * versions when a new one is published while it loads. `versionedAddress` reads the usual
260
+ * convention (`/v/<n>/<file>`, else the latest).
261
+ */
262
+ export interface FileAddress {
263
+ readonly instance: InstanceRef;
264
+ /** A path ending in `/`, each segment of `A-Z a-z 0-9 . _ : ~ -`, no `.` or `..` segment. */
265
+ readonly base: string;
266
+ readonly file?: string;
267
+ /**
268
+ * Whether `base` names this version and no other (`/v/3/`, never `/` or `/latest/`): its files
269
+ * are then immutable there. Default false: revalidated, as an address that may mean another
270
+ * version later.
271
+ */
272
+ readonly pinned?: boolean;
273
+ }
274
+
275
+ /** Whether `entry.at`'s answer is a file set's address rather than an instance. */
276
+ export const isFileAddress = (value: InstanceRef | FileAddress): value is FileAddress =>
277
+ "base" in value && "instance" in value;
278
+
279
+ /** Kept free on every content origin for an asset library across versions (P081): not built. */
280
+ export const ASSET_LIBRARY_PATH = "/_blob/";
281
+
282
+ /**
283
+ * The convention for a versioned scope's clean addresses (P081): `/v/<version>/<file>` is that
284
+ * version, pinned; any other path is the latest's `<file>` (`version` null). Null for a
285
+ * `/v/<version>` whose version isn't a name (`A-Z a-z 0-9 . _ : -`), and under `/_blob/`, kept for
286
+ * an asset library outside every version. `versionBase(version)` is the base to answer with.
287
+ */
288
+ export function versionedAddress(
289
+ path: string,
290
+ ): { readonly version: string | null; readonly file: string } | null {
291
+ if (path.startsWith(ASSET_LIBRARY_PATH)) {
292
+ return null;
293
+ }
294
+ const pinned = /^\/v\/([^/]*)(?:\/(.*))?$/u.exec(path);
295
+ if (pinned === null) {
296
+ return { version: null, file: path.replace(/^\//u, "") };
297
+ }
298
+ const [, version = "", file = ""] = pinned;
299
+ // A version is a name, never a dot segment.
300
+ return /^[A-Za-z0-9._:-]{1,200}$/u.test(version) && !/^\.{1,2}$/u.test(version)
301
+ ? { version, file }
302
+ : null;
303
+ }
304
+
305
+ /** A version's own address in `versionedAddress`'s convention: `/v/<version>/`. */
306
+ export const versionBase = (version: string): string => `/v/${version}/`;
307
+
247
308
  /** The clean address a redirect entry is opening, as its authorize route decoded it (P070). */
248
309
  export interface EntryContext {
249
310
  /** The address's label, and the scope it names (null: one the naming never makes). */
@@ -472,6 +533,12 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
472
533
  hostOrigins: options.appOrigins,
473
534
  configs,
474
535
  ...(options.source === undefined ? {} : { artifacts: { get: options.source } }),
536
+ ...(options.assets === undefined
537
+ ? {}
538
+ : {
539
+ assets:
540
+ typeof options.assets === "function" ? { get: options.assets } : options.assets,
541
+ }),
475
542
  ...(options.tickets === undefined ? {} : { tickets: options.tickets }),
476
543
  ...(options.upstream === undefined ? {} : { upstream: options.upstream }),
477
544
  ...(options.entry === undefined
@@ -1036,7 +1103,7 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1036
1103
  );
1037
1104
  }
1038
1105
  try {
1039
- const instance =
1106
+ const answer =
1040
1107
  scope === null
1041
1108
  ? null
1042
1109
  : ((await entry.at(
@@ -1045,6 +1112,9 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1045
1112
  viewer,
1046
1113
  request,
1047
1114
  )) ?? null);
1115
+ // A file set's address (P081) names its instance and where its version lives.
1116
+ const address = answer !== null && isFileAddress(answer) ? answer : null;
1117
+ const instance = address === null ? (answer as InstanceRef | null) : address.instance;
1048
1118
  const grant = instance === null ? null : await options.access(instance, viewer, request);
1049
1119
  // The address being opened, decoded, for the app's sign-in and refusal pages.
1050
1120
  const context: EntryContext = {
@@ -1091,7 +1161,18 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1091
1161
  }
1092
1162
  let location: string;
1093
1163
  try {
1094
- location = await server.enterBy(state, instance, grant);
1164
+ location = await server.enterBy(
1165
+ state,
1166
+ instance,
1167
+ grant,
1168
+ address === null
1169
+ ? undefined
1170
+ : {
1171
+ base: address.base,
1172
+ ...(address.file === undefined ? {} : { file: address.file }),
1173
+ ...(address.pinned === true ? { pinned: true } : {}),
1174
+ },
1175
+ );
1095
1176
  } catch {
1096
1177
  return appPage(
1097
1178
  409,
@@ -44,6 +44,11 @@ export {
44
44
  type ContentLogger,
45
45
  type EntryContext,
46
46
  type EntryOptions,
47
+ ASSET_LIBRARY_PATH,
48
+ type FileAddress,
49
+ isFileAddress,
50
+ versionBase,
51
+ versionedAddress,
47
52
  type ContentMeta,
48
53
  type HealthOptions,
49
54
  type HealthProbe,
@@ -79,9 +84,26 @@ export {
79
84
  } from "./proxy.ts";
80
85
  export { statusPageOf as statusPage } from "./pages.ts";
81
86
  export { contentHostFor, type ContentHostFor } from "./bootstrap.ts";
87
+ // A version made of files (P081): the rules its paths follow, its limits and its types.
88
+ export {
89
+ checkFileSet,
90
+ DEFAULT_ENTRY,
91
+ fileLimits,
92
+ filePathProblem,
93
+ type FileLimits,
94
+ type FileSetProblem,
95
+ } from "../files/paths.ts";
96
+ export { fileTypeOf, type FileRole, type FileType } from "../files/types.ts";
97
+ export { pseudonymFor } from "./pseudonym.ts";
82
98
  export type {
83
99
  Access,
84
100
  ArtifactStore,
101
+ AssetStore,
102
+ StoredAsset,
103
+ FileBody,
104
+ StoredFile,
105
+ StoredFiles,
106
+ StoredVersion,
85
107
  AuthorizeAnswer,
86
108
  AuthorizeRequest,
87
109
  Authorizer,
@@ -59,8 +59,19 @@ export interface Keys {
59
59
  sign(value: unknown): string;
60
60
  /** The signed value, or null when the signature doesn't hold. */
61
61
  verify(token: string): unknown;
62
+ /**
63
+ * `value` sealed (AES-256-GCM, Web Crypto): unreadable and unforgeable without the secret,
64
+ * base64url. A file set's access in a frame's path (P083), which content can read: the viewer
65
+ * and the host's subject inside it stay the host's.
66
+ */
67
+ seal(value: unknown): Promise<string>;
68
+ /** The sealed value, or null when it doesn't open. */
69
+ unseal(token: string): Promise<unknown>;
62
70
  }
63
71
 
72
+ /** What a sealed value is bound to, so it can never be taken for anything else sealed. */
73
+ const SEAL_CONTEXT = utf8("porthole/files");
74
+
64
75
  export function createKeys(secret: Uint8Array): Keys {
65
76
  if (secret.byteLength < 32) {
66
77
  throw new TypeError("The server's secret must be at least 32 random bytes");
@@ -69,6 +80,13 @@ export function createKeys(secret: Uint8Array): Keys {
69
80
  const labelKey = derive("label");
70
81
  const instanceKey = derive("instance");
71
82
  const signKey = derive("session");
83
+ const sealKey = derive("files");
84
+ let sealing: Promise<CryptoKey> | null = null;
85
+ const sealingKey = (): Promise<CryptoKey> =>
86
+ (sealing ??= crypto.subtle.importKey("raw", new Uint8Array(sealKey), "AES-GCM", false, [
87
+ "encrypt",
88
+ "decrypt",
89
+ ]));
72
90
  const mac = (key: Uint8Array, text: string): Uint8Array => hmacSha256(key, utf8(text));
73
91
 
74
92
  return {
@@ -98,6 +116,41 @@ export function createKeys(secret: Uint8Array): Keys {
98
116
  return null;
99
117
  }
100
118
  },
119
+ seal: async (value) => {
120
+ const iv = randomBytes(12);
121
+ const sealed = new Uint8Array(
122
+ await crypto.subtle.encrypt(
123
+ { name: "AES-GCM", iv: new Uint8Array(iv), additionalData: new Uint8Array(SEAL_CONTEXT) },
124
+ await sealingKey(),
125
+ new Uint8Array(utf8(JSON.stringify(value))),
126
+ ),
127
+ );
128
+ const token = new Uint8Array(iv.length + sealed.length);
129
+ token.set(iv);
130
+ token.set(sealed, iv.length);
131
+ return base64url(token);
132
+ },
133
+ unseal: async (token) => {
134
+ const bytes = token.length > 8_192 ? null : fromBase64url(token);
135
+ // 12 bytes of IV and 16 of tag at least.
136
+ if (bytes === null || bytes.length < 29) {
137
+ return null;
138
+ }
139
+ try {
140
+ const opened = await crypto.subtle.decrypt(
141
+ {
142
+ name: "AES-GCM",
143
+ iv: new Uint8Array(bytes.subarray(0, 12)),
144
+ additionalData: new Uint8Array(SEAL_CONTEXT),
145
+ },
146
+ await sealingKey(),
147
+ new Uint8Array(bytes.subarray(12)),
148
+ );
149
+ return JSON.parse(fromUtf8(new Uint8Array(opened))) as unknown;
150
+ } catch {
151
+ return null;
152
+ }
153
+ },
101
154
  };
102
155
  }
103
156