@botiverse/porthole 0.0.1 → 0.1.0

package/src/host/create-host.ts

@@ -0,0 +1,290 @@
+import { createBridge, type BridgeEvent } from "../bridge/bridge.ts";
+import { compile } from "../compile/compile.ts";
+import { declaredCapabilities } from "../compile/policy.ts";
+import { capabilitySpec } from "../config/capabilities.ts";
+import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
+import { locateServed } from "./locate.ts";
+import type { FrameSource } from "../isolation/types.ts";
+import { webPlatform } from "../platform/web.ts";
+import type { Surface } from "../platform/types.ts";
+import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
+import {
+  MCP_APPS_STYLE_VARIABLES,
+  PORTHOLE_STYLES,
+  type HostContext,
+} from "../protocol/mcp-apps.ts";
+import { shellAdapter } from "../protocol/shell-adapter.ts";
+import { resolveTheme } from "../theme/variables.ts";
+import type {
+  DisplayEvents,
+  DisplayHandle,
+  HostOptions,
+  MountOptions,
+  PortholeHost,
+} from "./types.ts";
+
+/** How many times a display is started again after its content navigated its frame away. */
+const MAX_RESTARTS = 3;
+
+const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
+const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
+
+/**
+ * Compiles `config` once and returns a host that mounts displays under it. Throws a `ConfigError`
+ * for a bad config.
+ */
+export function createHost<C extends AdapterConnection = ShellConnection>(
+  config: PortholeConfig,
+  options: HostOptions<C> = {},
+): PortholeHost<C> {
+  const compiled = compile(config);
+  if (
+    (config.isolation === "domain" || config.isolation === "external") &&
+    options.locator === undefined
+  ) {
+    throw new TypeError(`${config.isolation} isolation needs a locator (HostOptions.locator)`);
+  }
+  // A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
+  const speaks = config.mode !== "url";
+  const adapter = (options.adapter ?? shellAdapter) as ProtocolAdapter<C>;
+  const platform = options.platform ?? webPlatform;
+  const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
+
+  return {
+    compiled,
+    mount(container: HTMLElement, mount: MountOptions): DisplayHandle<C> {
+      const handlers = { ...options.handlers, ...mount.handlers };
+      const missing = declaredCapabilities(config).filter(
+        (name) =>
+          capabilitySpec(name).served === "handler" &&
+          (handlers as Record<string, unknown>)[name] === undefined,
+      );
+      if (missing.length > 0) {
+        throw new TypeError(`No handler for the declared capabilities: ${missing.join(", ")}`);
+      }
+      if (config.isolation !== "opaque" && mount.instance === undefined) {
+        throw new TypeError(`${config.isolation} isolation needs MountOptions.instance`);
+      }
+
+      const listeners = new Map<keyof DisplayEvents, Set<(detail: never) => void>>();
+      const emit = <E extends keyof DisplayEvents>(event: E, detail: DisplayEvents[E]) => {
+        for (const listener of listeners.get(event) ?? []) {
+          (listener as (detail: DisplayEvents[E]) => void)(detail);
+        }
+      };
+
+      let scheme: ColorScheme = mount.scheme;
+      let height = mount.initialHeightPx ?? 0;
+      let surface: Surface | null = null;
+      let connection: C | null = null;
+      let destroyed = false;
+      let restarts = 0;
+      let generation = 0;
+      let abort: AbortController | null = null;
+      // The adapter's own operations, the last call of each, replayed into every new frame.
+      const replay = new Map<string, unknown[]>();
+
+      const hostContext = (): HostContext => {
+        const width = container.getBoundingClientRect().width;
+        const view = container.ownerDocument.defaultView;
+        // The spec's names in `styles` (the App SDK refuses others there), the rest in our field.
+        const variables = resolveTheme(config.theme, scheme, options.theme?.(scheme));
+        const standard: Record<string, string> = {};
+        const own: Record<string, string> = {};
+        for (const [name, value] of Object.entries(variables)) {
+          (STANDARD.has(name) ? standard : own)[name] = value;
+        }
+        return {
+          theme: scheme,
+          styles: { variables: standard },
+          ...(Object.keys(own).length === 0 ? {} : { [PORTHOLE_STYLES]: { variables: own } }),
+          displayMode: "inline",
+          availableDisplayModes: ["inline"],
+          ...(width > 0 ? { containerDimensions: { maxWidth: Math.round(width) } } : {}),
+          ...(view === null
+            ? {}
+            : {
+                locale: view.navigator.language,
+                timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+                platform: "web" as const,
+              }),
+          ...options.hostContext?.(),
+        };
+      };
+
+      const onBridge = (event: BridgeEvent) => {
+        switch (event.type) {
+          case "resize": {
+            const next = Math.min(
+              config.limits.maxHeightPx,
+              Math.max(config.limits.minHeightPx, Math.ceil(event.height)),
+            );
+            height = next;
+            surface?.setHeight(next);
+            emit("resize", {
+              height: next,
+              ...(event.width === undefined ? {} : { width: event.width }),
+            });
+            return;
+          }
+          case "error":
+            emit("error", { message: event.message });
+            return;
+          case "refused":
+            emit("refused", { capability: event.capability, refusal: event.refusal });
+            return;
+          case "muted":
+            emit("muted", undefined);
+            return;
+        }
+      };
+
+      const stop = () => {
+        abort?.abort();
+        abort = null;
+        connection?.close();
+        connection = null;
+        surface?.destroy();
+        surface = null;
+      };
+
+      const start = (source: FrameSource) => {
+        const created = platform.createSurface(container, {
+          source,
+          title: mount.title,
+          sandbox: compiled.sandbox,
+          allow: compiled.allow,
+          referrerPolicy: compiled.referrerPolicy,
+          colorScheme: scheme,
+          initialHeightPx: height,
+        });
+        surface = created;
+        if (!speaks) {
+          return;
+        }
+        const bridge = createBridge({
+          config,
+          display: { id: mount.displayId, title: mount.title },
+          handlers,
+          ...(options.confirm === undefined ? {} : { confirm: options.confirm }),
+          userActivation: () => created.userActivation(),
+          onEvent: onBridge,
+        });
+        const opened = adapter.connect({
+          display: { id: mount.displayId, title: mount.title },
+          compiled,
+          transport: created.transport,
+          bridge,
+          hostInfo,
+          hostContext,
+          emit: (event) => {
+            if (event.type === "initialized") {
+              emit("initialized", undefined);
+            }
+          },
+          ...(mount.document === undefined ? {} : { document: mount.document }),
+        });
+        connection = opened;
+        for (const [name, args] of replay) {
+          (opened as unknown as Record<string, (...each: unknown[]) => unknown>)[name]?.(...args);
+        }
+        created.onNavigated(() => {
+          emit("navigated", undefined);
+          if (restarts < MAX_RESTARTS) {
+            restarts += 1;
+            run();
+          } else {
+            stop();
+            emit("error", {
+              message: "The content kept navigating its frame away; it was stopped.",
+            });
+          }
+        });
+      };
+
+      const run = () => {
+        stop();
+        if (destroyed) {
+          return;
+        }
+        generation += 1;
+        if (config.isolation === "opaque") {
+          start({
+            kind: "srcdoc",
+            html: compiled.shellDocument({
+              origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
+              title: mount.title,
+              ...(mount.document === undefined ? {} : { document: mount.document }),
+            }),
+          });
+          return;
+        }
+        const mine = generation;
+        const controller = new AbortController();
+        abort = controller;
+        const locator = options.locator;
+        const instance = mount.instance;
+        if (locator === undefined || instance === undefined) {
+          return;
+        }
+        const hostOrigin = container.ownerDocument.defaultView?.location.origin ?? "";
+        locateServed(locator, instance, config, hostOrigin, controller.signal).then(
+          (source) => {
+            if (mine === generation && !destroyed) {
+              start(source);
+            }
+          },
+          (error: unknown) => {
+            if (mine === generation && !controller.signal.aborted) {
+              emit("error", { message: error instanceof Error ? error.message : String(error) });
+            }
+          },
+        );
+      };
+
+      run();
+
+      const controls = {
+        displayId: mount.displayId,
+        setTheme(next: ColorScheme) {
+          scheme = next;
+          surface?.setColorScheme(next);
+          connection?.hostContextChanged(hostContext());
+        },
+        on<E extends keyof DisplayEvents>(event: E, listener: (detail: DisplayEvents[E]) => void) {
+          const set = listeners.get(event) ?? new Set();
+          set.add(listener);
+          listeners.set(event, set);
+          return () => set.delete(listener);
+        },
+        reload() {
+          restarts = 0;
+          run();
+        },
+        destroy() {
+          destroyed = true;
+          stop();
+          listeners.clear();
+        },
+      };
+
+      // The adapter's own operations (`setContent` for the shell adapter): forwarded to the frame
+      // running now, and remembered (the last call of each) for a frame started again.
+      return new Proxy(controls, {
+        get(target, key, receiver) {
+          if (typeof key === "string" && !(key in target) && !BASE_KEYS.has(key)) {
+            return (...args: unknown[]) => {
+              replay.delete(key);
+              replay.set(key, args);
+              const operation = (connection as unknown as Record<string, unknown> | null)?.[key];
+              return typeof operation === "function"
+                ? (operation as (...each: unknown[]) => unknown).apply(connection, args)
+                : undefined;
+            };
+          }
+          return Reflect.get(target, key, receiver);
+        },
+      }) as unknown as DisplayHandle<C>;
+    },
+  };
+}

