@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.
Files changed (73) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.js +8 -5
  3. package/dist/bridge/navigation.d.ts +1 -6
  4. package/dist/bridge/navigation.js +11 -0
  5. package/dist/check/check.d.ts +12 -3
  6. package/dist/check/check.js +54 -8
  7. package/dist/check/files.d.ts +26 -0
  8. package/dist/check/files.js +307 -0
  9. package/dist/check/lint.js +27 -10
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/tools.d.ts +23 -0
  12. package/dist/check/tools.js +25 -0
  13. package/dist/compile/policy.d.ts +15 -0
  14. package/dist/compile/policy.js +32 -0
  15. package/dist/config/schema.d.ts +8 -0
  16. package/dist/config/validate.js +8 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/files/paths.d.ts +99 -0
  19. package/dist/files/paths.js +263 -0
  20. package/dist/files/types.d.ts +24 -0
  21. package/dist/files/types.js +83 -0
  22. package/dist/guide/guide.js +11 -1
  23. package/dist/host/create-host.js +21 -0
  24. package/dist/index.d.ts +6 -3
  25. package/dist/index.js +8 -3
  26. package/dist/protocol/adapter.d.ts +4 -0
  27. package/dist/protocol/mcp-apps.d.ts +6 -0
  28. package/dist/protocol/mcp-apps.js +6 -0
  29. package/dist/protocol/shell-adapter.js +5 -1
  30. package/dist/server/files.d.ts +44 -0
  31. package/dist/server/files.js +244 -0
  32. package/dist/server/host.d.ts +38 -1
  33. package/dist/server/host.js +37 -2
  34. package/dist/server/index.d.ts +4 -2
  35. package/dist/server/index.js +4 -1
  36. package/dist/server/keys.d.ts +8 -0
  37. package/dist/server/keys.js +34 -0
  38. package/dist/server/server.js +287 -22
  39. package/dist/server/types.d.ts +49 -5
  40. package/dist/shell/document.d.ts +19 -0
  41. package/dist/shell/document.js +30 -0
  42. package/dist/shell/runtime.d.ts +2 -1
  43. package/dist/shell/runtime.js +85 -4
  44. package/docs/ADOPTING.md +56 -4
  45. package/docs/ARCHITECTURE.md +13 -3
  46. package/docs/DECISIONS.md +304 -4
  47. package/docs/DESIGN.md +31 -3
  48. package/package.json +1 -1
  49. package/src/bridge/bridge.ts +8 -5
  50. package/src/bridge/navigation.ts +12 -0
  51. package/src/check/check.ts +92 -14
  52. package/src/check/files.ts +384 -0
  53. package/src/check/lint.ts +29 -10
  54. package/src/check/tools.ts +50 -0
  55. package/src/compile/policy.ts +38 -0
  56. package/src/config/schema.ts +8 -0
  57. package/src/config/validate.ts +8 -1
  58. package/src/files/paths.ts +323 -0
  59. package/src/files/types.ts +101 -0
  60. package/src/guide/guide.ts +20 -0
  61. package/src/host/create-host.ts +21 -0
  62. package/src/index.ts +32 -0
  63. package/src/protocol/adapter.ts +3 -1
  64. package/src/protocol/mcp-apps.ts +7 -0
  65. package/src/protocol/shell-adapter.ts +5 -0
  66. package/src/server/files.ts +312 -0
  67. package/src/server/host.ts +72 -3
  68. package/src/server/index.ts +19 -0
  69. package/src/server/keys.ts +53 -0
  70. package/src/server/server.ts +353 -24
  71. package/src/server/types.ts +56 -4
  72. package/src/shell/document.ts +53 -0
  73. package/src/shell/runtime.ts +85 -4
