@botiverse/porthole 0.0.1 → 0.1.0

package/src/bridge/types.ts

@@ -0,0 +1,77 @@
+import type {
+  CapabilityArgs,
+  CapabilityName,
+  CapabilityResults,
+  HandledCapability,
+} from "../config/capabilities.ts";
+
+/**
+ * The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
+ * frame to the host's handler and its result back, checking at the boundary that the capability
+ * is declared, that its arguments are well formed, and that every gate passes, in that order.
+ * Adapters decode protocol messages into calls; the bridge alone decides whether they run.
+ */
+
+/** Which display a call came from. */
+export interface CallContext {
+  readonly displayId: string;
+  /** The display's title, as the host gave it (never the content's words). */
+  readonly title: string;
+  readonly capability: CapabilityName;
+}
+
+export type CapabilityHandler<N extends CapabilityName> = (
+  args: CapabilityArgs[N],
+  context: CallContext,
+) => CapabilityResults[N] | Promise<CapabilityResults[N]>;
+
+/** The host's handlers: one for each declared capability served by a handler. */
+export type CapabilityHandlers = { readonly [N in HandledCapability]?: CapabilityHandler<N> };
+
+/** What a person is asked to confirm: the call's whole effect, not a summary the content chose. */
+export type ConfirmRequest = {
+  [N in CapabilityName]: {
+    readonly capability: N;
+    readonly args: CapabilityArgs[N];
+    readonly display: { readonly id: string; readonly title: string };
+  };
+}[CapabilityName];
+
+/**
+ * Asks a person. Resolves true only if they accept. The host's UI, or the React binding's default
+ * dialog; drawn outside the frame, never inside it.
+ */
+export type Confirm = (request: ConfirmRequest) => Promise<boolean>;
+
+/** Why a call didn't run. */
+export type Refusal =
+  /** The config doesn't declare it. */
+  | "not-declared"
+  /** Its arguments were malformed (an `openLink` that isn't http(s), an empty prompt). */
+  | "invalid"
+  /** It needed a user gesture and had none. */
+  | "no-user-activation"
+  /** It needed a confirmation and there is no `confirm` function. */
+  | "no-confirm"
+  /** The person declined. */
+  | "declined"
+  /** The display was muted after too many declines (until it runs again). */
+  | "muted"
+  | "rate-limited"
+  /** The host's handler threw or rejected. */
+  | "failed";
+
+export type CallOutcome<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly refusal: Refusal; readonly message?: string };
+
+/** What adapters call; one per display. */
+export interface HostFunctionBridge {
+  /** Validates `args` for `capability`, applies its gates, then runs the host's handler. */
+  call<N extends CapabilityName>(
+    capability: N,
+    args: unknown,
+    options?: { readonly userActivated?: boolean },
+  ): Promise<CallOutcome<CapabilityResults[N]>>;
+  declared(capability: CapabilityName): boolean;
+}

package/src/compile/compile.ts

@@ -0,0 +1,68 @@
+import type { PortholeConfig } from "../config/schema.ts";
+import { validateConfig } from "../config/validate.ts";
+import { generateGuide, generateToolDescription, type GuideTopic } from "../guide/guide.ts";
+import { shellDocument, type ShellDocumentOptions } from "../shell/document.ts";
+import { shellPlan, type ShellPlan } from "../shell/plan.ts";
+import {
+  allowAttribute,
+  embedderFrameSources,
+  frameCspDirectives,
+  sandboxTokens,
+  serializeCsp,
+  type CspDirective,
+} from "./policy.ts";
+
+/**
+ * Everything derived from one config (PRINCIPLE 3): the frame's policies, the shell's wiring and
+ * document, and the agent manual and tool description. Compiled together from a validated config,
+ * so they cannot disagree; the agreement test checks that they don't.
+ */
+export interface CompiledConfig {
+  readonly config: PortholeConfig;
+  /** The frame's CSP, directive by directive; empty in url mode (the app sends its own). */
+  readonly cspDirectives: readonly CspDirective[];
+  /** The frame's CSP: in the shell's `<meta>`, or a served document's header. */
+  readonly csp: string;
+  /** The frame's `sandbox` attribute. */
+  readonly sandbox: string;
+  /** The frame's `allow` attribute (Permissions Policy). */
+  readonly allow: string;
+  /** The frame's `referrerpolicy` attribute. */
+  readonly referrerPolicy: "no-referrer";
+  /** The `frame-src` sources the embedding page must allow (see `embedderCsp`). */
+  readonly embedderFrameSources: readonly string[];
+  /** What the shell wires; null in url mode, which has no shell. */
+  readonly shell: ShellPlan | null;
+  /** The frame's document: the policy, the base styles and the shell's runtime. */
+  shellDocument(options: ShellDocumentOptions): string;
+  /** The agent manual for `topics` (every built-in topic by default). */
+  guide(topics?: readonly GuideTopic[]): string;
+  /** The description of the host's show tool. */
+  toolDescription(): string;
+}
+
+/** Validates `config` and derives everything from it. Throws a `ConfigError` on a bad config. */
+export function compile(config: PortholeConfig): CompiledConfig {
+  validateConfig(config);
+  const cspDirectives = frameCspDirectives(config);
+  const csp = serializeCsp(cspDirectives);
+  const shell = shellPlan(config);
+  return {
+    config,
+    cspDirectives,
+    csp,
+    sandbox: sandboxTokens(config).join(" "),
+    allow: allowAttribute(config),
+    referrerPolicy: "no-referrer",
+    embedderFrameSources: embedderFrameSources(config),
+    shell,
+    shellDocument: (options) => {
+      if (shell === null) {
+        throw new TypeError("url mode has no shell: the frame loads the app's own document");
+      }
+      return shellDocument(shell, csp, options);
+    },
+    guide: (topics) => generateGuide(config, topics),
+    toolDescription: () => generateToolDescription(config),
+  };
+}

