@botiverse/porthole 0.0.0-stage → 0.1.0

package/src/mcp/view.ts

@@ -0,0 +1,97 @@
+import type { EgressConfig } from "../config/schema.ts";
+import { isOriginSource } from "../config/validate.ts";
+
+/**
+ * What a host reads from an MCP Apps view's resource before showing it: the HTML, and the egress
+ * the view declares, in Porthole's vocabulary so it goes into a config (P003).
+ */
+
+/** The style variables MCP Apps standardizes: one list, the core's (P028). */
+export { MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** A declared domain as a CSP source Porthole accepts, or null (`'self'`, `*`, paths, quotes). */
+function originOf(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const source = value.trim().toLowerCase().replace(/\/$/u, "");
+  return isOriginSource(source) ? source : null;
+}
+
+const origins = (value: unknown): string[] =>
+  Array.isArray(value)
+    ? [...new Set(value.map(originOf).filter((each): each is string => each !== null))]
+    : [];
+
+/**
+ * A view's `_meta.ui.csp` as egress: `connectDomains` to connect, `resourceDomains` to scripts,
+ * styles, images, fonts and media. What isn't an exact origin (or `https://*.` one) is dropped,
+ * never widened. `frameDomains` and `baseUriDomains` open nothing: the shell removes nested frames
+ * (P006) and `base-uri` stays `'none'`, so a view that needs either runs without it.
+ */
+export function viewEgress(csp: unknown): EgressConfig {
+  if (!isRecord(csp)) {
+    return {};
+  }
+  const connect = origins(csp.connectDomains);
+  const resource = origins(csp.resourceDomains);
+  return {
+    ...(connect.length > 0 ? { connect } : {}),
+    ...(resource.length > 0
+      ? { script: resource, style: resource, img: resource, font: resource, media: resource }
+      : {}),
+  };
+}
+
+/** A view, as `resources/read` gives it. */
+export interface ViewResource {
+  readonly uri: string;
+  /** The view's whole document. */
+  readonly html: string;
+  /** What the view declares it reaches (its `_meta.ui.csp`), as egress. */
+  readonly egress: EgressConfig;
+  /** Whether the view asks the host for a border and background (`_meta.ui.prefersBorder`). */
+  readonly prefersBorder?: boolean;
+}
+
+/** The MIME type of an MCP Apps view. */
+export const VIEW_MIME_TYPE = "text/html;profile=mcp-app";
+
+/**
+ * The view in a `resources/read` result: its first content of the MCP Apps MIME type, as text or
+ * base64. Null when there is none.
+ */
+export function readViewResource(result: unknown): ViewResource | null {
+  const contents = isRecord(result) && Array.isArray(result.contents) ? result.contents : [];
+  for (const content of contents) {
+    if (!isRecord(content) || typeof content.mimeType !== "string") {
+      continue;
+    }
+    if (content.mimeType.replace(/\s/gu, "").toLowerCase() !== VIEW_MIME_TYPE) {
+      continue;
+    }
+    const html =
+      typeof content.text === "string"
+        ? content.text
+        : typeof content.blob === "string"
+          ? new TextDecoder().decode(
+              Uint8Array.from(atob(content.blob), (char) => char.charCodeAt(0)),
+            )
+          : null;
+    if (html === null) {
+      continue;
+    }
+    const meta = content["_meta"];
+    const ui = isRecord(meta) && isRecord(meta.ui) ? meta.ui : {};
+    return {
+      uri: typeof content.uri === "string" ? content.uri : "",
+      html,
+      egress: viewEgress(ui.csp),
+      ...(typeof ui.prefersBorder === "boolean" ? { prefersBorder: ui.prefersBorder } : {}),
+    };
+  }
+  return null;
+}

package/src/platform/types.ts

@@ -0,0 +1,48 @@
+import type { ColorScheme } from "../config/schema.ts";
+import type { FrameSource } from "../isolation/types.ts";
+import type { Transport } from "../transport/types.ts";
+
+/**
+ * The platform-host seam (ARCHITECTURE § Platform hosts): what owns the isolation primitive and
+ * the transport. The web's is an `<iframe>` with `postMessage`; a native web view is another
+ * implementation of the same interface, not a fork.
+ */
+
+/** What to create: the frame's document and its policy attributes, all from the compiled config. */
+export interface SurfaceSpec {
+  readonly source: FrameSource;
+  /** The frame's accessible name. */
+  readonly title: string;
+  readonly sandbox: string;
+  readonly allow: string;
+  readonly referrerPolicy: "no-referrer";
+  readonly colorScheme: ColorScheme;
+  /** The height to start at (a remembered height, so a frame mounting again doesn't jump). */
+  readonly initialHeightPx: number;
+}
+
+/** One isolated frame. */
+export interface Surface {
+  readonly transport: Transport;
+  /** The platform's own element for the frame (an `HTMLIFrameElement` on the web). */
+  readonly element: unknown;
+  setHeight(px: number): void;
+  setColorScheme(scheme: ColorScheme): void;
+  /**
+   * Whether the embedding page has transient user activation now (a gesture in the frame
+   * activates its ancestors), or undefined where the platform can't tell.
+   */
+  userActivation(): boolean | undefined;
+  /**
+   * The frame loaded a document other than the one it was given: the content navigated it. The
+   * framework starts it again from its content and reports it.
+   */
+  onNavigated(listener: () => void): () => void;
+  destroy(): void;
+}
+
+export interface PlatformHost<Container = HTMLElement> {
+  readonly name: string;
+  /** Creates an isolated frame in `container`, its policy set before its document loads. */
+  createSurface(container: Container, spec: SurfaceSpec): Surface;
+}

package/src/platform/web.ts

@@ -0,0 +1,78 @@
+import type { ColorScheme } from "../config/schema.ts";
+import { postMessageTransport } from "../transport/post-message.ts";
+import type { PlatformHost, Surface, SurfaceSpec } from "./types.ts";
+
+/**
+ * The web platform: an `<iframe>` whose policy attributes are set before its document is given,
+ * talking over `postMessage`. Its first load is the document it was given; any later load is the
+ * content navigating its frame away (a navigation the embedding page's `frame-src` let through, or
+ * one to a document of the frame's own), which the framework answers by starting it again.
+ */
+export const webPlatform: PlatformHost = {
+  name: "web",
+  createSurface(container: HTMLElement, spec: SurfaceSpec): Surface {
+    // oxlint-disable-next-line react/iframe-missing-sandbox -- set from the compiled config, next
+    const frame = container.ownerDocument.createElement("iframe");
+    // Policy first: the sandbox and Permissions Policy must be in place before the document is.
+    frame.setAttribute("sandbox", spec.sandbox);
+    frame.setAttribute("allow", spec.allow);
+    frame.setAttribute("referrerpolicy", spec.referrerPolicy);
+    frame.setAttribute("loading", "eager");
+    frame.title = spec.title;
+    frame.dataset.portholeFrame = "";
+    Object.assign(frame.style, {
+      display: "block",
+      width: "100%",
+      border: "0",
+      background: "transparent",
+      colorScheme: spec.colorScheme,
+      height: `${Math.max(0, Math.round(spec.initialHeightPx))}px`,
+    });
+    const origin = spec.source.kind === "srcdoc" ? "null" : spec.source.origin;
+    if (spec.source.kind === "srcdoc") {
+      frame.srcdoc = spec.source.html;
+    } else {
+      frame.src = spec.source.url;
+    }
+
+    const navigated = new Set<() => void>();
+    let loads = 0;
+    frame.addEventListener("load", () => {
+      loads += 1;
+      if (loads > 1) {
+        for (const listener of navigated) {
+          listener();
+        }
+      }
+    });
+    container.append(frame);
+
+    const view = container.ownerDocument.defaultView ?? window;
+    const transport = postMessageTransport(() => frame.contentWindow, origin, view);
+    return {
+      transport,
+      element: frame,
+      setHeight(px: number) {
+        frame.style.height = `${Math.max(0, Math.round(px))}px`;
+      },
+      setColorScheme(scheme: ColorScheme) {
+        frame.style.colorScheme = scheme;
+      },
+      userActivation() {
+        const activation = (
+          view.navigator as Navigator & { userActivation?: { isActive: boolean } }
+        ).userActivation;
+        return activation === undefined ? undefined : activation.isActive;
+      },
+      onNavigated(listener) {
+        navigated.add(listener);
+        return () => navigated.delete(listener);
+      },
+      destroy() {
+        navigated.clear();
+        transport.close();
+        frame.remove();
+      },
+    };
+  },
+};

package/src/presets/presets.ts

@@ -0,0 +1,193 @@
+import type { CapabilityName } from "../config/capabilities.ts";
+import type {
+  CapabilityConfig,
+  CapabilityMap,
+  EgressConfig,
+  EmbedderConfig,
+  GuideConfig,
+  IsolationKind,
+  LayoutConfig,
+  Limits,
+  PortholeConfig,
+  ThemeValue,
+} from "../config/schema.ts";
+import { validateConfig } from "../config/validate.ts";
+import { DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES } from "../theme/variables.ts";
+
+/**
+ * The preset policy layer (P001): named configs with safe defaults. Every preset starts with
+ * egress closed and only the capabilities that carry nothing out of the frame (its size, its
+ * errors, both to the host only); a host declares the rest, and each gets its default gates
+ * unless the host names its own. A preset returns a validated config.
+ */
+
+/** What a host may change about a preset. Anything else is the preset's. */
+export interface PresetOptions {
+  /** Capabilities to declare (merged over the preset's), or `false` to drop one the preset has. */
+  readonly capabilities?: { readonly [N in CapabilityName]?: CapabilityConfig | false };
+  /** Origins to open, added to the preset's (closed) egress. */
+  readonly egress?: EgressConfig;
+  /** Theme defaults to change or variables to add, and the theme event's name. */
+  readonly theme?: {
+    readonly variables?: Readonly<Record<string, ThemeValue>>;
+    readonly event?: string;
+  };
+  readonly limits?: Partial<Limits>;
+  readonly layout?: Partial<LayoutConfig>;
+  readonly guide?: GuideConfig;
+  /** `opaque` (default) or `domain` for a served document (needs `contentOrigins`). */
+  readonly isolation?: Exclude<IsolationKind, "external">;
+  readonly contentOrigins?: readonly string[];
+  readonly embedder?: EmbedderConfig;
+}
+
+/** The url preset's options: where the app is served, and the embedding page's extra frames. */
+export interface UrlPresetOptions {
+  readonly contentOrigins: readonly string[];
+  readonly limits?: Partial<Limits>;
+  readonly layout?: Partial<LayoutConfig>;
+  readonly embedder?: EmbedderConfig;
+}
+
+/**
+ * Library CDNs a host may open with one line (`egress: LIBRARY_CDNS`): read-only package caches
+ * for scripts, styles, fonts, images and data, plus Google Fonts. Not on by default: every preset
+ * starts with egress closed.
+ */
+export const LIBRARY_CDNS: EgressConfig = {
+  script: [
+    "https://cdnjs.cloudflare.com",
+    "https://cdn.jsdelivr.net",
+    "https://unpkg.com",
+    "https://esm.sh",
+  ],
+  style: [
+    "https://cdnjs.cloudflare.com",
+    "https://cdn.jsdelivr.net",
+    "https://unpkg.com",
+    "https://esm.sh",
+    "https://fonts.googleapis.com",
+  ],
+  font: [
+    "https://fonts.gstatic.com",
+    "https://cdnjs.cloudflare.com",
+    "https://cdn.jsdelivr.net",
+    "https://unpkg.com",
+    "https://esm.sh",
+  ],
+  img: [
+    "https://cdnjs.cloudflare.com",
+    "https://cdn.jsdelivr.net",
+    "https://unpkg.com",
+    "https://esm.sh",
+  ],
+  connect: [
+    "https://cdnjs.cloudflare.com",
+    "https://cdn.jsdelivr.net",
+    "https://unpkg.com",
+    "https://esm.sh",
+  ],
+};
+
+const BASE_LIMITS: Limits = {
+  maxHeightPx: 2_000,
+  minHeightPx: 24,
+  maxBytes: 200_000,
+  maxLiveFrames: 8,
+  declinesBeforeMute: 3,
+  maxPromptChars: 8_000,
+  maxErrorReports: 5,
+};
+
+const BASE_LAYOUT: LayoutConfig = { minWidthPx: 280, narrowWidthPx: 300, wideWidthPx: 750 };
+
+/** Only what reports to the host and carries nothing out: the frame's size and its errors. */
+const BASE_CAPABILITIES: CapabilityMap = { resize: {}, reportError: {} };
+
+const mergeEgress = (base: EgressConfig, extra: EgressConfig | undefined): EgressConfig => {
+  const kinds = ["connect", "script", "style", "img", "font", "media"] as const;
+  const merged: { -readonly [K in keyof EgressConfig]: EgressConfig[K] } = {};
+  for (const kind of kinds) {
+    const origins = [...new Set([...(base[kind] ?? []), ...(extra?.[kind] ?? [])])];
+    if (origins.length > 0) {
+      merged[kind] = origins;
+    }
+  }
+  return merged;
+};
+
+function build(
+  mode: PortholeConfig["mode"],
+  defaults: { readonly limits?: Partial<Limits> },
+  options: PresetOptions,
+): PortholeConfig {
+  const capabilities: { -readonly [N in CapabilityName]?: CapabilityConfig } = {
+    ...BASE_CAPABILITIES,
+  };
+  for (const [name, value] of Object.entries(options.capabilities ?? {}) as [
+    CapabilityName,
+    CapabilityConfig | false,
+  ][]) {
+    if (value === false) {
+      delete capabilities[name];
+    } else {
+      capabilities[name] = value;
+    }
+  }
+  return validateConfig({
+    mode,
+    isolation: options.isolation ?? "opaque",
+    capabilities,
+    egress: mergeEgress({}, options.egress),
+    theme: {
+      variables: { ...DEFAULT_THEME_VARIABLES, ...options.theme?.variables },
+      event: options.theme?.event ?? DEFAULT_THEME_EVENT,
+    },
+    limits: { ...BASE_LIMITS, ...defaults.limits, ...options.limits },
+    layout: { ...BASE_LAYOUT, ...options.layout },
+    guide: options.guide ?? {},
+    contentOrigins: options.contentOrigins ?? [],
+    embedder: options.embedder ?? {},
+  });
+}
+
+export const presets = {
+  /**
+   * An HTML fragment or SVG an agent wrote, drawn inline (a card in a conversation): an opaque
+   * frame with the shell, streamed as it is written.
+   */
+  inlineWidget: (options: PresetOptions = {}): PortholeConfig => build("inline", {}, options),
+
+  /**
+   * A whole HTML page: written into an opaque frame by the shell where the host has the page, or
+   * served on its own origin (`isolation: "domain"`). A document scrolls inside past a shorter cap.
+   */
+  artifact: (options: PresetOptions = {}): PortholeConfig =>
+    build("artifact", { limits: { maxHeightPx: 720, minHeightPx: 120 } }, options),
+
+  /**
+   * A standard MCP Apps view, through an MCP Apps adapter. The view's own `_meta.ui.csp` is
+   * mapped into `egress` by that adapter; the host declares the capabilities it serves.
+   */
+  mcpApp: (options: PresetOptions = {}): PortholeConfig => build("mcp-app", {}, options),
+
+  /**
+   * A running app by URL (a dev server's preview): frame, isolation and access auth only. No
+   * shell, no capabilities, no egress control: the app is someone else's, on its own origin.
+   */
+  url: (options: UrlPresetOptions): PortholeConfig =>
+    validateConfig({
+      mode: "url",
+      isolation: "external",
+      capabilities: {},
+      egress: {},
+      theme: { variables: {}, event: DEFAULT_THEME_EVENT },
+      limits: { ...BASE_LIMITS, maxHeightPx: 4_000, minHeightPx: 120, ...options.limits },
+      layout: { ...BASE_LAYOUT, ...options.layout },
+      guide: {},
+      contentOrigins: options.contentOrigins,
+      embedder: options.embedder ?? {},
+    }),
+} as const;
+
+export type PresetName = keyof typeof presets;

package/src/protocol/adapter.ts

@@ -0,0 +1,67 @@
+import type { HostFunctionBridge } from "../bridge/types.ts";
+import type { CompiledConfig } from "../compile/compile.ts";
+import type { Transport } from "../transport/types.ts";
+import type { HostContext } from "./mcp-apps.ts";
+
+/**
+ * The protocol-adapter seam (P004): the only layer that knows a wire protocol's method names and
+ * shapes. The framework speaks capabilities and lifecycle; an adapter translates.
+ *
+ * - Frame → host: the adapter validates each message (dropping what it doesn't recognize, and
+ *   answering an unknown request with "method not found"), turns every capability use into
+ *   `bridge.call(...)` (including sizes and errors, which the bridge turns into the framework's
+ *   own events), answers the handshake with `hostContext()`, and reports lifecycle with `emit`.
+ * - Host → frame: the framework calls the connection; the adapter encodes and sends.
+ *
+ * The bridge alone decides whether a call runs (declared, valid, gated); an adapter never calls a
+ * host handler itself.
+ */
+
+/** What the framework gives an adapter for one display. */
+export interface AdapterSession {
+  readonly display: { readonly id: string; readonly title: string };
+  readonly compiled: CompiledConfig;
+  readonly transport: Transport;
+  readonly bridge: HostFunctionBridge;
+  readonly hostInfo: { readonly name: string; readonly version: string };
+  /** The host context as of now: theme, its variables, display mode, sizes, locale. */
+  hostContext(): HostContext;
+  /** Lifecycle the framework acts on. */
+  emit(event: AdapterEvent): void;
+  /**
+   * The mount's whole document, when the host passed one (an MCP Apps view): for an adapter that
+   * delivers it itself, as through a sandbox proxy. In opaque isolation the framework has already
+   * put it in the frame, hardened.
+   */
+  readonly document?: string;
+}
+
+export type AdapterEvent =
+  /** The view finished its handshake; content may be sent. */
+  | { readonly type: "initialized" }
+  /** The view asked to be closed. */
+  | { readonly type: "teardown-requested" };
+
+/** What the framework drives on every adapter. Adapters add their protocol's own operations. */
+export interface AdapterConnection {
+  /** The host context changed (a theme flip, a new width): tell the view. */
+  hostContextChanged(context: HostContext): void;
+  /** Asks the view to clean up before it is removed; resolves when it answered or gave up. */
+  teardown(): Promise<void>;
+  /** Stops listening. The framework closes the transport. */
+  close(): void;
+}
+
+export interface ProtocolAdapter<C extends AdapterConnection = AdapterConnection> {
+  readonly name: string;
+  connect(session: AdapterSession): C;
+}
+
+/**
+ * The core adapter's connection: the MCP Apps subset the shell speaks (inline widgets, artifact
+ * pages). Content goes as `tool-input-partial` while it is written, then `tool-input` once.
+ */
+export interface ShellConnection extends AdapterConnection {
+  /** The content so far (`partial`, drawn inert, any number of times), then whole, once. */
+  setContent(html: string, options?: { readonly partial?: boolean }): void;
+}

package/src/protocol/jsonrpc.ts

@@ -0,0 +1,83 @@
+/**
+ * JSON-RPC 2.0, as MCP Apps carries it over a transport. Every message crossing the frame boundary
+ * is checked against these shapes before use; anything else is dropped, never coerced.
+ */
+
+export type JsonRpcId = string | number;
+
+export interface JsonRpcRequest {
+  readonly jsonrpc: "2.0";
+  readonly id: JsonRpcId;
+  readonly method: string;
+  readonly params?: Readonly<Record<string, unknown>>;
+}
+
+export interface JsonRpcNotification {
+  readonly jsonrpc: "2.0";
+  readonly method: string;
+  readonly params?: Readonly<Record<string, unknown>>;
+}
+
+export interface JsonRpcError {
+  readonly code: number;
+  readonly message: string;
+  readonly data?: unknown;
+}
+
+export type JsonRpcResponse =
+  | { readonly jsonrpc: "2.0"; readonly id: JsonRpcId; readonly result: unknown }
+  | { readonly jsonrpc: "2.0"; readonly id: JsonRpcId; readonly error: JsonRpcError };
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
+/** The standard error codes the adapters answer with. */
+export const JSON_RPC_ERRORS = {
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internal: -32603,
+} as const;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const isId = (value: unknown): value is JsonRpcId =>
+  (typeof value === "string" && value.length <= 256) ||
+  (typeof value === "number" && Number.isSafeInteger(value));
+
+/**
+ * `value` as a JSON-RPC message, or null when it isn't one: a request (id + method), a
+ * notification (method only), or a response (id + exactly one of result / error).
+ */
+export function parseJsonRpc(value: unknown): JsonRpcMessage | null {
+  if (!isRecord(value) || value.jsonrpc !== "2.0") {
+    return null;
+  }
+  if (value.params !== undefined && !isRecord(value.params)) {
+    return null;
+  }
+  if (typeof value.method === "string") {
+    if (value.method.length === 0 || value.method.length > 256) {
+      return null;
+    }
+    if (value.id === undefined) {
+      return value as unknown as JsonRpcNotification;
+    }
+    return isId(value.id) ? (value as unknown as JsonRpcRequest) : null;
+  }
+  if (!isId(value.id) || value.method !== undefined) {
+    return null;
+  }
+  const hasResult = "result" in value;
+  const hasError = "error" in value;
+  if (hasResult === hasError) {
+    return null;
+  }
+  if (hasError) {
+    const error = value.error;
+    if (!isRecord(error) || typeof error.code !== "number" || typeof error.message !== "string") {
+      return null;
+    }
+  }
+  return value as unknown as JsonRpcResponse;
+}