@botiverse/porthole 0.0.1 → 0.1.1

package/dist/config/validate.js

@@ -0,0 +1,261 @@
+import { CAPABILITY_NAMES, isCapabilityName } from "./capabilities.js";
+import { URL_SANDBOX_EXTRAS } from "./schema.js";
+/**
+ * Checks a config before anything is derived from it. Every string that ends up in a CSP, an
+ * attribute or the shell is checked here, so a malformed origin can't inject a directive
+ * (`https://a.com; script-src *`) and a typo can't widen a policy. A config that fails is refused
+ * whole, never repaired.
+ */
+export class ConfigError extends Error {
+    path;
+    constructor(path, message) {
+        super(`${path}: ${message}`);
+        this.name = "ConfigError";
+        this.path = path;
+    }
+}
+/** The built-in manual topics; a host's own topics may not reuse these names. */
+export const BUILT_IN_TOPICS = ["widget", "chart", "interactive"];
+const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/u;
+const HOST = /^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/u;
+/**
+ * Whether `value` is a CSP host source Porthole accepts: a scheme, a host (optionally `*.` for
+ * every subdomain) and an optional port, nothing else. Insecure schemes only for loopback names.
+ */
+export function isOriginSource(value) {
+    return originSourceProblem(value) === null;
+}
+/** Why `value` isn't an origin source Porthole accepts, in words to act on; null if it is. */
+export function originSourceProblem(value) {
+    const shape = "is not an origin (scheme://host[:port], lowercase, no path)";
+    if (typeof value !== "string" || value.length > 253 + 16) {
+        return `${JSON.stringify(value)} ${shape}`;
+    }
+    const match = /^(https|http|wss|ws):\/\/([^/:]+|\[::1\])(:(\d{1,5}))?$/u.exec(value);
+    if (match === null) {
+        return `${JSON.stringify(value)} ${shape}`;
+    }
+    const [, scheme, host = "", , port] = match;
+    if (port !== undefined && (Number(port) < 1 || Number(port) > 65_535)) {
+        return `${JSON.stringify(value)} has no valid port`;
+    }
+    if (host !== "[::1]" && !HOST.test(host)) {
+        return `${JSON.stringify(value)} ${shape}`;
+    }
+    if ((scheme === "http" || scheme === "ws") && !LOOPBACK.test(host.replace(/^\*\./u, "x."))) {
+        return `${JSON.stringify(value)} uses ${scheme} off loopback: ${scheme} is allowed only for localhost, *.localhost, 127.0.0.1 and [::1] (loopback development); use ${scheme === "http" ? "https" : "wss"}`;
+    }
+    return null;
+}
+const fail = (path, message) => {
+    throw new ConfigError(path, message);
+};
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+function object(value, path) {
+    return isObject(value) ? value : fail(path, "must be an object");
+}
+function only(value, keys, path) {
+    for (const key of Object.keys(value)) {
+        if (!keys.includes(key)) {
+            fail(`${path}.${key}`, "is not a known field");
+        }
+    }
+}
+function sources(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value)) {
+        fail(path, "must be an array of origins");
+        return;
+    }
+    value.forEach((source, index) => {
+        const problem = originSourceProblem(source);
+        if (problem !== null) {
+            fail(`${path}[${index}]`, problem);
+        }
+    });
+}
+function positive(value, path, max = Number.MAX_SAFE_INTEGER) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > max) {
+        fail(path, `must be an integer from 1 to ${max}`);
+    }
+}
+function gate(value, path) {
+    if (value === "user-activation" || value === "confirm") {
+        return;
+    }
+    const limit = isObject(value) && isObject(value.rateLimit) ? value.rateLimit : null;
+    if (limit === null || Object.keys(value).length !== 1) {
+        fail(path, 'must be "user-activation", "confirm" or { rateLimit: { perMinute } }');
+        return;
+    }
+    only(limit, ["perMinute"], `${path}.rateLimit`);
+    positive(limit.perMinute, `${path}.rateLimit.perMinute`, 10_000);
+}
+const MODES = ["inline", "artifact", "mcp-app", "url"];
+const ISOLATIONS = ["opaque", "domain", "external"];
+/** Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise. */
+export function validateConfig(input) {
+    const config = object(input, "config");
+    only(config, [
+        "mode",
+        "isolation",
+        "capabilities",
+        "egress",
+        "theme",
+        "limits",
+        "layout",
+        "guide",
+        "contentOrigins",
+        "embedder",
+        "sandbox",
+    ], "config");
+    if (!MODES.includes(config.mode)) {
+        fail("config.mode", `must be one of ${MODES.join(", ")}`);
+    }
+    if (!ISOLATIONS.includes(config.isolation)) {
+        fail("config.isolation", `must be one of ${ISOLATIONS.join(", ")}`);
+    }
+    if ((config.mode === "url") !== (config.isolation === "external")) {
+        fail("config.isolation", 'url mode, and only url mode, is "external"');
+    }
+    const capabilities = object(config.capabilities, "config.capabilities");
+    for (const [name, value] of Object.entries(capabilities)) {
+        const path = `config.capabilities.${name}`;
+        if (!isCapabilityName(name)) {
+            fail(path, `is not a capability (${CAPABILITY_NAMES.join(", ")})`);
+        }
+        const capability = object(value, path);
+        only(capability, ["gates", "connect", "resource", "guide"], path);
+        if (capability.gates !== undefined) {
+            if (!Array.isArray(capability.gates)) {
+                fail(`${path}.gates`, "must be an array");
+            }
+            capability.gates.forEach((each, index) => gate(each, `${path}.gates[${index}]`));
+        }
+        sources(capability.connect, `${path}.connect`);
+        sources(capability.resource, `${path}.resource`);
+        if (capability.guide !== undefined && typeof capability.guide !== "string") {
+            fail(`${path}.guide`, "must be a string");
+        }
+    }
+    if (config.mode === "url" && Object.keys(capabilities).length > 0) {
+        fail("config.capabilities", "url mode has no shell, so it can declare no capabilities");
+    }
+    const egress = object(config.egress, "config.egress");
+    const kinds = ["connect", "script", "style", "img", "font", "media"];
+    only(egress, kinds, "config.egress");
+    for (const kind of kinds) {
+        sources(egress[kind], `config.egress.${kind}`);
+    }
+    const theme = object(config.theme, "config.theme");
+    only(theme, ["variables", "event", "documents"], "config.theme");
+    if (theme.documents !== undefined &&
+        theme.documents !== "declared" &&
+        theme.documents !== "always") {
+        fail("config.theme.documents", 'must be "declared" or "always"');
+    }
+    const variables = object(theme.variables, "config.theme.variables");
+    for (const [name, value] of Object.entries(variables)) {
+        const path = `config.theme.variables[${JSON.stringify(name)}]`;
+        if (!/^--[a-z0-9]+(-[a-z0-9]+)*$/u.test(name)) {
+            fail(path, "must be a CSS custom property name (--lowercase-words)");
+        }
+        const values = isObject(value) ? [value.light, value.dark] : [value];
+        if (isObject(value)) {
+            only(value, ["light", "dark"], path);
+        }
+        for (const each of values) {
+            if (typeof each !== "string" ||
+                each.length === 0 ||
+                each.length > 500 ||
+                /[;{}<>]/u.test(each)) {
+                fail(path, "must be a CSS value (1–500 characters, no ; { } < >), or { light, dark } of them");
+            }
+        }
+    }
+    if (typeof theme.event !== "string" || !/^[a-z][a-z0-9]*([:.-][a-z0-9]+)*$/u.test(theme.event)) {
+        fail("config.theme.event", 'must be an event name such as "porthole:theme"');
+    }
+    const limits = object(config.limits, "config.limits");
+    const limitNames = [
+        "maxHeightPx",
+        "minHeightPx",
+        "maxBytes",
+        "maxLiveFrames",
+        "declinesBeforeMute",
+        "maxPromptChars",
+        "maxErrorReports",
+    ];
+    only(limits, [...limitNames, "loadTimeoutMs"], "config.limits");
+    for (const name of limitNames) {
+        positive(limits[name], `config.limits.${name}`);
+    }
+    if (limits.loadTimeoutMs !== undefined) {
+        positive(limits.loadTimeoutMs, "config.limits.loadTimeoutMs", 600_000);
+    }
+    if (limits.minHeightPx > limits.maxHeightPx) {
+        fail("config.limits.minHeightPx", "must not exceed maxHeightPx");
+    }
+    const layout = object(config.layout, "config.layout");
+    only(layout, ["minWidthPx", "narrowWidthPx", "wideWidthPx"], "config.layout");
+    for (const name of ["minWidthPx", "narrowWidthPx", "wideWidthPx"]) {
+        positive(layout[name], `config.layout.${name}`, 10_000);
+    }
+    if (layout.minWidthPx > layout.narrowWidthPx ||
+        layout.narrowWidthPx > layout.wideWidthPx) {
+        fail("config.layout", "must hold minWidthPx ≤ narrowWidthPx ≤ wideWidthPx");
+    }
+    const guide = object(config.guide, "config.guide");
+    only(guide, ["toolName", "guideToolName", "topics"], "config.guide");
+    for (const name of ["toolName", "guideToolName"]) {
+        const value = guide[name];
+        if (value !== undefined &&
+            (typeof value !== "string" || !/^[A-Za-z0-9_.-]{1,64}$/u.test(value))) {
+            fail(`config.guide.${name}`, "must be a tool name (letters, digits, _ . -)");
+        }
+    }
+    if (guide.topics !== undefined) {
+        for (const [name, text] of Object.entries(object(guide.topics, "config.guide.topics"))) {
+            const path = `config.guide.topics.${name}`;
+            if (!/^[a-z][a-z0-9-]{0,31}$/u.test(name) ||
+                BUILT_IN_TOPICS.includes(name)) {
+                fail(path, "must be a new topic name (lowercase), not a built-in one");
+            }
+            if (typeof text !== "string" || text.trim() === "") {
+                fail(path, "must be the topic's text");
+            }
+        }
+    }
+    sources(config.contentOrigins, "config.contentOrigins");
+    const served = config.isolation === "domain" || config.isolation === "external";
+    const contentOrigins = config.contentOrigins;
+    if (served !== contentOrigins.length > 0) {
+        fail("config.contentOrigins", served
+            ? `${String(config.isolation)} isolation needs the origins its content is served from`
+            : "opaque isolation serves nothing: leave it empty");
+    }
+    const embedder = object(config.embedder, "config.embedder");
+    only(embedder, ["frameSrc"], "config.embedder");
+    // The host's own frames may include its own origin, by name.
+    sources(Array.isArray(embedder.frameSrc)
+        ? embedder.frameSrc.filter((source) => source !== "'self'")
+        : embedder.frameSrc, "config.embedder.frameSrc");
+    if (config.sandbox !== undefined) {
+        if (config.mode !== "url") {
+            fail("config.sandbox", "only url mode may add sandbox tokens");
+        }
+        if (!Array.isArray(config.sandbox)) {
+            fail("config.sandbox", "must be an array of sandbox tokens");
+        }
+        config.sandbox.forEach((token, index) => {
+            if (!URL_SANDBOX_EXTRAS.includes(token)) {
+                fail(`config.sandbox[${index}]`, /top-navigation|same-origin/u.test(String(token))
+                    ? `${JSON.stringify(token)} is never granted (P037)`
+                    : `must be one of ${URL_SANDBOX_EXTRAS.join(", ")}`);
+            }
+        });
+    }
+    return input;
+}

package/dist/conformance/behavior.d.ts

@@ -0,0 +1,2 @@
+import { type Probe } from "./kit.ts";
+export declare const BEHAVIOR_PROBES: readonly Probe[];