@botiverse/porthole 0.5.0 → 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.d.ts +12 -4
- package/dist/bridge/bridge.js +62 -27
- package/dist/bridge/navigation.d.ts +6 -0
- package/dist/bridge/navigation.js +41 -0
- package/dist/bridge/refusal.d.ts +53 -0
- package/dist/bridge/refusal.js +121 -0
- package/dist/bridge/types.d.ts +7 -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/page.js +5 -0
- 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/capabilities.d.ts +5 -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 +25 -5
- package/dist/host/create-host.js +36 -4
- package/dist/host/types.d.ts +15 -2
- package/dist/index.d.ts +7 -3
- package/dist/index.js +10 -3
- package/dist/mcp/adapter.js +22 -7
- package/dist/protocol/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +12 -0
- package/dist/protocol/mcp-apps.js +12 -0
- package/dist/protocol/shell-adapter.js +18 -2
- package/dist/react/frame.d.ts +19 -4
- package/dist/react/frame.js +37 -9
- 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 +117 -10
- package/docs/ADOPTING.md +95 -13
- package/docs/ARCHITECTURE.md +13 -3
- package/docs/DECISIONS.md +396 -4
- package/docs/DESIGN.md +43 -10
- package/package.json +1 -1
- package/src/bridge/bridge.ts +74 -23
- package/src/bridge/navigation.ts +46 -0
- package/src/bridge/refusal.ts +151 -0
- package/src/bridge/types.ts +12 -1
- package/src/check/check.ts +92 -14
- package/src/check/files.ts +384 -0
- package/src/check/lint.ts +29 -10
- package/src/check/page.ts +7 -0
- package/src/check/tools.ts +50 -0
- package/src/compile/policy.ts +38 -0
- package/src/config/capabilities.ts +5 -1
- 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 +38 -4
- package/src/host/create-host.ts +37 -4
- package/src/host/types.ts +13 -2
- package/src/index.ts +41 -0
- package/src/mcp/adapter.ts +26 -6
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +14 -0
- package/src/protocol/shell-adapter.ts +20 -2
- package/src/react/frame.tsx +53 -14
- 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 +117 -10
|
@@ -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
|
-
/**
|
|
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
|
-
{
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
{ kind: "
|
|
73
|
-
{ kind: "
|
|
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:
|
|
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
|
|
96
|
+
{ kind: "connect", pattern: /\bfetch\s{0,64}\(\s{0,64}["'`](https?:\/\/[^"'`\n]{1,2048})/gu },
|
|
79
97
|
{
|
|
80
98
|
kind: "connect",
|
|
81
|
-
pattern:
|
|
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
|
|
package/src/check/page.ts
CHANGED
|
@@ -4,6 +4,7 @@ import {
|
|
|
4
4
|
isCapabilityName,
|
|
5
5
|
type HandledCapability,
|
|
6
6
|
} from "../config/capabilities.ts";
|
|
7
|
+
import { addressWithoutQuery } from "../bridge/navigation.ts";
|
|
7
8
|
import { createHost } from "../host/create-host.ts";
|
|
8
9
|
import type { PlatformHost } from "../platform/types.ts";
|
|
9
10
|
import { webPlatform } from "../platform/web.ts";
|
|
@@ -209,6 +210,12 @@ const check = {
|
|
|
209
210
|
calls.push({ capability, outcome: refusal });
|
|
210
211
|
}
|
|
211
212
|
});
|
|
213
|
+
// A navigation the shell stopped (P080): the content tried to leave its page.
|
|
214
|
+
display.on("navigationBlocked", ({ url }) => {
|
|
215
|
+
run.data.errors.push(
|
|
216
|
+
`It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page`,
|
|
217
|
+
);
|
|
218
|
+
});
|
|
212
219
|
display.on("outcome", (outcome) => {
|
|
213
220
|
run.data.outcome = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
|
|
214
221
|
});
|
package/src/check/tools.ts
CHANGED
|
@@ -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.
|
package/src/compile/policy.ts
CHANGED
|
@@ -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
|
}
|
|
@@ -147,7 +147,11 @@ export interface CapabilityArgs {
|
|
|
147
147
|
readonly content?: readonly unknown[];
|
|
148
148
|
readonly structuredContent?: Readonly<Record<string, unknown>>;
|
|
149
149
|
};
|
|
150
|
-
|
|
150
|
+
/**
|
|
151
|
+
* `navigationBlocked`: the address a navigation of the frame went to when the shell cancelled it
|
|
152
|
+
* (P080), the content's word; `message` is then Porthole's, which names it without its query.
|
|
153
|
+
*/
|
|
154
|
+
readonly reportError: { readonly message: string; readonly navigationBlocked?: string };
|
|
151
155
|
readonly resize: { readonly height: number; readonly width?: number };
|
|
152
156
|
readonly copyText: { readonly text: string };
|
|
153
157
|
/** What the frame reported, once checked (`AnnotationReport`). */
|
package/src/config/schema.ts
CHANGED
|
@@ -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
|
/**
|
package/src/config/validate.ts
CHANGED
|
@@ -428,13 +428,20 @@ export function validateConfig(input: unknown): PortholeConfig {
|
|
|
428
428
|
"maxPromptChars",
|
|
429
429
|
"maxErrorReports",
|
|
430
430
|
];
|
|
431
|
-
|
|
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
|
}
|