@botiverse/porthole 0.0.1 → 0.1.0

package/dist/server/types.d.ts

@@ -0,0 +1,97 @@
+import type { PortholeConfig } from "../config/schema.ts";
+import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
+export interface ContentDomain {
+    /**
+     * The registrable domain content is served under, used for nothing else
+     * (`example-usercontent.com`). Dev and tests: `localhost`, so labels are `<label>.localhost`,
+     * which browsers resolve to loopback.
+     */
+    readonly domain: string;
+    /** `http` only for `localhost`. */
+    readonly scheme: "https" | "http";
+    readonly port?: number;
+}
+/** Who may open an instance, decided by the host before it calls `issue`. */
+export interface Grant {
+    /** The host's id for the viewer: recorded with the ticket, never shown to content. */
+    readonly viewer: string;
+    /** How long the ticket is good for, seconds (default 60). */
+    readonly ttlSeconds?: number;
+    /**
+     * How long the cookie the ticket buys stays good, seconds (default 3600): what a reload, and a
+     * url-mode app's every request, rides on.
+     */
+    readonly sessionSeconds?: number;
+}
+export interface TicketRecord {
+    readonly instance: InstanceRef;
+    readonly viewer: string;
+    /** Epoch milliseconds. */
+    readonly expiresAt: number;
+    /** The grant's `sessionSeconds`, if it set one. */
+    readonly sessionSeconds?: number;
+}
+/** Where tickets live between `issue` and their one use. Default: in memory (one process). */
+export interface TicketStore {
+    put(id: string, record: TicketRecord): Promise<void>;
+    /** Returns the ticket once and never again (atomically), or null if unknown or expired. */
+    take(id: string): Promise<TicketRecord | null>;
+}
+/** Stored pages (artifact mode). Versions are immutable: a new page is a new version. */
+export interface ArtifactStore {
+    get(id: string, version: string): Promise<{
+        readonly html: string;
+    } | null>;
+}
+/** What a request's cookie lets in: one instance, for one viewer, on one origin, until a time. */
+export interface Access {
+    readonly instance: InstanceRef;
+    readonly viewer: string;
+    /** The content origin the access is for. */
+    readonly origin: string;
+    /** When the cookie stops being good, epoch milliseconds. */
+    readonly expiresAt: number;
+}
+/**
+ * Answers a url-mode app's request once `/server` has checked its access: the host's way to the
+ * running app (a proxy to a dev server, say; `proxyTo` is one). The request no longer carries
+ * Porthole's cookie; the answer gets `frame-ancestors` added, and loses any cookie named as ours.
+ */
+export type Upstream = (request: Request, access: Access) => Response | Promise<Response>;
+export interface ServerOptions {
+    readonly content: ContentDomain;
+    /** At least 32 random bytes: keys the labels and signs tickets and cookies. */
+    readonly secret: Uint8Array;
+    /** The host origins that may embed content (`frame-ancestors`) and talk to a served shell. */
+    readonly hostOrigins: readonly string[];
+    /**
+     * The configs a served shell or page is served under, by the name a `ServedDocument` gives
+     * (an artifact defaults to `artifact`, the MCP Apps sandbox proxy to `mcpApp`).
+     */
+    readonly configs: Readonly<Record<string, PortholeConfig>>;
+    readonly artifacts?: ArtifactStore;
+    readonly tickets?: TicketStore;
+    /** Url mode: where an external instance's requests go once let in. Absent: nothing serves them. */
+    readonly upstream?: Upstream;
+}
+export interface PortholeServer {
+    /**
+     * Answers a request for any host under the content domain; null for any other request, which
+     * the host's own routes then handle. Web-standard `Request`/`Response`.
+     */
+    handle(request: Request): Promise<Response | null>;
+    /** The origin a storage scope maps to. */
+    originFor(scope: string): string;
+    /**
+     * Mints a one-time ticket for `instance` and returns the URL its frame loads. Call it from the
+     * host's own authenticated API, once the host has decided the viewer may see the instance.
+     */
+    issue(instance: InstanceRef, grant: Grant): Promise<FrameLocation>;
+    /**
+     * The access a request's cookie carries for a url-mode app on the request's origin, or null:
+     * for a host's own WebSocket upgrade path, which a fetch-style handler can't take.
+     */
+    access(request: Request): Promise<Access | null>;
+    /** The frame source every content origin matches (`https://*.example-usercontent.com`). */
+    readonly contentSource: string;
+}

package/dist/server/types.js

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

package/dist/shell/document.d.ts

