fix(dev): bound Claude usage debug fetches

vincentkoc · vincentkoc · commit d09eb437f261 · 2026-05-27T14:10:15.000+02:00
diff --git a/scripts/debug-claude-usage.ts b/scripts/debug-claude-usage.ts
@@ -5,14 +5,26 @@ import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { normalizeOptionalString } from "../src/shared/string-coerce.ts";
-import { maskIdentifier, previewForDevToolLog, redactHomePath } from "./lib/dev-tooling-safety.ts";
+import {
+  maskIdentifier,
+  parseStrictIntegerOption,
+  previewForDevToolLog,
+  redactHomePath,
+} from "./lib/dev-tooling-safety.ts";
 
 type Args = {
   agentId: string;
   reveal: boolean;
   sessionKey?: string;
 };
 
+type FetchOptions = {
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+};
+
+const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
+
 const mask = (value: string) => {
   return maskIdentifier(
     value,
@@ -80,17 +92,68 @@ const pickAnthropicTokens = (store: {
   return found;
 };
 
-const fetchAnthropicOAuthUsage = async (token: string) => {
-  const res = await fetch("https://api.anthropic.com/api/oauth/usage", {
-    headers: {
-      Authorization: `Bearer ${token}`,
-      Accept: "application/json",
-      "anthropic-version": "2023-06-01",
-      "anthropic-beta": "oauth-2025-04-20",
-      "User-Agent": "openclaw-debug",
-    },
+const resolveFetchTimeoutMs = (raw = process.env.OPENCLAW_DEBUG_CLAUDE_USAGE_FETCH_TIMEOUT_MS) => {
+  return parseStrictIntegerOption({
+    fallback: DEFAULT_FETCH_TIMEOUT_MS,
+    label: "OPENCLAW_DEBUG_CLAUDE_USAGE_FETCH_TIMEOUT_MS",
+    min: 1,
+    raw,
+  });
+};
+
+const withFetchTimeout = async <T>(
+  label: string,
+  timeoutMs: number,
+  run: (signal: AbortSignal) => Promise<T>,
+): Promise<T> => {
+  const controller = new AbortController();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<T>((_resolve, reject) => {
+    timeout = setTimeout(() => {
+      const error = new Error(`${label} exceeded timeout of ${timeoutMs}ms`);
+      reject(error);
+      controller.abort(error);
+    }, timeoutMs);
   });
-  const text = await res.text();
+  try {
+    return await Promise.race([run(controller.signal), timeoutPromise]);
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+};
+
+const fetchText = async (
+  label: string,
+  url: string,
+  init: RequestInit,
+  options: FetchOptions = {},
+) => {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const timeoutMs = options.timeoutMs ?? resolveFetchTimeoutMs();
+  return await withFetchTimeout(label, timeoutMs, async (signal) => {
+    const res = await fetchImpl(url, { ...init, signal });
+    const text = await res.text();
+    return { res, text };
+  });
+};
+
+const fetchAnthropicOAuthUsage = async (token: string, options: FetchOptions = {}) => {
+  const { res, text } = await fetchText(
+    "Anthropic OAuth usage request",
+    "https://api.anthropic.com/api/oauth/usage",
+    {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+        "anthropic-version": "2023-06-01",
+        "anthropic-beta": "oauth-2025-04-20",
+        "User-Agent": "openclaw-debug",
+      },
+    },
+    options,
+  );
   return { status: res.status, contentType: res.headers.get("content-type"), text };
 };
 
@@ -303,15 +366,19 @@ const findClaudeSessionKey = (): { sessionKey: string; source: string } | null =
   return null;
 };
 
-const fetchClaudeWebUsage = async (sessionKey: string) => {
+const fetchClaudeWebUsage = async (sessionKey: string, options: FetchOptions = {}) => {
   const headers = {
     Cookie: `sessionKey=${sessionKey}`,
     Accept: "application/json",
     "User-Agent":
       "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Safari/605.1.15",
   };
-  const orgRes = await fetch("https://claude.ai/api/organizations", { headers });
-  const orgText = await orgRes.text();
+  const { res: orgRes, text: orgText } = await fetchText(
+    "Claude organizations request",
+    "https://claude.ai/api/organizations",
+    { headers },
+    options,
+  );
   if (!orgRes.ok) {
     return { ok: false as const, step: "organizations", status: orgRes.status, body: orgText };
   }
@@ -321,8 +388,12 @@ const fetchClaudeWebUsage = async (sessionKey: string) => {
     return { ok: false as const, step: "organizations", status: 200, body: orgText };
   }
 
-  const usageRes = await fetch(`https://claude.ai/api/organizations/${orgId}/usage`, { headers });
-  const usageText = await usageRes.text();
+  const { res: usageRes, text: usageText } = await fetchText(
+    "Claude usage request",
+    `https://claude.ai/api/organizations/${orgId}/usage`,
+    { headers },
+    options,
+  );
   return usageRes.ok
     ? { ok: true as const, orgId, body: usageText }
     : { ok: false as const, step: "usage", status: usageRes.status, body: usageText };
@@ -397,7 +468,9 @@ export const testing = {
   CLAUDE_COOKIE_HOST_SQL,
   CLAUDE_FIREFOX_COOKIE_HOST_SQL,
   browserRootLabel,
+  fetchAnthropicOAuthUsage,
   mask,
+  resolveFetchTimeoutMs,
 };
 
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
diff --git a/test/scripts/dev-tooling-safety.test.ts b/test/scripts/dev-tooling-safety.test.ts
@@ -204,4 +204,40 @@ describe("script-specific dev tooling hardening", () => {
     expect(claudeUsageTesting.CLAUDE_COOKIE_HOST_SQL).toContain("LIKE '%.claude.ai'");
     expect(claudeUsageTesting.CLAUDE_COOKIE_HOST_SQL).not.toContain("%claude.ai%");
   });
+
+  it("aborts stalled Claude usage fetches at the request timeout", async () => {
+    let signal: AbortSignal | undefined;
+    const request = claudeUsageTesting.fetchAnthropicOAuthUsage("test-token", {
+      timeoutMs: 5,
+      fetchImpl: ((_url, init) => {
+        signal = init?.signal ?? undefined;
+        return new Promise(() => {});
+      }) as typeof fetch,
+    });
+
+    await expect(request).rejects.toThrow(/Anthropic OAuth usage request exceeded timeout/u);
+    expect(signal?.aborted).toBe(true);
+  });
+
+  it("times out stalled Claude usage response body reads", async () => {
+    const response = {
+      ok: true,
+      status: 200,
+      headers: new Headers({ "content-type": "application/json" }),
+      text: () => new Promise(() => {}),
+    } as Response;
+    const request = claudeUsageTesting.fetchAnthropicOAuthUsage("test-token", {
+      timeoutMs: 5,
+      fetchImpl: (() => Promise.resolve(response)) as typeof fetch,
+    });
+
+    await expect(request).rejects.toThrow(/Anthropic OAuth usage request exceeded timeout/u);
+  });
+
+  it("rejects invalid Claude usage timeout values", () => {
+    expect(claudeUsageTesting.resolveFetchTimeoutMs("123")).toBe(123);
+    expect(() => claudeUsageTesting.resolveFetchTimeoutMs("1.5")).toThrow(
+      /OPENCLAW_DEBUG_CLAUDE_USAGE_FETCH_TIMEOUT_MS must be an integer/u,
+    );
+  });
 });