package/src/host/locate.ts

@@ -0,0 +1,20 @@
+import type { PortholeConfig } from "../config/schema.ts";
+import { checkFrameLocation } from "../isolation/served.ts";
+import type { FrameSource, InstanceLocator, InstanceRef } from "../isolation/types.ts";
+
+/**
+ * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
+ * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
+ * own site) before any frame is made.
+ */
+export async function locateServed(
+  locator: InstanceLocator,
+  instance: InstanceRef,
+  config: PortholeConfig,
+  hostOrigin: string,
+  signal?: AbortSignal,
+): Promise<FrameSource> {
+  const location = await locator.locate(instance, signal);
+  checkFrameLocation(location, config.contentOrigins, hostOrigin);
+  return { kind: "url", url: new URL(location.url).href, origin: location.origin };
+}

package/src/host/types.ts

@@ -0,0 +1,95 @@
+import type { Confirm, CapabilityHandlers, Refusal } from "../bridge/types.ts";
+import type { CompiledConfig } from "../compile/compile.ts";
+import type { CapabilityName } from "../config/capabilities.ts";
+import type { ColorScheme } from "../config/schema.ts";
+import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
+import type { PlatformHost } from "../platform/types.ts";
+import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
+import type { HostContext } from "../protocol/mcp-apps.ts";
+
+/**
+ * The host-side API (framework-agnostic; the web platform by default). A host compiles a config
+ * once (`createHost`), then mounts a display per piece of content. Everything here is mechanism;
+ * the host passes policy: its handlers, who confirms, its theme values.
+ */
+
+export interface HostOptions<C extends AdapterConnection = ShellConnection> {
+  /** Handlers for the declared capabilities; a mount may pass its own over these. */
+  readonly handlers?: CapabilityHandlers;
+  /** Who confirms `confirm`-gated calls. Absent: those calls are refused. */
+  readonly confirm?: Confirm;
+  /**
+   * The host's live values for the config's theme variables, for `scheme` (read from its own
+   * design tokens). A name it leaves out, or answers empty, gets the config's default.
+   */
+  readonly theme?: (scheme: ColorScheme) => Readonly<Record<string, string | null | undefined>>;
+  /** The host's own context fields (locale, time zone, platform): merged into the host context. */
+  readonly hostContext?: () => Partial<HostContext>;
+  /** How the host names itself in the handshake. */
+  readonly hostInfo?: { readonly name: string; readonly version: string };
+  /** The protocol adapter. Default: the core's shell adapter (inline and artifact modes). */
+  readonly adapter?: ProtocolAdapter<C>;
+  /** The platform host. Default: the web's iframe host. */
+  readonly platform?: PlatformHost;
+  /** Required for domain and external isolation: where an instance's frame loads from. */
+  readonly locator?: InstanceLocator;
+}
+
+export interface MountOptions {
+  /** The host's id for this display: what its height is remembered by, and calls name. */
+  readonly displayId: string;
+  /** The display's accessible name and the title its confirmations show (the host's words). */
+  readonly title: string;
+  readonly scheme: ColorScheme;
+  /** Handlers for this display only, over the host's. */
+  readonly handlers?: CapabilityHandlers;
+  /** Domain and external isolation: the instance to locate. */
+  readonly instance?: InstanceRef;
+  /** A whole document the frame starts with (an MCP Apps view), hardened by the shell. */
+  readonly document?: string;
+  /** The height to start at, before the content reports its own. */
+  readonly initialHeightPx?: number;
+}
+
+/** What a display reports, by event name. */
+export interface DisplayEvents {
+  /** The frame finished its handshake. */
+  readonly initialized: undefined;
+  /** The content's size, after the config's limits. */
+  readonly resize: { readonly height: number; readonly width?: number };
+  /** What the content threw, or what the sandbox blocked (its own words: untrusted). */
+  readonly error: { readonly message: string };
+  /** The content navigated its frame away; the frame was started again from its content. */
+  readonly navigated: undefined;
+  /** A call didn't run. */
+  readonly refused: { readonly capability: CapabilityName; readonly refusal: Refusal };
+  /** Too many declines: the display stops asking until it runs again. */
+  readonly muted: undefined;
+}
+
+export interface DisplayControls {
+  readonly displayId: string;
+  /** The theme flipped: the frame is re-themed in place, without a reload. */
+  setTheme(scheme: ColorScheme): void;
+  on<E extends keyof DisplayEvents>(
+    event: E,
+    listener: (detail: DisplayEvents[E]) => void,
+  ): () => void;
+  /** Runs the content again from the start, in a new frame. */
+  reload(): void;
+  /** Tears the view down and removes the frame. */
+  destroy(): void;
+}
+
+/** A mounted display: the framework's controls plus the adapter's own operations. */
+export type DisplayHandle<C extends AdapterConnection = ShellConnection> = DisplayControls &
+  Omit<C, keyof AdapterConnection>;
+
+export interface PortholeHost<C extends AdapterConnection = ShellConnection> {
+  readonly compiled: CompiledConfig;
+  /**
+   * Creates a display in `container`. Throws if a declared capability served by a handler has
+   * none (here or in the host's options), so a manual never teaches a function nobody serves.
+   */
+  mount(container: HTMLElement, options: MountOptions): DisplayHandle<C>;
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+/**
+ * `@botiverse/porthole`: the framework-agnostic core. One config (a preset's) compiles into the
+ * frame's policies, the shell, and the agent manual; the host mounts displays under it.
+ */
+
+// The config and its vocabulary.
+export {
+  CAPABILITIES,
+  CAPABILITY_NAMES,
+  capabilitySpec,
+  isCapabilityName,
+  type CapabilityArgs,
+  type CapabilityName,
+  type CapabilityResults,
+  type CapabilitySpec,
+  type Gate,
+  type HandledCapability,
+} from "./config/capabilities.ts";
+export type {
+  CapabilityConfig,
+  CapabilityMap,
+  ColorScheme,
+  DisplayMode,
+  EgressConfig,
+  EmbedderConfig,
+  GuideConfig,
+  IsolationKind,
+  LayoutConfig,
+  Limits,
+  PortholeConfig,
+  ThemeConfig,
+  ThemeValue,
+} from "./config/schema.ts";
+export { BUILT_IN_TOPICS, ConfigError, isOriginSource, validateConfig } from "./config/validate.ts";
+
+// Presets.
+export {
+  LIBRARY_CDNS,
+  presets,
+  type PresetName,
+  type PresetOptions,
+  type UrlPresetOptions,
+} from "./presets/presets.ts";
+
+// The compiler.
+export { compile, type CompiledConfig } from "./compile/compile.ts";
+export {
+  allEgressOrigins,
+  declaredCapabilities,
+  effectiveGates,
+  egressOrigins,
+  embedderCsp,
+  type CspDirective,
+  type EgressKind,
+} from "./compile/policy.ts";
+export { shellPlan, type ShellPlan } from "./shell/plan.ts";
+export type { ShellDocumentOptions } from "./shell/document.ts";
+export {
+  generateGuide,
+  generateToolDescription,
+  type BuiltInTopic,
+  type GuideTopic,
+} from "./guide/guide.ts";
+export { GUIDE_EXAMPLES, type GuideExample } from "./guide/examples.ts";
+
+// Theme.
+export {
+  CHART_PALETTE,
+  DEFAULT_THEME,
+  DEFAULT_THEME_EVENT,
+  DEFAULT_THEME_VARIABLES,
+  resolveTheme,
+  themeDefault,
+} from "./theme/variables.ts";
+
+// The seams: isolation, platform, transport, protocol, bridge, host.
+export type {
+  FrameLocation,
+  FrameSource,
+  InstanceLocator,
+  InstanceRef,
+  ServedDocument,
+} from "./isolation/types.ts";
+export type { PlatformHost, Surface, SurfaceSpec } from "./platform/types.ts";
+export type { Transport } from "./transport/types.ts";
+export type {
+  AdapterConnection,
+  AdapterEvent,
+  AdapterSession,
+  ProtocolAdapter,
+  ShellConnection,
+} from "./protocol/adapter.ts";
+export {
+  MCP_APPS_METHODS,
+  MCP_APPS_PROTOCOL_VERSION,
+  MCP_APPS_STYLE_VARIABLES,
+  PORTHOLE_STYLES,
+  type HostContext,
+} from "./protocol/mcp-apps.ts";
+export type {
+  CallContext,
+  CallOutcome,
+  CapabilityHandler,
+  CapabilityHandlers,
+  Confirm,
+  ConfirmRequest,
+  HostFunctionBridge,
+  Refusal,
+} from "./bridge/types.ts";
+export { createHost } from "./host/create-host.ts";
+export type {
+  DisplayControls,
+  DisplayEvents,
+  DisplayHandle,
+  HostOptions,
+  MountOptions,
+  PortholeHost,
+} from "./host/types.ts";

package/src/isolation/served.ts

@@ -0,0 +1,127 @@
+import type { FrameLocation } from "./types.ts";
+
+/**
+ * Checks for served frames (domain and external isolation), shared by the host's mount and by
+ * `/server`: a served origin must be one the config names, and never of the host's own site
+ * (P016, P020). Pure, no DOM and no Node, so both sides run the same code.
+ */
+
+const EXACT_ORIGIN = /^(https?):\/\/([a-z0-9.-]+|\[[0-9a-f:.]+\])(?::(\d{1,5}))?$/u;
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/u;
+
+interface ParsedOrigin {
+  readonly scheme: string;
+  readonly host: string;
+  readonly port: string;
+}
+
+const DEFAULT_PORTS: Readonly<Record<string, string>> = { http: "80", https: "443" };
+
+/** `scheme://host[:port]`, lowercase, nothing else; null for anything that isn't exactly that. */
+export function parseOrigin(origin: string): ParsedOrigin | null {
+  const match = EXACT_ORIGIN.exec(origin);
+  if (match === null) {
+    return null;
+  }
+  const [, scheme = "", host = "", port] = match;
+  return { scheme, host, port: port ?? DEFAULT_PORTS[scheme] ?? "" };
+}
+
+/** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
+export function isExactOrigin(origin: unknown): origin is string {
+  return typeof origin === "string" && parseOrigin(origin) !== null;
+}
+
+/**
+ * Whether two hosts may be the same site. Without the public-suffix list this errs one way only:
+ * it says "same site" whenever the hosts are equal or share their last two labels, so a pair it
+ * calls cross-site always is (a refused pair, like `a.github.io` and `b.github.io`, may not be:
+ * a safe failure). An IP address is a site of its own; `localhost`'s subdomains are each one, as
+ * browsers treat an unlisted top-level name as a public suffix.
+ */
+export function maybeSameSite(hostA: string, hostB: string): boolean {
+  const a = hostA.toLowerCase().replace(/\.$/u, "");
+  const b = hostB.toLowerCase().replace(/\.$/u, "");
+  if (a === b) {
+    return true;
+  }
+  if (IPV4.test(a) || IPV4.test(b) || a.startsWith("[") || b.startsWith("[")) {
+    return false;
+  }
+  const labelsA = a.split(".").toReversed();
+  const labelsB = b.split(".").toReversed();
+  let shared = 0;
+  while (
+    shared < labelsA.length &&
+    shared < labelsB.length &&
+    labelsA[shared] === labelsB[shared]
+  ) {
+    shared += 1;
+  }
+  return shared >= 2;
+}
+
+/**
+ * Whether `origin` matches a frame source as the config writes them (`https://*.example.com`,
+ * `http://*.localhost:8790`, or an exact origin): same scheme and port; `*.` matches one or more
+ * labels below the name, never the name itself.
+ */
+export function originMatchesSource(origin: string, source: string): boolean {
+  const parsed = parseOrigin(origin);
+  const wildcard = /^(https?):\/\/\*\.([a-z0-9.-]+)(?::(\d{1,5}))?$/u.exec(source);
+  if (parsed === null) {
+    return false;
+  }
+  if (wildcard === null) {
+    const exact = parseOrigin(source);
+    return (
+      exact !== null &&
+      exact.scheme === parsed.scheme &&
+      exact.host === parsed.host &&
+      exact.port === parsed.port
+    );
+  }
+  const [, scheme = "", suffix = "", port] = wildcard;
+  return (
+    scheme === parsed.scheme &&
+    (port ?? DEFAULT_PORTS[scheme]) === parsed.port &&
+    parsed.host.endsWith(`.${suffix}`) &&
+    parsed.host.length > suffix.length + 1
+  );
+}
+
+/**
+ * Throws unless `location` is a frame a host on `hostOrigin` may load for a config whose content
+ * is served from `contentOrigins`: its URL is on its stated origin, that origin is one the config
+ * names, and it is not of the host's own site (a same-site frame with `allow-same-origin` could
+ * reach cookies and storage the host shares with its site).
+ */
+export function checkFrameLocation(
+  location: FrameLocation,
+  contentOrigins: readonly string[],
+  hostOrigin: string,
+): void {
+  const origin = parseOrigin(location.origin);
+  let url: URL;
+  try {
+    url = new URL(location.url);
+  } catch {
+    throw new TypeError(`The located URL ${JSON.stringify(location.url)} is not a URL`);
+  }
+  if (origin === null || url.origin !== location.origin) {
+    throw new TypeError(
+      `The located URL ${JSON.stringify(location.url)} is not on its origin ${JSON.stringify(location.origin)}`,
+    );
+  }
+  if (!contentOrigins.some((source) => originMatchesSource(location.origin, source))) {
+    throw new TypeError(
+      `The located origin ${location.origin} is not one of the config's content origins`,
+    );
+  }
+  const host = parseOrigin(hostOrigin);
+  if (host !== null && maybeSameSite(origin.host, host.host)) {
+    throw new TypeError(
+      `The located origin ${location.origin} may be the same site as the host (${hostOrigin}): content must be served from a registrable domain the host uses for nothing else`,
+    );
+  }
+}