@@ -0,0 +1,28 @@
+import type { ShellPlan } from "./plan.ts";
+export interface ShellDocumentOptions {
+    /**
+     * The origins the shell takes messages from: the embedding page's own (`location.origin`), or
+     * every host origin a served document may be embedded by. Exact origins, no wildcards. The
+     * sender must also be the frame's parent.
+     */
+    readonly origins: readonly string[];
+    /** The frame document's title (for assistive technology inside the frame). */
+    readonly title?: string;
+    /**
+     * A whole document to show in place of the shell's own empty one (an MCP Apps view): the shell
+     * parses it inert, guards it, imports it, and runs its scripts in order, once its own policy
+     * and runtime are in place. It is never handed to the page's parser, which could build what the
+     * shell's guards can't see.
+     */
+    readonly document?: string;
+    /**
+     * Whether the CSP goes in a `<meta>` (default). A served document sends it as a header too;
+     * both apply, and the stricter wins.
+     */
+    readonly cspMeta?: boolean;
+}
+/**
+ * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
+ * A given `document` travels in the runtime's plan, as data.
+ */
+export declare function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string;

package/dist/shell/document.js

@@ -0,0 +1,84 @@
+import { SHELL_RUNTIME } from "./runtime.js";
+const EXACT_ORIGIN = /^(https?:\/\/[a-z0-9.-]+(:\d{1,5})?|https?:\/\/\[::1\](:\d{1,5})?)$/u;
+const escapeAttribute = (value) => value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;");
+const escapeText = (value) => value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+/** JSON that is safe inside a `<script>`: no `</script>`, no `<!--`. */
+const scriptJson = (value) => JSON.stringify(value)
+    .replace(/</gu, "\\u003c")
+    .replace(/\u2028/gu, "\\u2028")
+    .replace(/\u2029/gu, "\\u2029");
+/** The base styles: the theme's type and color on the body, and nothing drawn by the shell. */
+const BASE_STYLE = `:root { color-scheme: light dark; }
+html, body { margin: 0; padding: 0; background: transparent; }
+body {
+  font-family: var(--font-sans, system-ui, sans-serif);
+  font-size: var(--font-text-md-size, 14px);
+  line-height: var(--font-text-md-line-height, 20px);
+  color: var(--color-text-primary, CanvasText);
+  overflow-wrap: anywhere;
+  -webkit-text-size-adjust: 100%;
+}
+#porthole-root { display: flow-root; }
+#porthole-root > svg { display: block; max-width: 100%; height: auto; }
+:where(button, input, select, textarea) { font: inherit; color: inherit; box-sizing: border-box; }
+:where(button, select, input:is([type="button" i], [type="submit" i], [type="reset" i])) {
+  min-height: 44px;
+  padding: 0 14px;
+  border: var(--border-width-regular, 1px) solid var(--color-border-primary, ButtonBorder);
+  border-radius: var(--border-radius-md, 8px);
+  background: var(--color-background-secondary, ButtonFace);
+  color: var(--color-text-primary, ButtonText);
+  cursor: pointer;
+}
+:where(input:not([type]), input:is([type="text" i], [type="search" i], [type="number" i], [type="email" i], [type="url" i], [type="tel" i], [type="password" i], [type="date" i], [type="time" i]), textarea) {
+  min-height: 44px;
+  padding: 0 10px;
+  border: var(--border-width-regular, 1px) solid var(--color-border-primary, FieldText);
+  border-radius: var(--border-radius-md, 8px);
+  background: var(--color-background-secondary, Field);
+}
+:where(textarea) { padding: 8px 10px; }
+:where(input:is([type="checkbox" i], [type="radio" i], [type="range" i])) { accent-color: var(--color-accent, auto); }
+:where(button, input, select, textarea):focus-visible { outline: 2px solid var(--color-ring-primary, Highlight); outline-offset: 1px; }
+:where(button, input, select, textarea):disabled { color: var(--color-text-disabled, GrayText); cursor: default; }`;
+/**
+ * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
+ * A given `document` travels in the runtime's plan, as data.
+ */
+export function shellDocument(plan, csp, options) {
+    for (const origin of options.origins) {
+        if (!EXACT_ORIGIN.test(origin)) {
+            throw new TypeError(`shellDocument: ${JSON.stringify(origin)} is not an exact origin`);
+        }
+    }
+    const runtime = SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({
+        ...plan,
+        origins: options.origins,
+        ...(options.document === undefined ? {} : { document: options.document }),
+    }));
+    const head = [
+        '<meta charset="utf-8">',
+        options.cspMeta === false
+            ? null
+            : `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}">`,
+        '<meta name="referrer" content="no-referrer">',
+        // Off for good: an engine may prefetch names it sees in links, outside the CSP.
+        '<meta http-equiv="x-dns-prefetch-control" content="off">',
+    ].filter((line) => line !== null);
+    return `<!doctype html>
+<html lang="en">
+<head>
+${head.join("\n")}
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeText(options.title ?? "Content")}</title>
+<style>
+${BASE_STYLE}
+</style>
+</head>
+<body>
+<div id="porthole-root"></div>
+<script>${runtime}</script>
+</body>
+</html>
+`;
+}

