@tonyclaw/agent-inspector 3.0.26 → 3.0.27

package/src/proxy/constants.ts

@@ -26,12 +26,29 @@ export const HEADER_HOST = "host";
 // Auth header types
 export const AUTH_HEADER_X_API_KEY = "x-api-key";
 
+// Headers whose values contain secrets (API keys, bearer tokens).
+// These are redacted before being written to logs when captureMode is "full".
+export const SENSITIVE_HEADERS = new Set([
+  HEADER_AUTHORIZATION,
+  HEADER_X_API_KEY,
+  "cookie",
+  "set-cookie",
+  "proxy-authorization",
+]);
+
 // Content types
 export const CONTENT_TYPE_EVENT_STREAM = "text/event-stream";
 
 // Response status
 export const STATUS_FORBIDDEN = 403;
 export const STATUS_BAD_GATEWAY = 502;
+export const STATUS_PAYLOAD_TOO_LARGE = 413;
+
+// Maximum request body size accepted by the proxy (50 MB).
+// Legitimate LLM API requests (system prompts, conversation history, tool
+// definitions) are well under this limit; larger payloads are almost certainly
+// malicious or malformed.
+export const MAX_REQUEST_BODY_BYTES = 50 * 1024 * 1024;
 
 // Standard/safe headers to preserve when forwarding to upstream.
 // NOTE: Authorization is intentionally excluded to prevent client auth tokens from leaking.

package/src/proxy/formats/anthropic/handler.ts

