@tonyclaw/agent-inspector 3.0.45 → 3.0.47

package/src/proxy/identityProxy.ts

@@ -2,12 +2,22 @@ import http from "node:http";
 import { Buffer } from "node:buffer";
 import { createHash, timingSafeEqual } from "node:crypto";
 import { isIP } from "node:net";
+import {
+  BROWSER_RUNTIME_JSON_PLACEHOLDER,
+  BROWSER_RUNTIME_SCHEMA_VERSION,
+  type BrowserRuntimeDeployment,
+} from "../lib/browserRuntimeContract";
+import {
+  AGENT_INSPECTOR_BACKEND_HEADER,
+  type BackendImplementation,
+} from "../lib/backendImplementation";
 import {
   AGENT_INSPECTOR_BASE_PATH_META_NAME,
   AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER,
+  AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER,
   AGENT_INSPECTOR_PUBLIC_PORT_HEADER,
   getConfiguredBasePath,
-  normalizeBasePath,
+  normalizePublicBasePath,
   stripBasePath,
   stripBasePathFromRequestPath,
   withBasePath,
@@ -18,6 +28,7 @@ import {
   MANAGED_INSTANCE_TOKEN_HEADER,
 } from "../lib/managedInstance";
 import { lookupClientByPort } from "./socketTracker";
+import { loadUiAsset } from "./uiAssetServer";
 
 const IDENTITY_HEADERS = {
   pid: "x-agent-inspector-client-pid",
@@ -32,6 +43,8 @@ const CSRF_HEADER = "x-agent-inspector-csrf";
 const DEFAULT_MAX_REQUEST_BYTES = 64 * 1024 * 1024;
 const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 const ALIAS_CONTROL_MAX_REQUEST_BYTES = 8 * 1024;
+const INSTANCE_API_MAX_REQUEST_BYTES = 64 * 1024;
+const LOCAL_CONTROL_MAX_RESPONSE_BYTES = 1024 * 1024;
 
 export const IDENTITY_PROXY_CONTROL_NAMESPACE = "/.agent-inspector";
 export const IDENTITY_PROXY_ALIAS_CONTROL_PATH = `${IDENTITY_PROXY_CONTROL_NAMESPACE}/base-path-aliases`;
@@ -61,26 +74,19 @@ export type BasePathAliasRegistry = {
 function normalizedAliasCandidate(
   value: string,
 ): { ok: true; basePath: string } | { ok: false; code: "invalid" | "reserved"; error: string } {
-  const normalized = normalizeBasePath(value);
-  if (normalized.length === 0) {
-    return {
-      ok: false,
-      code: "invalid",
-      error: "Base Path aliases must be non-root paths such as /inspector.",
-    };
-  }
-  if (!/^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/u.test(normalized)) {
+  const normalized = normalizePublicBasePath(value);
+  if (normalized === null) {
     return {
       ok: false,
       code: "invalid",
       error: "Base Path aliases may contain only URL-safe path segments.",
     };
   }
-  if (normalized.split("/").some((segment) => segment === "." || segment === "..")) {
+  if (normalized.length === 0) {
     return {
       ok: false,
       code: "invalid",
-      error: "Base Path aliases cannot contain dot path segments.",
+      error: "Base Path aliases must be non-root paths such as /inspector.",
     };
   }
   if (
@@ -122,7 +128,7 @@ export function createBasePathAliasRegistry(
   canonicalBasePath: string,
   initialAliases: readonly string[] = [],
 ): BasePathAliasRegistry {
-  const canonical = normalizeBasePath(canonicalBasePath);
+  const canonical = normalizePublicBasePath(canonicalBasePath) ?? "";
   const aliases: string[] = [];
 
   const add = (value: string): BasePathAliasMutationResult => {
@@ -278,8 +284,9 @@ function rewriteRootRelativePublicPath(
   sourceBasePath: string,
 ): string {
   if (!value.startsWith("/") || value.startsWith("//")) return value;
-  const normalizedEffective = normalizeBasePath(effectiveBasePath);
-  const normalizedSource = normalizeBasePath(sourceBasePath);
+  const normalizedEffective = normalizePublicBasePath(effectiveBasePath);
+  const normalizedSource = normalizePublicBasePath(sourceBasePath);
+  if (normalizedEffective === null || normalizedSource === null) return value;
   const suffixIndex = value.search(/[?#]/u);
   const pathname = suffixIndex === -1 ? value : value.slice(0, suffixIndex);
   const suffix = suffixIndex === -1 ? "" : value.slice(suffixIndex);
@@ -299,11 +306,15 @@ function rewriteQuotedAssetPaths(
   source: string,
   effectiveBasePath: string,
   sourceBasePath: string,
+  escape: (value: string, quote: string) => string,
 ): string {
   return source.replace(
     /(["'])(\/(?:[^"'/]+\/)*assets\/)/gu,
     (_match: string, quote: string, assetPrefix: string) =>
-      `${quote}${rewriteRootRelativePublicPath(assetPrefix, effectiveBasePath, sourceBasePath)}`,
+      `${quote}${escape(
+        rewriteRootRelativePublicPath(assetPrefix, effectiveBasePath, sourceBasePath),
+        quote,
+      )}`,
   );
 }
 
@@ -312,7 +323,9 @@ export function rewriteHtmlForBasePath(
   basePath: string,
   sourceBasePath = "",
 ): string {
-  const normalized = normalizeBasePath(basePath);
+  const normalized = normalizePublicBasePath(basePath);
+  const normalizedSource = normalizePublicBasePath(sourceBasePath);
+  if (normalized === null || normalizedSource === null) return html;
   const escaped = htmlAttributeEscape(normalized);
   const meta = `<meta name="${AGENT_INSPECTOR_BASE_PATH_META_NAME}" content="${escaped}">`;
   const metaPattern = new RegExp(
@@ -331,13 +344,26 @@ export function rewriteHtmlForBasePath(
   const withRewrittenAttributes = withMeta.replace(
     /\b(href|src|action)=(["'])(\/(?!\/)[^"']*)\2/giu,
     (_match: string, attribute: string, quote: string, path: string) =>
-      `${attribute}=${quote}${rewriteRootRelativePublicPath(path, normalized, sourceBasePath)}${quote}`,
+      `${attribute}=${quote}${htmlAttributeEscape(
+        rewriteRootRelativePublicPath(path, normalized, normalizedSource),
+      )}${quote}`,
+  );
+  return rewriteQuotedAssetPaths(withRewrittenAttributes, normalized, normalizedSource, (value) =>
+    htmlAttributeEscape(value),
   );
-  return rewriteQuotedAssetPaths(withRewrittenAttributes, normalized, sourceBasePath);
 }
 
-function javaScriptStringEscape(value: string): string {
-  return value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"');
+function javaScriptStringEscape(value: string, quote: string): string {
+  const escaped = value
+    .replace(/\\/gu, "\\\\")
+    .replace(/\r/gu, "\\r")
+    .replace(/\n/gu, "\\n")
+    .replace(/\u2028/gu, "\\u2028")
+    .replace(/\u2029/gu, "\\u2029")
+    .replace(/&/gu, "\\u0026")
+    .replace(/</gu, "\\u003c")
+    .replace(/>/gu, "\\u003e");
+  return quote === "'" ? escaped.replace(/'/gu, "\\'") : escaped.replace(/"/gu, '\\"');
 }
 
 export function rewriteJavaScriptForBasePath(
@@ -345,25 +371,123 @@ export function rewriteJavaScriptForBasePath(
   basePath: string,
   sourceBasePath = "",
 ): string {
-  const normalized = normalizeBasePath(basePath);
-  const escaped = javaScriptStringEscape(normalized);
+  const normalized = normalizePublicBasePath(basePath);
+  const normalizedSource = normalizePublicBasePath(sourceBasePath);
+  if (normalized === null || normalizedSource === null) return source;
+  const escaped = javaScriptStringEscape(normalized, '"');
   const withRouterBasePath = source.replace(
     /\bbasepath:\s*(["'])[^"']*\1/gu,
     `basepath:"${escaped}"`,
   );
   const withDynamicPaths = withRouterBasePath.replace(
     /return(["'])(\/(?!\/)[^"']*)\1\+([A-Za-z_$][\w$]*)/gu,
-    (_match: string, quote: string, path: string, variable: string) =>
-      `return${quote}${rewriteRootRelativePublicPath(
-        path,
-        normalized,
-        sourceBasePath,
-      )}${quote}+${variable}`,
+    (_match: string, quote: string, path: string, variable: string) => {
+      const rewritten = rewriteRootRelativePublicPath(path, normalized, normalizedSource);
+      return `return${quote}${javaScriptStringEscape(rewritten, quote)}${quote}+${variable}`;
+    },
+  );
+  return rewriteQuotedAssetPaths(
+    withDynamicPaths,
+    normalized,
+    normalizedSource,
+    javaScriptStringEscape,
   );
-  return rewriteQuotedAssetPaths(withDynamicPaths, normalized, sourceBasePath);
+}
+
+function publicOriginForRequest(req: http.IncomingMessage, options: IdentityProxyOptions): string {
+  if (options.publicOrigin !== undefined) {
+    try {
+      return new URL(options.publicOrigin).origin;
+    } catch {
+      // Invalid explicit values are rejected by the CLI; retain a safe local fallback for embedders.
+    }
+  }
+  return `http://${req.headers.host ?? "localhost"}`;
+}
+
+function browserRuntimeForRequest(
+  req: http.IncomingMessage,
+  options: IdentityProxyOptions,
+  basePath: string,
+): BrowserRuntimeDeployment {
+  const origin = publicOriginForRequest(req, options);
+  const normalized = normalizePublicBasePath(basePath) ?? "";
+  const baseUrl = normalized.length === 0 ? origin : `${origin}${normalized}`;
+  return {
+    schemaVersion: BROWSER_RUNTIME_SCHEMA_VERSION,
+    deploymentMode: "composed",
+    ui: { basePath: normalized.length === 0 ? "/" : normalized },
+    control: { baseUrl },
+    agent: { baseUrl },
+    capabilities: {
+      rest: true,
+      sse: true,
+      proxy: true,
+      mcp: true,
+    },
+  };
+}
+
+function safeInlineJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/&/gu, "\\u0026")
+    .replace(/</gu, "\\u003c")
+    .replace(/>/gu, "\\u003e")
+    .replace(/\u2028/gu, "\\u2028")
+    .replace(/\u2029/gu, "\\u2029");
+}
+
+function injectBrowserRuntime(html: string, runtime: BrowserRuntimeDeployment): string {
+  const runtimeJson = safeInlineJson(runtime);
+  if (html.includes(BROWSER_RUNTIME_JSON_PLACEHOLDER)) {
+    return html.replaceAll(BROWSER_RUNTIME_JSON_PLACEHOLDER, runtimeJson);
+  }
+  const bootstrap = `<script>window.__AGENT_INSPECTOR_RUNTIME__=${runtimeJson};</script>`;
+  return html.replace(/<head(\s[^>]*)?>/iu, (head) => `${head}${bootstrap}`);
+}
+
+async function tryServeUiAsset(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  options: IdentityProxyOptions,
+  pathname: string,
+  basePath: string,
+  sourceBasePath: string,
+): Promise<boolean> {
+  const method = (req.method ?? "GET").toUpperCase();
+  if ((method !== "GET" && method !== "HEAD") || options.uiDirectory === undefined) return false;
+  const asset = await loadUiAsset(options.uiDirectory, pathname);
+  if (asset === null) return false;
+  let body = asset.body;
+  if (asset.document) {
+    const rewritten = rewriteHtmlForBasePath(body.toString("utf8"), basePath, sourceBasePath);
+    body = Buffer.from(
+      injectBrowserRuntime(rewritten, browserRuntimeForRequest(req, options, basePath)),
+      "utf8",
+    );
+  } else if (basePath.length > 0 && asset.contentType.includes("javascript")) {
+    body = Buffer.from(
+      rewriteJavaScriptForBasePath(body.toString("utf8"), basePath, sourceBasePath),
+      "utf8",
+    );
+  }
+  const headers: Record<string, string | number> = {
+    ...BASE_SECURITY_HEADERS,
+    "cache-control": asset.cacheControl,
+    "content-length": body.byteLength,
+    "content-type": asset.contentType,
+  };
+  if (asset.document) headers["content-security-policy"] = DOCUMENT_CONTENT_SECURITY_POLICY;
+  res.writeHead(200, headers);
+  if (method === "HEAD") res.end();
+  else res.end(body);
+  req.resume();
+  return true;
 }
 
 export type IdentityProxyOptions = {
+  /** Backend child implementation supervised behind this protected ingress. */
+  backendImplementation?: BackendImplementation;
   /** Public port to listen on. Clients point at this. */
   listenPort: number;
   /** Interface exposed to clients. Defaults are chosen by the CLI. */
@@ -384,6 +508,12 @@ export type IdentityProxyOptions = {
   allowUnauthenticatedRemoteProxy?: boolean;
   /** Additional public hostnames accepted by the ingress Host boundary. */
   trustedHosts?: readonly string[];
+  /** Exact browser UI origins allowed to call control REST/SSE across origins. */
+  allowedUiOrigins?: readonly string[];
+  /** Independent static UI artifact directory served only by the protected ingress. */
+  uiDirectory?: string;
+  /** Explicit public origin for reverse-proxy deployments; never inferred from forwarded headers. */
+  publicOrigin?: string;
   /** Maximum declared or streamed request body size. */
   maxRequestBytes?: number;
   /** Deadline for receiving and forwarding one request body. */
@@ -392,9 +522,12 @@ export type IdentityProxyOptions = {
   aliasRegistry?: BasePathAliasRegistry;
   /** Private lifecycle identity exposed only to the owning local instance manager. */
   managedInstance?: ManagedInstanceControlOptions;
+  /** Optional Node-supervisor instance API retained when the selected backend is Rust. */
+  instanceApiHandler?: (request: Request) => Promise<Response>;
 };
 
 export type ManagedInstanceControlOptions = {
+  backend?: BackendImplementation;
   name: string;
   instanceId: string;
   launchId: string;
@@ -452,7 +585,52 @@ function normalizedHostname(value: string): string | null {
 }
 
 function isLoopbackHostname(hostname: string): boolean {
-  return hostname === "localhost" || hostname === "::1" || hostname.startsWith("127.");
+  if (hostname === "localhost" || hostname === "::1") return true;
+  if (isIP(hostname) !== 4) return false;
+  return hostname.split(".", 1)[0] === "127";
+}
+
+export type UiOriginAllowlist = {
+  origins: readonly string[];
+  rejected: readonly string[];
+};
+
+function parseUrl(value: string): URL | null {
+  try {
+    return new URL(value);
+  } catch {
+    return null;
+  }
+}
+
+export function parseUiOriginAllowlist(value: string | undefined): UiOriginAllowlist {
+  const origins: string[] = [];
+  const rejected: string[] = [];
+  for (const entry of (value ?? "").split(",")) {
+    const candidate = entry.trim();
+    if (candidate.length === 0) continue;
+    const parsed = parseUrl(candidate);
+    const valid =
+      parsed !== null &&
+      (parsed.protocol === "http:" || parsed.protocol === "https:") &&
+      parsed.username.length === 0 &&
+      parsed.password.length === 0 &&
+      parsed.pathname === "/" &&
+      parsed.search.length === 0 &&
+      parsed.hash.length === 0 &&
+      isLoopbackHostname(parsed.hostname.toLowerCase().replace(/^\[|\]$/gu, ""));
+    if (!valid || parsed === null) {
+      rejected.push(candidate);
+      continue;
+    }
+    if (!origins.includes(parsed.origin)) origins.push(parsed.origin);
+  }
+  return { origins, rejected };
+}
+
+function normalizeTrustedPublicOrigin(value: string | undefined): string | null | undefined {
+  if (value === undefined) return undefined;
+  return normalizedRequestOrigin(value.trim());
 }
 
 export function isTrustedIdentityProxyHost(
@@ -476,6 +654,111 @@ function isSafeMethod(method: string | undefined): boolean {
   return normalized === "GET" || normalized === "HEAD" || normalized === "OPTIONS";
 }
 
+const UI_CORS_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"] as const;
+const UI_CORS_HEADERS = ["authorization", "content-type", "last-event-id", CSRF_HEADER] as const;
+
+function normalizedRequestOrigin(origin: string): string | null {
+  try {
+    const parsed = new URL(origin);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    if (parsed.username.length > 0 || parsed.password.length > 0) return null;
+    if (parsed.pathname !== "/" || parsed.search.length > 0 || parsed.hash.length > 0) return null;
+    return parsed.origin;
+  } catch {
+    return null;
+  }
+}
+
+function isSameRequestOrigin(
+  origin: string,
+  host: string | undefined,
+  publicOrigin?: string,
+): boolean {
+  const parsedOrigin = normalizedRequestOrigin(origin);
+  if (parsedOrigin === null) return false;
+  const expected = normalizedRequestOrigin(publicOrigin ?? `http://${host ?? "localhost"}`);
+  return expected !== null && parsedOrigin === expected;
+}
+
+function matchedUiOrigin(
+  origin: string | undefined,
+  allowedUiOrigins: readonly string[] | undefined,
+): string | null {
+  if (origin === undefined) return null;
+  return (allowedUiOrigins ?? []).find((candidate) => candidate === origin) ?? null;
+}
+
+function isUiControlPath(pathname: string): boolean {
+  if (pathname === "/livez" || pathname === "/readyz") return true;
+  if (pathname === "/api/mcp") return false;
+  return pathname === "/api" || pathname.startsWith("/api/");
+}
+
+function isModelProxyPath(pathname: string): boolean {
+  return pathname === "/proxy" || pathname.startsWith("/proxy/");
+}
+
+function uiCorsHeaders(origin: string | null): Record<string, string> {
+  if (origin === null) return {};
+  return {
+    "access-control-allow-origin": origin,
+    "access-control-expose-headers": "Content-Disposition",
+    vary: "Origin",
+  };
+}
+
+function appendVaryHeader(existing: string | string[] | undefined, name: string): string {
+  const values = (Array.isArray(existing) ? existing.join(",") : (existing ?? ""))
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+  if (!values.some((value) => value.toLowerCase() === name.toLowerCase())) values.push(name);
+  return values.join(", ");
+}
+
+function requestedCorsHeaders(value: string | undefined): readonly string[] {
+  return (value ?? "")
+    .split(",")
+    .map((header) => header.trim().toLowerCase())
+    .filter((header) => header.length > 0);
+}
+
+function handleUiCorsPreflight(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  origin: string,
+): void {
+  const requestedMethod = firstHeader(req.headers["access-control-request-method"])?.toUpperCase();
+  const requestedHeaders = requestedCorsHeaders(
+    firstHeader(req.headers["access-control-request-headers"]),
+  );
+  const methodAllowed =
+    requestedMethod !== undefined && UI_CORS_METHODS.some((method) => method === requestedMethod);
+  const headersAllowed = requestedHeaders.every((header) =>
+    UI_CORS_HEADERS.some((allowedHeader) => allowedHeader === header),
+  );
+  if (!methodAllowed || !headersAllowed) {
+    res.writeHead(403, {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+      ...uiCorsHeaders(origin),
+    });
+    res.end(JSON.stringify({ error: "CORS preflight is not allowed for this request." }));
+    req.resume();
+    return;
+  }
+  res.writeHead(204, {
+    "cache-control": "no-store",
+    "access-control-allow-origin": origin,
+    "access-control-allow-methods": UI_CORS_METHODS.join(", "),
+    "access-control-allow-headers": UI_CORS_HEADERS.join(", "),
+    "access-control-max-age": "600",
+    vary: "Origin, Access-Control-Request-Method, Access-Control-Request-Headers",
+  });
+  res.end();
+  req.resume();
+}
+
 function isPublicHealthPath(pathname: string): boolean {
   return pathname === "/livez" || pathname === "/readyz" || pathname === "/api/health";
 }
@@ -503,23 +786,35 @@ export function isBrowserMutationAllowed(input: {
   origin?: string;
   secFetchSite?: string;
   csrfToken?: string;
+  allowedUiOrigins?: readonly string[];
+  publicOrigin?: string;
 }): boolean {
   if (isSafeMethod(input.method)) return true;
   const pathname = stripBasePath(
     new URL(input.path, "http://localhost").pathname,
     input.basePath ?? getConfiguredBasePath(process.env),
   );
-  if (pathname === "/proxy" || pathname.startsWith("/proxy/")) return true;
-
   const fetchSite = input.secFetchSite?.toLowerCase();
   const browserRequest = input.origin !== undefined || fetchSite !== undefined;
   if (!browserRequest) return true;
-  if (fetchSite !== undefined && fetchSite !== "same-origin") return false;
+  if (isModelProxyPath(pathname)) {
+    if (fetchSite !== undefined && fetchSite !== "same-origin") return false;
+    if (
+      input.origin !== undefined &&
+      !isSameRequestOrigin(input.origin, input.host, input.publicOrigin)
+    ) {
+      return false;
+    }
+    return input.csrfToken === "1";
+  }
+  const allowedOrigin = matchedUiOrigin(input.origin, input.allowedUiOrigins);
+  if (fetchSite !== undefined && fetchSite !== "same-origin" && allowedOrigin === null)
+    return false;
   if (input.origin !== undefined) {
-    try {
-      const originHost = new URL(input.origin).host.toLowerCase();
-      if (originHost !== input.host?.toLowerCase()) return false;
-    } catch {
+    if (
+      !isSameRequestOrigin(input.origin, input.host, input.publicOrigin) &&
+      allowedOrigin === null
+    ) {
       return false;
     }
   }
@@ -616,6 +911,128 @@ function readAliasControlBody(req: http.IncomingMessage): Promise<AliasControlBo
   });
 }
 
+type LocalControlBodyResult =
+  | { ok: true; body: Buffer }
+  | { ok: false; status: number; error: string };
+
+function readLocalControlBody(
+  req: http.IncomingMessage,
+  maxBytes: number,
+  timeoutMs: number,
+): Promise<LocalControlBodyResult> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    let receivedBytes = 0;
+    let settled = false;
+    const timer = setTimeout(() => {
+      finish({ ok: false, status: 408, error: "Instance request body timed out" });
+      req.resume();
+    }, timeoutMs);
+    const finish = (result: LocalControlBodyResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    req.on("data", (chunk: unknown) => {
+      if (settled) return;
+      const buffer = toBuffer(chunk);
+      receivedBytes += buffer.byteLength;
+      if (receivedBytes > maxBytes) {
+        finish({
+          ok: false,
+          status: 413,
+          error: `Instance request body exceeds ${String(maxBytes)} bytes`,
+        });
+        req.resume();
+        return;
+      }
+      chunks.push(buffer);
+    });
+    req.on("end", () => finish({ ok: true, body: Buffer.concat(chunks) }));
+    req.on("aborted", () =>
+      finish({ ok: false, status: 400, error: "Client aborted instance request body" }),
+    );
+    req.on("error", () =>
+      finish({ ok: false, status: 400, error: "Instance request body failed" }),
+    );
+  });
+}
+
+function writeLocalControlError(
+  res: http.ServerResponse,
+  status: number,
+  error: string,
+  allowedUiOrigin: string | null,
+): void {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    ...uiCorsHeaders(allowedUiOrigin),
+  });
+  res.end(JSON.stringify({ error }));
+}
+
+async function handleLocalInstanceApi(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  handler: (request: Request) => Promise<Response>,
+  upstreamPath: string,
+  requestPublicOrigin: string,
+  allowedUiOrigin: string | null,
+  maxRequestBytes: number,
+  requestTimeoutMs: number,
+): Promise<void> {
+  const body = await readLocalControlBody(
+    req,
+    Math.min(maxRequestBytes, INSTANCE_API_MAX_REQUEST_BYTES),
+    requestTimeoutMs,
+  );
+  if (!body.ok) {
+    writeLocalControlError(res, body.status, body.error, allowedUiOrigin);
+    return;
+  }
+  const method = (req.method ?? "GET").toUpperCase();
+  const headers = new Headers();
+  const contentType = firstHeader(req.headers["content-type"]);
+  if (contentType !== undefined) headers.set("content-type", contentType);
+  const request = new Request(new URL(upstreamPath, requestPublicOrigin), {
+    method,
+    headers,
+    body: method === "GET" || method === "HEAD" ? undefined : body.body.toString("utf8"),
+  });
+  let response: Response;
+  try {
+    response = await handler(request);
+  } catch {
+    writeLocalControlError(res, 503, "Instance supervisor request failed", allowedUiOrigin);
+    return;
+  }
+  const responseBody = Buffer.from(await response.arrayBuffer());
+  if (responseBody.byteLength > LOCAL_CONTROL_MAX_RESPONSE_BYTES) {
+    writeLocalControlError(
+      res,
+      502,
+      "Instance supervisor response exceeded its resource limit",
+      allowedUiOrigin,
+    );
+    return;
+  }
+  const responseHeaders: Record<string, string> = {
+    ...uiCorsHeaders(allowedUiOrigin),
+    "content-length": String(responseBody.byteLength),
+  };
+  response.headers.forEach((value, name) => {
+    const lowerName = name.toLowerCase();
+    if (!REQUEST_HOP_BY_HOP.has(lowerName) && lowerName !== "content-length") {
+      responseHeaders[lowerName] = value;
+    }
+  });
+  responseHeaders["cache-control"] = "no-store";
+  res.writeHead(response.status, responseHeaders);
+  res.end(responseBody);
+}
+
 function isUnknownRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -786,6 +1203,7 @@ function handleManagedInstanceControlRequest(
     }
     writeManagedInstanceControlResponse(res, 200, {
       schemaVersion: 1,
+      backend: managedInstance.backend ?? "typescript",
       name: managedInstance.name,
       instanceId: managedInstance.instanceId,
       launchId: managedInstance.launchId,
@@ -847,6 +1265,27 @@ function isIdentityProxyControlPath(pathname: string): boolean {
  * best-effort scan inside TanStack Start.
  */
 export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.Server> {
+  const allowedUiOrigins = parseUiOriginAllowlist(options.allowedUiOrigins?.join(","));
+  if (allowedUiOrigins.rejected.length > 0) {
+    return Promise.reject(
+      new Error(
+        `Unsafe UI origins are not accepted: ${allowedUiOrigins.rejected.join(", ")}. Only exact loopback HTTP(S) origins are supported.`,
+      ),
+    );
+  }
+  const publicOrigin = normalizeTrustedPublicOrigin(options.publicOrigin);
+  if (publicOrigin === null) {
+    return Promise.reject(
+      new Error(
+        "publicOrigin must be an exact HTTP(S) origin without credentials, path, or query.",
+      ),
+    );
+  }
+  const effectiveOptions: IdentityProxyOptions = {
+    ...options,
+    allowedUiOrigins: allowedUiOrigins.origins,
+    publicOrigin,
+  };
   return new Promise((resolve, reject) => {
     const server = http.createServer();
     const aliasRegistry =
@@ -893,7 +1332,7 @@ export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.
       };
       res.once("finish", release);
       res.once("close", release);
-      void handleRequest(req, res, options, aliasRegistry).catch((err: unknown) => {
+      void handleRequest(req, res, effectiveOptions, aliasRegistry).catch((err: unknown) => {
         const message = err instanceof Error ? err.message : String(err);
         if (!res.headersSent) {
           res.writeHead(502, { "content-type": "text/plain" });
@@ -979,6 +1418,55 @@ async function handleRequest(
   const resolution = resolveBasePathAliasRequest(aliasRegistry, req.url ?? "/");
   const basePath = resolution.effectiveBasePath;
   const upstreamPath = resolution.upstreamPath;
+  const upstreamPathname = new URL(upstreamPath, "http://localhost").pathname;
+  const requestOrigin = req.headers.origin;
+  const requestPublicOrigin = publicOriginForRequest(req, options);
+  const crossOriginRequest =
+    requestOrigin !== undefined &&
+    !isSameRequestOrigin(requestOrigin, req.headers.host, requestPublicOrigin);
+  const allowedUiOrigin = crossOriginRequest
+    ? matchedUiOrigin(requestOrigin, options.allowedUiOrigins)
+    : null;
+
+  if (crossOriginRequest && isModelProxyPath(upstreamPathname)) {
+    res.writeHead(403, {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(
+      JSON.stringify({ error: "Cross-origin browser access to the model proxy is forbidden." }),
+    );
+    req.resume();
+    return;
+  }
+
+  if (crossOriginRequest && upstreamPathname === "/api/mcp") {
+    res.writeHead(403, {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(JSON.stringify({ error: "Browser CORS is not enabled for the MCP endpoint." }));
+    req.resume();
+    return;
+  }
+
+  if (crossOriginRequest && isUiControlPath(upstreamPathname)) {
+    if (allowedUiOrigin === null) {
+      res.writeHead(403, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+      });
+      res.end(
+        JSON.stringify({ error: "UI origin is not allowed by this Agent Inspector runtime." }),
+      );
+      req.resume();
+      return;
+    }
+    if ((req.method ?? "GET").toUpperCase() === "OPTIONS") {
+      handleUiCorsPreflight(req, res, allowedUiOrigin);
+      return;
+    }
+  }
 
   if (basePath.length > 0 && requestUrl.pathname.startsWith("/assets/")) {
     res.writeHead(307, {
@@ -999,11 +1487,14 @@ async function handleRequest(
       origin: req.headers.origin,
       secFetchSite: firstHeader(req.headers["sec-fetch-site"]),
       csrfToken: firstHeader(req.headers[CSRF_HEADER]),
+      allowedUiOrigins: options.allowedUiOrigins,
+      publicOrigin: requestPublicOrigin,
     })
   ) {
     res.writeHead(403, {
       "content-type": "application/json; charset=utf-8",
       "cache-control": "no-store",
+      ...uiCorsHeaders(allowedUiOrigin),
     });
     res.end(JSON.stringify({ error: "Browser mutation requires same-origin CSRF proof" }));
     req.resume();
@@ -1024,6 +1515,7 @@ async function handleRequest(
     res.writeHead(403, {
       "content-type": "application/json; charset=utf-8",
       "cache-control": "no-store",
+      ...uiCorsHeaders(allowedUiOrigin),
     });
     res.end(
       JSON.stringify({
@@ -1034,6 +1526,19 @@ async function handleRequest(
     return;
   }
 
+  if (
+    await tryServeUiAsset(
+      req,
+      res,
+      options,
+      upstreamPathname,
+      basePath,
+      aliasRegistry.canonicalBasePath,
+    )
+  ) {
+    return;
+  }
+
   // The connection-time lookup already populated the per-port cache; this
   // call now hits the cache and returns the result synchronously.
   const remotePort = req.socket.remotePort;
@@ -1057,6 +1562,7 @@ async function handleRequest(
     res.writeHead(400, {
       "content-type": "application/json; charset=utf-8",
       "cache-control": "no-store",
+      ...uiCorsHeaders(allowedUiOrigin),
     });
     res.end(JSON.stringify({ error: "Invalid Content-Length header" }));
     req.resume();
@@ -1066,6 +1572,7 @@ async function handleRequest(
     res.writeHead(413, {
       "content-type": "application/json; charset=utf-8",
       "cache-control": "no-store",
+      ...uiCorsHeaders(allowedUiOrigin),
     });
     res.end(JSON.stringify({ error: `Request body exceeds ${String(maxRequestBytes)} bytes` }));
     req.resume();
@@ -1082,10 +1589,12 @@ async function handleRequest(
     )
       continue;
     if (lowerName.startsWith(IDENTITY_HEADER_PREFIX)) continue;
+    if (lowerName === "authorization" && !isModelProxyPath(upstreamPathname)) continue;
     if (value === undefined) continue;
     upstreamHeaders[name] = value;
   }
   upstreamHeaders[AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER] = basePath.length === 0 ? "/" : basePath;
+  upstreamHeaders[AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER] = requestPublicOrigin;
   const publicPort = req.socket.localPort;
   if (publicPort !== undefined && publicPort > 0 && publicPort <= 65_535) {
     upstreamHeaders[AGENT_INSPECTOR_PUBLIC_PORT_HEADER] = String(publicPort);
@@ -1108,6 +1617,19 @@ async function handleRequest(
     options.requestTimeoutMs,
     DEFAULT_REQUEST_TIMEOUT_MS,
   );
+  if (options.instanceApiHandler !== undefined && isInstanceManagementPath(upstreamPathname)) {
+    await handleLocalInstanceApi(
+      req,
+      res,
+      options.instanceApiHandler,
+      upstreamPath,
+      requestPublicOrigin,
+      allowedUiOrigin,
+      maxRequestBytes,
+      requestTimeoutMs,
+    );
+    return;
+  }
   const proxyReq = http.request(
     {
       hostname: options.upstreamHost,
@@ -1179,6 +1701,12 @@ async function handleRequest(
       for (const [name, value] of Object.entries(BASE_SECURITY_HEADERS)) {
         outHeaders[name] = value;
       }
+      outHeaders[AGENT_INSPECTOR_BACKEND_HEADER] = options.backendImplementation ?? "typescript";
+      if (allowedUiOrigin !== null && isUiControlPath(upstreamPathname)) {
+        outHeaders["access-control-allow-origin"] = allowedUiOrigin;
+        outHeaders["access-control-expose-headers"] = "Content-Disposition";
+        outHeaders["vary"] = appendVaryHeader(outHeaders["vary"], "Origin");
+      }
       if (contentType?.toLowerCase().includes("text/html") === true) {
         outHeaders["content-security-policy"] = DOCUMENT_CONTENT_SECURITY_POLICY;
       }