package/dist/shell/plan.d.ts

@@ -0,0 +1,35 @@
+import { type CapabilityName } from "../config/capabilities.ts";
+import type { PortholeConfig } from "../config/schema.ts";
+/**
+ * What the shell wires, derived from the config: the JSON the shell's runtime is given. The
+ * agreement test reads it against the CSP and the manual, so it lists everything the shell
+ * offers content and nothing else.
+ */
+export interface ShellPlan {
+    /**
+     * `shell`: the shell speaks MCP Apps with its host and draws the content it is sent (inline
+     * widgets, artifact pages). `none`: the content is a view that speaks for itself (an MCP Apps
+     * view); the shell only hardens the frame before it runs.
+     */
+    readonly protocol: "shell" | "none";
+    /** What the host sends: a fragment (or SVG) the shell inserts, or a whole document it writes. */
+    readonly content: "fragment" | "document";
+    /** Each declared capability, and whether the shell refuses a call made without a gesture. */
+    readonly capabilities: {
+        readonly [N in CapabilityName]?: {
+            readonly userActivation: boolean;
+        };
+    };
+    /** The globals the shell defines on `window` (sugar over the protocol's requests). */
+    readonly globals: readonly string[];
+    /** The theme variables the shell applies; it drops any other name the host sends. */
+    readonly themeVariables: readonly string[];
+    /** The window event fired after a theme change. */
+    readonly themeEvent: string;
+    /** `memory`: an opaque origin has no storage, so a map stands in for the frame's life. */
+    readonly storage: "memory" | "native";
+    readonly maxErrorReports: number;
+    readonly maxPromptChars: number;
+    readonly protocolVersion: string;
+}
+export declare function shellPlan(config: PortholeConfig): ShellPlan | null;

package/dist/shell/plan.js

@@ -0,0 +1,34 @@
+import { capabilitySpec } from "../config/capabilities.js";
+import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
+import { MCP_APPS_PROTOCOL_VERSION } from "../protocol/mcp-apps.js";
+export function shellPlan(config) {
+    if (config.mode === "url") {
+        return null;
+    }
+    const protocol = config.mode === "mcp-app" ? "none" : "shell";
+    const declared = declaredCapabilities(config);
+    const capabilities = {};
+    for (const name of declared) {
+        capabilities[name] = {
+            userActivation: effectiveGates(config, name).includes("user-activation"),
+        };
+    }
+    const globals = protocol === "shell"
+        ? declared.flatMap((name) => {
+            const spec = capabilitySpec(name);
+            return spec.global === undefined ? [] : [spec.global];
+        })
+        : [];
+    return {
+        protocol,
+        content: config.mode === "artifact" ? "document" : "fragment",
+        capabilities,
+        globals,
+        themeVariables: Object.keys(config.theme.variables),
+        themeEvent: config.theme.event,
+        storage: config.isolation === "opaque" ? "memory" : "native",
+        maxErrorReports: config.limits.maxErrorReports,
+        maxPromptChars: config.limits.maxPromptChars,
+        protocolVersion: MCP_APPS_PROTOCOL_VERSION,
+    };
+}

package/dist/shell/runtime.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
+ * no imports and no build step, so every engine (a browser frame now, a native web view later)
+ * runs it as it is. `__PLAN__` is replaced with the frame's plan (`ShellPlan` plus the origins it
+ * takes messages from, and a document to render, if any).
+ *
+ * Before any content runs, it:
+ * 1. stands in for storage an opaque origin lacks (a map for the frame's life);
+ * 2. removes every WebRTC constructor, non-configurably: a peer connection reaches the network
+ *    outside connect-src (ICE gathering), and not every engine honors the CSP's `webrtc 'block'`;
+ * 3. removes every frame-like element content adds, wherever it adds it (the document, any shadow
+ *    root), since a nested frame runs in a fresh realm where step 2 never happened (and not every
+ *    engine enforces `frame-src 'none'` for `srcdoc`/`about:blank` children); and the resource
+ *    hints and refreshes a CSP doesn't govern;
+ * 4. closes the parser entry points that could build a shadow root step 3 can't see (declarative
+ *    shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`).
+ * A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
+ * imported, and its scripts run in order, as a fragment's are.
+ *
+ * Then, when it speaks for the content (`protocol: "shell"`), it asks its host `ui/initialize`,
+ * applies the theme the host answers, draws the content it is sent (inert while partial, run once
+ * when whole), reports its size and errors, sends link clicks out through `openLink`, and defines
+ * a global for each declared capability that has one.
+ *
+ * Nothing secret is ever in the frame: everything it says, the host treats as the content's own
+ * words. It takes messages only from its parent, and only from the plan's origins.
+ */
+export declare const SHELL_RUNTIME: string;