@@ -0,0 +1,384 @@
1
+ import type { PortholeConfig } from "../config/schema.ts";
2
+ import {
3
+ checkFileSet,
4
+ DEFAULT_ENTRY,
5
+ fileLimits,
6
+ lookupFile,
7
+ servesFiles,
8
+ } from "../files/paths.ts";
9
+ import { fileTypeOf, knownType } from "../files/types.ts";
10
+ import { sizeWords } from "../guide/limits.ts";
11
+ import { lintContent, type Finding } from "./lint.ts";
12
+
13
+ /**
14
+ * What can be told about a page that comes with files (P081), without running it: each page
15
+ * linted as a page is, the set held to the path rules and limits, and every relative reference
16
+ * looked up in the set. Errors are what certainly fails (`admitFiles` refuses them); the rest
17
+ * are warnings. Pure: any runtime.
18
+ */
19
+
20
+ /** A finding about one file of the set (`path`), or about the set as a whole. */
21
+ export interface FileFinding extends Omit<Finding, "rule"> {
22
+ readonly rule: Finding["rule"] | "files" | "missing-file" | "root-path" | "file-type";
23
+ readonly path?: string;
24
+ }
25
+
26
+ /** A set's files, by path: text, or bytes. */
27
+ export type FileContents = Readonly<Record<string, string | Uint8Array>>;
28
+
29
+ /** A text's line numbers by offset: its line starts found once, each line then a binary search. */
30
+ function linesOf(text: string): (index: number) => number {
31
+ const starts = [0];
32
+ for (let at = text.indexOf("\n"); at >= 0; at = text.indexOf("\n", at + 1)) {
33
+ starts.push(at + 1);
34
+ }
35
+ return (index) => {
36
+ let low = 0;
37
+ let high = starts.length - 1;
38
+ while (low < high) {
39
+ const middle = (low + high + 1) >> 1;
40
+ if ((starts[middle] ?? 0) <= index) {
41
+ low = middle;
42
+ } else {
43
+ high = middle - 1;
44
+ }
45
+ }
46
+ return low + 1;
47
+ };
48
+ }
49
+
50
+ const textOf = (body: string | Uint8Array): string =>
51
+ typeof body === "string" ? body : new TextDecoder().decode(body);
52
+
53
+ const sizeOf = (body: string | Uint8Array): number =>
54
+ typeof body === "string" ? new TextEncoder().encode(body).byteLength : body.byteLength;
55
+
56
+ /** How much of one file the references are looked for in: its first 2 MiB of text. */
57
+ const SCANNED = 2 * 1024 * 1024;
58
+ /** The most references of one kind looked up in one file: past that, a file is only linted. */
59
+ const MOST_REFERENCES = 2_000;
60
+
61
+ /** A reference a file makes, and where it starts in the file's text. */
62
+ interface Reference {
63
+ readonly reference: string;
64
+ readonly index: number;
65
+ }
66
+
67
+ /** The elements whose attribute names a file the page loads or links: which attribute. */
68
+ const REFERENCE_ATTRIBUTES: Readonly<Record<string, readonly string[]>> = {
69
+ script: ["src"],
70
+ img: ["src"],
71
+ source: ["src"],
72
+ video: ["src", "poster"],
73
+ audio: ["src"],
74
+ track: ["src"],
75
+ embed: ["src"],
76
+ input: ["src"],
77
+ link: ["href"],
78
+ a: ["href"],
79
+ area: ["href"],
80
+ };
81
+
82
+ /** A tag: its name and its attributes' text. Bounded, and never across another `<`: linear. */
83
+ const TAG = /<([a-z][a-z0-9-]{0,30})\b([^<>]{0,8192})>/giu;
84
+
85
+ const isSpace = (code: number): boolean =>
86
+ code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
87
+
88
+ /** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
89
+ function attributesOf(text: string): { name: string; value: string; at: number }[] {
90
+ const out: { name: string; value: string; at: number }[] = [];
91
+ let at = 0;
92
+ while (at < text.length) {
93
+ while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
94
+ at += 1;
95
+ }
96
+ const nameStart = at;
97
+ while (
98
+ at < text.length &&
99
+ !isSpace(text.charCodeAt(at)) &&
100
+ text[at] !== "=" &&
101
+ text[at] !== "/"
102
+ ) {
103
+ at += 1;
104
+ }
105
+ const name = text.slice(nameStart, at).toLowerCase();
106
+ if (name === "") {
107
+ at += 1;
108
+ continue;
109
+ }
110
+ while (at < text.length && isSpace(text.charCodeAt(at))) {
111
+ at += 1;
112
+ }
113
+ if (text[at] !== "=") {
114
+ continue;
115
+ }
116
+ at += 1;
117
+ while (at < text.length && isSpace(text.charCodeAt(at))) {
118
+ at += 1;
119
+ }
120
+ const quote = text[at];
121
+ if (quote === '"' || quote === "'") {
122
+ const close = text.indexOf(quote, at + 1);
123
+ const end = close < 0 ? text.length : close;
124
+ out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
125
+ at = end + 1;
126
+ } else {
127
+ const start = at;
128
+ while (at < text.length && !isSpace(text.charCodeAt(at))) {
129
+ at += 1;
130
+ }
131
+ out.push({ name, value: text.slice(start, at), at: start });
132
+ }
133
+ }
134
+ return out;
135
+ }
136
+
137
+ /** What a page's markup loads or links: each element's `src`, `href` or `poster`. */
138
+ function markupReferences(text: string): Reference[] {
139
+ const found: Reference[] = [];
140
+ for (const tag of text.matchAll(TAG)) {
141
+ if (found.length >= MOST_REFERENCES) {
142
+ break;
143
+ }
144
+ const name = (tag[1] ?? "").toLowerCase();
145
+ const wanted = Object.hasOwn(REFERENCE_ATTRIBUTES, name)
146
+ ? REFERENCE_ATTRIBUTES[name]
147
+ : undefined;
148
+ if (wanted === undefined) {
149
+ continue;
150
+ }
151
+ const offset = tag.index + 1 + name.length;
152
+ for (const attribute of attributesOf(tag[2] ?? "")) {
153
+ if (wanted.includes(attribute.name) && attribute.value !== "") {
154
+ found.push({ reference: attribute.value, index: offset + attribute.at });
155
+ }
156
+ }
157
+ }
158
+ return found;
159
+ }
160
+
161
+ /**
162
+ * The references a text's patterns find (group 2 of each). Every pattern is bounded and stops at
163
+ * its own delimiters, so a text is read in linear time, however it was written.
164
+ */
165
+ function patternReferences(text: string, patterns: readonly RegExp[]): Reference[] {
166
+ const found: Reference[] = [];
167
+ for (const pattern of patterns) {
168
+ let count = 0;
169
+ for (const match of text.matchAll(pattern)) {
170
+ found.push({ reference: match[2] ?? "", index: match.index });
171
+ count += 1;
172
+ if (count >= MOST_REFERENCES) {
173
+ break;
174
+ }
175
+ }
176
+ }
177
+ return found;
178
+ }
179
+
180
+ const CSS_REFERENCES: readonly RegExp[] = [
181
+ /url\(\s{0,64}(["']?)([^"'()\s]{1,2048})\1\s{0,64}\)/giu,
182
+ /@import\s{1,64}(["'])([^"'\n]{1,2048})\1/giu,
183
+ ];
184
+ /** In a script: what resolves from the module (imports, `new URL(…, import.meta.url)`). */
185
+ const MODULE_REFERENCES: readonly RegExp[] = [
186
+ /\bfrom\s{0,64}(["'])(\.{1,2}\/[^"'\n]{0,2048})\1/gu,
187
+ /\bimport\s{0,64}\(?\s{0,64}(["'])(\.{1,2}\/[^"'\n]{0,2048})\1/gu,
188
+ /\bnew\s{1,64}URL\s{0,64}\(\s{0,64}(["'])([^"'\n]{1,2048})\1\s{0,64},\s{0,64}import\.meta\.url\b/gu,
189
+ ];
190
+ /** In a script: what resolves from the page (fetches, workers made from a string). */
191
+ const PAGE_REFERENCES: readonly RegExp[] = [
192
+ /\bfetch\s{0,64}\(\s{0,64}(["'`])(\.{0,2}\/?[\w./-][^"'`$\n]{0,2048})\1/gu,
193
+ /\bnew\s{1,64}(?:Shared)?Worker\s{0,64}\(\s{0,64}(["'`])([^"'`$\n]{1,2048})\1/gu,
194
+ ];
195
+
196
+ /** Whether a reference leaves the set for good reason: another origin, inline data, an anchor. */
197
+ const elsewhere = (reference: string): boolean =>
198
+ /^[a-z][a-z0-9+.-]*:/iu.test(reference) ||
199
+ reference.startsWith("//") ||
200
+ reference.startsWith("#");
201
+
202
+ /** `reference` from a file in `directory` ("" or "a/b/"), as a path of the set; null above it. */
203
+ function resolve(directory: string, reference: string): string | null {
204
+ const bare = reference.split("#")[0]?.split("?")[0] ?? "";
205
+ let decoded: string;
206
+ try {
207
+ decoded = decodeURIComponent(bare);
208
+ } catch {
209
+ decoded = bare;
210
+ }
211
+ const segments = `${directory}${decoded}`.split("/");
212
+ const out: string[] = [];
213
+ for (const [index, segment] of segments.entries()) {
214
+ if (segment === "..") {
215
+ if (out.length === 0) {
216
+ return null;
217
+ }
218
+ out.pop();
219
+ } else if (segment !== "." && (segment !== "" || index === segments.length - 1)) {
220
+ out.push(segment);
221
+ }
222
+ }
223
+ return out.join("/");
224
+ }
225
+
226
+ const directoryOf = (path: string): string => path.slice(0, path.lastIndexOf("/") + 1);
227
+
228
+ /**
229
+ * Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
230
+ * `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
231
+ * names the address's root rather than the version, is an error in a page's markup), and each
232
+ * file whose extension the server doesn't know (a download).
233
+ */
234
+ export function lintFiles(
235
+ config: PortholeConfig,
236
+ files: FileContents,
237
+ options: { readonly entry?: string } = {},
238
+ ): FileFinding[] {
239
+ const findings: FileFinding[] = [];
240
+ if (!servesFiles(config)) {
241
+ findings.push({
242
+ rule: "files",
243
+ severity: "error",
244
+ message:
245
+ "A page here is one document: it can't come with files. Put its styles, scripts and data in the page itself.",
246
+ });
247
+ return findings;
248
+ }
249
+ const entry = options.entry ?? DEFAULT_ENTRY;
250
+ const sized = Object.fromEntries(
251
+ Object.entries(files).map(([path, body]) => [path, { size: sizeOf(body) }]),
252
+ );
253
+ const problems = checkFileSet(sized, { entry, limits: fileLimits(config.limits) });
254
+ for (const problem of problems) {
255
+ findings.push({
256
+ rule: "files",
257
+ severity: "error",
258
+ message: `${problem.message}.`,
259
+ ...(problem.path === undefined ? {} : { path: problem.path }),
260
+ });
261
+ }
262
+ // Over the limits, the version isn't taken: nothing in it is read.
263
+ if (
264
+ problems.some((each) => each.code === "count" || each.code === "size" || each.code === "total")
265
+ ) {
266
+ return findings;
267
+ }
268
+ const has = (path: string): boolean => Object.hasOwn(files, path);
269
+ const found = (path: string): boolean =>
270
+ lookupFile(has, path, { entry, navigation: false }).kind !== "none";
271
+ const reported = new Set<string>();
272
+ const check = (
273
+ from: string,
274
+ lineOf: (index: number) => number,
275
+ references: readonly Reference[],
276
+ directory: string,
277
+ rooted: "error" | "warning",
278
+ also?: string,
279
+ ) => {
280
+ const seen = new Set<string>();
281
+ for (const { reference, index } of references) {
282
+ if (seen.has(reference)) {
283
+ continue;
284
+ }
285
+ seen.add(reference);
286
+ if (reference === "" || elsewhere(reference) || reference.includes("${")) {
287
+ continue;
288
+ }
289
+ if (reference.startsWith("/")) {
290
+ const key = `${from} / ${reference}`;
291
+ if (!reported.has(key)) {
292
+ reported.add(key);
293
+ findings.push({
294
+ rule: "root-path",
295
+ severity: rooted,
296
+ message: `${reference} starts with /: that is the address's root, not this version's files. Write it relative (.${reference})${reference.startsWith("/assets/") ? '; for a Vite build, set base: "./"' : ""}.`,
297
+ path: from,
298
+ line: lineOf(index),
299
+ });
300
+ }
301
+ continue;
302
+ }
303
+ const target = resolve(directory, reference);
304
+ const other = also === undefined ? null : resolve(also, reference);
305
+ const named = (target !== null && found(target)) || (other !== null && found(other));
306
+ const key = `${from} ${target ?? reference}`;
307
+ if (!named && !reported.has(key)) {
308
+ reported.add(key);
309
+ findings.push({
310
+ rule: "missing-file",
311
+ severity: "warning",
312
+ message:
313
+ target === null && other === null
314
+ ? `${reference} goes above the version's own files: nothing is there.`
315
+ : `${reference} names ${(target ?? other) === "" ? "the version's entry" : (target ?? other)}, which isn't one of the files.`,
316
+ path: from,
317
+ line: lineOf(index),
318
+ });
319
+ }
320
+ }
321
+ };
322
+ const maxPage = config.limits.maxBytes;
323
+ for (const [path, body] of Object.entries(files)) {
324
+ const { role } = fileTypeOf(path);
325
+ if (!knownType(path)) {
326
+ findings.push({
327
+ rule: "file-type",
328
+ severity: "warning",
329
+ message: `${path} is served as a download: its extension isn't one the server knows.`,
330
+ path,
331
+ });
332
+ }
333
+ const directory = directoryOf(path);
334
+ if (role === "page") {
335
+ const bytes = sizeOf(body);
336
+ if (bytes > maxPage) {
337
+ // Over the page's limit: said, and not read further.
338
+ findings.push({
339
+ rule: "size",
340
+ severity: "error",
341
+ message: `It is ${sizeWords(bytes)}; a page may be at most ${sizeWords(maxPage)}: move what it holds into files of its own (scripts, styles, data).`,
342
+ path,
343
+ });
344
+ continue;
345
+ }
346
+ const text = textOf(body);
347
+ for (const finding of lintContent(config, text)) {
348
+ findings.push({ ...finding, path });
349
+ }
350
+ const lines = linesOf(text);
351
+ check(path, lines, markupReferences(text), directory, "error");
352
+ check(path, lines, patternReferences(text, CSS_REFERENCES), directory, "warning");
353
+ check(
354
+ path,
355
+ lines,
356
+ patternReferences(text, [...MODULE_REFERENCES, ...PAGE_REFERENCES]),
357
+ directory,
358
+ "warning",
359
+ );
360
+ } else if (path.endsWith(".css")) {
361
+ const text = textOf(body).slice(0, SCANNED);
362
+ check(path, linesOf(text), patternReferences(text, CSS_REFERENCES), directory, "warning");
363
+ } else if (role === "script") {
364
+ const text = textOf(body).slice(0, SCANNED);
365
+ const lines = linesOf(text);
366
+ check(path, lines, patternReferences(text, MODULE_REFERENCES), directory, "warning");
367
+ // A fetch from a script resolves from the page that runs it: the entry's directory, or the
368
+ // script's own (a worker's).
369
+ check(
370
+ path,
371
+ lines,
372
+ patternReferences(text, PAGE_REFERENCES),
373
+ directoryOf(entry),
374
+ "warning",
375
+ directory,
376
+ );
377
+ }
378
+ }
379
+ return findings;
380
+ }
381
+
382
+ /** Where a finding is, for the agent: `about.html line 3: `. */
383
+ export const whereOf = (finding: FileFinding): string =>
384
+ `${finding.path === undefined ? "" : finding.path}${finding.line === undefined ? "" : `${finding.path === undefined ? "" : " "}line ${finding.line}`}${finding.path === undefined && finding.line === undefined ? "" : ": "}`;
package/src/check/lint.ts CHANGED
@@ -63,22 +63,41 @@ export function fragmentOf(content: string): string | null {
63
63
  return body.trim() === "" ? null : `${kept}${kept === "" ? "" : "\n"}${body.trim()}`;
64
64
  }
65
65
 
66
- /** Where content reaches out, by the kind of egress each would need. */
66
+ /**
67
+ * Where content reaches out, by the kind of egress each would need. Each pattern is bounded and
68
+ * never runs past its own delimiters (a tag's `<`, a string's quote), so a text is read in linear
69
+ * time however it was written.
70
+ */
67
71
  const REACHES: readonly { readonly kind: EgressKind; readonly pattern: RegExp }[] = [
68
- { kind: "script", pattern: /<script\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
69
- { kind: "script", pattern: /\bimport\s*(?:[\w{}\s*,]+from\s*)?\(?\s*["'](https?:\/\/[^"']+)/gu },
70
- { kind: "style", pattern: /<link\b[^>]*\bhref\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
71
- { kind: "style", pattern: /@import\s+(?:url\()?["']?(https?:\/\/[^"')\s]+)/giu },
72
- { kind: "img", pattern: /<img\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
73
- { kind: "img", pattern: /url\(\s*["']?(https?:\/\/[^"')\s]+)/giu },
72
+ {
73
+ kind: "script",
74
+ pattern: /<script\b[^<>]{0,8192}?\bsrc\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
75
+ },
76
+ { kind: "script", pattern: /\bfrom\s{0,64}["'](https?:\/\/[^"'\n]{1,2048})/gu },
77
+ { kind: "script", pattern: /\bimport\s{0,64}\(?\s{0,64}["'](https?:\/\/[^"'\n]{1,2048})/gu },
78
+ {
79
+ kind: "style",
80
+ pattern: /<link\b[^<>]{0,8192}?\bhref\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
81
+ },
82
+ {
83
+ kind: "style",
84
+ pattern: /@import\s{1,64}(?:url\()?["']?(https?:\/\/[^"')\s]{1,2048})/giu,
85
+ },
86
+ {
87
+ kind: "img",
88
+ pattern: /<img\b[^<>]{0,8192}?\bsrc\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
89
+ },
90
+ { kind: "img", pattern: /url\(\s{0,64}["']?(https?:\/\/[^"')\s]{1,2048})/giu },
74
91
  {
75
92
  kind: "media",
76
- pattern: /<(?:video|audio|source)\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu,
93
+ pattern:
94
+ /<(?:video|audio|source)\b[^<>]{0,8192}?\bsrc\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
77
95
  },
78
- { kind: "connect", pattern: /\bfetch\s*\(\s*["'`](https?:\/\/[^"'`]+)/gu },
96
+ { kind: "connect", pattern: /\bfetch\s{0,64}\(\s{0,64}["'`](https?:\/\/[^"'`\n]{1,2048})/gu },
79
97
  {
80
98
  kind: "connect",
81
- pattern: /\bnew\s+(?:WebSocket|EventSource)\s*\(\s*["'`]((?:https?|wss?):\/\/[^"'`]+)/gu,
99
+ pattern:
100
+ /\bnew\s{1,64}(?:WebSocket|EventSource)\s{0,64}\(\s{0,64}["'`]((?:https?|wss?):\/\/[^"'`\n]{1,2048})/gu,
82
101
  },
83
102
  ];
84
103
 
@@ -2,6 +2,7 @@ import type { PortholeConfig } from "../config/schema.ts";
2
2
  import { BUILT_IN_TOPICS } from "../config/validate.ts";
3
3
  import { generateGuide, generateToolDescription } from "../guide/guide.ts";
4
4
  import { fragmentOf, lintContent, type Finding } from "./lint.ts";
5
+ import { lintFiles, whereOf, type FileContents, type FileFinding } from "./files.ts";
5
6
 
6
7
  /**
7
8
  * The agent's tools, as a tool list names them (P073): a name, a description and a JSON Schema
@@ -189,6 +190,55 @@ export function admitContent(
189
190
  };
190
191
  }
191
192
 
193
+ export type AdmitFilesResult =
194
+ | {
195
+ readonly ok: true;
196
+ /** Warnings (and errors, with `refuseOn: "never"`), for the tool's answer. */
197
+ readonly findings: readonly FileFinding[];
198
+ /** One line for the agent, or null when there's nothing to say. */
199
+ readonly note: string | null;
200
+ }
201
+ | {
202
+ readonly ok: false;
203
+ readonly findings: readonly FileFinding[];
204
+ /** What to tell the agent: what to change, and to call the tool again. */
205
+ readonly refusal: string;
206
+ };
207
+
208
+ /**
209
+ * A publish tool's check before it takes a page with files (P081): refuses only what certainly
210
+ * fails (a path or limit the server won't take, no entry, a page `admitContent` would refuse, a
211
+ * page's reference that starts with /); the rest, references to files that aren't in the set
212
+ * among them, are warnings. `refuseOn: "never"` refuses nothing.
213
+ */
214
+ export function admitFiles(
215
+ config: PortholeConfig,
216
+ files: FileContents,
217
+ options: { readonly entry?: string; readonly refuseOn?: "error" | "never" } = {},
218
+ ): AdmitFilesResult {
219
+ const findings = lintFiles(
220
+ config,
221
+ files,
222
+ options.entry === undefined ? {} : { entry: options.entry },
223
+ );
224
+ const errors = findings.filter((each) => each.severity === "error");
225
+ if (errors.length > 0 && (options.refuseOn ?? "error") === "error") {
226
+ return {
227
+ ok: false,
228
+ findings,
229
+ refusal: `Not published. Change this, then publish again:\n${errors.map((each) => `- ${whereOf(each)}${each.message}`).join("\n")}`,
230
+ };
231
+ }
232
+ return {
233
+ ok: true,
234
+ findings,
235
+ note:
236
+ findings.length === 0
237
+ ? null
238
+ : `Published. Fix these next time:\n${findings.map((each) => `- ${whereOf(each)}${each.message}`).join("\n")}`,
239
+ };
240
+ }
241
+
192
242
  /**
193
243
  * What to tell the agent when its manual changes (a display kind flipped between served and
194
244
  * opaque, P073): the lines that are new, or null when the manual reads the same.
@@ -101,6 +101,44 @@ export function frameCspDirectives(config: PortholeConfig): CspDirective[] {
101
101
  ];
102
102
  }
103
103
 
104
+ /** The directives a page of a file set loads its own files under (P082): everything that loads. */
105
+ export const FILE_SET_DIRECTIVES = [
106
+ "script-src",
107
+ "style-src",
108
+ "font-src",
109
+ "img-src",
110
+ "media-src",
111
+ "connect-src",
112
+ "worker-src",
113
+ ] as const;
114
+
115
+ /**
116
+ * A served page's CSP when it comes with files (P082): the frame's, with its version's own files
117
+ * opened for each kind that loads (`FILE_SET_DIRECTIVES`), by `source`, the files' path on the
118
+ * content origin (`https://a-x.example-usercontent.com/v/3/`). Never `'self'`: the origin's other
119
+ * paths (other versions, Porthole's own) stay closed, and frames, plugins, forms and `<base>` stay
120
+ * `'none'`. Opaque frames have no files, and keep P022's rule whole.
121
+ */
122
+ export function fileSetCspDirectives(
123
+ directives: readonly CspDirective[],
124
+ source: string,
125
+ ): CspDirective[] {
126
+ const opened = new Set<string>(FILE_SET_DIRECTIVES);
127
+ return directives.map(([name, ...sources]) => {
128
+ if (!opened.has(name)) {
129
+ return [name, ...sources];
130
+ }
131
+ const kept = sources.filter((each) => each !== "'none'");
132
+ return [name, ...kept, source];
133
+ });
134
+ }
135
+
136
+ /**
137
+ * The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
138
+ * and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
139
+ */
140
+ export const INERT_FILE_CSP = "default-src 'none'; sandbox";
141
+
104
142
  export function serializeCsp(directives: readonly CspDirective[]): string {
105
143
  return directives.map((directive) => directive.join(" ")).join("; ");
106
144
  }
@@ -120,6 +120,14 @@ export interface Limits {
120
120
  * when absent.
121
121
  */
122
122
  readonly loadTimeoutMs?: number;
123
+ /**
124
+ * A served page's files (P081): the most a version holds (default 1000), the largest one,
125
+ * bytes (default 25 MiB), and all of them together, bytes (default 100 MiB: a host sets its
126
+ * own). The manual states them; `checkFileSet` and `lintFiles` hold a version to them.
127
+ */
128
+ readonly maxFiles?: number;
129
+ readonly maxFileBytes?: number;
130
+ readonly maxVersionBytes?: number;
123
131
  }
124
132
 
125
133
  /**
@@ -428,13 +428,20 @@ export function validateConfig(input: unknown): PortholeConfig {
428
428
  "maxPromptChars",
429
429
  "maxErrorReports",
430
430
  ];
431
- only(limits, [...limitNames, "loadTimeoutMs"], "config.limits");
431
+ const fileLimitNames = ["maxFiles", "maxFileBytes", "maxVersionBytes"];
432
+ only(limits, [...limitNames, "loadTimeoutMs", ...fileLimitNames], "config.limits");
432
433
  for (const name of limitNames) {
433
434
  positive(limits[name], `config.limits.${name}`);
434
435
  }
435
436
  if (limits.loadTimeoutMs !== undefined) {
436
437
  positive(limits.loadTimeoutMs, "config.limits.loadTimeoutMs", 600_000);
437
438
  }
439
+ // A served page's files (P081): optional, with fileLimits' defaults.
440
+ for (const name of fileLimitNames) {
441
+ if (limits[name] !== undefined) {
442
+ positive(limits[name], `config.limits.${name}`);
443
+ }
444
+ }
438
445
  if ((limits.minHeightPx as number) > (limits.maxHeightPx as number)) {
439
446
  fail("config.limits.minHeightPx", "must not exceed maxHeightPx");
440
447
  }