@botiverse/porthole 0.0.1 → 0.1.0

package/dist/compile/policy.js

@@ -0,0 +1,106 @@
+import { CAPABILITIES } from "../config/capabilities.js";
+/** The capabilities a config declares, in vocabulary order. */
+export function declaredCapabilities(config) {
+    return Object.keys(CAPABILITIES).filter((name) => config.capabilities[name] !== undefined);
+}
+/** The gates a declared capability runs under: its own, else the vocabulary's defaults. */
+export function effectiveGates(config, name) {
+    return config.capabilities[name]?.gates ?? CAPABILITIES[name].defaultGates;
+}
+const unique = (values) => [...new Set(values)];
+/** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
+export function egressOrigins(config, kind) {
+    const fromCapabilities = declaredCapabilities(config).flatMap((name) => {
+        const capability = config.capabilities[name];
+        return (kind === "connect" ? capability?.connect : capability?.resource) ?? [];
+    });
+    return unique([...(config.egress[kind] ?? []), ...fromCapabilities]);
+}
+/** Every origin content may reach, of any kind. */
+export function allEgressOrigins(config) {
+    const kinds = ["connect", "script", "style", "img", "font", "media"];
+    return unique(kinds.flatMap((kind) => egressOrigins(config, kind)));
+}
+const list = (sources) => sources.length === 0 ? ["'none'"] : [...sources];
+/**
+ * The frame's CSP directives. Closed by default: `default-src 'none'`, and each kind opened only
+ * to the config's origins. Inline code runs (agent content is inline), so the walls are origin
+ * isolation and egress, not script provenance. No `'self'` anywhere: an opaque frame has nothing
+ * of its own to load, and its `'self'` may be the embedding page's origin. Empty for url mode,
+ * whose app serves its own policy.
+ */
+export function frameCspDirectives(config) {
+    if (config.mode === "url") {
+        return [];
+    }
+    const origins = (kind) => egressOrigins(config, kind);
+    return [
+        ["default-src", "'none'"],
+        ["script-src", "'unsafe-inline'", "'unsafe-eval'", "blob:", ...origins("script")],
+        ["style-src", "'unsafe-inline'", ...origins("style")],
+        ["font-src", "data:", ...origins("font")],
+        ["img-src", "data:", "blob:", ...origins("img")],
+        ["media-src", "data:", "blob:", ...origins("media")],
+        ["connect-src", ...list(origins("connect"))],
+        ["worker-src", "blob:"],
+        ["child-src", "blob:"],
+        ["frame-src", "'none'"],
+        ["object-src", "'none'"],
+        ["base-uri", "'none'"],
+        ["form-action", "'none'"],
+        // WebRTC reaches the network outside connect-src (ICE gathering against a STUN/TURN server).
+        // Engines that honor this token block it; the shell removes the RTC constructors for the rest.
+        ["webrtc", "'block'"],
+    ];
+}
+export function serializeCsp(directives) {
+    return directives.map((directive) => directive.join(" ")).join("; ");
+}
+/**
+ * The frame's `sandbox` tokens. Opaque: scripts only, so the frame is an opaque origin and gets
+ * no forms, popups, downloads, modals or top navigation. Domain: its own origin as well, which is
+ * safe only because that origin is a separate site from the host's (the mount refuses one that
+ * isn't). External (url mode): what a running web app needs to work on its own origin.
+ */
+export function sandboxTokens(config) {
+    switch (config.isolation) {
+        case "opaque":
+            return ["allow-scripts"];
+        case "domain":
+            return ["allow-scripts", "allow-same-origin"];
+        case "external":
+            return ["allow-scripts", "allow-same-origin", "allow-forms"];
+    }
+}
+/**
+ * The frame's `allow` attribute (Permissions Policy). Empty: no camera, microphone, geolocation,
+ * clipboard, fullscreen or other powerful feature is delegated to the frame.
+ */
+export function allowAttribute(_config) {
+    return "";
+}
+/**
+ * The `frame-src` sources the EMBEDDING page must allow, and nothing else: a frame's own CSP can't
+ * stop it navigating itself to an external URL with data in the query, but the embedding page's
+ * `frame-src` governs every navigation of its frames, including self-initiated ones. `srcdoc`
+ * frames need no source (measured: they load under `frame-src 'none'`), so opaque content gets
+ * none, and can't navigate its frame even to the host's own origin (P033); served and external
+ * content adds its own origins, and a host its own frames (`'self'` only if it names it).
+ */
+export function embedderFrameSources(config) {
+    return unique([...config.contentOrigins, ...(config.embedder.frameSrc ?? [])]);
+}
+/**
+ * The CSP the embedding page sends (a header, or the host's own document's policy), for every kind
+ * of display it shows. It sets no `default-src`: it restricts frames only, leaving the host's own
+ * scripts, styles and fetches to the host's policy. `child-src` repeats `frame-src` for engines
+ * that read frames from it.
+ */
+export function embedderCsp(configs) {
+    const sources = unique(configs.flatMap(embedderFrameSources));
+    const all = sources.length === 0 ? ["'none'"] : sources;
+    return serializeCsp([
+        ["frame-src", ...all],
+        ["child-src", ...all],
+    ]);
+}