@@ -13,7 +13,11 @@ export const AnthropicFormatHandler: FormatHandler = {
       if (result.success) {
         return {
           model: result.data.model,
-          sessionId: result.data.metadata?.user_id ?? headers?.get("x-session-affinity") ?? null,
+          sessionId:
+            result.data.metadata?.user_id ??
+            headers?.get("x-agent-inspector-session-id") ??
+            headers?.get("x-session-affinity") ??
+            null,
         };
       }
       return null;

package/src/proxy/formats/anthropic/schemas.ts

@@ -1,12 +1,6 @@
 export {
   AnthropicRequestSchema,
   AnthropicResponseSchema,
-  InspectorRequestSchema,
-  InspectorResponseSchema,
   SseEventSchema,
 } from "../../../contracts/anthropic";
-export type {
-  AnthropicResponse,
-  InspectorResponse,
-  ResponseContentBlockType,
-} from "../../../contracts/anthropic";
+export type { AnthropicResponse, ResponseContentBlockType } from "../../../contracts/anthropic";

package/src/proxy/formats/index.ts

@@ -9,5 +9,5 @@ import "./openai/zhipuProvider";
 import "./openai/alibabaProvider";
 
 export type { FormatHandler, ParsedRequest } from "./handler";
-export { apiFormatForPath, formatRegistry, formatForPath, requestFormatForPath } from "./registry";
+export { apiFormatForPath, formatRegistry, formatForPath } from "./registry";
 export { registry } from "./providers";

package/src/proxy/formats/openai/schemas.ts

@@ -20,9 +20,6 @@ export {
 } from "../../../contracts/openai";
 export type {
   OpenAIResponse,
-  OpenAIResponsesRequest,
   OpenAIResponsesResponse,
-  OpenAIResponsesSSEvent,
-  OpenAIResponsesOutputItem,
   OpenAIToolCall,
 } from "../../../contracts/openai";

package/src/proxy/formats/registry.ts

@@ -72,9 +72,6 @@ export function apiFormatForPath(path: string): ApiFormat {
   return formatRegistry.getApiFormatByPath(path) ?? "unknown";
 }
 
-/** Backward-compatible alias for older internal imports. */
-export const requestFormatForPath = apiFormatForPath;
-
 // Register known paths
 formatRegistry.registerPath(PATH_V1_MESSAGES, "anthropic");
 formatRegistry.registerPath(PATH_V1_CHAT_COMPLETIONS, "openai");

package/src/proxy/handler.ts

@@ -15,12 +15,19 @@ import {
   HEADER_CONTENT_ENCODING,
   HEADER_CONTENT_LENGTH,
   CONTENT_TYPE_EVENT_STREAM,
+  SENSITIVE_HEADERS,
   STATUS_FORBIDDEN,
   STATUS_BAD_GATEWAY,
+  STATUS_PAYLOAD_TOO_LARGE,
+  MAX_REQUEST_BODY_BYTES,
 } from "./constants";
 import { getConfig } from "./config";
+import { safeFetch } from "../lib/safeFetch";
+
+const ALLOW_LOOPBACK = process.env["AGENT_INSPECTOR_ALLOW_LOOPBACK"] === "1";
 import { stripClaudeCodeBillingHeader } from "./claudeCodeStrip";
 import { stripOpenAIOrphanToolMessages } from "./openaiOrphanToolStrip";
+import { maskApiKey } from "../lib/mask";
 import { buildFileLogEntry, type FinalizeLogJob } from "./logFinalizer";
 import { enqueueFinalizeLogJob } from "./sessionRuntime";
 import { RawStreamCapture } from "./rawStreamCapture";
@@ -49,7 +56,8 @@ function buildProxyHeaders(
 
   if (rawHeaders !== undefined) {
     originalHeaders.forEach((value, key) => {
-      rawHeaders[key.toLowerCase()] = value;
+      const lowerKey = key.toLowerCase();
+      rawHeaders[lowerKey] = SENSITIVE_HEADERS.has(lowerKey) ? maskApiKey(value) : value;
     });
   }
 
@@ -91,6 +99,50 @@ function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+type BodyReadResult = { ok: true; body: string | null } | { ok: false; reason: "too-large" };
+
+/**
+ * Reads the request body as text, enforcing a maximum byte limit to prevent
+ * memory exhaustion from oversized payloads. Returns the body string, or null
+ * if the request has no body.
+ */
+async function readBodyWithLimit(req: Request, limitBytes: number): Promise<BodyReadResult> {
+  if (req.body === null || req.method === "GET" || req.method === "HEAD") {
+    return { ok: true, body: null };
+  }
+
+  // Fast path: if Content-Length is present and exceeds the limit, reject
+  // without reading any bytes.
+  const contentLengthHeader = req.headers.get(HEADER_CONTENT_LENGTH);
+  if (contentLengthHeader !== null) {
+    const declared = Number.parseInt(contentLengthHeader, 10);
+    if (Number.isFinite(declared) && declared > limitBytes) {
+      return { ok: false, reason: "too-large" };
+    }
+  }
+
+  const reader = req.body.getReader();
+  const decoder = new TextDecoder();
+  const chunks: string[] = [];
+  let totalBytes = 0;
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      totalBytes += value.byteLength;
+      if (totalBytes > limitBytes) {
+        return { ok: false, reason: "too-large" };
+      }
+      chunks.push(decoder.decode(value, { stream: true }));
+    }
+    chunks.push(decoder.decode());
+    return { ok: true, body: chunks.join("") };
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 function scheduleLogFinalization(job: FinalizeLogJob): void {
   void enqueueFinalizeLogJob(job).catch((err) => {
     logger.error(
@@ -230,11 +282,16 @@ export async function handleProxy(req: Request): Promise<Response> {
   const url = new URL(req.url);
   const parsed = parseRequestPath(req, url);
 
-  // Read body only after cheap path checks
-  let requestBody: string | null = null;
-  if (req.body && req.method !== "GET" && req.method !== "HEAD") {
-    requestBody = await req.text();
+  // Read body with a size limit to prevent memory exhaustion from oversized
+  // payloads. The limit is generous (50 MB) — legitimate LLM API requests are
+  // well under this, but a malicious client could send a multi-GB body to OOM
+  // the proxy.
+  const bodyRead = await readBodyWithLimit(req, MAX_REQUEST_BODY_BYTES);
+  if (!bodyRead.ok) {
+    logger.warn(`[handler] Rejected oversized request body: ${req.method} ${parsed.apiPath}`);
+    return new Response("Request body too large", { status: STATUS_PAYLOAD_TOO_LARGE });
   }
+  const requestBody = bodyRead.body;
 
   // Opt-in: strip Claude Code's synthetic billing-header text block from the
   // system prompt. Only runs for Anthropic-format requests (those whose path
@@ -284,6 +341,7 @@ export async function handleProxy(req: Request): Promise<Response> {
   const route = describeApiRoute(parsed.apiPath);
   const upstreamBase = selectUpstreamBase(route, matchedProviderConfig);
   const upstreamUrl = buildUpstreamUrl(upstreamBase, parsed.normalizedPath);
+
   const startTime = Date.now();
 
   const captureFullDetails = config.captureMode === "full";
@@ -324,7 +382,8 @@ export async function handleProxy(req: Request): Promise<Response> {
     : undefined;
   if (upstreamHeadersObj !== undefined) {
     upstreamHeaders.forEach((value, key) => {
-      upstreamHeadersObj[key.toLowerCase()] = value;
+      const lowerKey = key.toLowerCase();
+      upstreamHeadersObj[lowerKey] = SENSITIVE_HEADERS.has(lowerKey) ? maskApiKey(value) : value;
     });
   }
   const log = await createLog(
@@ -343,12 +402,32 @@ export async function handleProxy(req: Request): Promise<Response> {
 
   let upstreamRes: Response;
   try {
-    upstreamRes = await fetch(upstreamUrl, {
-      method: req.method,
-      headers: upstreamHeaders,
-      body: bodyToForward,
-      signal: req.signal,
-    });
+    const fetchResult = await safeFetch(
+      upstreamUrl,
+      {
+        method: req.method,
+        headers: upstreamHeaders,
+        body: bodyToForward,
+        signal: req.signal,
+      },
+      { allowLoopback: ALLOW_LOOPBACK },
+    );
+    if (!fetchResult.ok) {
+      const status = fetchResult.kind === "network-policy" ? STATUS_FORBIDDEN : STATUS_BAD_GATEWAY;
+      logger.warn(`[handler] Safe fetch blocked ${upstreamUrl}: ${fetchResult.reason}`);
+      log.elapsedMs = Date.now() - startTime;
+      log.responseStatus = status;
+      log.responseText = fetchResult.reason;
+      appendLogEntry({ ...buildFileLogEntry(log, upstreamUrl), error: fetchResult.reason });
+      finalizeLogUpdate(log);
+      return new Response(
+        fetchResult.kind === "network-policy"
+          ? "Forbidden: upstream URL is not permitted"
+          : "Proxy error: upstream redirects are not permitted",
+        { status },
+      );
+    }
+    upstreamRes = fetchResult.response;
   } catch (err) {
     log.elapsedMs = Date.now() - startTime;
     // Check if it was a client abort (not a proxy error)

package/src/proxy/identityProxy.ts

@@ -1,5 +1,6 @@
 import http from "node:http";
 import { Buffer } from "node:buffer";
+import { timingSafeEqual } from "node:crypto";
 import { lookupClientByPort } from "./socketTracker";
 
 const IDENTITY_HEADERS = {
@@ -35,12 +36,63 @@ const RESPONSE_HOP_BY_HOP = new Set([
 export type IdentityProxyOptions = {
   /** Public port to listen on. Clients point at this. */
   listenPort: number;
+  /** Interface exposed to clients. Defaults are chosen by the CLI. */
+  listenHost: string;
   /** Host the upstream TanStack Start server listens on. */
   upstreamHost: string;
   /** Port the upstream TanStack Start server listens on. */
   upstreamPort: number;
+  /** Restrict non-proxy routes for clients outside the local machine. */
+  restrictRemoteControl?: boolean;
+  /** Explicitly expose UI, REST, and MCP to remote peers. */
+  allowRemoteControl?: boolean;
+  /** Optional Bearer token for remote control-plane API clients. */
+  controlToken?: string;
 };
 
+function isLoopbackPeer(address: string | undefined): boolean {
+  if (address === undefined) return false;
+  const normalized = address.toLowerCase();
+  return (
+    normalized === "::1" || normalized.startsWith("127.") || normalized.startsWith("::ffff:127.")
+  );
+}
+
+function bearerToken(authorization: string | undefined): string | null {
+  if (authorization === undefined) return null;
+  const match = /^Bearer\s+(.+)$/i.exec(authorization.trim());
+  return match?.[1] ?? null;
+}
+
+function tokensMatch(received: string | null, expected: string | undefined): boolean {
+  if (received === null || expected === undefined || expected === "") return false;
+  const receivedBuffer = Buffer.from(received);
+  const expectedBuffer = Buffer.from(expected);
+  return (
+    receivedBuffer.byteLength === expectedBuffer.byteLength &&
+    timingSafeEqual(receivedBuffer, expectedBuffer)
+  );
+}
+
+export function isIdentityProxyRequestAllowed(input: {
+  path: string;
+  remoteAddress?: string;
+  authorization?: string;
+  options: Pick<
+    IdentityProxyOptions,
+    "restrictRemoteControl" | "allowRemoteControl" | "controlToken"
+  >;
+}): boolean {
+  if (input.options.restrictRemoteControl !== true) return true;
+  if (input.options.allowRemoteControl === true) return true;
+  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;
+  return tokensMatch(bearerToken(input.authorization), input.options.controlToken);
+}
+
 /**
  * Start a tiny native Node HTTP server that:
  *   1. Reads the client connection's source port (`req.socket.remotePort`).
@@ -88,7 +140,7 @@ export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.
       });
     });
     server.once("error", reject);
-    server.listen(options.listenPort, () => {
+    server.listen(options.listenPort, options.listenHost, () => {
       server.removeListener("error", reject);
       resolve(server);
     });
@@ -100,6 +152,27 @@ async function handleRequest(
   res: http.ServerResponse,
   options: IdentityProxyOptions,
 ): Promise<void> {
+  if (
+    !isIdentityProxyRequestAllowed({
+      path: req.url ?? "/",
+      remoteAddress: req.socket.remoteAddress,
+      authorization: req.headers.authorization,
+      options,
+    })
+  ) {
+    res.writeHead(403, {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(
+      JSON.stringify({
+        error:
+          "Remote control-plane access is disabled. Use the proxy endpoint or connect locally.",
+      }),
+    );
+    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;

package/src/proxy/logImporter.ts

@@ -1,4 +1,5 @@
 import { basename } from "node:path";
+import { Buffer } from "node:buffer";
 import JSZip from "jszip";
 import { z } from "zod";
 import {
@@ -14,6 +15,17 @@ import { analyzeToolSchemaWarnings } from "./toolSchemaWarnings";
 
 export type ImportedLogDraft = Omit<CapturedLog, "id">;
 
+// Maximum compressed size for a ZIP import (200 MB). Legitimate exports are
+// well under this; anything larger is almost certainly malicious.
+const MAX_ZIP_COMPRESSED_BYTES = 200 * 1024 * 1024;
+
+// Maximum total decompressed bytes within a single ZIP (500 MB). Prevents a
+// small "ZIP bomb" archive (a few MB compressed → hundreds of GB decompressed)
+// from exhausting memory. The ratio is checked against the compressed size of
+// the *archive*, not per-entry, since the archive size is the only hard cap
+// available before decompression begins.
+const MAX_ZIP_DECOMPRESSED_BYTES = 500 * 1024 * 1024;
+
 export type ParsedLogImport =
   | {
       ok: true;
@@ -288,13 +300,31 @@ function legacyDraftFromParts(input: {
   });
 }
 
-async function readZipText(zip: JSZip, path: string): Promise<string | null> {
+/**
+ * Reads a file from the ZIP as UTF-8 text. Decrements `remaining.bytes` by the
+ * decoded byte size; callers check `remaining.bytes < 0` after the call to
+ * detect that the cumulative decompressed size has blown the budget (a
+ * zip-bomb signal). We do NOT throw on budget exceeded because the project's
+ * lint rules forbid throwing inside non-CLI modules — using a mutable
+ * counter keeps the budget check declarative at every call site.
+ */
+async function readZipText(
+  zip: JSZip,
+  path: string,
+  remaining: { bytes: number },
+): Promise<string | null> {
   const file = zip.file(path);
-  return file === null ? null : await file.async("text");
+  if (file === null) return null;
+  const text = await file.async("text");
+  remaining.bytes -= Buffer.byteLength(text, "utf8");
+  return text;
 }
 
-async function readManifest(zip: JSZip): Promise<ParsedManifest | null> {
-  const text = await readZipText(zip, "manifest.json");
+async function readManifest(
+  zip: JSZip,
+  remaining: { bytes: number },
+): Promise<ParsedManifest | null> {
+  const text = await readZipText(zip, "manifest.json", remaining);
   const parsed = ManifestSchema.safeParse(parseJson(text));
   return parsed.success ? parsed.data : null;
 }
@@ -357,10 +387,24 @@ function validateManifestVersion(manifest: ParsedManifest | null):
   return { ok: true, warning: null };
 }
 
+function bombError(warnings: string[] = []): ParsedLogImport {
+  return {
+    ok: false,
+    message: `Archive decompresses to more than ${MAX_ZIP_DECOMPRESSED_BYTES} bytes.`,
+    warnings,
+  };
+}
+
 async function parseZipLogImport(data: Uint8Array): Promise<ParsedLogImport> {
   const warnings: string[] = [];
   const zip = await JSZip.loadAsync(data);
-  const manifest = await readManifest(zip);
+
+  // Tracks remaining budget for decompressed bytes. Decremented on every read;
+  // any read that pushes it below zero marks the archive as a zip bomb.
+  const remaining = { bytes: MAX_ZIP_DECOMPRESSED_BYTES };
+
+  const manifest = await readManifest(zip, remaining);
+  if (remaining.bytes < 0) return bombError();
   const versionCheck = validateManifestVersion(manifest);
   if (!versionCheck.ok) {
     return {
@@ -378,16 +422,22 @@ async function parseZipLogImport(data: Uint8Array): Promise<ParsedLogImport> {
     warnings.push("Imported redacted export. Secrets and some replay details may be unavailable.");
   }
 
-  const metadataText = await readZipText(zip, "logs.json");
+  const metadataText = await readZipText(zip, "logs.json", remaining);
+  if (remaining.bytes < 0) return bombError(warnings);
   const metadataLogs = metadataText === null ? null : parseJsonLogs(metadataText);
   const logs: ImportedLogDraft[] = [];
   let skipped = 0;
 
   if (metadataLogs !== null) {
     for (const log of metadataLogs) {
-      const requestText = await readZipText(zip, `#${String(log.id)}.Request.json`);
-      const responseText = await readZipText(zip, `#${String(log.id)}.Response.json`);
-      const streamingText = await readZipText(zip, `#${String(log.id)}.SSE.Response.json`);
+      const requestText = await readZipText(zip, `#${String(log.id)}.Request.json`, remaining);
+      const responseText = await readZipText(zip, `#${String(log.id)}.Response.json`, remaining);
+      const streamingText = await readZipText(
+        zip,
+        `#${String(log.id)}.SSE.Response.json`,
+        remaining,
+      );
+      if (remaining.bytes < 0) return bombError(warnings);
       logs.push(
         draftFromCapturedLog(
           log,
@@ -401,9 +451,14 @@ async function parseZipLogImport(data: Uint8Array): Promise<ParsedLogImport> {
   }
 
   for (const originalId of manifest?.logIds ?? []) {
-    const requestText = await readZipText(zip, `#${String(originalId)}.Request.json`);
-    const responseText = await readZipText(zip, `#${String(originalId)}.Response.json`);
-    const streamingText = await readZipText(zip, `#${String(originalId)}.SSE.Response.json`);
+    const requestText = await readZipText(zip, `#${String(originalId)}.Request.json`, remaining);
+    const responseText = await readZipText(zip, `#${String(originalId)}.Response.json`, remaining);
+    const streamingText = await readZipText(
+      zip,
+      `#${String(originalId)}.SSE.Response.json`,
+      remaining,
+    );
+    if (remaining.bytes < 0) return bombError(warnings);
     if (requestText === null && responseText === null && streamingText === null) {
       skipped += 1;
       continue;
@@ -469,9 +524,24 @@ export async function parseImportedLogFile(input: {
 }): Promise<ParsedLogImport> {
   try {
     if (looksLikeZip(input.data, input.fileName)) {
+      if (input.data.byteLength > MAX_ZIP_COMPRESSED_BYTES) {
+        return {
+          ok: false,
+          message: `Archive exceeds maximum size of ${MAX_ZIP_COMPRESSED_BYTES} bytes.`,
+          warnings: [],
+        };
+      }
       return await parseZipLogImport(input.data);
     }
 
+    if (input.data.byteLength > MAX_ZIP_COMPRESSED_BYTES) {
+      return {
+        ok: false,
+        message: `Import file exceeds maximum size of ${MAX_ZIP_COMPRESSED_BYTES} bytes.`,
+        warnings: [],
+      };
+    }
+
     return parseTextLogImport(new TextDecoder("utf-8").decode(input.data));
   } catch (err) {
     return {

package/src/proxy/logIndex.ts

@@ -5,6 +5,7 @@ import { createInterface } from "node:readline";
 import { Buffer } from "node:buffer";
 import { resolveLogDir, logger } from "./logger";
 import type { ApiFormat, CapturedLog } from "./schemas";
+import { textByteLength } from "../lib/unknown";
 import {
   findSqliteLogIndexEntry,
   getSqliteLogIndexMaxId,
@@ -82,10 +83,6 @@ function getIndexPath(): string {
 let cachedIndex: LogIndex | null = null;
 let sqliteBackfillScheduledMaxId = 0;
 
-function textByteLength(value: string | null): number | null {
-  return value === null ? null : Buffer.byteLength(value, "utf8");
-}
-
 export function createLogIndexEntryMetadata(log: CapturedLog): LogIndexEntryMetadata {
   return {
     sessionId: log.sessionId,