@botiverse/porthole 0.0.1 → 0.1.1

package/src/index.ts

@@ -0,0 +1,128 @@
+/**
+ * `@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,
+  originSourceProblem,
+  validateConfig,
+} from "./config/validate.ts";
+export { URL_SANDBOX_EXTRAS, type UrlSandboxExtra } from "./config/schema.ts";
+export { hostOriginProblem, isHostOrigin } from "./isolation/served.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,
+  ConfirmAnswer,
+  ConfirmRequest,
+  Proceed,
+  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,151 @@
+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;
+}
+
+/**
+ * A host page's origin, exactly as `location.origin` and a message's `event.origin` give it:
+ * `scheme://host[:port]`, lowercase, any scheme (an Electron or Tauri app's own registered scheme,
+ * `ferry://app`, `app://local`), never `"null"` (an opaque origin isn't one origin: every opaque
+ * page says "null") and never a path. The shell takes messages only from these, exactly.
+ */
+const HOST_ORIGIN =
+  /^[a-z][a-z0-9+.-]*:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*|\[[0-9a-f:.]+\])(:\d{1,5})?$/u;
+
+export function isHostOrigin(origin: unknown): origin is string {
+  return typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
+}
+
+/** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
+export function hostOriginProblem(origin: unknown): string | null {
+  if (isHostOrigin(origin)) {
+    return null;
+  }
+  if (origin === "null") {
+    return 'the host page\'s origin is opaque ("null"): serve it from a real origin (an Electron custom protocol must be registered as standard, and file: pages have none)';
+  }
+  return `${JSON.stringify(origin)} is not an exact origin (scheme://host[:port], lowercase, no path)`;
+}
+
+/**
+ * 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`,
+    );
+  }
+}

package/src/isolation/types.ts

@@ -0,0 +1,91 @@
+/**
+ * The isolation-mode seam. Opaque frames need nothing from outside: the host builds the shell
+ * document and the frame is `srcdoc`. Served modes (domain, and url mode's external app) load a
+ * URL, so the host asks a locator for one; the locator is the host's own code, typically a call to
+ * the host's backend, which asks `/server` for a ticketed URL after deciding the viewer may see it.
+ *
+ * Storage is keyed by origin. In domain mode each storage scope gets its own subdomain of the
+ * content domain (`<label>.example-usercontent.com`, the label derived from the scope by `/server`,
+ * not guessable from it), so content with the same scope shares an origin and its storage and
+ * nothing else does. The host chooses the scope (PRINCIPLE 8): per display, per conversation, per
+ * app. Browsers partition a framed origin's storage by the top-level site, so it is stable within
+ * one host app.
+ */
+import type { EgressConfig } from "../config/schema.ts";
+
+/**
+ * Which document a served frame loads. `preset` names the config it is served under (the server's
+ * `configs`); the artifact and the proxy default to their presets' names.
+ */
+export type ServedDocument =
+  /** The shell, served with its CSP in headers; content arrives over the transport as for opaque. */
+  | { readonly kind: "shell"; readonly preset: string }
+  /** A stored page (artifact mode), by id and version: versions are immutable. */
+  | {
+      readonly kind: "artifact";
+      readonly id: string;
+      readonly version: string;
+      /** Default `artifact`. */
+      readonly preset?: string;
+    }
+  /**
+   * The MCP Apps sandbox proxy: a second origin the host hands the view's HTML to, which becomes
+   * the view. `egress` is what the view declares (`_meta.ui.csp`, mapped by `/mcp`'s
+   * `viewEgress`), opened on top of the config's: its CSP goes out in the proxy's headers, before
+   * the HTML arrives.
+   */
+  | { readonly kind: "mcp-proxy"; readonly preset?: string; readonly egress?: EgressConfig }
+  /**
+   * Someone else's running app (url mode), e.g. a dev server behind the host's preview gateway:
+   * `url` is where the host's upstream finds it; the frame lands on its path and query.
+   */
+  | { readonly kind: "external"; readonly url: string };
+
+/** One served instance: where its storage lives, and what it shows. */
+export interface InstanceRef {
+  /**
+   * What the content's origin, and so its storage, is keyed by. Instances with the same scope
+   * share an origin. Opaque to Porthole: the host picks it (a display id, an app id).
+   */
+  readonly scope: string;
+  readonly document: ServedDocument;
+}
+
+/** Where a served frame loads from. */
+export interface FrameLocation {
+  /** The URL the frame loads, carrying a one-time ticket where the content is private. */
+  readonly url: string;
+  /** Its origin: the host takes messages only from this origin, from this frame. */
+  readonly origin: string;
+  /**
+   * Whether the pages there report how loading went (`porthole/notifications/frame-status`):
+   * Porthole's `/server` does, so a page that never ran (refused framing) can be told apart from
+   * one that loaded. A host's own gateway may send the same message without this.
+   */
+  readonly reports?: boolean;
+}
+
+/** The message a served page sends its host about loading (own-prefixed, P040). */
+export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
+
+/**
+ * Turns an instance into the URL its frame loads. Implemented by the host, usually by asking its
+ * own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called on every
+ * mount: a ticket is good once.
+ */
+export interface InstanceLocator {
+  locate(instance: InstanceRef, signal?: AbortSignal): Promise<FrameLocation>;
+}
+
+/**
+ * Where a frame's document comes from: built by the host (`srcdoc`, opaque isolation), or loaded
+ * from a URL (domain and external isolation).
+ */
+export type FrameSource =
+  | { readonly kind: "srcdoc"; readonly html: string }
+  | {
+      readonly kind: "url";
+      readonly url: string;
+      readonly origin: string;
+      readonly reports?: boolean;
+    };