package/dist/config/capabilities.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The capability vocabulary (PRINCIPLE 4): every power content has beyond drawing is one of these
+ * host functions, named in the config. A capability the config doesn't declare is not wired into
+ * the shell, not carried by the bridge, adds nothing to the CSP, and is absent from the manual.
+ *
+ * Each has default gates, applied when a config declares it without its own (PRINCIPLE 1: gates
+ * are on by default), and is served either by a handler the host passes or as an event the
+ * framework emits.
+ */
+export declare const CAPABILITY_NAMES: readonly ["sendPrompt", "openLink", "downloadFile", "callTool", "readData", "setModelContext", "reportError", "resize"];
+export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
+/**
+ * What must hold before a call reaches the host's handler. A capability's gates all apply.
+ *
+ * - `user-activation`: the call follows a real user gesture in the frame. The shell refuses a call
+ *   without one, and the host checks its own page's activation (which a gesture in a child frame
+ *   propagates to). It stops calls made on load or on a timer; it is not proof of intent.
+ * - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
+ *   goes only if they accept. No `confirm` function means the call is refused (fail closed).
+ * - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
+ */
+export type Gate = "user-activation" | "confirm" | {
+    readonly rateLimit: {
+        readonly perMinute: number;
+    };
+};
+export interface CapabilitySpec {
+    /** The gates a declared capability gets when its config names none. */
+    readonly defaultGates: readonly Gate[];
+    /** `handler`: the host passes a function that performs it. `event`: the framework emits it. */
+    readonly served: "handler" | "event";
+    /** The global the shell defines for it (sugar over the protocol message), if any. */
+    readonly global?: string;
+    /**
+     * How content reaches it without the shell's global: the MCP Apps request, and the official
+     * App SDK's method for it. Absent for what the shell does by itself (sizes, errors).
+     */
+    readonly request?: {
+        readonly method: string;
+        readonly sdk: string;
+    };
+}
+export declare const CAPABILITIES: {
+    readonly sendPrompt: {
+        readonly defaultGates: readonly ["user-activation", "confirm"];
+        readonly served: "handler";
+        readonly global: "sendPrompt";
+        readonly request: {
+            readonly method: "ui/message";
+            readonly sdk: "app.sendMessage";
+        };
+    };
+    readonly openLink: {
+        readonly defaultGates: readonly ["user-activation", "confirm"];
+        readonly served: "handler";
+        readonly global: "openLink";
+        readonly request: {
+            readonly method: "ui/open-link";
+            readonly sdk: "app.openLink";
+        };
+    };
+    readonly downloadFile: {
+        readonly defaultGates: readonly ["user-activation", "confirm"];
+        readonly served: "handler";
+        readonly request: {
+            readonly method: "ui/download-file";
+            readonly sdk: "app.downloadFile";
+        };
+    };
+    readonly callTool: {
+        readonly defaultGates: readonly ["confirm"];
+        readonly served: "handler";
+        readonly request: {
+            readonly method: "tools/call";
+            readonly sdk: "app.callServerTool";
+        };
+    };
+    readonly readData: {
+        readonly defaultGates: readonly [Gate];
+        readonly served: "handler";
+        readonly request: {
+            readonly method: "resources/read";
+            readonly sdk: "app.readServerResource";
+        };
+    };
+    readonly setModelContext: {
+        readonly defaultGates: readonly [Gate];
+        readonly served: "handler";
+        readonly request: {
+            readonly method: "ui/update-model-context";
+            readonly sdk: "app.updateModelContext";
+        };
+    };
+    readonly reportError: {
+        readonly defaultGates: readonly [Gate];
+        readonly served: "event";
+    };
+    readonly resize: {
+        readonly defaultGates: readonly [];
+        readonly served: "event";
+    };
+};
+/** The arguments a call carries, once the adapter has validated them. */
+export interface CapabilityArgs {
+    readonly sendPrompt: {
+        readonly text: string;
+    };
+    readonly openLink: {
+        readonly url: string;
+    };
+    /** MCP resource contents (embedded or linked), as the protocol carries them. */
+    readonly downloadFile: {
+        readonly contents: readonly unknown[];
+    };
+    readonly callTool: {
+        readonly name: string;
+        readonly arguments: Readonly<Record<string, unknown>>;
+    };
+    readonly readData: {
+        readonly uri: string;
+    };
+    readonly setModelContext: {
+        readonly content?: readonly unknown[];
+        readonly structuredContent?: Readonly<Record<string, unknown>>;
+    };
+    readonly reportError: {
+        readonly message: string;
+    };
+    readonly resize: {
+        readonly height: number;
+        readonly width?: number;
+    };
+}
+/** What a call resolves to. Protocol-shaped results (a tool's result) stay opaque to the core. */
+export interface CapabilityResults {
+    /** Whether the prompt was sent. */
+    readonly sendPrompt: boolean;
+    /** Whether the link was opened. */
+    readonly openLink: boolean;
+    /** Whether the download started. */
+    readonly downloadFile: boolean;
+    readonly callTool: unknown;
+    readonly readData: unknown;
+    readonly setModelContext: undefined;
+    readonly reportError: undefined;
+    readonly resize: undefined;
+}
+/** The capabilities a host serves with a handler. */
+export type HandledCapability = {
+    [N in CapabilityName]: (typeof CAPABILITIES)[N]["served"] extends "handler" ? N : never;
+}[CapabilityName];
+/** A capability's spec, as the general shape (the table above keeps literal types). */
+export declare function capabilitySpec(name: CapabilityName): CapabilitySpec;
+export declare function isCapabilityName(value: unknown): value is CapabilityName;