package/src/compile/policy.ts

@@ -0,0 +1,133 @@
+import { CAPABILITIES, type CapabilityName, type Gate } from "../config/capabilities.ts";
+import type { EgressConfig, PortholeConfig } from "../config/schema.ts";
+
+/**
+ * The frame's policies, derived from the config: its CSP (in the shell's `<meta>` for opaque
+ * frames, in headers for served ones), its `sandbox` and `allow` attributes, and the `frame-src`
+ * the EMBEDDING page must send. Pure, so a test can tie each source back to the config.
+ */
+
+/** A CSP directive: its name, then its sources. */
+export type CspDirective = readonly [name: string, ...sources: string[]];
+
+export type EgressKind = keyof EgressConfig;
+
+/** The capabilities a config declares, in vocabulary order. */
+export function declaredCapabilities(config: PortholeConfig): CapabilityName[] {
+  return (Object.keys(CAPABILITIES) as CapabilityName[]).filter(
+    (name) => config.capabilities[name] !== undefined,
+  );
+}
+
+/** The gates a declared capability runs under: its own, else the vocabulary's defaults. */
+export function effectiveGates(config: PortholeConfig, name: CapabilityName): readonly Gate[] {
+  return config.capabilities[name]?.gates ?? CAPABILITIES[name].defaultGates;
+}
+
+const unique = (values: readonly string[]): string[] => [...new Set(values)];
+
+/** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
+export function egressOrigins(config: PortholeConfig, kind: EgressKind): string[] {
+  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: PortholeConfig): string[] {
+  const kinds: EgressKind[] = ["connect", "script", "style", "img", "font", "media"];
+  return unique(kinds.flatMap((kind) => egressOrigins(config, kind)));
+}
+
+const list = (sources: readonly string[]): string[] =>
+  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: PortholeConfig): CspDirective[] {
+  if (config.mode === "url") {
+    return [];
+  }
+  const origins = (kind: EgressKind) => 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: readonly CspDirective[]): string {
+  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: PortholeConfig): string[] {
+  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: PortholeConfig): string {
+  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: PortholeConfig): string[] {
+  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: readonly PortholeConfig[]): string {
+  const sources = unique(configs.flatMap(embedderFrameSources));
+  const all = sources.length === 0 ? ["'none'"] : sources;
+  return serializeCsp([
+    ["frame-src", ...all],
+    ["child-src", ...all],
+  ]);
+}

package/src/config/capabilities.ts

@@ -0,0 +1,138 @@
+/**
+ * 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",
+] as const;
+
+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 };
+}
+
+const rate = (perMinute: number): Gate => ({ 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" },
+} as const satisfies { readonly [N in CapabilityName]: CapabilitySpec };
+
+/** 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 function capabilitySpec(name: CapabilityName): CapabilitySpec {
+  return CAPABILITIES[name];
+}
+
+export function isCapabilityName(value: unknown): value is CapabilityName {
+  return typeof value === "string" && (CAPABILITY_NAMES as readonly string[]).includes(value);
+}

package/src/config/schema.ts

@@ -0,0 +1,140 @@
+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;
+}