@tonyclaw/agent-inspector 3.0.44 → 3.0.46

package/src/proxy/identityProxy.ts

@@ -1,15 +1,30 @@
 import http from "node:http";
 import { Buffer } from "node:buffer";
-import { timingSafeEqual } from "node:crypto";
+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_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,
 } from "../lib/basePath";
+import {
+  MANAGED_INSTANCE_CONTROL_PATH,
+  MANAGED_INSTANCE_SHUTDOWN_PATH,
+  MANAGED_INSTANCE_TOKEN_HEADER,
+} from "../lib/managedInstance";
 import { lookupClientByPort } from "./socketTracker";
+import { loadUiAsset } from "./uiAssetServer";
 
 const IDENTITY_HEADERS = {
   pid: "x-agent-inspector-client-pid",
@@ -23,6 +38,180 @@ const PROXY_TOKEN_HEADER = "x-agent-inspector-proxy-token";
 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;
+
+export const IDENTITY_PROXY_CONTROL_NAMESPACE = "/.agent-inspector";
+export const IDENTITY_PROXY_ALIAS_CONTROL_PATH = `${IDENTITY_PROXY_CONTROL_NAMESPACE}/base-path-aliases`;
+
+export type BasePathAliasResolution = {
+  effectiveBasePath: string;
+  isAlias: boolean;
+  upstreamPath: string;
+};
+
+export type BasePathAliasMutationResult =
+  | { ok: true; basePath: string }
+  | {
+      ok: false;
+      code: "canonical" | "duplicate" | "invalid" | "not-found" | "overlap" | "reserved";
+      error: string;
+    };
+
+export type BasePathAliasRegistry = {
+  canonicalBasePath: string;
+  add: (basePath: string) => BasePathAliasMutationResult;
+  list: () => readonly string[];
+  remove: (basePath: string) => BasePathAliasMutationResult;
+  resolve: (rawPath: string) => BasePathAliasResolution;
+};
+
+function normalizedAliasCandidate(
+  value: string,
+): { ok: true; basePath: string } | { ok: false; code: "invalid" | "reserved"; error: string } {
+  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.length === 0) {
+    return {
+      ok: false,
+      code: "invalid",
+      error: "Base Path aliases must be non-root paths such as /inspector.",
+    };
+  }
+  if (
+    normalized === IDENTITY_PROXY_CONTROL_NAMESPACE ||
+    normalized.startsWith(`${IDENTITY_PROXY_CONTROL_NAMESPACE}/`)
+  ) {
+    return {
+      ok: false,
+      code: "reserved",
+      error: `${normalized} collides with the reserved Agent Inspector control path.`,
+    };
+  }
+  const publicNamespace = ["/api", "/assets", "/proxy", "/session", "/livez", "/readyz"].find(
+    (namespace) => normalized === namespace || normalized.startsWith(`${namespace}/`),
+  );
+  if (publicNamespace !== undefined) {
+    return {
+      ok: false,
+      code: "reserved",
+      error: `${normalized} collides with the reserved ${publicNamespace} public namespace.`,
+    };
+  }
+  return { ok: true, basePath: normalized };
+}
+
+function pathMatchesBasePath(pathname: string, basePath: string): boolean {
+  return pathname === basePath || pathname.startsWith(`${basePath}/`);
+}
+
+function basePathsOverlap(left: string, right: string): boolean {
+  return pathMatchesBasePath(left, right) || pathMatchesBasePath(right, left);
+}
+
+/**
+ * Create an in-memory registry owned by one identity ingress. Runtime aliases
+ * intentionally disappear when that ingress exits.
+ */
+export function createBasePathAliasRegistry(
+  canonicalBasePath: string,
+  initialAliases: readonly string[] = [],
+): BasePathAliasRegistry {
+  const canonical = normalizePublicBasePath(canonicalBasePath) ?? "";
+  const aliases: string[] = [];
+
+  const add = (value: string): BasePathAliasMutationResult => {
+    const candidate = normalizedAliasCandidate(value);
+    if (!candidate.ok) return candidate;
+    if (candidate.basePath === canonical) {
+      return {
+        ok: false,
+        code: "canonical",
+        error: `${candidate.basePath} is already the canonical Base Path.`,
+      };
+    }
+    if (canonical.length > 0 && basePathsOverlap(candidate.basePath, canonical)) {
+      return {
+        ok: false,
+        code: "overlap",
+        error: `${candidate.basePath} overlaps the canonical Base Path ${canonical}.`,
+      };
+    }
+    if (aliases.includes(candidate.basePath)) {
+      return {
+        ok: false,
+        code: "duplicate",
+        error: `${candidate.basePath} is already an active runtime alias.`,
+      };
+    }
+    const overlappingAlias = aliases.find((alias) => basePathsOverlap(candidate.basePath, alias));
+    if (overlappingAlias !== undefined) {
+      return {
+        ok: false,
+        code: "overlap",
+        error: `${candidate.basePath} overlaps the active runtime alias ${overlappingAlias}.`,
+      };
+    }
+    aliases.push(candidate.basePath);
+    aliases.sort((left, right) => right.length - left.length || left.localeCompare(right));
+    return { ok: true, basePath: candidate.basePath };
+  };
+
+  const remove = (value: string): BasePathAliasMutationResult => {
+    const candidate = normalizedAliasCandidate(value);
+    if (!candidate.ok) return candidate;
+    if (candidate.basePath === canonical) {
+      return {
+        ok: false,
+        code: "canonical",
+        error: `${candidate.basePath} is the canonical Base Path and cannot be removed.`,
+      };
+    }
+    const index = aliases.indexOf(candidate.basePath);
+    if (index === -1) {
+      return {
+        ok: false,
+        code: "not-found",
+        error: `${candidate.basePath} is not an active runtime alias.`,
+      };
+    }
+    aliases.splice(index, 1);
+    return { ok: true, basePath: candidate.basePath };
+  };
+
+  const resolve = (rawPath: string): BasePathAliasResolution => {
+    const requestUrl = new URL(rawPath, "http://localhost");
+    const alias = aliases.find((candidate) => pathMatchesBasePath(requestUrl.pathname, candidate));
+    const effectiveBasePath = alias ?? canonical;
+    return {
+      effectiveBasePath,
+      isAlias: alias !== undefined,
+      upstreamPath: stripBasePathFromRequestPath(rawPath, effectiveBasePath),
+    };
+  };
+
+  const registry: BasePathAliasRegistry = {
+    canonicalBasePath: canonical,
+    add,
+    list: () => [...aliases],
+    remove,
+    resolve,
+  };
+  for (const alias of initialAliases) add(alias);
+  return registry;
+}
+
+export function resolveBasePathAliasRequest(
+  registry: BasePathAliasRegistry,
+  rawPath: string,
+): BasePathAliasResolution {
+  return registry.resolve(rawPath);
+}
 
 type IdentityProxyRuntimeState = {
   acceptingRequests: boolean;
@@ -83,34 +272,211 @@ function htmlAttributeEscape(value: string): string {
     .replace(/>/gu, ">");
 }
 
-export function rewriteHtmlForBasePath(html: string, basePath: string): string {
-  const normalized = normalizeBasePath(basePath);
-  if (normalized.length === 0) return html;
+function rewriteRootRelativePublicPath(
+  value: string,
+  effectiveBasePath: string,
+  sourceBasePath: string,
+): string {
+  if (!value.startsWith("/") || value.startsWith("//")) return value;
+  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);
+  if (normalizedEffective.length > 0 && pathMatchesBasePath(pathname, normalizedEffective)) {
+    return value;
+  }
+  const rootRelativePath =
+    normalizedSource.length > 0 && pathMatchesBasePath(pathname, normalizedSource)
+      ? pathname.slice(normalizedSource.length) || "/"
+      : pathname;
+  const rewritten = withBasePath(rootRelativePath, normalizedEffective);
+  const trailingSlash = pathname.endsWith("/") && !rewritten.endsWith("/") ? "/" : "";
+  return `${rewritten}${trailingSlash}${suffix}`;
+}
+
+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}${escape(
+        rewriteRootRelativePublicPath(assetPrefix, effectiveBasePath, sourceBasePath),
+        quote,
+      )}`,
+  );
+}
+
+export function rewriteHtmlForBasePath(
+  html: string,
+  basePath: string,
+  sourceBasePath = "",
+): string {
+  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 withMeta = html.includes(`name="${AGENT_INSPECTOR_BASE_PATH_META_NAME}"`)
-    ? html
-    : html.replace(/<head(\s[^>]*)?>/iu, (match) => `${match}${meta}`);
-  const escapedBase = normalized.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const metaPattern = new RegExp(
+    `<meta\\b[^>]*\\bname\\s*=\\s*("|')${AGENT_INSPECTOR_BASE_PATH_META_NAME}\\1[^>]*>`,
+    "giu",
+  );
+  let replacedMeta = false;
+  const withReplacedMeta = html.replace(metaPattern, () => {
+    if (replacedMeta) return "";
+    replacedMeta = true;
+    return meta;
+  });
+  const withMeta = replacedMeta
+    ? withReplacedMeta
+    : withReplacedMeta.replace(/<head(\s[^>]*)?>/iu, (match) => `${match}${meta}`);
   const withRewrittenAttributes = withMeta.replace(
-    new RegExp(`\\b(href|src|action)=("|')/(?!/|${escapedBase.slice(1)}(?:/|$))`, "giu"),
-    (_match: string, attr: string, quote: string) => `${attr}=${quote}${normalized}/`,
+    /\b(href|src|action)=(["'])(\/(?!\/)[^"']*)\2/giu,
+    (_match: string, attribute: string, quote: string, path: string) =>
+      `${attribute}=${quote}${htmlAttributeEscape(
+        rewriteRootRelativePublicPath(path, normalized, normalizedSource),
+      )}${quote}`,
+  );
+  return rewriteQuotedAssetPaths(withRewrittenAttributes, normalized, normalizedSource, (value) =>
+    htmlAttributeEscape(value),
   );
-  return withRewrittenAttributes.replace(/(["'])\/assets\//gu, `$1${normalized}/assets/`);
 }
 
-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(
+  source: string,
+  basePath: string,
+  sourceBasePath = "",
+): string {
+  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) => {
+      const rewritten = rewriteRootRelativePublicPath(path, normalized, normalizedSource);
+      return `return${quote}${javaScriptStringEscape(rewritten, quote)}${quote}+${variable}`;
+    },
+  );
+  return rewriteQuotedAssetPaths(
+    withDynamicPaths,
+    normalized,
+    normalizedSource,
+    javaScriptStringEscape,
+  );
+}
+
+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}`);
 }
 
-export function rewriteJavaScriptForBasePath(source: string, basePath: string): string {
-  const normalized = normalizeBasePath(basePath);
-  if (normalized.length === 0) return source;
-  const escaped = javaScriptStringEscape(normalized);
-  return source
-    .replace(/\bbasepath:\s*""/gu, `basepath:"${escaped}"`)
-    .replace(/return"\/"\+([A-Za-z_$][\w$]*)/gu, `return"${escaped}/"+$1`)
-    .replace(/(["'])\/assets\//gu, `$1${normalized}/assets/`);
+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 = {
@@ -134,10 +500,32 @@ 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. */
   requestTimeoutMs?: number;
+  /** Runtime-scoped additional public Base Path mounts. */
+  aliasRegistry?: BasePathAliasRegistry;
+  /** Private lifecycle identity exposed only to the owning local instance manager. */
+  managedInstance?: ManagedInstanceControlOptions;
+};
+
+export type ManagedInstanceControlOptions = {
+  name: string;
+  instanceId: string;
+  launchId: string;
+  controlToken: string;
+  supervisorPid: number;
+  startedAt: string;
+  publicPort: number;
+  upstreamPort: number;
+  requestShutdown: () => void;
 };
 
 function isLoopbackPeer(address: string | undefined): boolean {
@@ -164,6 +552,13 @@ function tokensMatch(received: string | null, expected: string | undefined): boo
   );
 }
 
+function managedInstanceTokensMatch(received: string | undefined, expected: string): boolean {
+  if (received === undefined || received.length === 0 || expected.length === 0) return false;
+  const receivedDigest = createHash("sha256").update(received).digest();
+  const expectedDigest = createHash("sha256").update(expected).digest();
+  return timingSafeEqual(receivedDigest, expectedDigest);
+}
+
 function firstHeader(value: string | readonly string[] | undefined): string | undefined {
   return typeof value === "string" ? value : value?.[0];
 }
@@ -179,7 +574,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(
@@ -203,9 +643,117 @@ 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 {
-  const path = stripBasePath(pathname, getConfiguredBasePath(process.env));
-  return path === "/livez" || path === "/readyz" || path === "/api/health";
+  return pathname === "/livez" || pathname === "/readyz" || pathname === "/api/health";
+}
+
+function isInstanceManagementPath(pathname: string): boolean {
+  return pathname === "/api/instances" || pathname.startsWith("/api/instances/");
 }
 
 function configuredPositiveInteger(value: number | undefined, fallback: number): number {
@@ -221,28 +769,41 @@ function declaredContentLength(value: string | undefined): number | null {
 
 export function isBrowserMutationAllowed(input: {
   path: string;
+  basePath?: string;
   method?: string;
   host?: string;
   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,
-    getConfiguredBasePath(process.env),
+    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;
     }
   }
@@ -251,6 +812,7 @@ export function isBrowserMutationAllowed(input: {
 
 export function isIdentityProxyRequestAllowed(input: {
   path: string;
+  basePath?: string;
   remoteAddress?: string;
   authorization?: string;
   proxyAuthorization?: string;
@@ -264,14 +826,17 @@ export function isIdentityProxyRequestAllowed(input: {
     | "allowUnauthenticatedRemoteProxy"
   >;
 }): boolean {
+  const pathname = stripBasePath(
+    new URL(input.path, "http://localhost").pathname,
+    input.basePath ?? getConfiguredBasePath(process.env),
+  );
+  if (!isLoopbackPeer(input.remoteAddress) && isInstanceManagementPath(pathname)) {
+    return tokensMatch(bearerToken(input.authorization), input.options.controlToken);
+  }
   if (input.options.restrictRemoteControl !== true) return true;
   if (input.options.allowRemoteControl === true) return true;
   if (isLoopbackPeer(input.remoteAddress)) return true;
 
-  const pathname = stripBasePath(
-    new URL(input.path, "http://localhost").pathname,
-    getConfiguredBasePath(process.env),
-  );
   if (pathname === "/proxy" || pathname.startsWith("/proxy/")) {
     if (input.options.allowUnauthenticatedRemoteProxy === true) return true;
     const proxyCredential = bearerToken(input.proxyAuthorization) ?? input.proxyTokenHeader ?? null;
@@ -281,6 +846,267 @@ export function isIdentityProxyRequestAllowed(input: {
   return tokensMatch(bearerToken(input.authorization), input.options.controlToken);
 }
 
+type AliasControlBodyResult =
+  | { ok: true; body: string }
+  | { ok: false; status: number; error: string };
+
+function readAliasControlBody(req: http.IncomingMessage): Promise<AliasControlBodyResult> {
+  const contentLength = declaredContentLength(req.headers["content-length"]);
+  if (contentLength !== null && (!Number.isFinite(contentLength) || contentLength < 0)) {
+    req.resume();
+    return Promise.resolve({ ok: false, status: 400, error: "Invalid Content-Length header" });
+  }
+  if (contentLength !== null && contentLength > ALIAS_CONTROL_MAX_REQUEST_BYTES) {
+    req.resume();
+    return Promise.resolve({
+      ok: false,
+      status: 413,
+      error: `Alias control body exceeds ${String(ALIAS_CONTROL_MAX_REQUEST_BYTES)} bytes`,
+    });
+  }
+
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    let receivedBytes = 0;
+    let settled = false;
+    const finish = (result: AliasControlBodyResult): void => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    req.on("data", (chunk: unknown) => {
+      if (settled) return;
+      const buffer = toBuffer(chunk);
+      receivedBytes += buffer.byteLength;
+      if (receivedBytes > ALIAS_CONTROL_MAX_REQUEST_BYTES) {
+        finish({
+          ok: false,
+          status: 413,
+          error: `Alias control body exceeds ${String(ALIAS_CONTROL_MAX_REQUEST_BYTES)} bytes`,
+        });
+        return;
+      }
+      chunks.push(buffer);
+    });
+    req.on("end", () => {
+      finish({ ok: true, body: Buffer.concat(chunks).toString("utf8") });
+    });
+    req.on("aborted", () => {
+      finish({ ok: false, status: 400, error: "Client aborted alias control request" });
+    });
+    req.on("error", () => {
+      finish({ ok: false, status: 400, error: "Alias control request body failed" });
+    });
+  });
+}
+
+function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function aliasBasePathFromJson(
+  body: string,
+): { ok: true; basePath: string } | { ok: false; error: string } {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return { ok: false, error: "Alias control body must be valid JSON." };
+  }
+  if (!isUnknownRecord(parsed) || typeof parsed.basePath !== "string") {
+    return { ok: false, error: 'Alias control body must contain a string "basePath" field.' };
+  }
+  return { ok: true, basePath: parsed.basePath };
+}
+
+function writeAliasControlResponse(
+  res: http.ServerResponse,
+  registry: BasePathAliasRegistry,
+  status: number,
+  result:
+    | { basePath?: string; code?: string; error?: string }
+    | { basePath: string }
+    | undefined = undefined,
+  extraHeaders: Readonly<Record<string, string>> = {},
+): void {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    ...extraHeaders,
+  });
+  res.end(
+    JSON.stringify({
+      canonicalBasePath: registry.canonicalBasePath,
+      aliases: registry.list(),
+      runtimeScoped: true,
+      ...result,
+    }),
+  );
+}
+
+async function handleAliasControlRequest(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  registry: BasePathAliasRegistry,
+): Promise<void> {
+  if (!isLoopbackPeer(req.socket.remoteAddress)) {
+    req.resume();
+    writeAliasControlResponse(res, registry, 403, {
+      error: "Base Path aliases can only be managed from the local machine.",
+    });
+    return;
+  }
+  if (
+    !isBrowserMutationAllowed({
+      path: req.url ?? IDENTITY_PROXY_ALIAS_CONTROL_PATH,
+      basePath: "",
+      method: req.method,
+      host: req.headers.host,
+      origin: req.headers.origin,
+      secFetchSite: firstHeader(req.headers["sec-fetch-site"]),
+      csrfToken: firstHeader(req.headers[CSRF_HEADER]),
+    })
+  ) {
+    req.resume();
+    writeAliasControlResponse(res, registry, 403, {
+      error: "Browser mutation requires same-origin CSRF proof.",
+    });
+    return;
+  }
+
+  const method = (req.method ?? "GET").toUpperCase();
+  if (method === "GET") {
+    req.resume();
+    writeAliasControlResponse(res, registry, 200);
+    return;
+  }
+  if (method !== "POST" && method !== "DELETE") {
+    req.resume();
+    writeAliasControlResponse(
+      res,
+      registry,
+      405,
+      { error: "Alias control supports GET, POST, and DELETE." },
+      { allow: "GET, POST, DELETE" },
+    );
+    return;
+  }
+
+  const bodyResult = await readAliasControlBody(req);
+  if (!bodyResult.ok) {
+    writeAliasControlResponse(res, registry, bodyResult.status, { error: bodyResult.error });
+    return;
+  }
+  const input = aliasBasePathFromJson(bodyResult.body);
+  if (!input.ok) {
+    writeAliasControlResponse(res, registry, 400, { error: input.error });
+    return;
+  }
+  const mutation =
+    method === "POST" ? registry.add(input.basePath) : registry.remove(input.basePath);
+  if (mutation.ok) {
+    writeAliasControlResponse(res, registry, method === "POST" ? 201 : 200, {
+      basePath: mutation.basePath,
+    });
+    return;
+  }
+  const status =
+    mutation.code === "duplicate" || mutation.code === "overlap"
+      ? 409
+      : mutation.code === "not-found"
+        ? 404
+        : 400;
+  writeAliasControlResponse(res, registry, status, {
+    code: mutation.code,
+    error: mutation.error,
+  });
+}
+
+function writeManagedInstanceControlResponse(
+  res: http.ServerResponse,
+  status: number,
+  body: Readonly<Record<string, unknown>>,
+  extraHeaders: Readonly<Record<string, string>> = {},
+  onFinished: (() => void) | undefined = undefined,
+): void {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    ...extraHeaders,
+  });
+  res.end(JSON.stringify(body), onFinished);
+}
+
+function handleManagedInstanceControlRequest(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+  managedInstance: ManagedInstanceControlOptions | undefined,
+): void {
+  req.resume();
+  if (managedInstance === undefined) {
+    writeManagedInstanceControlResponse(res, 404, { error: "Control endpoint not found" });
+    return;
+  }
+  const authorized = managedInstanceTokensMatch(
+    firstHeader(req.headers[MANAGED_INSTANCE_TOKEN_HEADER]),
+    managedInstance.controlToken,
+  );
+  if (!authorized) {
+    writeManagedInstanceControlResponse(res, 403, { error: "Instance control access denied" });
+    return;
+  }
+
+  const method = (req.method ?? "GET").toUpperCase();
+  if (pathname === MANAGED_INSTANCE_CONTROL_PATH) {
+    if (method !== "GET") {
+      writeManagedInstanceControlResponse(
+        res,
+        405,
+        { error: "Instance identity supports GET only" },
+        { allow: "GET" },
+      );
+      return;
+    }
+    writeManagedInstanceControlResponse(res, 200, {
+      schemaVersion: 1,
+      name: managedInstance.name,
+      instanceId: managedInstance.instanceId,
+      launchId: managedInstance.launchId,
+      supervisorPid: managedInstance.supervisorPid,
+      startedAt: managedInstance.startedAt,
+      publicPort: managedInstance.publicPort,
+      upstreamPort: managedInstance.upstreamPort,
+    });
+    return;
+  }
+  if (method !== "POST") {
+    writeManagedInstanceControlResponse(
+      res,
+      405,
+      { error: "Instance shutdown supports POST only" },
+      { allow: "POST" },
+    );
+    return;
+  }
+  writeManagedInstanceControlResponse(
+    res,
+    202,
+    { accepted: true, launchId: managedInstance.launchId },
+    {},
+    () => {
+      process.nextTick(managedInstance.requestShutdown);
+    },
+  );
+}
+
+function isIdentityProxyControlPath(pathname: string): boolean {
+  return (
+    pathname === IDENTITY_PROXY_CONTROL_NAMESPACE ||
+    pathname.startsWith(`${IDENTITY_PROXY_CONTROL_NAMESPACE}/`)
+  );
+}
+
 /**
  * Start a tiny native Node HTTP server that:
  *   1. Reads the client connection's source port (`req.socket.remotePort`).
@@ -305,8 +1131,31 @@ export function isIdentityProxyRequestAllowed(input: {
  * 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 =
+      options.aliasRegistry ?? createBasePathAliasRegistry(getConfiguredBasePath(process.env));
     const runtimeState: IdentityProxyRuntimeState = {
       acceptingRequests: true,
       activeRequests: 0,
@@ -349,7 +1198,7 @@ export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.
       };
       res.once("finish", release);
       res.once("close", release);
-      void handleRequest(req, res, options).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" });
@@ -400,9 +1249,8 @@ async function handleRequest(
   req: http.IncomingMessage,
   res: http.ServerResponse,
   options: IdentityProxyOptions,
+  aliasRegistry: BasePathAliasRegistry,
 ): Promise<void> {
-  const basePath = getConfiguredBasePath(process.env);
-  const upstreamPath = stripBasePathFromRequestPath(req.url ?? "/", basePath);
   const requestUrl = new URL(req.url ?? "/", "http://localhost");
   if (!isTrustedIdentityProxyHost(req.headers.host, options)) {
     res.writeHead(400, {
@@ -414,6 +1262,78 @@ async function handleRequest(
     return;
   }
 
+  if (requestUrl.pathname === IDENTITY_PROXY_ALIAS_CONTROL_PATH) {
+    await handleAliasControlRequest(req, res, aliasRegistry);
+    return;
+  }
+
+  if (
+    requestUrl.pathname === MANAGED_INSTANCE_CONTROL_PATH ||
+    requestUrl.pathname === MANAGED_INSTANCE_SHUTDOWN_PATH
+  ) {
+    handleManagedInstanceControlRequest(req, res, requestUrl.pathname, options.managedInstance);
+    return;
+  }
+
+  if (isIdentityProxyControlPath(requestUrl.pathname)) {
+    req.resume();
+    writeManagedInstanceControlResponse(res, 404, { error: "Control endpoint not found" });
+    return;
+  }
+
+  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, {
       location: `${basePath}${requestUrl.pathname}${requestUrl.search}`,
@@ -427,16 +1347,20 @@ async function handleRequest(
   if (
     !isBrowserMutationAllowed({
       path: req.url ?? "/",
+      basePath,
       method: req.method,
       host: req.headers.host,
       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();
@@ -446,6 +1370,7 @@ async function handleRequest(
   if (
     !isIdentityProxyRequestAllowed({
       path: req.url ?? "/",
+      basePath,
       remoteAddress: req.socket.remoteAddress,
       authorization: req.headers.authorization,
       proxyAuthorization: req.headers["proxy-authorization"],
@@ -456,6 +1381,7 @@ async function handleRequest(
     res.writeHead(403, {
       "content-type": "application/json; charset=utf-8",
       "cache-control": "no-store",
+      ...uiCorsHeaders(allowedUiOrigin),
     });
     res.end(
       JSON.stringify({
@@ -466,6 +1392,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;
@@ -489,6 +1428,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();
@@ -498,6 +1438,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();
@@ -508,11 +1449,22 @@ async function handleRequest(
   for (const [name, value] of Object.entries(req.headers)) {
     const lowerName = name.toLowerCase();
     if (REQUEST_HOP_BY_HOP.has(lowerName)) continue;
-    if (basePath.length > 0 && lowerName === "accept-encoding") continue;
+    if (
+      basePath.length > 0 &&
+      (lowerName === "accept-encoding" || lowerName === "range" || lowerName === "if-range")
+    )
+      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);
+  }
   if (identity !== null && identity.pid !== null) {
     upstreamHeaders[IDENTITY_HEADERS.pid] = String(identity.pid);
     if (identity.port !== null) {
@@ -540,10 +1492,25 @@ async function handleRequest(
       headers: upstreamHeaders,
     },
     (proxyRes) => {
-      if (terminal) {
-        proxyRes.resume();
+      if (terminal || res.destroyed) {
+        proxyRes.destroy();
         return;
       }
+      const destroyUpstreamResponse = (): void => {
+        proxyRes.destroy();
+        proxyRes.socket.destroy();
+        proxyReq.destroy();
+      };
+      const removeDownstreamListeners = (): void => {
+        res.removeListener("close", destroyUpstreamResponse);
+        res.removeListener("error", destroyUpstreamResponse);
+        req.socket.removeListener("close", destroyUpstreamResponse);
+      };
+      res.once("close", destroyUpstreamResponse);
+      res.once("error", destroyUpstreamResponse);
+      req.socket.once("close", destroyUpstreamResponse);
+      proxyRes.once("end", removeDownstreamListeners);
+      proxyRes.once("close", removeDownstreamListeners);
       const outHeaders: Record<string, string | string[]> = {};
       const contentType = firstHeader(proxyRes.headers["content-type"]);
       const shouldRewriteHtml =
@@ -556,17 +1523,48 @@ async function handleRequest(
       for (const [name, value] of Object.entries(proxyRes.headers)) {
         const lowerName = name.toLowerCase();
         if (RESPONSE_HOP_BY_HOP.has(lowerName)) continue;
-        if (shouldRewriteBody && lowerName === "content-length") continue;
+        if (
+          shouldRewriteBody &&
+          (lowerName === "content-length" ||
+            lowerName === "content-range" ||
+            lowerName === "accept-ranges" ||
+            lowerName === "etag" ||
+            lowerName === "last-modified" ||
+            lowerName === "content-md5" ||
+            lowerName === "digest")
+        )
+          continue;
         if (value === undefined) continue;
-        outHeaders[name] = value;
+        if (
+          lowerName === "location" &&
+          basePath.length > 0 &&
+          typeof value === "string" &&
+          value.startsWith("/") &&
+          !value.startsWith("//")
+        ) {
+          outHeaders[name] = rewriteRootRelativePublicPath(
+            value,
+            basePath,
+            aliasRegistry.canonicalBasePath,
+          );
+        } else {
+          outHeaders[name] = value;
+        }
       }
       for (const [name, value] of Object.entries(BASE_SECURITY_HEADERS)) {
         outHeaders[name] = value;
       }
+      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;
       }
-      res.writeHead(proxyRes.statusCode ?? 502, outHeaders);
+      const responseStatus =
+        shouldRewriteBody && proxyRes.statusCode === 206 ? 200 : (proxyRes.statusCode ?? 502);
+      res.writeHead(responseStatus, outHeaders);
       if (shouldRewriteBody) {
         const chunks: Buffer[] = [];
         proxyRes.on("data", (chunk: unknown) => {
@@ -574,11 +1572,12 @@ async function handleRequest(
         });
         proxyRes.on("end", () => {
           const body = Buffer.concat(chunks).toString("utf8");
-          res.end(
+          res.write(
             shouldRewriteHtml
-              ? rewriteHtmlForBasePath(body, basePath)
-              : rewriteJavaScriptForBasePath(body, basePath),
+              ? rewriteHtmlForBasePath(body, basePath, aliasRegistry.canonicalBasePath)
+              : rewriteJavaScriptForBasePath(body, basePath, aliasRegistry.canonicalBasePath),
           );
+          res.end();
         });
         proxyRes.on("error", () => {
           if (!res.writableEnded) res.destroy();
@@ -626,7 +1625,7 @@ async function handleRequest(
   proxyReq.on("drain", () => req.resume());
   res.once("close", () => {
     clearDeadline();
-    if (!res.writableEnded) proxyReq.destroy();
+    proxyReq.destroy();
   });
 
   let receivedBytes = 0;