@botiverse/porthole 0.2.4 → 0.3.1
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 +17 -11
- package/dist/check/check.d.ts +100 -0
- package/dist/check/check.js +247 -0
- package/dist/check/drivers.d.ts +43 -0
- package/dist/check/drivers.js +181 -0
- package/dist/check/index.d.ts +8 -0
- package/dist/check/index.js +8 -0
- package/dist/check/instrument.d.ts +71 -0
- package/dist/check/instrument.js +84 -0
- package/dist/check/lint.d.ts +21 -0
- package/dist/check/lint.js +131 -0
- package/dist/check/page-source.d.ts +2 -0
- package/dist/check/page-source.js +2 -0
- package/dist/check/page.d.ts +13 -0
- package/dist/check/page.js +170 -0
- package/dist/check/tools.d.ts +61 -0
- package/dist/check/tools.js +140 -0
- package/dist/conformance/host-kit.d.ts +26 -5
- package/dist/conformance/host-kit.js +46 -22
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/reporter.d.ts +14 -0
- package/dist/conformance/reporter.js +28 -0
- package/dist/displays/displays.d.ts +61 -0
- package/dist/displays/displays.js +113 -0
- package/dist/host/client.d.ts +110 -0
- package/dist/host/client.js +274 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +6 -0
- package/dist/node/index.d.ts +26 -1
- package/dist/node/index.js +91 -1
- package/dist/react/frame.d.ts +79 -3
- package/dist/react/frame.js +183 -42
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +1 -0
- package/dist/react/view.d.ts +54 -0
- package/dist/react/view.js +151 -0
- package/dist/server/bootstrap.d.ts +27 -0
- package/dist/server/bootstrap.js +63 -0
- package/dist/server/host.d.ts +77 -8
- package/dist/server/host.js +268 -11
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +3 -1
- package/dist/server/pages.d.ts +19 -0
- package/dist/server/pages.js +8 -0
- package/dist/server/proxy.d.ts +24 -0
- package/dist/server/proxy.js +67 -0
- package/dist/server/server.js +14 -1
- package/dist/server/types.d.ts +8 -0
- package/docs/ADOPTING.md +278 -108
- package/docs/DECISIONS.md +280 -0
- package/docs/DESIGN.md +84 -2
- package/examples/app.mjs +82 -78
- package/examples/conformance/page.spec.mjs +23 -0
- package/examples/conformance/playwright.config.mjs +3 -2
- package/examples/conformance/porthole.spec.mjs +6 -3
- package/examples/displays.mjs +21 -0
- package/examples/mcp/server.mjs +121 -0
- package/examples/node/server.mjs +16 -34
- package/examples/workers/worker.mjs +19 -7
- package/package.json +13 -1
- package/src/check/check.ts +386 -0
- package/src/check/drivers.ts +242 -0
- package/src/check/index.ts +22 -0
- package/src/check/instrument.ts +138 -0
- package/src/check/lint.ts +238 -0
- package/src/check/page-source.ts +19 -0
- package/src/check/page.ts +230 -0
- package/src/check/tools.ts +206 -0
- package/src/conformance/host-kit.ts +82 -27
- package/src/conformance/index.ts +1 -0
- package/src/conformance/reporter.ts +38 -0
- package/src/displays/displays.ts +191 -0
- package/src/host/client.ts +395 -0
- package/src/index.ts +25 -0
- package/src/node/index.ts +112 -2
- package/src/react/frame.tsx +271 -57
- package/src/react/index.ts +9 -0
- package/src/react/view.tsx +237 -0
- package/src/server/bootstrap.ts +97 -0
- package/src/server/host.ts +372 -18
- package/src/server/index.ts +11 -1
- package/src/server/pages.ts +28 -0
- package/src/server/proxy.ts +86 -0
- package/src/server/server.ts +26 -2
- package/src/server/types.ts +5 -0
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import type { InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* What the check puts in the content it runs (P073, P074): a small script first that reports
|
|
6
|
+
* what happens inside to the page that frames it, and a name on each inline script so an error
|
|
7
|
+
* says the line in the content as written. Pure: the check (any runtime) and its page both use it.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
export interface CheckRunSpec {
|
|
11
|
+
readonly config: PortholeConfig;
|
|
12
|
+
readonly content: string;
|
|
13
|
+
/** Where each inline script's text starts in the content as written (file lines), by index. */
|
|
14
|
+
readonly scriptLines: readonly number[];
|
|
15
|
+
/** A served config's instance (located through the check's own server), else opaque. */
|
|
16
|
+
readonly instance?: InstanceRef;
|
|
17
|
+
readonly widthPx: number;
|
|
18
|
+
readonly heightPx?: number;
|
|
19
|
+
readonly scheme: ColorScheme;
|
|
20
|
+
readonly hostTheme?: Readonly<Record<string, string>>;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* A host function the content called (P074): `answered` where the call reached the check's stub
|
|
25
|
+
* (which answers no, as a declining host would), else the refusal a host's gates gave it
|
|
26
|
+
* (`no-user-activation` for a call on load, `declined` where a person was asked).
|
|
27
|
+
*/
|
|
28
|
+
export interface CheckCall {
|
|
29
|
+
readonly capability: string;
|
|
30
|
+
readonly outcome: string;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface CheckRunData {
|
|
34
|
+
readonly errors: string[];
|
|
35
|
+
readonly calls: CheckCall[];
|
|
36
|
+
readonly blocked: { readonly url: string; readonly directive: string }[];
|
|
37
|
+
readonly failedLoads: { readonly url: string; readonly tag: string }[];
|
|
38
|
+
readonly console: { readonly level: "error" | "warning"; readonly text: string }[];
|
|
39
|
+
readonly height: number | null;
|
|
40
|
+
readonly scrollWidth: number | null;
|
|
41
|
+
readonly clientWidth: number | null;
|
|
42
|
+
readonly outcome: string | null;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Each inline script's name (`//# sourceURL`): its index in the content. */
|
|
46
|
+
export const SCRIPT_NAME = "porthole-script-";
|
|
47
|
+
|
|
48
|
+
/** Put first in the content: it reports to the page that frames it. */
|
|
49
|
+
export const INSTRUMENT = `<script>(() => {
|
|
50
|
+
const send = (kind, data) => { try { parent.postMessage({ portholeCheck: kind, data }, "*"); } catch (_) {} };
|
|
51
|
+
const text = (value) => { try { return String(value && value.stack ? value.message || value : value); } catch (_) { return "?"; } };
|
|
52
|
+
for (const [method, level] of [["error", "error"], ["warn", "warning"]]) {
|
|
53
|
+
const original = console[method];
|
|
54
|
+
console[method] = (...args) => { send("console", { level, text: args.map(text).join(" ").slice(0, 400) }); return original.apply(console, args); };
|
|
55
|
+
}
|
|
56
|
+
addEventListener("error", (event) => {
|
|
57
|
+
const target = event.target;
|
|
58
|
+
if (target && target !== window && (target.src || target.href)) {
|
|
59
|
+
send("load", { url: String(target.src || target.href).slice(0, 400), tag: String(target.tagName || "").toLowerCase() });
|
|
60
|
+
} else if (event.message || event.error) {
|
|
61
|
+
const error = event.error;
|
|
62
|
+
send("error", {
|
|
63
|
+
message: (error && error.message ? (error.name || "Error") + ": " + error.message : String(event.message)).slice(0, 400),
|
|
64
|
+
file: String(event.filename || ""),
|
|
65
|
+
line: event.lineno || 0,
|
|
66
|
+
stack: error && error.stack ? String(error.stack).slice(0, 1000) : "",
|
|
67
|
+
});
|
|
68
|
+
}
|
|
69
|
+
}, true);
|
|
70
|
+
addEventListener("unhandledrejection", (event) => send("error", {
|
|
71
|
+
message: ("Unhandled rejection: " + text(event.reason)).slice(0, 400),
|
|
72
|
+
file: "", line: 0,
|
|
73
|
+
stack: event.reason && event.reason.stack ? String(event.reason.stack).slice(0, 1000) : "",
|
|
74
|
+
}));
|
|
75
|
+
addEventListener("securitypolicyviolation", (event) => send("blocked", { url: String(event.blockedURI || "inline").slice(0, 400), directive: String(event.effectiveDirective) }));
|
|
76
|
+
addEventListener("message", (event) => {
|
|
77
|
+
if (event.source === parent && event.data && event.data.portholeCheck === "measure") {
|
|
78
|
+
const root = document.documentElement;
|
|
79
|
+
send("measure", { scrollWidth: Math.max(root.scrollWidth, document.body ? document.body.scrollWidth : 0), clientWidth: root.clientWidth });
|
|
80
|
+
}
|
|
81
|
+
});
|
|
82
|
+
})();</script>`;
|
|
83
|
+
|
|
84
|
+
/** The content with the instrument first: after a document's <head>, or before a fragment. */
|
|
85
|
+
export function instrumented(content: string): string {
|
|
86
|
+
const head = /<head[^>]*>/iu.exec(content);
|
|
87
|
+
if (head !== null) {
|
|
88
|
+
const at = head.index + head[0].length;
|
|
89
|
+
return `${content.slice(0, at)}${INSTRUMENT}${content.slice(at)}`;
|
|
90
|
+
}
|
|
91
|
+
const html = /<html[^>]*>/iu.exec(content);
|
|
92
|
+
if (html !== null) {
|
|
93
|
+
const at = html.index + html[0].length;
|
|
94
|
+
return `${content.slice(0, at)}<head>${INSTRUMENT}</head>${content.slice(at)}`;
|
|
95
|
+
}
|
|
96
|
+
return /^\s*<!doctype/iu.test(content)
|
|
97
|
+
? content.replace(/^(\s*<!doctype[^>]*>)/iu, `$1${INSTRUMENT}`)
|
|
98
|
+
: `${INSTRUMENT}${content}`;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* The content with each inline script named (`//# sourceURL=porthole-script-<n>`, after its
|
|
103
|
+
* last line, so no line moves), and where each one's text starts in the content as written.
|
|
104
|
+
*/
|
|
105
|
+
export function namedScripts(content: string): { content: string; scriptLines: number[] } {
|
|
106
|
+
const scriptLines: number[] = [];
|
|
107
|
+
const named = content.replace(
|
|
108
|
+
/(<script\b(?![^>]*\bsrc\s*=)[^>]*>)([\s\S]*?)(<\/script>)/giu,
|
|
109
|
+
(whole, open: string, body: string, close: string, offset: number) => {
|
|
110
|
+
const index = scriptLines.length;
|
|
111
|
+
scriptLines.push(content.slice(0, offset + open.length).split("\n").length);
|
|
112
|
+
return `${open}${body}\n//# sourceURL=${SCRIPT_NAME}${index}\n${close}`;
|
|
113
|
+
},
|
|
114
|
+
);
|
|
115
|
+
return { content: named, scriptLines };
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* An error's line in the content as written: from its script's name (the event's file, or its
|
|
120
|
+
* stack's first frame there) and its line in that script; null where it can't be told.
|
|
121
|
+
*/
|
|
122
|
+
export function contentLine(
|
|
123
|
+
error: { readonly file: string; readonly line: number; readonly stack: string },
|
|
124
|
+
scriptLines: readonly number[],
|
|
125
|
+
): number | null {
|
|
126
|
+
const named = new RegExp(`${SCRIPT_NAME}(\\d+)(?::(\\d+))?`, "u");
|
|
127
|
+
const fromFile = named.exec(error.file);
|
|
128
|
+
if (fromFile?.[1] !== undefined && error.line > 0) {
|
|
129
|
+
const start = scriptLines[Number(fromFile[1])];
|
|
130
|
+
return start === undefined ? null : start + error.line - 1;
|
|
131
|
+
}
|
|
132
|
+
const fromStack = named.exec(error.stack);
|
|
133
|
+
if (fromStack?.[1] !== undefined && fromStack[2] !== undefined) {
|
|
134
|
+
const start = scriptLines[Number(fromStack[1])];
|
|
135
|
+
return start === undefined ? null : start + Number(fromStack[2]) - 1;
|
|
136
|
+
}
|
|
137
|
+
return null;
|
|
138
|
+
}
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
import {
|
|
2
|
+
anyHttps,
|
|
3
|
+
declaredCapabilities,
|
|
4
|
+
egressOrigins,
|
|
5
|
+
type EgressKind,
|
|
6
|
+
} from "../compile/policy.ts";
|
|
7
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
8
|
+
import { sizeWords } from "../guide/limits.ts";
|
|
9
|
+
import { originMatchesSource } from "../isolation/served.ts";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* What can be told about content without running it (P073), worded as the manual words it, so
|
|
13
|
+
* the agent fixes it before anyone sees it. Pure: any runtime. Errors are only what certainly
|
|
14
|
+
* fails or is cut (`refuseOn: "error"` refuses those); the rest are warnings.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
export type LintRule =
|
|
18
|
+
| "size"
|
|
19
|
+
| "document"
|
|
20
|
+
| "nested-frame"
|
|
21
|
+
| "document-write"
|
|
22
|
+
| "clipboard"
|
|
23
|
+
| "dialog"
|
|
24
|
+
| "form"
|
|
25
|
+
| "egress"
|
|
26
|
+
| "unpinned"
|
|
27
|
+
| "position-fixed"
|
|
28
|
+
| "new-window";
|
|
29
|
+
|
|
30
|
+
export interface Finding {
|
|
31
|
+
readonly rule: LintRule;
|
|
32
|
+
readonly severity: "error" | "warning";
|
|
33
|
+
/** What to change, for the agent. */
|
|
34
|
+
readonly message: string;
|
|
35
|
+
/** Where (1-based), where a line says it. */
|
|
36
|
+
readonly line?: number;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const lineOf = (text: string, index: number): number => text.slice(0, index).split("\n").length;
|
|
40
|
+
|
|
41
|
+
const noun = (config: PortholeConfig) =>
|
|
42
|
+
config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
|
|
43
|
+
|
|
44
|
+
/** A whole document's markers: what a fragment must not have. */
|
|
45
|
+
const DOCUMENT = /<!doctype\b|<html[\s>]|<head[\s>]|<body[\s>]/iu;
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* A whole document sent where a fragment is shown (an inline widget), as the fragment it means:
|
|
49
|
+
* its head's styles and scripts, then its body. Null where it has no body to take.
|
|
50
|
+
*/
|
|
51
|
+
export function fragmentOf(content: string): string | null {
|
|
52
|
+
const head = /<head[^>]*>([\s\S]*?)<\/head>/iu.exec(content)?.[1] ?? "";
|
|
53
|
+
const kept = [...head.matchAll(/<(style|script)\b[\s\S]*?<\/\1>|<link\b[^>]*>/giu)]
|
|
54
|
+
.map((each) => each[0])
|
|
55
|
+
.join("\n");
|
|
56
|
+
const body =
|
|
57
|
+
/<body[^>]*>([\s\S]*?)(?:<\/body>|$)/iu.exec(content)?.[1] ??
|
|
58
|
+
content
|
|
59
|
+
.replace(/<!doctype[^>]*>/iu, "")
|
|
60
|
+
.replace(/<\/?html[^>]*>/giu, "")
|
|
61
|
+
.replace(/<head[^>]*>[\s\S]*?<\/head>/iu, "");
|
|
62
|
+
return body.trim() === "" ? null : `${kept}${kept === "" ? "" : "\n"}${body.trim()}`;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Where content reaches out, by the kind of egress each would need. */
|
|
66
|
+
const REACHES: readonly { readonly kind: EgressKind; readonly pattern: RegExp }[] = [
|
|
67
|
+
{ kind: "script", pattern: /<script\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
|
|
68
|
+
{ kind: "script", pattern: /\bimport\s*(?:[\w{}\s*,]+from\s*)?\(?\s*["'](https?:\/\/[^"']+)/gu },
|
|
69
|
+
{ kind: "style", pattern: /<link\b[^>]*\bhref\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
|
|
70
|
+
{ kind: "style", pattern: /@import\s+(?:url\()?["']?(https?:\/\/[^"')\s]+)/giu },
|
|
71
|
+
{ kind: "img", pattern: /<img\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
|
|
72
|
+
{ kind: "img", pattern: /url\(\s*["']?(https?:\/\/[^"')\s]+)/giu },
|
|
73
|
+
{
|
|
74
|
+
kind: "media",
|
|
75
|
+
pattern: /<(?:video|audio|source)\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu,
|
|
76
|
+
},
|
|
77
|
+
{ kind: "connect", pattern: /\bfetch\s*\(\s*["'`](https?:\/\/[^"'`]+)/gu },
|
|
78
|
+
{
|
|
79
|
+
kind: "connect",
|
|
80
|
+
pattern: /\bnew\s+(?:WebSocket|EventSource)\s*\(\s*["'`]((?:https?|wss?):\/\/[^"'`]+)/gu,
|
|
81
|
+
},
|
|
82
|
+
];
|
|
83
|
+
|
|
84
|
+
const CDN_PACKAGE =
|
|
85
|
+
/^https:\/\/(?:cdn\.jsdelivr\.net\/npm|unpkg\.com|esm\.sh)\/((?:@[^/]+\/)?[^/@]+)(@[^/]*)?/u;
|
|
86
|
+
|
|
87
|
+
export function lintContent(config: PortholeConfig, content: string): Finding[] {
|
|
88
|
+
if (config.mode === "url") {
|
|
89
|
+
return [];
|
|
90
|
+
}
|
|
91
|
+
const findings: Finding[] = [];
|
|
92
|
+
const add = (rule: LintRule, severity: Finding["severity"], message: string, index?: number) =>
|
|
93
|
+
findings.push({
|
|
94
|
+
rule,
|
|
95
|
+
severity,
|
|
96
|
+
message,
|
|
97
|
+
...(index === undefined ? {} : { line: lineOf(content, index) }),
|
|
98
|
+
});
|
|
99
|
+
const it = noun(config);
|
|
100
|
+
const declared = new Set(declaredCapabilities(config));
|
|
101
|
+
|
|
102
|
+
const bytes = new TextEncoder().encode(content).byteLength;
|
|
103
|
+
if (bytes > config.limits.maxBytes) {
|
|
104
|
+
add(
|
|
105
|
+
"size",
|
|
106
|
+
"error",
|
|
107
|
+
`It is ${sizeWords(bytes)}; a ${it} may be at most ${sizeWords(config.limits.maxBytes)}: make it smaller (less data inline, no embedded fonts or images it doesn't need).`,
|
|
108
|
+
);
|
|
109
|
+
}
|
|
110
|
+
if (config.mode === "inline") {
|
|
111
|
+
const at = content.search(DOCUMENT);
|
|
112
|
+
if (at >= 0) {
|
|
113
|
+
if (fragmentOf(content) === null) {
|
|
114
|
+
add(
|
|
115
|
+
"document",
|
|
116
|
+
"error",
|
|
117
|
+
"Send an HTML fragment (styles, markup, scripts), not a whole document: this one has no body to show.",
|
|
118
|
+
at,
|
|
119
|
+
);
|
|
120
|
+
} else {
|
|
121
|
+
add(
|
|
122
|
+
"document",
|
|
123
|
+
"warning",
|
|
124
|
+
"Send an HTML fragment, not a whole document (no <!doctype>, <html>, <head> or <body>): it was taken as its body, with its head's styles and scripts.",
|
|
125
|
+
at,
|
|
126
|
+
);
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
const frame = /<(iframe|frame|object|embed)\b/iu.exec(content);
|
|
131
|
+
if (frame !== null) {
|
|
132
|
+
add(
|
|
133
|
+
"nested-frame",
|
|
134
|
+
"error",
|
|
135
|
+
`Remove the <${frame[1]?.toLowerCase()}>: nested frames and plugins are taken out of a ${it} and never run. Draw it inline instead.`,
|
|
136
|
+
frame.index,
|
|
137
|
+
);
|
|
138
|
+
}
|
|
139
|
+
const write = /\bdocument\s*\.\s*write(?:ln)?\s*\(/u.exec(content);
|
|
140
|
+
if (write !== null) {
|
|
141
|
+
add(
|
|
142
|
+
"document-write",
|
|
143
|
+
"error",
|
|
144
|
+
"Remove document.write: it throws here. Build elements with document.createElement, or set innerHTML.",
|
|
145
|
+
write.index,
|
|
146
|
+
);
|
|
147
|
+
}
|
|
148
|
+
const clipboard =
|
|
149
|
+
/\bnavigator\s*\.\s*clipboard\b|\bexecCommand\s*\(\s*["'](?:copy|cut)["']/u.exec(content);
|
|
150
|
+
if (clipboard !== null) {
|
|
151
|
+
add(
|
|
152
|
+
"clipboard",
|
|
153
|
+
"warning",
|
|
154
|
+
declared.has("copyText")
|
|
155
|
+
? "The clipboard is closed to content: a copy button calls copyText(text) from its click."
|
|
156
|
+
: "The clipboard is closed to content: copying from a button doesn't work here.",
|
|
157
|
+
clipboard.index,
|
|
158
|
+
);
|
|
159
|
+
}
|
|
160
|
+
const dialog = /(?:^|[^.\w$])(?:window\s*\.\s*)?(alert|confirm|prompt)\s*\(/u.exec(content);
|
|
161
|
+
if (dialog !== null) {
|
|
162
|
+
add(
|
|
163
|
+
"dialog",
|
|
164
|
+
"warning",
|
|
165
|
+
`${dialog[1]}() shows nothing here (confirm returns false, prompt null): show it in the ${it}'s own markup.`,
|
|
166
|
+
dialog.index,
|
|
167
|
+
);
|
|
168
|
+
}
|
|
169
|
+
const form = /<form\b/iu.exec(content);
|
|
170
|
+
if (form !== null) {
|
|
171
|
+
add(
|
|
172
|
+
"form",
|
|
173
|
+
"warning",
|
|
174
|
+
'Forms never submit here, and some browsers fire no submit event: use <button type="button"> and a click handler.',
|
|
175
|
+
form.index,
|
|
176
|
+
);
|
|
177
|
+
}
|
|
178
|
+
const reported = new Set<string>();
|
|
179
|
+
for (const { kind, pattern } of REACHES) {
|
|
180
|
+
for (const match of content.matchAll(pattern)) {
|
|
181
|
+
const address = match[1] ?? "";
|
|
182
|
+
let origin: string;
|
|
183
|
+
try {
|
|
184
|
+
origin = new URL(address.replace(/^ws/u, "http")).origin;
|
|
185
|
+
} catch {
|
|
186
|
+
continue;
|
|
187
|
+
}
|
|
188
|
+
const open =
|
|
189
|
+
(kind !== "script" &&
|
|
190
|
+
kind !== "style" &&
|
|
191
|
+
kind !== "connect" &&
|
|
192
|
+
address.startsWith("https:") &&
|
|
193
|
+
anyHttps(config, kind)) ||
|
|
194
|
+
egressOrigins(config, kind).some(
|
|
195
|
+
(source) => source === origin || originMatchesSource(origin, source),
|
|
196
|
+
);
|
|
197
|
+
if (!open && !reported.has(`${kind} ${origin}`)) {
|
|
198
|
+
reported.add(`${kind} ${origin}`);
|
|
199
|
+
add(
|
|
200
|
+
"egress",
|
|
201
|
+
"warning",
|
|
202
|
+
`Nothing loads from ${origin} here (${kind}): ${kind === "script" || kind === "style" ? "write it inline, or use a library from an allowed CDN" : kind === "connect" ? "the content can't call it; work from data in the content" : "put it inline as a data: URL"}.`,
|
|
203
|
+
match.index,
|
|
204
|
+
);
|
|
205
|
+
}
|
|
206
|
+
const pinned = CDN_PACKAGE.exec(address);
|
|
207
|
+
if (pinned !== null && (pinned[2] === undefined || !/^@\d+\.\d+\.\d+/u.test(pinned[2]))) {
|
|
208
|
+
add(
|
|
209
|
+
"unpinned",
|
|
210
|
+
"warning",
|
|
211
|
+
`Pin an exact version of ${pinned[1]} (${pinned[1]}@1.2.3 in its URL), never @latest or a range: the code then can't change under the ${it}.`,
|
|
212
|
+
match.index,
|
|
213
|
+
);
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
if (config.layout.kind !== "fill") {
|
|
218
|
+
const fixed = /position\s*:\s*fixed/iu.exec(content);
|
|
219
|
+
if (fixed !== null) {
|
|
220
|
+
add(
|
|
221
|
+
"position-fixed",
|
|
222
|
+
"warning",
|
|
223
|
+
`No position: fixed: the frame grows with the ${it}'s content, so a fixed element covers it. Use position: sticky or normal flow.`,
|
|
224
|
+
fixed.index,
|
|
225
|
+
);
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
const opens = /target\s*=\s*["']?_blank|\bwindow\s*\.\s*open\s*\(/u.exec(content);
|
|
229
|
+
if (opens !== null && !declared.has("openLink")) {
|
|
230
|
+
add(
|
|
231
|
+
"new-window",
|
|
232
|
+
"warning",
|
|
233
|
+
"Nothing opens a new window here (window.open returns null, target=_blank does nothing): show it inline.",
|
|
234
|
+
opens.index,
|
|
235
|
+
);
|
|
236
|
+
}
|
|
237
|
+
return findings;
|
|
238
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The check page's script as a module (`@botiverse/porthole/check/page`): from the sources, bundled
|
|
3
|
+
* now (Node, esbuild); the package ships it built (`dist/check/page-source.js`), for a Worker to
|
|
4
|
+
* import and pass to `checkPage` as `page`.
|
|
5
|
+
*/
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
|
|
8
|
+
const { build } = await import("esbuild");
|
|
9
|
+
const result = await build({
|
|
10
|
+
entryPoints: [fileURLToPath(new URL("./page.ts", import.meta.url))],
|
|
11
|
+
bundle: true,
|
|
12
|
+
format: "iife",
|
|
13
|
+
platform: "browser",
|
|
14
|
+
target: "es2022",
|
|
15
|
+
write: false,
|
|
16
|
+
logLevel: "silent",
|
|
17
|
+
});
|
|
18
|
+
const source: string = result.outputFiles[0]?.text ?? "";
|
|
19
|
+
export default source;
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
import type { CapabilityHandlers } from "../bridge/types.ts";
|
|
2
|
+
import {
|
|
3
|
+
capabilitySpec,
|
|
4
|
+
isCapabilityName,
|
|
5
|
+
type HandledCapability,
|
|
6
|
+
} from "../config/capabilities.ts";
|
|
7
|
+
import { createHost } from "../host/create-host.ts";
|
|
8
|
+
import type { DisplayHandle } from "../host/types.ts";
|
|
9
|
+
import type { FrameLocation } from "../isolation/types.ts";
|
|
10
|
+
import {
|
|
11
|
+
contentLine,
|
|
12
|
+
instrumented,
|
|
13
|
+
type CheckCall,
|
|
14
|
+
type CheckRunData,
|
|
15
|
+
type CheckRunSpec,
|
|
16
|
+
} from "./instrument.ts";
|
|
17
|
+
|
|
18
|
+
export type { CheckCall, CheckRunData, CheckRunSpec } from "./instrument.ts";
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* What a host that declines answers each host function with (P074): no prompt sent, no link
|
|
22
|
+
* opened, nothing downloaded or copied; a tool call or a read refused.
|
|
23
|
+
*/
|
|
24
|
+
const DECLINED: { readonly [N in HandledCapability]: () => unknown } = {
|
|
25
|
+
sendPrompt: () => false,
|
|
26
|
+
openLink: () => false,
|
|
27
|
+
downloadFile: () => false,
|
|
28
|
+
copyText: () => false,
|
|
29
|
+
setModelContext: () => undefined,
|
|
30
|
+
callTool: () => {
|
|
31
|
+
throw new Error("The host declined the tool call");
|
|
32
|
+
},
|
|
33
|
+
readData: () => {
|
|
34
|
+
throw new Error("The host declined the read");
|
|
35
|
+
},
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
/** A handler for each host function the config declares: it notes the call and answers no. */
|
|
39
|
+
function declining(capabilities: readonly string[], calls: CheckCall[]): CapabilityHandlers {
|
|
40
|
+
const handlers: Record<string, () => unknown> = {};
|
|
41
|
+
for (const name of capabilities) {
|
|
42
|
+
if (isCapabilityName(name) && capabilitySpec(name).served === "handler") {
|
|
43
|
+
const answer = DECLINED[name as HandledCapability];
|
|
44
|
+
handlers[name] = () => {
|
|
45
|
+
calls.push({ capability: name, outcome: "answered" });
|
|
46
|
+
return answer();
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
return handlers;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* The check page (P073): runs content in the real sandbox (the core's `createHost`, the config's
|
|
55
|
+
* own CSP) at one width and scheme at a time, and hears what happens inside from a small script
|
|
56
|
+
* the check puts first in the content: what it throws, what the sandbox blocks, what fails to
|
|
57
|
+
* load, what it logs, and its width. Bundled into one script (`@botiverse/porthole/check/page`)
|
|
58
|
+
* that `checkPage` loads into a blank page through its driver.
|
|
59
|
+
*/
|
|
60
|
+
|
|
61
|
+
interface Run {
|
|
62
|
+
readonly display: DisplayHandle;
|
|
63
|
+
readonly box: HTMLElement;
|
|
64
|
+
readonly scriptLines: readonly number[];
|
|
65
|
+
readonly data: {
|
|
66
|
+
errors: string[];
|
|
67
|
+
calls: CheckCall[];
|
|
68
|
+
blocked: { url: string; directive: string }[];
|
|
69
|
+
failedLoads: { url: string; tag: string }[];
|
|
70
|
+
console: { level: "error" | "warning"; text: string }[];
|
|
71
|
+
height: number | null;
|
|
72
|
+
scrollWidth: number | null;
|
|
73
|
+
clientWidth: number | null;
|
|
74
|
+
outcome: string | null;
|
|
75
|
+
};
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
const runs = new Map<number, Run>();
|
|
79
|
+
let next = 0;
|
|
80
|
+
|
|
81
|
+
const frameOf = (run: Run) => run.box.querySelector("iframe");
|
|
82
|
+
|
|
83
|
+
addEventListener("message", (event: MessageEvent) => {
|
|
84
|
+
const data = event.data as { portholeCheck?: unknown; data?: unknown } | null;
|
|
85
|
+
if (data === null || typeof data !== "object" || typeof data.portholeCheck !== "string") {
|
|
86
|
+
return;
|
|
87
|
+
}
|
|
88
|
+
for (const run of runs.values()) {
|
|
89
|
+
if (frameOf(run)?.contentWindow !== event.source) {
|
|
90
|
+
continue;
|
|
91
|
+
}
|
|
92
|
+
const said = data.data as Record<string, unknown>;
|
|
93
|
+
switch (data.portholeCheck) {
|
|
94
|
+
case "error": {
|
|
95
|
+
const error = data.data as {
|
|
96
|
+
message?: unknown;
|
|
97
|
+
file?: unknown;
|
|
98
|
+
line?: unknown;
|
|
99
|
+
stack?: unknown;
|
|
100
|
+
};
|
|
101
|
+
const line = contentLine(
|
|
102
|
+
{
|
|
103
|
+
file: typeof error.file === "string" ? error.file : "",
|
|
104
|
+
line: typeof error.line === "number" ? error.line : 0,
|
|
105
|
+
stack: typeof error.stack === "string" ? error.stack : "",
|
|
106
|
+
},
|
|
107
|
+
run.scriptLines,
|
|
108
|
+
);
|
|
109
|
+
const message = typeof error.message === "string" ? error.message : "Error";
|
|
110
|
+
run.data.errors.push(`${message}${line === null ? "" : ` (line ${line})`}`);
|
|
111
|
+
break;
|
|
112
|
+
}
|
|
113
|
+
case "blocked":
|
|
114
|
+
run.data.blocked.push({ url: String(said.url), directive: String(said.directive) });
|
|
115
|
+
break;
|
|
116
|
+
case "load":
|
|
117
|
+
run.data.failedLoads.push({ url: String(said.url), tag: String(said.tag) });
|
|
118
|
+
break;
|
|
119
|
+
case "console":
|
|
120
|
+
run.data.console.push({
|
|
121
|
+
level: said.level === "warning" ? "warning" : "error",
|
|
122
|
+
text: String(said.text),
|
|
123
|
+
});
|
|
124
|
+
break;
|
|
125
|
+
case "measure":
|
|
126
|
+
run.data.scrollWidth = Number(said.scrollWidth);
|
|
127
|
+
run.data.clientWidth = Number(said.clientWidth);
|
|
128
|
+
break;
|
|
129
|
+
default:
|
|
130
|
+
break;
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
const check = {
|
|
136
|
+
/** Shows the content at one width and scheme; returns its run id. */
|
|
137
|
+
run(spec: CheckRunSpec): number {
|
|
138
|
+
const id = next;
|
|
139
|
+
next += 1;
|
|
140
|
+
const box = document.createElement("section");
|
|
141
|
+
box.id = `porthole-check-${id}`;
|
|
142
|
+
box.style.cssText = `width:${spec.widthPx}px;${spec.heightPx === undefined ? "" : `height:${spec.heightPx}px;`}`;
|
|
143
|
+
document.body.append(box);
|
|
144
|
+
const theme = spec.hostTheme ?? {};
|
|
145
|
+
const calls: CheckCall[] = [];
|
|
146
|
+
const display = createHost(spec.config, {
|
|
147
|
+
theme: () => theme,
|
|
148
|
+
hostInfo: { name: "porthole-check", version: "1" },
|
|
149
|
+
// Every host function the config declares, answered as a host that declines (P074): a
|
|
150
|
+
// person asked to confirm says no, a handler says no, and each call is noted.
|
|
151
|
+
handlers: declining(Object.keys(spec.config.capabilities), calls),
|
|
152
|
+
confirm: () => Promise.resolve("declined"),
|
|
153
|
+
// A served config's instance, issued by the check's own server on this page's origin.
|
|
154
|
+
locator: {
|
|
155
|
+
locate: async (instance) =>
|
|
156
|
+
(await (
|
|
157
|
+
await fetch("/issue", { method: "POST", body: JSON.stringify({ instance }) })
|
|
158
|
+
).json()) as FrameLocation,
|
|
159
|
+
},
|
|
160
|
+
}).mount(box, {
|
|
161
|
+
displayId: `check-${id}`,
|
|
162
|
+
title: "Check",
|
|
163
|
+
scheme: spec.scheme,
|
|
164
|
+
...(spec.instance === undefined ? {} : { instance: spec.instance }),
|
|
165
|
+
});
|
|
166
|
+
const run: Run = {
|
|
167
|
+
display,
|
|
168
|
+
box,
|
|
169
|
+
scriptLines: spec.scriptLines,
|
|
170
|
+
data: {
|
|
171
|
+
errors: [],
|
|
172
|
+
calls,
|
|
173
|
+
blocked: [],
|
|
174
|
+
failedLoads: [],
|
|
175
|
+
console: [],
|
|
176
|
+
height: null,
|
|
177
|
+
scrollWidth: null,
|
|
178
|
+
clientWidth: null,
|
|
179
|
+
outcome: null,
|
|
180
|
+
},
|
|
181
|
+
};
|
|
182
|
+
display.on("resize", ({ height }) => {
|
|
183
|
+
run.data.height = height;
|
|
184
|
+
});
|
|
185
|
+
display.on("refused", ({ capability, refusal }) => {
|
|
186
|
+
// "failed": the declining handler's own no, already noted.
|
|
187
|
+
if (refusal !== "failed") {
|
|
188
|
+
calls.push({ capability, outcome: refusal });
|
|
189
|
+
}
|
|
190
|
+
});
|
|
191
|
+
display.on("outcome", (outcome) => {
|
|
192
|
+
run.data.outcome = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
|
|
193
|
+
});
|
|
194
|
+
runs.set(id, run);
|
|
195
|
+
// A stored page comes from the check's server; a shell (served or opaque) gets the content.
|
|
196
|
+
if (spec.instance?.document.kind !== "artifact") {
|
|
197
|
+
display.on("initialized", () => display.setContent(instrumented(spec.content)));
|
|
198
|
+
}
|
|
199
|
+
return id;
|
|
200
|
+
},
|
|
201
|
+
/** Asks the frame for its width; resolves when it answers (or after a second). */
|
|
202
|
+
async measure(id: number): Promise<void> {
|
|
203
|
+
const run = runs.get(id);
|
|
204
|
+
const frame = run === undefined ? null : frameOf(run);
|
|
205
|
+
if (run === undefined || frame?.contentWindow === null || frame === null) {
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
frame.contentWindow.postMessage({ portholeCheck: "measure" }, "*");
|
|
209
|
+
const started = Date.now();
|
|
210
|
+
while (run.data.scrollWidth === null && Date.now() - started < 1_000) {
|
|
211
|
+
await new Promise((resolve) => setTimeout(resolve, 50));
|
|
212
|
+
}
|
|
213
|
+
},
|
|
214
|
+
/** What the run saw. */
|
|
215
|
+
result(id: number): CheckRunData | null {
|
|
216
|
+
return runs.get(id)?.data ?? null;
|
|
217
|
+
},
|
|
218
|
+
/** Removes a run's display. */
|
|
219
|
+
end(id: number): void {
|
|
220
|
+
const run = runs.get(id);
|
|
221
|
+
run?.display.destroy();
|
|
222
|
+
run?.box.remove();
|
|
223
|
+
runs.delete(id);
|
|
224
|
+
},
|
|
225
|
+
};
|
|
226
|
+
|
|
227
|
+
export type CheckPageApi = typeof check;
|
|
228
|
+
|
|
229
|
+
(window as unknown as { portholeCheck: CheckPageApi }).portholeCheck = check;
|
|
230
|
+
document.documentElement.dataset.portholeCheck = "ready";
|