@tonyclaw/agent-inspector 3.0.29 → 3.0.31

package/src/proxy/identityProxy.ts

@@ -1,6 +1,7 @@
 import http from "node:http";
 import { Buffer } from "node:buffer";
 import { timingSafeEqual } from "node:crypto";
+import { isIP } from "node:net";
 import { lookupClientByPort } from "./socketTracker";
 
 const IDENTITY_HEADERS = {
@@ -10,6 +11,20 @@ const IDENTITY_HEADERS = {
   projectFolder: "x-agent-inspector-client-project-folder",
 } as const;
 
+const IDENTITY_HEADER_PREFIX = "x-agent-inspector-";
+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;
+
+type IdentityProxyRuntimeState = {
+  acceptingRequests: boolean;
+  activeRequests: number;
+  drainWaiters: Set<() => void>;
+};
+
+const identityProxyRuntimeStates = new WeakMap<http.Server, IdentityProxyRuntimeState>();
+
 const REQUEST_HOP_BY_HOP = new Set([
   "connection",
   "keep-alive",
@@ -33,6 +48,26 @@ const RESPONSE_HOP_BY_HOP = new Set([
   "upgrade",
 ]);
 
+const BASE_SECURITY_HEADERS = {
+  "permissions-policy": "camera=(), microphone=(), geolocation=()",
+  "referrer-policy": "no-referrer",
+  "x-content-type-options": "nosniff",
+  "x-frame-options": "DENY",
+} as const;
+
+const DOCUMENT_CONTENT_SECURITY_POLICY = [
+  "default-src 'self'",
+  "base-uri 'self'",
+  "connect-src 'self'",
+  "font-src 'self' data:",
+  "frame-ancestors 'none'",
+  "img-src 'self' data: blob:",
+  "object-src 'none'",
+  "script-src 'self' 'unsafe-inline'",
+  "style-src 'self' 'unsafe-inline'",
+  "worker-src 'self' blob:",
+].join("; ");
+
 export type IdentityProxyOptions = {
   /** Public port to listen on. Clients point at this. */
   listenPort: number;
@@ -48,6 +83,16 @@ export type IdentityProxyOptions = {
   allowRemoteControl?: boolean;
   /** Optional Bearer token for remote control-plane API clients. */
   controlToken?: string;
+  /** Dedicated credential for non-loopback model-proxy clients. */
+  proxyToken?: string;
+  /** Temporary compatibility escape hatch for legacy unauthenticated remote proxy clients. */
+  allowUnauthenticatedRemoteProxy?: boolean;
+  /** Additional public hostnames accepted by the ingress Host boundary. */
+  trustedHosts?: readonly string[];
+  /** Maximum declared or streamed request body size. */
+  maxRequestBytes?: number;
+  /** Deadline for receiving and forwarding one request body. */
+  requestTimeoutMs?: number;
 };
 
 function isLoopbackPeer(address: string | undefined): boolean {
@@ -74,13 +119,100 @@ function tokensMatch(received: string | null, expected: string | undefined): boo
   );
 }
 
+function firstHeader(value: string | readonly string[] | undefined): string | undefined {
+  return typeof value === "string" ? value : value?.[0];
+}
+
+function normalizedHostname(value: string): string | null {
+  const candidate = value.trim();
+  if (candidate.length === 0) return null;
+  try {
+    return new URL(`http://${candidate}`).hostname.toLowerCase().replace(/^\[|]$/g, "");
+  } catch {
+    return null;
+  }
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "::1" || hostname.startsWith("127.");
+}
+
+export function isTrustedIdentityProxyHost(
+  host: string | undefined,
+  options: Pick<IdentityProxyOptions, "listenHost" | "trustedHosts">,
+): boolean {
+  if (host === undefined) return false;
+  const hostname = normalizedHostname(host);
+  if (hostname === null) return false;
+  if (isLoopbackHostname(hostname) || isIP(hostname) !== 0) return true;
+
+  const listenHostname = normalizedHostname(options.listenHost);
+  if (listenHostname !== null && hostname === listenHostname) return true;
+  return (options.trustedHosts ?? []).some(
+    (trustedHost) => normalizedHostname(trustedHost) === hostname,
+  );
+}
+
+function isSafeMethod(method: string | undefined): boolean {
+  const normalized = (method ?? "GET").toUpperCase();
+  return normalized === "GET" || normalized === "HEAD" || normalized === "OPTIONS";
+}
+
+function isPublicHealthPath(pathname: string): boolean {
+  return pathname === "/livez" || pathname === "/readyz" || pathname === "/api/health";
+}
+
+function configuredPositiveInteger(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+function declaredContentLength(value: string | undefined): number | null {
+  if (value === undefined) return null;
+  if (!/^\d+$/.test(value)) return Number.NaN;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : Number.NaN;
+}
+
+export function isBrowserMutationAllowed(input: {
+  path: string;
+  method?: string;
+  host?: string;
+  origin?: string;
+  secFetchSite?: string;
+  csrfToken?: string;
+}): boolean {
+  if (isSafeMethod(input.method)) return true;
+  const pathname = new URL(input.path, "http://localhost").pathname;
+  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 (input.origin !== undefined) {
+    try {
+      const originHost = new URL(input.origin).host.toLowerCase();
+      if (originHost !== input.host?.toLowerCase()) return false;
+    } catch {
+      return false;
+    }
+  }
+  return input.csrfToken === "1";
+}
+
 export function isIdentityProxyRequestAllowed(input: {
   path: string;
   remoteAddress?: string;
   authorization?: string;
+  proxyAuthorization?: string;
+  proxyTokenHeader?: string;
   options: Pick<
     IdentityProxyOptions,
-    "restrictRemoteControl" | "allowRemoteControl" | "controlToken"
+    | "restrictRemoteControl"
+    | "allowRemoteControl"
+    | "controlToken"
+    | "proxyToken"
+    | "allowUnauthenticatedRemoteProxy"
   >;
 }): boolean {
   if (input.options.restrictRemoteControl !== true) return true;
@@ -88,8 +220,12 @@ export function isIdentityProxyRequestAllowed(input: {
   if (isLoopbackPeer(input.remoteAddress)) return true;
 
   const pathname = new URL(input.path, "http://localhost").pathname;
-  if (pathname === "/proxy" || pathname.startsWith("/proxy/")) return true;
-  if (pathname === "/api/health") return true;
+  if (pathname === "/proxy" || pathname.startsWith("/proxy/")) {
+    if (input.options.allowUnauthenticatedRemoteProxy === true) return true;
+    const proxyCredential = bearerToken(input.proxyAuthorization) ?? input.proxyTokenHeader ?? null;
+    return tokensMatch(proxyCredential, input.options.proxyToken);
+  }
+  if (isPublicHealthPath(pathname)) return true;
   return tokensMatch(bearerToken(input.authorization), input.options.controlToken);
 }
 
@@ -119,6 +255,12 @@ export function isIdentityProxyRequestAllowed(input: {
 export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.Server> {
   return new Promise((resolve, reject) => {
     const server = http.createServer();
+    const runtimeState: IdentityProxyRuntimeState = {
+      acceptingRequests: true,
+      activeRequests: 0,
+      drainWaiters: new Set(),
+    };
+    identityProxyRuntimeStates.set(server, runtimeState);
     // Eagerly resolve client identity on `connection` — at that point the
     // socket is fresh and the OS connection table still lists it as
     // ESTABLISHED. By the time `request` fires (let alone after we finish
@@ -131,6 +273,30 @@ export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.
       }
     });
     server.on("request", (req, res) => {
+      if (!runtimeState.acceptingRequests) {
+        res.writeHead(503, {
+          "content-type": "application/json; charset=utf-8",
+          "cache-control": "no-store",
+          connection: "close",
+          "retry-after": "5",
+        });
+        res.end(JSON.stringify({ error: "Agent Inspector is shutting down" }));
+        req.resume();
+        return;
+      }
+
+      runtimeState.activeRequests += 1;
+      let released = false;
+      const release = (): void => {
+        if (released) return;
+        released = true;
+        runtimeState.activeRequests = Math.max(0, runtimeState.activeRequests - 1);
+        if (runtimeState.activeRequests !== 0) return;
+        for (const resolveDrain of runtimeState.drainWaiters) resolveDrain();
+        runtimeState.drainWaiters.clear();
+      };
+      res.once("finish", release);
+      res.once("close", release);
       void handleRequest(req, res, options).catch((err: unknown) => {
         const message = err instanceof Error ? err.message : String(err);
         if (!res.headersSent) {
@@ -147,16 +313,78 @@ export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.
   });
 }
 
+export function stopIdentityProxyAdmission(server: http.Server): void {
+  const state = identityProxyRuntimeStates.get(server);
+  if (state !== undefined) state.acceptingRequests = false;
+}
+
+export async function waitForIdentityProxyDrain(server: http.Server): Promise<void> {
+  const state = identityProxyRuntimeStates.get(server);
+  if (state === undefined || state.activeRequests === 0) return;
+  await new Promise<void>((resolve) => {
+    state.drainWaiters.add(resolve);
+  });
+}
+
+export async function closeIdentityProxyGracefully(server: http.Server): Promise<void> {
+  stopIdentityProxyAdmission(server);
+  const closed = new Promise<void>((resolve) => {
+    if (!server.listening) {
+      resolve();
+      return;
+    }
+    server.close(() => resolve());
+  });
+  await Promise.all([closed, waitForIdentityProxyDrain(server)]);
+}
+
+export function forceCloseIdentityProxy(server: http.Server): void {
+  stopIdentityProxyAdmission(server);
+  server.closeAllConnections();
+  server.close();
+}
+
 async function handleRequest(
   req: http.IncomingMessage,
   res: http.ServerResponse,
   options: IdentityProxyOptions,
 ): Promise<void> {
+  if (!isTrustedIdentityProxyHost(req.headers.host, options)) {
+    res.writeHead(400, {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(JSON.stringify({ error: "Untrusted Host header" }));
+    req.resume();
+    return;
+  }
+
+  if (
+    !isBrowserMutationAllowed({
+      path: req.url ?? "/",
+      method: req.method,
+      host: req.headers.host,
+      origin: req.headers.origin,
+      secFetchSite: firstHeader(req.headers["sec-fetch-site"]),
+      csrfToken: firstHeader(req.headers[CSRF_HEADER]),
+    })
+  ) {
+    res.writeHead(403, {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(JSON.stringify({ error: "Browser mutation requires same-origin CSRF proof" }));
+    req.resume();
+    return;
+  }
+
   if (
     !isIdentityProxyRequestAllowed({
       path: req.url ?? "/",
       remoteAddress: req.socket.remoteAddress,
       authorization: req.headers.authorization,
+      proxyAuthorization: req.headers["proxy-authorization"],
+      proxyTokenHeader: firstHeader(req.headers[PROXY_TOKEN_HEADER]),
       options,
     })
   ) {
@@ -166,10 +394,10 @@ async function handleRequest(
     });
     res.end(
       JSON.stringify({
-        error:
-          "Remote control-plane access is disabled. Use the proxy endpoint or connect locally.",
+        error: "Remote access requires a credential scoped to this endpoint.",
       }),
     );
+    req.resume();
     return;
   }
 
@@ -185,17 +413,37 @@ async function handleRequest(
     }
   }
 
-  // Buffer the request body — TanStack Start needs the raw bytes intact
-  // for SSE/streaming endpoints, so we can't decode-and-re-encode.
-  const chunks: Buffer[] = [];
-  for await (const chunk of req) {
-    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : toBuffer(chunk));
+  // Validate declared size before any body allocation, then forward the raw
+  // stream with backpressure while enforcing the actual-byte budget below.
+  const maxRequestBytes = configuredPositiveInteger(
+    options.maxRequestBytes,
+    DEFAULT_MAX_REQUEST_BYTES,
+  );
+  const contentLength = declaredContentLength(req.headers["content-length"]);
+  if (contentLength !== null && (!Number.isFinite(contentLength) || contentLength < 0)) {
+    res.writeHead(400, {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(JSON.stringify({ error: "Invalid Content-Length header" }));
+    req.resume();
+    return;
+  }
+  if (contentLength !== null && contentLength > maxRequestBytes) {
+    res.writeHead(413, {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(JSON.stringify({ error: `Request body exceeds ${String(maxRequestBytes)} bytes` }));
+    req.resume();
+    return;
   }
-  const body = Buffer.concat(chunks);
 
   const upstreamHeaders: Record<string, string | string[]> = {};
   for (const [name, value] of Object.entries(req.headers)) {
-    if (REQUEST_HOP_BY_HOP.has(name.toLowerCase())) continue;
+    const lowerName = name.toLowerCase();
+    if (REQUEST_HOP_BY_HOP.has(lowerName)) continue;
+    if (lowerName.startsWith(IDENTITY_HEADER_PREFIX)) continue;
     if (value === undefined) continue;
     upstreamHeaders[name] = value;
   }
@@ -212,6 +460,11 @@ async function handleRequest(
     }
   }
 
+  let terminal = false;
+  const requestTimeoutMs = configuredPositiveInteger(
+    options.requestTimeoutMs,
+    DEFAULT_REQUEST_TIMEOUT_MS,
+  );
   const proxyReq = http.request(
     {
       hostname: options.upstreamHost,
@@ -221,24 +474,90 @@ async function handleRequest(
       headers: upstreamHeaders,
     },
     (proxyRes) => {
+      if (terminal) {
+        proxyRes.resume();
+        return;
+      }
       const outHeaders: Record<string, string | string[]> = {};
       for (const [name, value] of Object.entries(proxyRes.headers)) {
         if (RESPONSE_HOP_BY_HOP.has(name.toLowerCase())) continue;
         if (value === undefined) continue;
         outHeaders[name] = value;
       }
+      for (const [name, value] of Object.entries(BASE_SECURITY_HEADERS)) {
+        outHeaders[name] = value;
+      }
+      const contentType = firstHeader(proxyRes.headers["content-type"]);
+      if (contentType?.toLowerCase().includes("text/html") === true) {
+        outHeaders["content-security-policy"] = DOCUMENT_CONTENT_SECURITY_POLICY;
+      }
       res.writeHead(proxyRes.statusCode ?? 502, outHeaders);
       proxyRes.pipe(res);
     },
   );
+  const deadline = setTimeout(() => {
+    failRequest(408, "Request body deadline exceeded");
+  }, requestTimeoutMs);
+  deadline.unref();
+
+  function clearDeadline(): void {
+    clearTimeout(deadline);
+  }
+
+  function failRequest(status: number, error: string): void {
+    if (terminal) return;
+    terminal = true;
+    clearDeadline();
+    proxyReq.destroy();
+    if (res.headersSent) {
+      res.destroy();
+    } else {
+      res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+      });
+      res.end(JSON.stringify({ error }));
+    }
+    req.resume();
+  }
+
   proxyReq.on("error", (err) => {
+    if (terminal) return;
+    terminal = true;
+    clearDeadline();
     if (!res.headersSent) {
       res.writeHead(502, { "content-type": "text/plain" });
     }
     res.end(`Upstream error: ${err.message}`);
   });
-  if (body.length > 0) proxyReq.write(body);
-  proxyReq.end();
+  proxyReq.on("drain", () => req.resume());
+  res.once("close", () => {
+    clearDeadline();
+    if (!res.writableEnded) proxyReq.destroy();
+  });
+
+  let receivedBytes = 0;
+  req.on("data", (chunk: unknown) => {
+    if (terminal) return;
+    const buffer = toBuffer(chunk);
+    receivedBytes += buffer.byteLength;
+    if (receivedBytes > maxRequestBytes) {
+      failRequest(413, `Request body exceeds ${String(maxRequestBytes)} bytes`);
+      return;
+    }
+    if (buffer.byteLength > 0 && !proxyReq.write(buffer)) req.pause();
+  });
+  req.on("end", () => {
+    if (terminal) return;
+    clearDeadline();
+    proxyReq.end();
+  });
+  req.on("aborted", () => {
+    failRequest(400, "Client aborted request body");
+  });
+  req.on("error", () => {
+    failRequest(400, "Request body stream failed");
+  });
 }
 
 // `Readable` chunks in Node are typed as `any` (they can be Buffer | string

package/src/proxy/logFinalizer.ts

@@ -1,12 +1,18 @@
 import { Buffer } from "node:buffer";
-import { readFileSync, rmSync, statSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { Worker } from "node:worker_threads";
 import { writeChunks } from "./chunkStorage";
 import { formatForPath } from "./formats";
 import { appendLogEntry, logger } from "./logger";
 import type { RawStreamSource } from "./rawStreamCapture";
 import type { CapturedLog } from "./schemas";
-import { getSessionProcess, isSessionProcessAvailable } from "./sessionProcess";
+import {
+  getSessionProcess,
+  getSessionProcessPendingCount,
+  isSessionProcessAvailable,
+} from "./sessionProcess";
 import { finalizeLogUpdate } from "./store";
 import { computeTokensPerSecond } from "./streamTiming";
 import { analyzeToolSchemaWarnings } from "./toolSchemaWarnings";
@@ -500,9 +506,8 @@ export function commitFinalizeLogResult(result: FinalizeLogResult): void {
 //   "process" → per-session child process (max isolation)
 //   "worker"  → shared Worker Thread pool
 //   "inline"  → synchronous in-process (debug / fallback)
-// The default is "process" only when its worker entry exists. Production
-// bundles that do not emit the standalone worker entry fall back to "inline"
-// instead of repeatedly spawning a failing child process.
+// The default is the bounded shared Worker pool when its entry exists. The
+// per-session process backend remains an explicit isolation option only.
 // For backward compatibility, FINALIZER_USE_WORKER=0 forces "inline".
 
 const RUNTIME: "process" | "worker" | "inline" = (() => {
@@ -511,6 +516,7 @@ const RUNTIME: "process" | "worker" | "inline" = (() => {
   if (mode === "process") return "process";
   if (mode === "worker") return "worker";
   if (mode === "inline") return "inline";
+  if (isLogFinalizerWorkerAvailable()) return "worker";
   return isSessionProcessAvailable() ? "process" : "inline";
 })();
 
@@ -558,11 +564,51 @@ const _pending = new Map<
 let _nextWorker = 0;
 let _jobSeq = 0;
 
+function resolveLogFinalizerWorkerUrl(): URL {
+  const workerDir = process.env["AGENT_INSPECTOR_WORKER_DIR"];
+  if (workerDir !== undefined && workerDir.trim().length > 0) {
+    const builtWorkerPath = join(workerDir, "logFinalizer.worker.js");
+    if (existsSync(builtWorkerPath)) return pathToFileURL(builtWorkerPath);
+  }
+  return new URL("./logFinalizer.worker.ts", import.meta.url);
+}
+
+export function isLogFinalizerWorkerAvailable(): boolean {
+  return existsSync(fileURLToPath(resolveLogFinalizerWorkerUrl()));
+}
+
+export type FinalizerRuntimeHealth = {
+  runtime: "process" | "worker" | "inline";
+  artifactAvailable: boolean;
+  activeWorkers: number | null;
+  configuredWorkers: number;
+  pendingJobs: number;
+};
+
+/** Safe aggregate state used by readiness checks; it contains no job or session data. */
+export function getFinalizerRuntimeHealth(): FinalizerRuntimeHealth {
+  const artifactAvailable =
+    RUNTIME === "worker"
+      ? isLogFinalizerWorkerAvailable()
+      : RUNTIME === "process"
+        ? isSessionProcessAvailable()
+        : isLogFinalizerWorkerAvailable() || isSessionProcessAvailable();
+  const activeWorkers =
+    _workers === null ? null : _workers.filter((worker) => worker.threadId > 0).length;
+  return {
+    runtime: RUNTIME,
+    artifactAvailable,
+    activeWorkers,
+    configuredWorkers: WORKER_COUNT,
+    pendingJobs: RUNTIME === "process" ? getSessionProcessPendingCount() : _pending.size,
+  };
+}
+
 function getWorkers(): Worker[] {
   if (_workers !== null) return _workers;
   _workers = [];
   for (let i = 0; i < WORKER_COUNT; i++) {
-    const w = new Worker(new URL("./logFinalizer.worker.ts", import.meta.url));
+    const w = new Worker(resolveLogFinalizerWorkerUrl());
     w.on("message", (raw: unknown) => {
       if (!isPlainRecord(raw)) {
         logger.error("[logFinalizer] Received malformed IPC message from worker, discarding");
@@ -627,3 +673,24 @@ export function executeFinalizeLogJob(job: FinalizeLogJob): Promise<void> {
     return undefined;
   });
 }
+
+function detachLogFinalizerWorkers(): Worker[] {
+  const workers = _workers ?? [];
+  _workers = null;
+  for (const [id, entry] of _pending) {
+    _pending.delete(id);
+    entry.reject(new Error("Log finalizer worker pool is shutting down"));
+  }
+  return workers;
+}
+
+/** Close the shared worker pool after queued session tasks have drained. */
+export async function closeLogFinalizerWorkers(): Promise<void> {
+  const workers = detachLogFinalizerWorkers();
+  await Promise.all(workers.map((worker) => worker.terminate()));
+}
+
+/** Best-effort immediate worker teardown used when the shutdown deadline expires. */
+export function forceCloseLogFinalizerWorkers(): void {
+  for (const worker of detachLogFinalizerWorkers()) void worker.terminate();
+}