package/dist/config/capabilities.js

@@ -0,0 +1,63 @@
+/**
+ * The capability vocabulary (PRINCIPLE 4): every power content has beyond drawing is one of these
+ * host functions, named in the config. A capability the config doesn't declare is not wired into
+ * the shell, not carried by the bridge, adds nothing to the CSP, and is absent from the manual.
+ *
+ * Each has default gates, applied when a config declares it without its own (PRINCIPLE 1: gates
+ * are on by default), and is served either by a handler the host passes or as an event the
+ * framework emits.
+ */
+export const CAPABILITY_NAMES = [
+    "sendPrompt",
+    "openLink",
+    "downloadFile",
+    "callTool",
+    "readData",
+    "setModelContext",
+    "reportError",
+    "resize",
+];
+const rate = (perMinute) => ({ rateLimit: { perMinute } });
+export const CAPABILITIES = {
+    sendPrompt: {
+        defaultGates: ["user-activation", "confirm"],
+        served: "handler",
+        global: "sendPrompt",
+        request: { method: "ui/message", sdk: "app.sendMessage" },
+    },
+    openLink: {
+        defaultGates: ["user-activation", "confirm"],
+        served: "handler",
+        global: "openLink",
+        request: { method: "ui/open-link", sdk: "app.openLink" },
+    },
+    downloadFile: {
+        defaultGates: ["user-activation", "confirm"],
+        served: "handler",
+        request: { method: "ui/download-file", sdk: "app.downloadFile" },
+    },
+    callTool: {
+        defaultGates: ["confirm"],
+        served: "handler",
+        request: { method: "tools/call", sdk: "app.callServerTool" },
+    },
+    readData: {
+        defaultGates: [rate(120)],
+        served: "handler",
+        request: { method: "resources/read", sdk: "app.readServerResource" },
+    },
+    setModelContext: {
+        defaultGates: [rate(30)],
+        served: "handler",
+        request: { method: "ui/update-model-context", sdk: "app.updateModelContext" },
+    },
+    reportError: { defaultGates: [rate(10)], served: "event" },
+    resize: { defaultGates: [], served: "event" },
+};
+/** A capability's spec, as the general shape (the table above keeps literal types). */
+export function capabilitySpec(name) {
+    return CAPABILITIES[name];
+}
+export function isCapabilityName(value) {
+    return typeof value === "string" && CAPABILITY_NAMES.includes(value);
+}

