@tonyclaw/agent-inspector 3.0.43 → 3.0.45

package/src/proxy/identityProxy.ts

@@ -1,14 +1,22 @@
 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 {
   AGENT_INSPECTOR_BASE_PATH_META_NAME,
+  AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER,
+  AGENT_INSPECTOR_PUBLIC_PORT_HEADER,
   getConfiguredBasePath,
   normalizeBasePath,
   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";
 
 const IDENTITY_HEADERS = {
@@ -23,6 +31,187 @@ 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 = 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)) {
+    return {
+      ok: false,
+      code: "invalid",
+      error: "Base Path aliases may contain only URL-safe path segments.",
+    };
+  }
+  if (normalized.split("/").some((segment) => segment === "." || segment === "..")) {
+    return {
+      ok: false,
+      code: "invalid",
+      error: "Base Path aliases cannot contain dot path segments.",
+    };
+  }
+  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 = normalizeBasePath(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,33 +272,95 @@ function htmlAttributeEscape(value: string): string {
     .replace(/>/gu, ">");
 }
 
-export function rewriteHtmlForBasePath(html: string, basePath: string): string {
+function rewriteRootRelativePublicPath(
+  value: string,
+  effectiveBasePath: string,
+  sourceBasePath: string,
+): string {
+  if (!value.startsWith("/") || value.startsWith("//")) return value;
+  const normalizedEffective = normalizeBasePath(effectiveBasePath);
+  const normalizedSource = normalizeBasePath(sourceBasePath);
+  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,
+): string {
+  return source.replace(
+    /(["'])(\/(?:[^"'/]+\/)*assets\/)/gu,
+    (_match: string, quote: string, assetPrefix: string) =>
+      `${quote}${rewriteRootRelativePublicPath(assetPrefix, effectiveBasePath, sourceBasePath)}`,
+  );
+}
+
+export function rewriteHtmlForBasePath(
+  html: string,
+  basePath: string,
+  sourceBasePath = "",
+): string {
   const normalized = normalizeBasePath(basePath);
-  if (normalized.length === 0) 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, "\\$&");
-  return withMeta.replace(
-    new RegExp(`\\b(href|src|action)=("|')/(?!/|${escapedBase.slice(1)}(?:/|$))`, "giu"),
-    (_match: string, attr: string, quote: string) => `${attr}=${quote}${normalized}/`,
+  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(
+    /\b(href|src|action)=(["'])(\/(?!\/)[^"']*)\2/giu,
+    (_match: string, attribute: string, quote: string, path: string) =>
+      `${attribute}=${quote}${rewriteRootRelativePublicPath(path, normalized, sourceBasePath)}${quote}`,
   );
+  return rewriteQuotedAssetPaths(withRewrittenAttributes, normalized, sourceBasePath);
 }
 
 function javaScriptStringEscape(value: string): string {
   return value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"');
 }
 
-export function rewriteJavaScriptForBasePath(source: string, basePath: string): string {
+export function rewriteJavaScriptForBasePath(
+  source: string,
+  basePath: string,
+  sourceBasePath = "",
+): 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/`);
+  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}`,
+  );
+  return rewriteQuotedAssetPaths(withDynamicPaths, normalized, sourceBasePath);
 }
 
 export type IdentityProxyOptions = {
@@ -137,6 +388,22 @@ export type IdentityProxyOptions = {
   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 {
@@ -163,6 +430,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];
 }
@@ -203,8 +477,11 @@ function isSafeMethod(method: string | undefined): boolean {
 }
 
 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 {
@@ -220,6 +497,7 @@ function declaredContentLength(value: string | undefined): number | null {
 
 export function isBrowserMutationAllowed(input: {
   path: string;
+  basePath?: string;
   method?: string;
   host?: string;
   origin?: string;
@@ -229,7 +507,7 @@ export function isBrowserMutationAllowed(input: {
   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;
 
@@ -250,6 +528,7 @@ export function isBrowserMutationAllowed(input: {
 
 export function isIdentityProxyRequestAllowed(input: {
   path: string;
+  basePath?: string;
   remoteAddress?: string;
   authorization?: string;
   proxyAuthorization?: string;
@@ -263,14 +542,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;
@@ -280,6 +562,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`).
@@ -306,6 +849,8 @@ export function isIdentityProxyRequestAllowed(input: {
 export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.Server> {
   return new Promise((resolve, reject) => {
     const server = http.createServer();
+    const aliasRegistry =
+      options.aliasRegistry ?? createBasePathAliasRegistry(getConfiguredBasePath(process.env));
     const runtimeState: IdentityProxyRuntimeState = {
       acceptingRequests: true,
       activeRequests: 0,
@@ -348,7 +893,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, options, aliasRegistry).catch((err: unknown) => {
         const message = err instanceof Error ? err.message : String(err);
         if (!res.headersSent) {
           res.writeHead(502, { "content-type": "text/plain" });
@@ -399,9 +944,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, {
@@ -413,6 +957,29 @@ 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;
+
   if (basePath.length > 0 && requestUrl.pathname.startsWith("/assets/")) {
     res.writeHead(307, {
       location: `${basePath}${requestUrl.pathname}${requestUrl.search}`,
@@ -426,6 +993,7 @@ async function handleRequest(
   if (
     !isBrowserMutationAllowed({
       path: req.url ?? "/",
+      basePath,
       method: req.method,
       host: req.headers.host,
       origin: req.headers.origin,
@@ -445,6 +1013,7 @@ async function handleRequest(
   if (
     !isIdentityProxyRequestAllowed({
       path: req.url ?? "/",
+      basePath,
       remoteAddress: req.socket.remoteAddress,
       authorization: req.headers.authorization,
       proxyAuthorization: req.headers["proxy-authorization"],
@@ -507,11 +1076,20 @@ 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 (value === undefined) continue;
     upstreamHeaders[name] = value;
   }
+  upstreamHeaders[AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER] = basePath.length === 0 ? "/" : basePath;
+  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) {
@@ -539,10 +1117,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 =
@@ -555,9 +1148,33 @@ 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;
@@ -565,7 +1182,9 @@ async function handleRequest(
       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) => {
@@ -573,11 +1192,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();
@@ -625,7 +1245,7 @@ async function handleRequest(
   proxyReq.on("drain", () => req.resume());
   res.once("close", () => {
     clearDeadline();
-    if (!res.writableEnded) proxyReq.destroy();
+    proxyReq.destroy();
   });
 
   let receivedBytes = 0;