package/dist/config/schema.d.ts

@@ -0,0 +1,131 @@
+import type { CapabilityName, Gate } from "./capabilities.ts";
+/**
+ * One config per kind of display (PRINCIPLE 3). The compiler derives the frame's CSP, its sandbox
+ * and `allow` attributes, the embedding page's frame policy, the shell's wiring, and the agent
+ * manual and tool description from it, together. A preset is a config with safe defaults filled
+ * in; hosts adopt one and override theme values and callbacks.
+ */
+/** What is shown. */
+export type DisplayMode = 
+/** An HTML fragment or SVG the host has (an agent wrote it), drawn by the shell. */
+"inline"
+/** A whole HTML document: a standalone page. */
+ | "artifact"
+/** A standard MCP Apps view: a `ui://` template, its tool input and result. */
+ | "mcp-app"
+/** A running app by URL (a dev server's preview): frame, isolation and access auth only. */
+ | "url";
+/** How the content is kept away from the host. */
+export type IsolationKind = 
+/** A sandboxed `srcdoc` frame without `allow-same-origin`: an opaque origin, no storage. */
+"opaque"
+/**
+ * A document served on its own subdomain of a separate registrable domain (`/server`): a real,
+ * stable origin per storage scope, its CSP in headers, private content behind a ticket.
+ */
+ | "domain"
+/** Someone else's origin (url mode): the frame loads it as is; there is no shell. */
+ | "external";
+export type ColorScheme = "light" | "dark";
+/** A theme variable's value: one for both schemes, or one per scheme. */
+export type ThemeValue = string | {
+    readonly light: string;
+    readonly dark: string;
+};
+export interface CapabilityConfig {
+    /** Every gate must pass. Omitted: the capability's default gates. `[]`: ungated. */
+    readonly gates?: readonly Gate[];
+    /** Extra `connect-src` origins this capability needs. */
+    readonly connect?: readonly string[];
+    /** Extra script/style/img/font/media origins this capability needs. */
+    readonly resource?: readonly string[];
+    /** Replaces the generated manual entry for this capability. */
+    readonly guide?: string;
+}
+/** The declared capabilities. Absent: not available, not wired, not in the CSP, not in the manual. */
+export type CapabilityMap = {
+    readonly [N in CapabilityName]?: CapabilityConfig;
+};
+/**
+ * Where content may load from and talk to, as exact origins (`https://cdn.example.com`, or
+ * `https://*.example.com` for every subdomain). Empty everywhere is the default: egress closed.
+ * Capabilities add their own needs to these.
+ */
+export interface EgressConfig {
+    readonly connect?: readonly string[];
+    readonly script?: readonly string[];
+    readonly style?: readonly string[];
+    readonly img?: readonly string[];
+    readonly font?: readonly string[];
+    readonly media?: readonly string[];
+}
+export interface ThemeConfig {
+    /**
+     * Every CSS variable the content may read, with its default per scheme. The shell injects
+     * exactly these names (the host supplies live values for them) and the manual teaches them.
+     */
+    readonly variables: Readonly<Record<string, ThemeValue>>;
+    /** The window event the shell fires after the theme changed, for code that must redraw. */
+    readonly event: string;
+}
+export interface Limits {
+    /** The tallest the frame grows before its content scrolls inside it. */
+    readonly maxHeightPx: number;
+    /** The shortest the frame is once its content reported a size. */
+    readonly minHeightPx: number;
+    /** The largest content the manual allows (the host enforces it where it takes content in). */
+    readonly maxBytes: number;
+    /** The most frames of this kind a page runs at once (the React binding's live-frame cap). */
+    readonly maxLiveFrames: number;
+    /** Declined confirmations after which a display stops asking until it runs again. */
+    readonly declinesBeforeMute: number;
+    /** The longest prompt `sendPrompt` carries. */
+    readonly maxPromptChars: number;
+    /** The most errors one run of a display reports. */
+    readonly maxErrorReports: number;
+}
+/** Where the host shows the content, for the manual's size rules. */
+export interface LayoutConfig {
+    /** The narrowest the frame ever is (a small phone). */
+    readonly minWidthPx: number;
+    /** A typical phone's width: what the content is designed for first. */
+    readonly narrowWidthPx: number;
+    /** The widest the frame is (a desktop column). */
+    readonly wideWidthPx: number;
+}
+export interface GuideConfig {
+    /** The host's tool that shows this content, as the manual names it (`show_widget`). */
+    readonly toolName?: string;
+    /** The host's tool that answers this manual, as the tool description names it. */
+    readonly guideToolName?: string;
+    /**
+     * The host's own topics, by name, appended to the manual when asked for (a host's file tool,
+     * say). They may not name a built-in topic. Write them about the host's tools, not the sandbox:
+     * the sandbox's rules are generated, so they always match it.
+     */
+    readonly topics?: Readonly<Record<string, string>>;
+}
+export interface EmbedderConfig {
+    /**
+     * Extra `frame-src` sources the embedding page allows, for frames it shows besides these:
+     * origins, or `'self'` if it frames its own pages (which lets content navigate there too).
+     */
+    readonly frameSrc?: readonly string[];
+}
+export interface PortholeConfig {
+    readonly mode: DisplayMode;
+    readonly isolation: IsolationKind;
+    readonly capabilities: CapabilityMap;
+    readonly egress: EgressConfig;
+    readonly theme: ThemeConfig;
+    readonly limits: Limits;
+    readonly layout: LayoutConfig;
+    readonly guide: GuideConfig;
+    /**
+     * Where `domain` and `external` content is served from, as frame-src sources
+     * (`https://*.example-usercontent.com`; dev `http://*.localhost:8790`): the embedding page frames
+     * them, and the host takes messages only from a frame whose origin matches. Empty for `opaque`.
+     */
+    readonly contentOrigins: readonly string[];
+    readonly embedder: EmbedderConfig;
+}

package/dist/config/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/config/validate.d.ts

@@ -0,0 +1,20 @@
+import type { PortholeConfig } from "./schema.ts";
+/**
+ * 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 declare class ConfigError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+/** The built-in manual topics; a host's own topics may not reuse these names. */
+export declare const BUILT_IN_TOPICS: readonly ["widget", "chart", "interactive"];
+/**
+ * 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 declare function isOriginSource(value: unknown): value is string;
+/** Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise. */
+export declare function validateConfig(input: unknown): PortholeConfig;